jsonc-parser

Scanner and parser for JSON with comments.

Why?

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

npm install --save jsonc-parser

API

Scanner:

1
2/**
3 * Creates a JSON scanner on the given text.
4 * If ignoreTrivia is set, whitespaces or comments are ignored.
5 */
6export function createScanner(text: string, ignoreTrivia: boolean = false): JSONScanner;
7
8/**
9 * The scanner object, representing a JSON scanner at a position in the input string.
10 */
11export interface JSONScanner {
12    /**
13     * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.
14     */
15    setPosition(pos: number): any;
16    /**
17     * Read the next token. Returns the token code.
18     */
19    scan(): SyntaxKind;
20    /**
21     * Returns the zero-based current scan position, which is after the last read token.
22     */
23    getPosition(): number;
24    /**
25     * Returns the last read token.
26     */
27    getToken(): SyntaxKind;
28    /**
29     * 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.
30     */
31    getTokenValue(): string;
32    /**
33     * The zero-based start offset of the last read token.
34     */
35    getTokenOffset(): number;
36    /**
37     * The length of the last read token.
38     */
39    getTokenLength(): number;
40    /**
41     * The zero-based start line number of the last read token.
42     */
43    getTokenStartLine(): number;
44    /**
45     * The zero-based start character (column) of the last read token.
46     */
47    getTokenStartCharacter(): number;
48    /**
49     * An error code of the last scan.
50     */
51    getTokenError(): ScanError;
52}

Parser:

1
2export interface ParseOptions {
3    disallowComments?: boolean;
4    allowTrailingComma?: boolean;
5    allowEmptyContent?: boolean;
6}
7/**
8 * 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.
9 * Therefore always check the errors list to find out if the input was valid.
10 */
11export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
12
13/**
14 * Parses the given text and invokes the visitor functions for each object, array and literal reached.
15 */
16export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
17
18/**
19 * Visitor called by {@linkcode visit} when parsing JSON.
20 *
21 * The visitor functions have the following common parameters:
22 * - `offset`: Global offset within the JSON document, starting at 0
23 * - `startLine`: Line number, starting at 0
24 * - `startCharacter`: Start character (column) within the current line, starting at 0
25 *
26 * Additionally some functions have a `pathSupplier` parameter which can be used to obtain the
27 * current `JSONPath` within the document.
28 */
29export interface JSONVisitor {
30    /**
31     * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
32     * When `false` is returned, the array items will not be visited.
33     */
34    onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void | boolean;
35
36    /**
37     * Invoked when a property is encountered. The offset and length represent the location of the property name.
38     * The `JSONPath` created by the `pathSupplier` refers to the enclosing JSON object, it does not include the
39     * property name yet.
40     */
41    onObjectProperty?: (property: string, offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
42    /**
43     * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
44     */
45    onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
46    /**
47     * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
48     * When `false` is returned, the array items will not be visited.*
49     */
50    onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void | boolean;
51    /**
52     * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
53     */
54    onArrayEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
55    /**
56     * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
57     */
58    onLiteralValue?: (value: any, offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
59    /**
60     * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
61     */
62    onSeparator?: (character: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
63    /**
64     * When comments are allowed, invoked when a line or block comment is encountered. The offset and length represent the location of the comment.
65     */
66    onComment?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
67    /**
68     * Invoked on an error.
69     */
70    onError?: (error: ParseErrorCode, offset: number, length: number, startLine: number, startCharacter: number) => void;
71}
72
73/**
74 * 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.
75 */
76export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node | undefined;
77
78export declare type NodeType = "object" | "array" | "property" | "string" | "number" | "boolean" | "null";
79export interface Node {
80    type: NodeType;
81    value?: any;
82    offset: number;
83    length: number;
84    colonOffset?: number;
85    parent?: Node;
86    children?: Node[];
87}
88

Utilities:

1/**
2 * Takes JSON with JavaScript-style comments and remove
3 * them. Optionally replaces every none-newline character
4 * of comments with a replaceCharacter
5 */
6export declare function stripComments(text: string, replaceCh?: string): string;
7
8/**
9 * 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.
10 */
11export declare function getLocation(text: string, position: number): Location;
12
13/**
14 * A {@linkcode JSONPath} segment. Either a string representing an object property name
15 * or a number (starting at 0) for array indices.
16 */
17export declare type Segment = string | number;
18export declare type JSONPath = Segment[];
19export interface Location {
20    /**
21     * The previous property key or literal value (string, number, boolean or null) or undefined.
22     */
23    previousNode?: Node;
24    /**
25     * The path describing the location in the JSON document. The path consists of a sequence strings
26     * representing an object property or numbers for array indices.
27     */
28    path: JSONPath;
29    /**
30     * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
31     * '*' will match a single segment, of any property name or index.
32     * '**' will match a sequence of segments or no segment, of any property name or index.
33     */
34    matches: (patterns: JSONPath) => boolean;
35    /**
36     * If set, the location's offset is at a property key.
37     */
38    isAtPropertyKey: boolean;
39}
40
41/**
42 * Finds the node at the given path in a JSON DOM.
43 */
44export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;
45
46/**
47 * Finds the most inner node at the given offset. If includeRightBound is set, also finds nodes that end at the given offset.
48 */
49export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node | undefined;
50
51/**
52 * Gets the JSON path of the given JSON DOM node
53 */
54export function getNodePath(node: Node): JSONPath;
55
56/**
57 * Evaluates the JavaScript object of the given JSON DOM node
58 */
59export function getNodeValue(node: Node): any;
60
61/**
62 * Computes the edit operations needed to format a JSON document.
63 *
64 * @param documentText The input text
65 * @param range The range to format or `undefined` to format the full content
66 * @param options The formatting options
67 * @returns The edit operations describing the formatting changes to the original document following the format described in {@linkcode EditResult}.
68 * To apply the edit operations to the input, use {@linkcode applyEdits}.
69 */
70export function format(documentText: string, range: Range, options: FormattingOptions): EditResult;
71
72/**
73 * Computes the edit operations needed to modify a value in the JSON document.
74 *
75 * @param documentText The input text
76 * @param path The path of the value to change. The path represents either to the document root, a property or an array item.
77 * If the path points to an non-existing property or item, it will be created.
78 * @param value The new value for the specified property or item. If the value is undefined,
79 * the property or item will be removed.
80 * @param options Options
81 * @returns The edit operations describing the changes to the original document, following the format described in {@linkcode EditResult}.
82 * To apply the edit operations to the input, use {@linkcode applyEdits}.
83 */
84export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): EditResult;
85
86/**
87 * Applies edits to an input string.
88 * @param text The input text
89 * @param edits Edit operations following the format described in {@linkcode EditResult}.
90 * @returns The text with the applied edits.
91 * @throws An error if the edit operations are not well-formed as described in {@linkcode EditResult}.
92 */
93export function applyEdits(text: string, edits: EditResult): string;
94
95/**
96 * An edit result describes a textual edit operation. It is the result of a {@linkcode format} and {@linkcode modify} operation.
97 * It consist of one or more edits describing insertions, replacements or removals of text segments.
98 * * The offsets of the edits refer to the original state of the document.
99 * * No two edits change or remove the same range of text in the original document.
100 * * Multiple edits can have the same offset if they are multiple inserts, or an insert followed by a remove or replace.
101 * * The order in the array defines which edit is applied first.
102 * To apply an edit result use {@linkcode applyEdits}.
103 * In general multiple EditResults must not be concatenated because they might impact each other, producing incorrect or malformed JSON data.
104 */
105export type EditResult = Edit[];
106
107/**
108 * Represents a text modification
109 */
110export interface Edit {
111    /**
112     * The start offset of the modification.
113     */
114    offset: number;
115    /**
116     * The length of the modification. Must not be negative. Empty length represents an *insert*.
117     */
118    length: number;
119    /**
120     * The new content. Empty content represents a *remove*.
121     */
122    content: string;
123}
124
125/**
126 * A text range in the document
127*/
128export interface Range {
129    /**
130     * The start offset of the range.
131     */
132    offset: number;
133    /**
134     * The length of the range. Must not be negative.
135     */
136    length: number;
137}
138
139/**
140 * Options used by {@linkcode format} when computing the formatting edit operations
141 */
142export interface FormattingOptions {
143    /**
144     * If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?
145     */
146    tabSize: number;
147    /**
148     * Is indentation based on spaces?
149     */
150    insertSpaces: boolean;
151    /**
152     * The default 'end of line' character
153     */
154    eol: string;
155}
156
157/**
158 * Options used by {@linkcode modify} when computing the modification edit operations
159 */
160export interface ModificationOptions {
161    /**
162     * Formatting options. If undefined, the newly inserted code will be inserted unformatted.
163    */
164    formattingOptions?: FormattingOptions;
165    /**
166     * Default false. If `JSONPath` refers to an index of an array and `isArrayInsertion` is `true`, then
167     * {@linkcode modify} will insert a new item at that location instead of overwriting its contents.
168     */
169    isArrayInsertion?: boolean;
170    /**
171     * Optional function to define the insertion index given an existing list of properties.
172     */
173    getInsertionIndex?: (properties: string[]) => number;
174}

License

(MIT License)

Copyright 2018, Microsoft