JSONC is JSON with JavaScript style comments. This node module provides a scanner and fault tolerant parser that can process JSONC but is also useful for standard JSON.
the scanner tokenizes the input string into tokens and token offsets
the visit function implements a 'SAX' style parser with callbacks for the encountered properties and values.
the parseTree function computes a hierarchical DOM with offsets representing the encountered properties and values.
the parse function evaluates the JavaScript object represented by JSON string in a fault tolerant fashion.
the getLocation API returns a location object that describes the property or value located at a given offset in a JSON document.
the findNodeAtLocation API finds the node at a given location path in a JSON DOM.
the format API computes edits to format a JSON document.
the modify API computes edits to insert, remove or replace a property or value in a JSON document.
the applyEdits API applies edits to a document.
Installation
jsonc-parser is published as an ESM-only package.
npm install --save jsonc-parser
API
Scanner:
/** * Creates a JSON scanner on the given text. * If ignoreTrivia is set, whitespaces or comments are ignored. */export function createScanner(text: string, ignoreTrivia: boolean = false): JSONScanner;/** * The scanner object, representing a JSON scanner at a position in the input string. */export interface JSONScanner { /** * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token. */ setPosition(pos: number): any; /** * Read the next token. Returns the token code. */ scan(): SyntaxKind;
Parser:
export interface ParseOptions { disallowComments?: boolean; allowTrailingComma?: boolean; allowEmptyContent?: boolean;}/** * 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. * Therefore always check the errors list to find out if the input was valid. */export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;/** * Parses the given text and invokes the visitor functions for each object, array and literal reached. */export declare function visit
Utilities:
/** * Takes JSON with JavaScript-style comments and remove * them. Optionally replaces every none-newline character * of comments with a replaceCharacter */export declare function stripComments(text: string, replaceCh?: string): string;/** * 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. */export declare function getLocation(text: string, position: number): Location;/** * A {@linkcode JSONPath} segment. Either a string representing an object property name * or a number (starting at 0) for array indices. */
License
(MIT License)
Copyright 2018, Microsoft
/**
* Returns the zero-based current scan position, which is after the last read token.
*/
getPosition(): number;
/**
* Returns the last read token.
*/
getToken(): SyntaxKind;
/**
* Returns the last read token value. The value for strings is the decoded string content. For numbers it's of type number, for boolean it's true or false.
*/
getTokenValue(): string;
/**
* The zero-based start offset of the last read token.
*/
getTokenOffset(): number;
/**
* The length of the last read token.
*/
getTokenLength(): number;
/**
* The zero-based start line number of the last read token.
*/
getTokenStartLine(): number;
/**
* The zero-based start character (column) of the last read token.
*/
getTokenStartCharacter(): number;
/**
* An error code of the last scan.
*/
getTokenError(): ScanError;
}
(text
:
string
, visitor
:
JSONVisitor
, options
?:
ParseOptions
)
:
any
;
/**
* Visitor called by {@linkcode visit} when parsing JSON.
*
* The visitor functions have the following common parameters:
* - `offset`: Global offset within the JSON document, starting at 0
* - `startLine`: Line number, starting at 0
* - `startCharacter`: Start character (column) within the current line, starting at 0
*
* Additionally some functions have a `pathSupplier` parameter which can be used to obtain the
* current `JSONPath` within the document.
*/
export interface JSONVisitor {
/**
* Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
* When `false` is returned, the array items will not be visited.
* 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.