1 | # jsonc-parser
|
2 | Scanner and parser for JSON with comments.
|
3 |
|
4 | [![npm Package](https://img.shields.io/npm/v/jsonc-parser.svg?style=flat-square)](https://www.npmjs.org/package/jsonc-parser)
|
5 | [![NPM Downloads](https://img.shields.io/npm/dm/jsonc-parser.svg)](https://npmjs.org/package/jsonc-parser)
|
6 | [![Build Status](https://travis-ci.org/Microsoft/node-jsonc-parser.svg?branch=master)](https://travis-ci.org/Microsoft/node-jsonc-parser)
|
7 |
|
8 | Why?
|
9 | ----
|
10 | 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.
|
11 | - the *scanner* tokenizes the input string into tokens and token offsets
|
12 | - the *parse* function evaluates the JavaScipt object represented by JSON string in a fault tolerant fashion.
|
13 | - the *visit* function implements a 'SAX' style parser with callbacks for the encountered properties and values.
|
14 | - the *getLocation* API returns a path that describes the location of a given offset in a given file.
|
15 |
|
16 | Installation
|
17 | ------------
|
18 |
|
19 | npm install --save jsonc-parser
|
20 |
|
21 |
|
22 | API
|
23 | ---
|
24 |
|
25 | ### Scanner:
|
26 | ```typescript
|
27 |
|
28 | /**
|
29 | * Creates a JSON scanner on the given text.
|
30 | * If ignoreTrivia is set, whitespaces or comments are ignored.
|
31 | */
|
32 | export function createScanner(text:string, ignoreTrivia:boolean = false):JSONScanner;
|
33 |
|
34 | /**
|
35 | * The scanner object, representing a JSON scanner at a position in the input string.
|
36 | */
|
37 | export interface JSONScanner {
|
38 | /**
|
39 | * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.
|
40 | */
|
41 | setPosition(pos: number): any;
|
42 | /**
|
43 | * Read the next token. Returns the tolen code.
|
44 | */
|
45 | scan(): SyntaxKind;
|
46 | /**
|
47 | * Returns the current scan position, which is after the last read token.
|
48 | */
|
49 | getPosition(): number;
|
50 | /**
|
51 | * Returns the last read token.
|
52 | */
|
53 | getToken(): SyntaxKind;
|
54 | /**
|
55 | * 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.
|
56 | */
|
57 | getTokenValue(): string;
|
58 | /**
|
59 | * The start offset of the last read token.
|
60 | */
|
61 | getTokenOffset(): number;
|
62 | /**
|
63 | * The length of the last read token.
|
64 | */
|
65 | getTokenLength(): number;
|
66 | /**
|
67 | * An error code of the last scan.
|
68 | */
|
69 | getTokenError(): ScanError;
|
70 | }
|
71 | ```
|
72 |
|
73 | ### Parser:
|
74 | ```typescript
|
75 |
|
76 | export interface ParseOptions {
|
77 | disallowComments?: boolean;
|
78 | }
|
79 | /**
|
80 | * 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.
|
81 | * Therefore always check the errors list to find out if the input was valid.
|
82 | */
|
83 | export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
|
84 |
|
85 | /**
|
86 | * Parses the given text and invokes the visitor functions for each object, array and literal reached.
|
87 | */
|
88 | export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
|
89 |
|
90 | export interface JSONVisitor {
|
91 | /**
|
92 | * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
|
93 | */
|
94 | onObjectBegin?: (offset: number, length: number) => void;
|
95 | /**
|
96 | * Invoked when a property is encountered. The offset and length represent the location of the property name.
|
97 | */
|
98 | onObjectProperty?: (property: string, offset: number, length: number) => void;
|
99 | /**
|
100 | * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
|
101 | */
|
102 | onObjectEnd?: (offset: number, length: number) => void;
|
103 | /**
|
104 | * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
|
105 | */
|
106 | onArrayBegin?: (offset: number, length: number) => void;
|
107 | /**
|
108 | * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
|
109 | */
|
110 | onArrayEnd?: (offset: number, length: number) => void;
|
111 | /**
|
112 | * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
|
113 | */
|
114 | onLiteralValue?: (value: any, offset: number, length: number) => void;
|
115 | /**
|
116 | * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
|
117 | */
|
118 | onSeparator?: (charcter: string, offset: number, length: number) => void;
|
119 | /**
|
120 | * Invoked on an error.
|
121 | */
|
122 | onError?: (error: ParseErrorCode, offset: number, length: number) => void;
|
123 | }
|
124 |
|
125 | /**
|
126 | * 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.
|
127 | */
|
128 | export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node;
|
129 |
|
130 | export declare type NodeType = "object" | "array" | "property" | "string" | "number" | "boolean" | "null";
|
131 | export interface Node {
|
132 | type: NodeType;
|
133 | value?: any;
|
134 | offset: number;
|
135 | length: number;
|
136 | columnOffset?: number;
|
137 | parent?: Node;
|
138 | children?: Node[];
|
139 | }
|
140 |
|
141 | ```
|
142 |
|
143 | ### Utilities:
|
144 | ```typescript
|
145 | /**
|
146 | * Takes JSON with JavaScript-style comments and remove
|
147 | * them. Optionally replaces every none-newline character
|
148 | * of comments with a replaceCharacter
|
149 | */
|
150 | export declare function stripComments(text: string, replaceCh?: string): string;
|
151 |
|
152 | /**
|
153 | * 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.
|
154 | */
|
155 | export declare function getLocation(text: string, position: number): Location;
|
156 |
|
157 | export declare type Segment = string | number;
|
158 | export interface Location {
|
159 | /**
|
160 | * The previous property key or literal value (string, number, boolean or null) or undefined.
|
161 | */
|
162 | previousNode?: Node;
|
163 | /**
|
164 | * The path describing the location in the JSON document. The path consists of a sequence strings
|
165 | * representing an object property or numbers for array indices.
|
166 | */
|
167 | path: Segment[];
|
168 | /**
|
169 | * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
|
170 | * '*' will match a single segment, of any property name or index.
|
171 | * '**' will match a sequece of segments or no segment, of any property name or index.
|
172 | */
|
173 | matches: (patterns: Segment[]) => boolean;
|
174 | /**
|
175 | * If set, the location's offset is at a property key.
|
176 | */
|
177 | isAtPropertyKey: boolean;
|
178 | }
|
179 |
|
180 |
|
181 |
|
182 | ```
|
183 |
|
184 |
|
185 | License
|
186 | -------
|
187 |
|
188 | (MIT License)
|
189 |
|
190 | Copyright 2016, Microsoft |
\ | No newline at end of file |