Scanner and parser for JSON with comments.

\href{https://www.npmjs.org/package/jsonc-parser}{\texttt{ }} \href{https://npmjs.org/package/jsonc-parser}{\texttt{ }} \href{https://travis-ci.org/Microsoft/node-jsonc-parser}{\texttt{ }}\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14421}{}\doxysection{Why?}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14421}
JSONC is JSON with Java\+Script style comments. This node module provides a scanner and fault tolerant parser that can process JSONC but is also useful for standard JSON.
\begin{DoxyItemize}
\item the {\itshape scanner} tokenizes the input string into tokens and token offsets
\item the {\itshape visit} function implements a \textquotesingle{}SAX\textquotesingle{} style parser with callbacks for the encountered properties and values.
\item the {\itshape parse\+Tree} function computes a hierarchical DOM with offsets representing the encountered properties and values.
\item the {\itshape parse} function evaluates the Java\+Script object represented by JSON string in a fault tolerant fashion.
\item the {\itshape get\+Location} API returns a location object that describes the property or value located at a given offset in a JSON document.
\item the {\itshape find\+Node\+At\+Location} API finds the node at a given location path in a JSON DOM.
\item the {\itshape format} API computes edits to format a JSON document.
\item the {\itshape modify} API computes edits to insert, remove or replace a property or value in a JSON document.
\item the {\itshape apply\+Edits} API applies edits to a document.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14422}{}\doxysection{Installation}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14422}
\begin{DoxyVerb}npm install --save jsonc-parser
\end{DoxyVerb}
\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14423}{}\doxysection{API}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14423}
\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14424}{}\doxysubsection{Scanner\+:}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14424}

\begin{DoxyCode}{0}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Creates a JSON scanner on the given text.}
\DoxyCodeLine{ * If ignoreTrivia is set, whitespaces or comments are ignored.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function createScanner(text:string, ignoreTrivia:boolean = false):JSONScanner;}
\DoxyCodeLine{    }
\DoxyCodeLine{/**}
\DoxyCodeLine{ * The scanner object, representing a JSON scanner at a position in the input string.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export interface JSONScanner \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    setPosition(pos: number): any;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Read the next token. Returns the token code.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    scan(): SyntaxKind;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Returns the current scan position, which is after the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getPosition(): number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Returns the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getToken(): SyntaxKind;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Returns the last read token value. The value for strings is the decoded string content. For numbers its of type number, for boolean it's true or false.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenValue(): string;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The start offset of the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenOffset(): number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The length of the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenLength(): number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The zero-\/based start line number of the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenStartLine(): number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The zero-\/based start character (column) of the last read token.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenStartCharacter(): number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * An error code of the last scan.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    getTokenError(): ScanError;}
\DoxyCodeLine{\} }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14425}{}\doxysubsection{Parser\+:}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14425}

\begin{DoxyCode}{0}
\DoxyCodeLine{export interface ParseOptions \{}
\DoxyCodeLine{    disallowComments?: boolean;}
\DoxyCodeLine{\}}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Parses the given text and returns the object the JSON content represents. On invalid input, the parser tries to be as fault tolerant as possible, but still return a result.}
\DoxyCodeLine{ * Therefore always check the errors list to find out if the input was valid.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export declare function parse(text: string, errors?: \{error: ParseErrorCode;\}[], options?: ParseOptions): any;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Parses the given text and invokes the visitor functions for each object, array and literal reached.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;}
\DoxyCodeLine{}
\DoxyCodeLine{export interface JSONVisitor \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when a property is encountered. The offset and length represent the location of the property name.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onObjectProperty?: (property: string, offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onArrayEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onLiteralValue?: (value: any, offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onSeparator?: (character: string, offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * When comments are allowed, invoked when a line or block comment is encountered. The offset and length represent the location of the comment.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onComment?: (offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Invoked on an error.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    onError?: (error: ParseErrorCode, offset: number, length: number, startLine: number, startCharacter: number) => void;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Parses the given text and returns a tree representation the JSON content. On invalid input, the parser tries to be as fault tolerant as possible, but still return a result.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node;}
\DoxyCodeLine{}
\DoxyCodeLine{export declare type NodeType = "{}object"{} | "{}array"{} | "{}property"{} | "{}string"{} | "{}number"{} | "{}boolean"{} | "{}null"{};}
\DoxyCodeLine{export interface Node \{}
\DoxyCodeLine{    type: NodeType;}
\DoxyCodeLine{    value?: any;}
\DoxyCodeLine{    offset: number;}
\DoxyCodeLine{    length: number;}
\DoxyCodeLine{    colonOffset?: number;}
\DoxyCodeLine{    parent?: Node;}
\DoxyCodeLine{    children?: Node[];}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14426}{}\doxysubsection{Utilities\+:}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14426}

\begin{DoxyCode}{0}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Takes JSON with JavaScript-\/style comments and remove}
\DoxyCodeLine{ * them. Optionally replaces every none-\/newline character}
\DoxyCodeLine{ * of comments with a replaceCharacter}
\DoxyCodeLine{ */}
\DoxyCodeLine{export declare function stripComments(text: string, replaceCh?: string): string;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * For a given offset, evaluate the location in the JSON document. Each segment in the location path is either a property name or an array index.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export declare function getLocation(text: string, position: number): Location;}
\DoxyCodeLine{}
\DoxyCodeLine{export declare type Segment = string | number;}
\DoxyCodeLine{export interface Location \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The previous property key or literal value (string, number, boolean or null) or undefined.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    previousNode?: Node;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The path describing the location in the JSON document. The path consists of a sequence strings}
\DoxyCodeLine{     * representing an object property or numbers for array indices.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    path: Segment[];}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).}
\DoxyCodeLine{     * '*' will match a single segment, of any property name or index.}
\DoxyCodeLine{     * '**' will match a sequece of segments or no segment, of any property name or index.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    matches: (patterns: Segment[]) => boolean;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * If set, the location's offset is at a property key.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    isAtPropertyKey: boolean;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Finds the node at the given path in a JSON DOM.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Finds the most inner node at the given offset. If includeRightBound is set, also finds nodes that end at the given offset.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node | undefined;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Gets the JSON path of the given JSON DOM node}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function getNodePath(node: Node) : JSONPath;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Evaluates the JavaScript object of the given JSON DOM node }
\DoxyCodeLine{ */}
\DoxyCodeLine{export function getNodeValue(node: Node): any;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Computes the edits needed to format a JSON document. }
\DoxyCodeLine{ * }
\DoxyCodeLine{ * @param documentText The input text }
\DoxyCodeLine{ * @param range The range to format or `undefined` to format the full content}
\DoxyCodeLine{ * @param options The formatting options}
\DoxyCodeLine{ * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or}
\DoxyCodeLine{ * removals of text segments. All offsets refer to the original state of the document. No two edits must change or remove the same range of}
\DoxyCodeLine{ * text in the original document. However, multiple edits can have}
\DoxyCodeLine{ * the same offset, for example multiple inserts, or an insert followed by a remove or replace. The order in the array defines which edit is applied first.}
\DoxyCodeLine{ * To apply edits to an input, you can use `applyEdits`}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function format(documentText: string, range: Range, options: FormattingOptions): Edit[];}
\DoxyCodeLine{}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Computes the edits needed to modify a value in the JSON document.}
\DoxyCodeLine{ * }
\DoxyCodeLine{ * @param documentText The input text }
\DoxyCodeLine{ * @param path The path of the value to change. The path represents either to the document root, a property or an array item.}
\DoxyCodeLine{ * If the path points to an non-\/existing property or item, it will be created. }
\DoxyCodeLine{ * @param value The new value for the specified property or item. If the value is undefined,}
\DoxyCodeLine{ * the property or item will be removed.}
\DoxyCodeLine{ * @param options Options}
\DoxyCodeLine{ * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or}
\DoxyCodeLine{ * removals of text segments. All offsets refer to the original state of the document. No two edits must change or remove the same range of}
\DoxyCodeLine{ * text in the original document. However, multiple edits can have}
\DoxyCodeLine{ * the same offset, for example multiple inserts, or an insert followed by a remove or replace. The order in the array defines which edit is applied first.}
\DoxyCodeLine{ * To apply edits to an input, you can use `applyEdits`}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): Edit[];}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Applies edits to a input string.}
\DoxyCodeLine{ */}
\DoxyCodeLine{export function applyEdits(text: string, edits: Edit[]): string;}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * Represents a text modification}
\DoxyCodeLine{ */}
\DoxyCodeLine{export interface Edit \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The start offset of the modification.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    offset: number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The length of the modification. Must not be negative. Empty length represents an *insert*.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    length: number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The new content. Empty content represents a *remove*.}
\DoxyCodeLine{     */}
\DoxyCodeLine{    content: string;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{/**}
\DoxyCodeLine{ * A text range in the document}
\DoxyCodeLine{*/}
\DoxyCodeLine{export interface Range \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The start offset of the range. }
\DoxyCodeLine{     */}
\DoxyCodeLine{    offset: number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The length of the range. Must not be negative.  }
\DoxyCodeLine{     */}
\DoxyCodeLine{    length: number;}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{export interface FormattingOptions \{}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?}
\DoxyCodeLine{     */}
\DoxyCodeLine{    tabSize: number;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * Is indentation based on spaces?}
\DoxyCodeLine{     */}
\DoxyCodeLine{    insertSpaces: boolean;}
\DoxyCodeLine{    /**}
\DoxyCodeLine{     * The default 'end of line' character}
\DoxyCodeLine{     */}
\DoxyCodeLine{    eol: string;}
\DoxyCodeLine{\}}

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14427}{}\doxysection{License}\label{md_sfcode_node_modules_jsonc_parser_README_autotoc_md14427}
(MIT License)

Copyright 2018, Microsoft 