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 JavaScipt 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.
• ths 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 tolen code.
18     */
19    scan(): SyntaxKind;
20    /**
21     * Returns the 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 its of type number, for boolean it's true or false.
30     */
31    getTokenValue(): string;
32    /**
33     * The 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     * An error code of the last scan.
42     */
43    getTokenError(): ScanError;
44}

Parser:

1
2export interface ParseOptions {
3    disallowComments?: boolean;
4}
5/**
6 * Parses the given text and returns the object the JSON content represents. On invalid input, the parser tries to be as fault lolerant as possible, but still return a result.
7 * Therefore always check the errors list to find out if the input was valid.
8 */
9export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
10
11/**
12 * Parses the given text and invokes the visitor functions for each object, array and literal reached.
13 */
14export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
15
16export interface JSONVisitor {
17    /**
18     * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
19     */
20    onObjectBegin?: (offset: number, length: number) => void;
21    /**
22     * Invoked when a property is encountered. The offset and length represent the location of the property name.
23     */
24    onObjectProperty?: (property: string, offset: number, length: number) => void;
25    /**
26     * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
27     */
28    onObjectEnd?: (offset: number, length: number) => void;
29    /**
30     * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
31     */
32    onArrayBegin?: (offset: number, length: number) => void;
33    /**
34     * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
35     */
36    onArrayEnd?: (offset: number, length: number) => void;
37    /**
38     * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
39     */
40    onLiteralValue?: (value: any, offset: number, length: number) => void;
41    /**
42     * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
43     */
44    onSeparator?: (charcter: string, offset: number, length: number) => void;
45    /**
46     * Invoked on an error.
47     */
48    onError?: (error: ParseErrorCode, offset: number, length: number) => void;
49}
50
51/**
52 * 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.
53 */
54export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node;
55
56export declare type NodeType = "object" | "array" | "property" | "string" | "number" | "boolean" | "null";
57export interface Node {
58    type: NodeType;
59    value?: any;
60    offset: number;
61    length: number;
62    columnOffset?: number;
63    parent?: Node;
64    children?: Node[];
65}
66

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
13export declare type Segment = string | number;
14export interface Location {
15    /**
16     * The previous property key or literal value (string, number, boolean or null) or undefined.
17     */
18    previousNode?: Node;
19    /**
20     * The path describing the location in the JSON document. The path consists of a sequence strings
21     * representing an object property or numbers for array indices.
22     */
23    path: Segment[];
24    /**
25     * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
26     * '*' will match a single segment, of any property name or index.
27     * '**' will match a sequece of segments or no segment, of any property name or index.
28     */
29    matches: (patterns: Segment[]) => boolean;
30    /**
31     * If set, the location's offset is at a property key.
32     */
33    isAtPropertyKey: boolean;
34}
35
36/**
37 * Finds the node at the given path in a JSON DOM.
38 */
39export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;
40
41/**
42 * Evaluates the JavaScript object of the given JSON DOM node 
43 */
44export function getNodeValue(node: Node): any;
45
46/**
47 * Computes the edits needed to format a JSON document. 
48 * 
49 * @param documentText The input text 
50 * @param range The range to format or `undefined` to format the full content
51 * @param options The formatting options
52 * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
53 * 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
54 * text in the original document. However, multiple edits can have
55 * 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.
56 * To apply edits to an input, you can use `applyEdits`
57 */
58export function format(documentText: string, range: Range, options: FormattingOptions): Edit[];
59
60
61/**
62 * Computes the edits needed to modify a value in the JSON document.
63 * 
64 * @param documentText The input text 
65 * @param path The path of the value to change. The path represents either to the document root, a property or an array item.
66 * If the path points to an non-existing property or item, it will be created. 
67 * @param value The new value for the specified property or item. If the value is undefined,
68 * the property or item will be removed.
69 * @param options Options
70 * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
71 * 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
72 * text in the original document. However, multiple edits can have
73 * 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.
74 * To apply edits to an input, you can use `applyEdits`
75 */
76export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): Edit[];
77
78/**
79 * Applies edits to a input string.
80 */
81export function applyEdits(text: string, edits: Edit[]): string;
82
83/**
84 * Represents a text modification
85 */
86export interface Edit {
87	/**
88	 * The start offset of the modification.
89	 */
90	offset: number;
91	/**
92	 * The length of the modification. Must not be negative. Empty length represents an *insert*.
93	 */
94	length: number;
95	/**
96	 * The new content. Empty content represents a *remove*.
97	 */
98	content: string;
99}
100
101/**
102 * A text range in the document
103*/
104export interface Range {
105	/**
106	 * The start offset of the range. 
107	 */
108	offset: number;
109	/**
110	 * The length of the range. Must not be negative.  
111	 */
112	length: number;
113}
114
115export interface FormattingOptions {
116	/**
117	 * If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?
118	 */
119	tabSize: number;
120	/**
121	 * Is indentation based on spaces?
122	 */
123	insertSpaces: boolean;
124	/**
125	 * The default 'end of line' character
126	 */
127	eol: string;
128}
129

License

(MIT License)

Copyright 2018, Microsoft