// Copyright (c) 2020 Google LLC All rights reserved.

// Use of this source code is governed by a BSD-style

// license that can be found in the LICENSE file.

//! A stylized formatter for [JSON5](https://json5.org) ("JSON for Humans") documents.

//!

//! The intent of this formatter is to rewrite a given valid JSON5 document, restructuring the

//! output (if required) to conform to a consistent style.

//!

//! The resulting document should preserve all data precision, data format representations, and

//! semantic intent. Readability should be maintained, if not improved by the consistency within and

//! across documents.

//!

//! Most importantly, all JSON5 comments should be preserved, maintaining the

//! positional relationship with the JSON5 data elements they were intended to document.

//!

//! # Example

//!

//! ```rust

//!   use json5format::*;

//!   use maplit::hashmap;

//!   use maplit::hashset;

//!

//!   let json5=r##"{

//!       "name": {

//!           "last": "Smith",

//!           "first": "John",

//!           "middle": "Jacob"

//!       },

//!       "children": [

//!           "Buffy",

//!           "Biff",

//!           "Balto"

//!       ],

//!       // Consider adding a note field to the `other` contact option

//!       "contact_options": [

//!           {

//!               "home": {

//!                   "email": "jj@notreallygmail.com",   // This was the original user id.

//!                                                       // Now user id's are hash values.

//!                   "phone": "212-555-4321"

//!               },

//!               "other": {

//!                   "email": "volunteering@serviceprojectsrus.org"

//!               },

//!               "work": {

//!                   "phone": "212-555-1234",

//!                   "email": "john.j.smith@worksforme.gov"

//!               }

//!           }

//!       ],

//!       "address": {

//!           "city": "Anytown",

//!           "country": "USA",

//!           "state": "New York",

//!           "street": "101 Main Street"

//!           /* Update schema to support multiple addresses:

//!              "work": {

//!                  "city": "Anytown",

//!                  "country": "USA",

//!                  "state": "New York",

//!                  "street": "101 Main Street"

//!              }

//!           */

//!       }

//!   }

//!   "##;

//!

//!   let options = FormatOptions {

//!       indent_by: 2,

//!       collapse_containers_of_one: true,

//!       options_by_path: hashmap! {

//!           "/*" => hashset! {

//!               PathOption::PropertyNameOrder(vec![

//!                   "name",

//!                   "address",

//!                   "contact_options",

//!               ]),

//!           },

//!           "/*/name" => hashset! {

//!               PathOption::PropertyNameOrder(vec![

//!                   "first",

//!                   "middle",

//!                   "last",

//!                   "suffix",

//!               ]),

//!           },

//!           "/*/children" => hashset! {

//!               PathOption::SortArrayItems(true),

//!           },

//!           "/*/*/*" => hashset! {

//!               PathOption::PropertyNameOrder(vec![

//!                   "work",

//!                   "home",

//!                   "other",

//!               ]),

//!           },

//!           "/*/*/*/*" => hashset! {

//!               PathOption::PropertyNameOrder(vec![

//!                   "phone",

//!                   "email",

//!               ]),

//!           },

//!       },

//!       ..Default::default()

//!   };

//!

//!   let filename = "new_contact.json5".to_string();

//!

//!   let format = Json5Format::with_options(options)?;

//!   let parsed_document = ParsedDocument::from_str(&json5, Some(filename))?;

//!   let bytes: Vec<u8> = format.to_utf8(&parsed_document)?;

//!

//!   assert_eq!(std::str::from_utf8(&bytes)?, r##"{

//!   name: {

//!     first: "John",

//!     middle: "Jacob",

//!     last: "Smith",

//!   },

//!   address: {

//!     city: "Anytown",

//!     country: "USA",

//!     state: "New York",

//!     street: "101 Main Street",

//!

//!     /* Update schema to support multiple addresses:

//!        "work": {

//!            "city": "Anytown",

//!            "country": "USA",

//!            "state": "New York",

//!            "street": "101 Main Street"

//!        }

//!     */

//!   },

//!

//!   // Consider adding a note field to the `other` contact option

//!   contact_options: [

//!     {

//!       work: {

//!         phone: "212-555-1234",

//!         email: "john.j.smith@worksforme.gov",

//!       },

//!       home: {

//!         phone: "212-555-4321",

//!         email: "jj@notreallygmail.com", // This was the original user id.

//!                                         // Now user id's are hash values.

//!       },

//!       other: { email: "volunteering@serviceprojectsrus.org" },

//!     },

//!   ],

//!   children: [

//!     "Balto",

//!     "Biff",

//!     "Buffy",

//!   ],

//! }

//! "##);

//! # Ok::<(),anyhow::Error>(())

//! ```

//!

//! # Formatter Actions

//!

//! When the options above are applied to the input, the formatter will make the following changes:

//!

//!   * The formatted document will be indented by 2 spaces.

//!   * Quotes are removed from all property names (since they are all legal ECMAScript identifiers)

//!   * The top-level properties will be reordered to [`name`, `address`, `contact_options`]. Since

//!     property name `children` was not included in the sort order, it will be placed at the end.

//!   * The `name` properties will be reordered to [`first`, `middle`, `last`].

//!   * The properties of the unnamed object in array `contact_options` will be reordered to

//!     [`work`, `home`, `other`].

//!   * The properties of the `work`, `home`, and `other` objects will be reordered to

//!     [`phone`, `email`].

//!   * The `children` names array of string primitives will be sorted.

//!   * All elements (except the top-level object, represented by the outermost curly braces) will

//!     end with a comma.

//!   * Since the `contact_options` descendant element `other` has only one property, the `other`

//!     object structure will collapse to a single line, with internal trailing comma suppressed.

//!   * The line comment will retain its relative position, above `contact_options`.

//!   * The block comment will retain its relative position, inside and at the end of the `address`

//!     object.

//!   * The end-of-line comment after `home`/`email` will retain its relative location (appended at

//!     the end of the `email` value) and any subsequent line comments with the same vertical

//!     alignment are also retained, and vertically adjusted to be left-aligned with the new

//!     position of the first comment line.

//!

//! # Formatter Behavior Details

//!

//! For reference, the following sections detail how the JSON5 formatter verifies and processes

//! JSON5 content.

//!

//! ## Syntax Validation

//!

//! * Structural syntax is checked, such as validating matching braces, property name-colon-value

//!   syntax, enforced separation of values by commas, properly quoted strings, and both block and

//!   line comment extraction.

//! * Non-string literal value syntax is checked (null, true, false, and the various legal formats

//!   for JSON5 Numbers).

//! * Syntax errors produce error messages with the line and column where the problem

//!   was encountered.

//!

//! ## Property Names

//!

//! * Duplicate property names are retained, but may constitute errors in higher-level JSON5

//!   parsers or schema-specific deserializers.

//! * All JSON5 unquoted property name characters are supported, including '$' and '_'. Digits are

//!   the only valid property name character that cannot be the first character. Property names

//!   can also be represented as quoted strings. All valid JSON5 strings, if quoted, are valid

//!   property names (including multi-line strings and quoted numbers).

//!

//! Example:

//! ```json

//!     $_meta_prop: 'Has "double quotes" and \'single quotes\' and \

//! multiple lines with escaped \\ backslash',

//! ```

//!

//! ## Literal Values

//!

//! * JSON5 supports quoting strings (literal values or quoted property names) by either double (")

//!   or single (') quote. The formatter does not change the quotes. Double-quoting is

//!   conventional, but single quotes may be used when quoting strings containing double-quotes, and

//!   leaving the single quotes as-is is preferred.

//! * JSON5 literal values are retained as-is. Strings retain all spacing characters, including

//!   escaped newlines. All other literals (unquoted tokens without spaces, such as false, null,

//!   0.234, 1337, or l33t) are _not_ interpreted syntactically. Other schema-based tools and JSON5

//!   deserializers may flag these invalid values.

//!

//! ## Optional Sorting

//!

//! * By default, array items and object properties retain their original order. (Some JSON arrays

//!   are order-dependent, and sorting them indiscriminantly might change the meaning of the data.)

//! * The formatter can automatically sort array items and object properties if enabled via

//!   `FormatOptions`:

//!   - To sort all arrays in the document, set

//!     [FormatOptions.sort_array_items](struct.FormatOptions.html#structfield.sort_array_items) to

//!     `true`

//!   - To sort only specific arrays in the target schema, specify the schema location under

//!     [FormatOptions.options_by_path](struct.FormatOptions.html#structfield.options_by_path), and

//!     set its [SortArrayItems](enum.PathOption.html#variant.SortArrayItems) option.

//!   - Properties are sorted based on an explicit user-supplied list of property names in the

//!     preferred order, for objects at a specified path. Specify the object's location in the

//!     target schema using

//!     [FormatOptions.options_by_path](struct.FormatOptions.html#structfield.options_by_path), and

//!     provide a vector of property name strings with the

//!     [PropertyNameOrder](enum.PathOption.html#variant.PropertyNameOrder) option. Properties not

//!     included in this option retain their original order, behind the explicitly ordered

//!     properties, if any.

//! * When sorting array items, the formatter only sorts array item literal values (strings,

//!   numbers, bools, and null). Child arrays or objects are left in their original order, after

//!   sorted literals, if any, within the same array.

//! * Array items are sorted in case-insensitive unicode lexicographic order. **(Note that, since

//!   the formatter does not parse unquoted literals, number types cannot be sorted numerically.)**

//!   Items that are case-insensitively equal are re-compared and ordered case-sensitively with

//!   respect to each other.

//!

//! ## Associated Comments

//!

//! * All comments immediately preceding an element (value or start of an array or object), and

//!   trailing line comments (starting on the same line as the element, optionally continued on

//!   successive lines if all line comments are left-aligned), are retained and move with the

//!   associated item if the item is repositioned during sorting.

//! * All line and block comments are retained. Typically, the comments are re-aligned vertically

//!   (indented) with the values with which they were associated.

//! * A single line comment appearing immediately after a JSON value (primitive or closing brace),

//!   on the same line, will remain appended to that value on its line after re-formatting.

//! * Spaces separate block comments from blocks of contiguous line comments associated with the

//!   same entry.

//! * Comments at the end of a list (after the last property or item) are retained at the end of

//!   the same list.

//! * Block comments with lines that extend to the left of the opening "/\*" are not re-aligned.

//!

//! ## Whitespace Handling

//!

//! * Unicode characters are allowed, and unicode space characters should retain their meaning

//!   according to unicode standards.

//! * All spaces inside single- or multi-line strings are retained. All spaces in comments are

//!   retained *except* trailing spaces at the end of a line.

//! * All other original spaces are removed.

#![deny(missing_docs)]

#![allow(clippy::len_zero)]

#[macro_use]

mod error;

mod content;

mod formatter;

mod options;

mod parser;

use {

    crate::formatter::*, std::cell::RefCell, std::collections::HashMap, std::collections::HashSet,

    std::rc::Rc,

};

pub use content::Array;

pub use content::Comment;

pub use content::Comments;

pub use content::Object;

pub use content::ParsedDocument;

pub use content::Primitive;

pub use content::Property;

pub use content::Value;

pub use error::Error;

pub use error::Location;

pub use options::FormatOptions;

pub use options::PathOption;

/// Format a JSON5 document, applying a consistent style, with given options.

///

/// See [FormatOptions](struct.FormatOptions.html) for style options, and confirm the defaults by

/// reviewing the source of truth via the `src` link for

/// [impl Default for FormatOptions](struct.FormatOptions.html#impl-Default).

///

/// # Format and Style (Default)

///

/// Unless FormatOptions are modified, the JSON5 formatter takes a JSON5 document (as a unicode

/// String) and generates a new document with the following formatting:

///

/// * Indents 4 spaces.

/// * Quotes are removed from property names if they are legal ECMAScript 5.1 identifiers. Property

///   names that do not comply with ECMAScript identifier format requirements will retain their

///   existing (single or double) quotes.

/// * All property and item lists end with a trailing comma.

/// * All property and item lists are broken down; that is, the braces are on separate lines and

///   all values are indented.

///

/// ```json

/// {

///     key: "value",

///     array: [

///         3.145,

///     ]

/// }

/// ```

///

/// # Arguments

///   * buffer - A unicode string containing the original JSON5 document.

///   * filename - An optional filename. Parsing errors typically include the filename (if given),

///     and the line number and character column where the error was detected.

///   * options - Format style options to override the default style, if provided.

/// # Returns

///   * The formatted result in UTF-8 encoded bytes.

pub fn format(

    buffer: &str,

    filename: Option<String>,

    options: Option<FormatOptions>,

) -> Result<Vec<u8>, Error> {

    let parsed_document = ParsedDocument::from_str(buffer, filename)?;

    let options = match options {

        Some(options) => options,

        None => FormatOptions { ..Default::default() },

    };

    Json5Format::with_options(options)?.to_utf8(&parsed_document)

}

/// A JSON5 formatter that parses a valid JSON5 input buffer and produces a new, formatted document.

pub struct Json5Format {

    /// Options that alter how the formatter generates the formatted output. This instance of

    /// FormatOptions is a subset of the FormatOptions passed to the `with_options` constructor.

    /// The `options_by_path` are first removed, and then used to initialize the SubpathOptions

    /// hierarchy rooted at the `document_root_options_ref`.

    default_options: FormatOptions,

    /// Depth-specific options applied at the document root and below.

    document_root_options_ref: Rc<RefCell<SubpathOptions>>,

}

impl Json5Format {

    /// Create and return a Json5Format, with the given options to be applied to the

    /// [Json5Format::to_utf8()](struct.Json5Format.html#method.to_utf8) operation.

    pub fn with_options(mut options: FormatOptions) -> Result<Self, Error> {

        let mut document_root_options = SubpathOptions::new(&options);

        // Typical JSON5 documents start and end with curly braces for a top-level unnamed

        // object. This is by convention, and the Json5Format represents this

        // top-level object as a single child in a conceptual array. The array square braces

        // are not rendered, and by convention, the child object should not have a trailing

        // comma, even if trailing commas are the default everywhere else in the document.

        //

        // Set the SubpathOptions for the document array items to prevent trailing commas.

        document_root_options.options.trailing_commas = false;

        let mut options_by_path =

            options.options_by_path.drain().collect::<HashMap<&'static str, HashSet<PathOption>>>();

        // Default options remain after draining the `options_by_path`

        let default_options = options;

        // Transfer the options_by_path from the given options into the SubpathOptions tree

        // rooted at `document_options_root`.

        for (path, path_options) in options_by_path.drain() {

            let rc; // extend life of temporary

            let mut borrowed; // extend life of temporary

            let subpath_options = if path == "/" {

                &mut document_root_options

            } else if let Some(remaining) = path.strip_prefix('/') {

                rc = document_root_options.get_or_create_subpath_options(

                    &remaining.split('/').collect::<Vec<_>>(),

                    &default_options,

                );

                borrowed = rc.borrow_mut();

                &mut *borrowed

            } else {

                return Err(Error::configuration(format!(

                    "PathOption path '{}' is invalid.",

                    path

                )));

            };

            subpath_options.override_default_options(&path_options);

        }

        Ok(Json5Format {

            default_options,

            document_root_options_ref: Rc::new(RefCell::new(document_root_options)),

        })

    }

    /// Create and return a Json5Format, with the default settings.

    pub fn new() -> Result<Self, Error> {

        Self::with_options(FormatOptions { ..Default::default() })

    }

    /// Formats the parsed document into a new Vector of UTF8 bytes.

    ///

    /// # Arguments

    ///   * `parsed_document` - The parsed state of the incoming document.

    ///

    /// # Example

    ///

    /// ```

    /// # use json5format::*;

    /// # let buffer = String::from("{}");

    /// # let filename = String::from("example.json5");

    /// let format = Json5Format::new()?;

    /// let parsed_document = ParsedDocument::from_str(&buffer, Some(filename))?;

    /// let bytes = format.to_utf8(&parsed_document)?;

    /// # assert_eq!("{}\n", std::str::from_utf8(&bytes).unwrap());

    /// # Ok::<(),anyhow::Error>(())

    /// ```

    pub fn to_utf8(&self, parsed_document: &ParsedDocument) -> Result<Vec<u8>, Error> {

        let formatter =

            Formatter::new(self.default_options.clone(), self.document_root_options_ref.clone());

        formatter.format(parsed_document)

    }

    /// Formats the parsed document into a new String.

    ///

    /// # Arguments

    ///   * `parsed_document` - The parsed state of the incoming document.

    ///

    /// # Example

    ///

    /// ```

    /// # use json5format::*;

    /// # fn main() -> std::result::Result<(), Error> {

    /// # let buffer = String::from("{}");

    /// # let filename = String::from("example.json5");

    /// let format = Json5Format::new()?;

    /// let parsed_document = ParsedDocument::from_str(&buffer, Some(filename))?;

    /// let formatted = format.to_string(&parsed_document)?;

    /// # assert_eq!("{}\n", formatted);

    /// # Ok(())

    /// # }

    /// ```

    pub fn to_string(&self, parsed_document: &ParsedDocument) -> Result<String, Error> {

        String::from_utf8(self.to_utf8(parsed_document)?)

            .map_err(|e| Error::internal(None, e.to_string()))

    }

}