code-block-pro / build / shiki / node_modules / jsonc-parser / README.md

README.md in Code Block Pro – Beautiful Syntax Highlighting 1.13.0, at build/shiki/node_modules/jsonc-parser/README.md

362 lines 13.7 KB

Raw Download Zip

1	# jsonc-parser
2	Scanner and parser for JSON with comments.
3
4	[](https://www.npmjs.org/package/jsonc-parser![npm Package](https://img.shields.io/npm/v/jsonc-parser.svg?style=flat-square)](https://www.npmjs.org/package/jsonc-parser](https://www.npmjs.org/package/jsonc-parser)
5	[](https://npmjs.org/package/jsonc-parser![NPM Downloads](https://img.shields.io/npm/dm/jsonc-parser.svg)](https://npmjs.org/package/jsonc-parser](https://npmjs.org/package/jsonc-parser)
6	[](https://travis-ci.org/Microsoft/node-jsonc-parser![Build Status](https://travis-ci.org/microsoft/node-jsonc-parser.svg?branch=main)](https://travis-ci.org/Microsoft/node-jsonc-parser](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 visit function implements a 'SAX' style parser with callbacks for the encountered properties and values.
13	- the parseTree function computes a hierarchical DOM with offsets representing the encountered properties and values.
14	- the parse function evaluates the JavaScript object represented by JSON string in a fault tolerant fashion.
15	- the getLocation API returns a location object that describes the property or value located at a given offset in a JSON document.
16	- the findNodeAtLocation API finds the node at a given location path in a JSON DOM.
17	- the format API computes edits to format a JSON document.
18	- the modify API computes edits to insert, remove or replace a property or value in a JSON document.
19	- the applyEdits API applies edits to a document.
20
21	Installation
22	------------
23
24	```
25	npm install --save jsonc-parser
26	```
27
28	API
29	---
30
31	### Scanner:
32	```typescript
33
34	/**
35	* Creates a JSON scanner on the given text.
36	* If ignoreTrivia is set, whitespaces or comments are ignored.
37	*/
38	export function createScanner(text: string, ignoreTrivia: boolean = false): JSONScanner;
39
40	/**
41	* The scanner object, representing a JSON scanner at a position in the input string.
42	*/
43	export interface JSONScanner {
44	/**
45	* Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.
46	*/
47	setPosition(pos: number): any;
48	/**
49	* Read the next token. Returns the token code.
50	*/
51	scan(): SyntaxKind;
52	/**
53	* Returns the zero-based current scan position, which is after the last read token.
54	*/
55	getPosition(): number;
56	/**
57	* Returns the last read token.
58	*/
59	getToken(): SyntaxKind;
60	/**
61	* 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.
62	*/
63	getTokenValue(): string;
64	/**
65	* The zero-based start offset of the last read token.
66	*/
67	getTokenOffset(): number;
68	/**
69	* The length of the last read token.
70	*/
71	getTokenLength(): number;
72	/**
73	* The zero-based start line number of the last read token.
74	*/
75	getTokenStartLine(): number;
76	/**
77	* The zero-based start character (column) of the last read token.
78	*/
79	getTokenStartCharacter(): number;
80	/**
81	* An error code of the last scan.
82	*/
83	getTokenError(): ScanError;
84	}
85	```
86
87	### Parser:
88	```typescript
89
90	export interface ParseOptions {
91	disallowComments?: boolean;
92	allowTrailingComma?: boolean;
93	allowEmptyContent?: boolean;
94	}
95	/**
96	* 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.
97	* Therefore always check the errors list to find out if the input was valid.
98	*/
99	export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
100
101	/**
102	* Parses the given text and invokes the visitor functions for each object, array and literal reached.
103	*/
104	export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
105
106	/**
107	* Visitor called by {@linkcode visit} when parsing JSON.
108	*
109	* The visitor functions have the following common parameters:
110	* - `offset`: Global offset within the JSON document, starting at 0
111	* - `startLine`: Line number, starting at 0
112	* - `startCharacter`: Start character (column) within the current line, starting at 0
113	*
114	* Additionally some functions have a `pathSupplier` parameter which can be used to obtain the
115	* current `JSONPath` within the document.
116	*/
117	export interface JSONVisitor {
118	/**
119	* Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
120	*/
121	onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
122
123	/**
124	* Invoked when a property is encountered. The offset and length represent the location of the property name.
125	* The `JSONPath` created by the `pathSupplier` refers to the enclosing JSON object, it does not include the
126	* property name yet.
127	*/
128	onObjectProperty?: (property: string, offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
129	/**
130	* Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
131	*/
132	onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
133	/**
134	* Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
135	*/
136	onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
137	/**
138	* Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
139	*/
140	onArrayEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
141	/**
142	* Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
143	*/
144	onLiteralValue?: (value: any, offset: number, length: number, startLine: number, startCharacter: number, pathSupplier: () => JSONPath) => void;
145	/**
146	* Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
147	*/
148	onSeparator?: (character: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
149	/**
150	* When comments are allowed, invoked when a line or block comment is encountered. The offset and length represent the location of the comment.
151	*/
152	onComment?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
153	/**
154	* Invoked on an error.
155	*/
156	onError?: (error: ParseErrorCode, offset: number, length: number, startLine: number, startCharacter: number) => void;
157	}
158
159	/**
160	* 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.
161	*/
162	export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node \| undefined;
163
164	export declare type NodeType = "object" \| "array" \| "property" \| "string" \| "number" \| "boolean" \| "null";
165	export interface Node {
166	type: NodeType;
167	value?: any;
168	offset: number;
169	length: number;
170	colonOffset?: number;
171	parent?: Node;
172	children?: Node[];
173	}
174
175	```
176
177	### Utilities:
178	```typescript
179	/**
180	* Takes JSON with JavaScript-style comments and remove
181	* them. Optionally replaces every none-newline character
182	* of comments with a replaceCharacter
183	*/
184	export declare function stripComments(text: string, replaceCh?: string): string;
185
186	/**
187	* 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.
188	*/
189	export declare function getLocation(text: string, position: number): Location;
190
191	/**
192	* A {@linkcode JSONPath} segment. Either a string representing an object property name
193	* or a number (starting at 0) for array indices.
194	*/
195	export declare type Segment = string \| number;
196	export declare type JSONPath = Segment[];
197	export interface Location {
198	/**
199	* The previous property key or literal value (string, number, boolean or null) or undefined.
200	*/
201	previousNode?: Node;
202	/**
203	* The path describing the location in the JSON document. The path consists of a sequence strings
204	* representing an object property or numbers for array indices.
205	*/
206	path: JSONPath;
207	/**
208	* Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
209	* '*' will match a single segment, of any property name or index.
210	* '**' will match a sequence of segments or no segment, of any property name or index.
211	*/
212	matches: (patterns: JSONPath) => boolean;
213	/**
214	* If set, the location's offset is at a property key.
215	*/
216	isAtPropertyKey: boolean;
217	}
218
219	/**
220	* Finds the node at the given path in a JSON DOM.
221	*/
222	export function findNodeAtLocation(root: Node, path: JSONPath): Node \| undefined;
223
224	/**
225	* Finds the most inner node at the given offset. If includeRightBound is set, also finds nodes that end at the given offset.
226	*/
227	export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node \| undefined;
228
229	/**
230	* Gets the JSON path of the given JSON DOM node
231	*/
232	export function getNodePath(node: Node): JSONPath;
233
234	/**
235	* Evaluates the JavaScript object of the given JSON DOM node
236	*/
237	export function getNodeValue(node: Node): any;
238
239	/**
240	* Computes the edit operations needed to format a JSON document.
241	*
242	* @param documentText The input text
243	* @param range The range to format or `undefined` to format the full content
244	* @param options The formatting options
245	* @returns The edit operations describing the formatting changes to the original document following the format described in {@linkcode EditResult}.
246	* To apply the edit operations to the input, use {@linkcode applyEdits}.
247	*/
248	export function format(documentText: string, range: Range, options: FormattingOptions): EditResult;
249
250	/**
251	* Computes the edit operations needed to modify a value in the JSON document.
252	*
253	* @param documentText The input text
254	* @param path The path of the value to change. The path represents either to the document root, a property or an array item.
255	* If the path points to an non-existing property or item, it will be created.
256	* @param value The new value for the specified property or item. If the value is undefined,
257	* the property or item will be removed.
258	* @param options Options
259	* @returns The edit operations describing the changes to the original document, following the format described in {@linkcode EditResult}.
260	* To apply the edit operations to the input, use {@linkcode applyEdits}.
261	*/
262	export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): EditResult;
263
264	/**
265	* Applies edits to an input string.
266	* @param text The input text
267	* @param edits Edit operations following the format described in {@linkcode EditResult}.
268	* @returns The text with the applied edits.
269	* @throws An error if the edit operations are not well-formed as described in {@linkcode EditResult}.
270	*/
271	export function applyEdits(text: string, edits: EditResult): string;
272
273	/**
274	* An edit result describes a textual edit operation. It is the result of a {@linkcode format} and {@linkcode modify} operation.
275	* It consist of one or more edits describing insertions, replacements or removals of text segments.
276	* * The offsets of the edits refer to the original state of the document.
277	* * No two edits change or remove the same range of text in the original document.
278	* * Multiple edits can have the same offset if they are multiple inserts, or an insert followed by a remove or replace.
279	* * The order in the array defines which edit is applied first.
280	* To apply an edit result use {@linkcode applyEdits}.
281	* In general multiple EditResults must not be concatenated because they might impact each other, producing incorrect or malformed JSON data.
282	*/
283	export type EditResult = Edit[];
284
285	/**
286	* Represents a text modification
287	*/
288	export interface Edit {
289	/**
290	* The start offset of the modification.
291	*/
292	offset: number;
293	/**
294	* The length of the modification. Must not be negative. Empty length represents an insert.
295	*/
296	length: number;
297	/**
298	* The new content. Empty content represents a remove.
299	*/
300	content: string;
301	}
302
303	/**
304	* A text range in the document
305	*/
306	export interface Range {
307	/**
308	* The start offset of the range.
309	*/
310	offset: number;
311	/**
312	* The length of the range. Must not be negative.
313	*/
314	length: number;
315	}
316
317	/**
318	* Options used by {@linkcode format} when computing the formatting edit operations
319	*/
320	export interface FormattingOptions {
321	/**
322	* If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?
323	*/
324	tabSize: number;
325	/**
326	* Is indentation based on spaces?
327	*/
328	insertSpaces: boolean;
329	/**
330	* The default 'end of line' character
331	*/
332	eol: string;
333	}
334
335	/**
336	* Options used by {@linkcode modify} when computing the modification edit operations
337	*/
338	export interface ModificationOptions {
339	/**
340	* Formatting options. If undefined, the newly inserted code will be inserted unformatted.
341	*/
342	formattingOptions?: FormattingOptions;
343	/**
344	* Default false. If `JSONPath` refers to an index of an array and `isArrayInsertion` is `true`, then
345	* {@linkcode modify} will insert a new item at that location instead of overwriting its contents.
346	*/
347	isArrayInsertion?: boolean;
348	/**
349	* Optional function to define the insertion index given an existing list of properties.
350	*/
351	getInsertionIndex?: (properties: string[]) => number;
352	}
353	```
354
355
356	License
357	-------
358
359	(MIT License)
360
361	Copyright 2018, Microsoft
362