.config/coc/extensions/node_modules/coc-json/node_modules/jsonc-parser/README.md

   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 *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     npm install --save jsonc-parser
  25
  26
  27 API
  28 ---
  29
  30 ### Scanner:
  31 ```typescript
  32
  33 /**
  34  * Creates a JSON scanner on the given text.
  35  * If ignoreTrivia is set, whitespaces or comments are ignored.
  36  */
  37 export function createScanner(text:string, ignoreTrivia:boolean = false):JSONScanner;
  38
  39 /**
  40  * The scanner object, representing a JSON scanner at a position in the input string.
  41  */
  42 export interface JSONScanner {
  43     /**
  44      * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.
  45      */
  46     setPosition(pos: number): any;
  47     /**
  48      * Read the next token. Returns the token code.
  49      */
  50     scan(): SyntaxKind;
  51     /**
  52      * Returns the current scan position, which is after the last read token.
  53      */
  54     getPosition(): number;
  55     /**
  56      * Returns the last read token.
  57      */
  58     getToken(): SyntaxKind;
  59     /**
  60      * 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.
  61      */
  62     getTokenValue(): string;
  63     /**
  64      * The start offset of the last read token.
  65      */
  66     getTokenOffset(): number;
  67     /**
  68      * The length of the last read token.
  69      */
  70     getTokenLength(): number;
  71     /**
  72      * The zero-based start line number of the last read token.
  73      */
  74     getTokenStartLine(): number;
  75     /**
  76      * The zero-based start character (column) of the last read token.
  77      */
  78     getTokenStartCharacter(): number;
  79     /**
  80      * An error code of the last scan.
  81      */
  82     getTokenError(): ScanError;
  83 }
  84 ```
  85
  86 ### Parser:
  87 ```typescript
  88
  89 export interface ParseOptions {
  90     disallowComments?: boolean;
  91 }
  92 /**
  93  * 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.
  94  * Therefore always check the errors list to find out if the input was valid.
  95  */
  96 export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
  97
  98 /**
  99  * Parses the given text and invokes the visitor functions for each object, array and literal reached.
 100  */
 101 export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
 102
 103 export interface JSONVisitor {
 104     /**
 105      * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
 106      */
 107     onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
 108     /**
 109      * Invoked when a property is encountered. The offset and length represent the location of the property name.
 110      */
 111     onObjectProperty?: (property: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
 112     /**
 113      * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
 114      */
 115     onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
 116     /**
 117      * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
 118      */
 119     onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
 120     /**
 121      * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
 122      */
 123     onArrayEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
 124     /**
 125      * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
 126      */
 127     onLiteralValue?: (value: any, offset: number, length: number, startLine: number, startCharacter: number) => void;
 128     /**
 129      * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
 130      */
 131     onSeparator?: (character: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
 132     /**
 133      * When comments are allowed, invoked when a line or block comment is encountered. The offset and length represent the location of the comment.
 134      */
 135     onComment?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
 136     /**
 137      * Invoked on an error.
 138      */
 139     onError?: (error: ParseErrorCode, offset: number, length: number, startLine: number, startCharacter: number) => void;
 140 }
 141
 142 /**
 143  * 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.
 144  */
 145 export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node | undefined;
 146
 147 export declare type NodeType = "object" | "array" | "property" | "string" | "number" | "boolean" | "null";
 148 export interface Node {
 149     type: NodeType;
 150     value?: any;
 151     offset: number;
 152     length: number;
 153     colonOffset?: number;
 154     parent?: Node;
 155     children?: Node[];
 156 }
 157
 158 ```
 159
 160 ### Utilities:
 161 ```typescript
 162 /**
 163  * Takes JSON with JavaScript-style comments and remove
 164  * them. Optionally replaces every none-newline character
 165  * of comments with a replaceCharacter
 166  */
 167 export declare function stripComments(text: string, replaceCh?: string): string;
 168
 169 /**
 170  * 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.
 171  */
 172 export declare function getLocation(text: string, position: number): Location;
 173
 174 export declare type Segment = string | number;
 175 export interface Location {
 176     /**
 177      * The previous property key or literal value (string, number, boolean or null) or undefined.
 178      */
 179     previousNode?: Node;
 180     /**
 181      * The path describing the location in the JSON document. The path consists of a sequence strings
 182      * representing an object property or numbers for array indices.
 183      */
 184     path: Segment[];
 185     /**
 186      * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
 187      * '*' will match a single segment, of any property name or index.
 188      * '**' will match a sequece of segments or no segment, of any property name or index.
 189      */
 190     matches: (patterns: Segment[]) => boolean;
 191     /**
 192      * If set, the location's offset is at a property key.
 193      */
 194     isAtPropertyKey: boolean;
 195 }
 196
 197 /**
 198  * Finds the node at the given path in a JSON DOM.
 199  */
 200 export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;
 201
 202 /**
 203  * Finds the most inner node at the given offset. If includeRightBound is set, also finds nodes that end at the given offset.
 204  */
 205 export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node | undefined;
 206
 207 /**
 208  * Gets the JSON path of the given JSON DOM node
 209  */
 210 export function getNodePath(node: Node) : JSONPath;
 211
 212 /**
 213  * Evaluates the JavaScript object of the given JSON DOM node
 214  */
 215 export function getNodeValue(node: Node): any;
 216
 217 /**
 218  * Computes the edits needed to format a JSON document.
 219  *
 220  * @param documentText The input text
 221  * @param range The range to format or `undefined` to format the full content
 222  * @param options The formatting options
 223  * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
 224  * 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
 225  * text in the original document. However, multiple edits can have
 226  * 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.
 227  * To apply edits to an input, you can use `applyEdits`
 228  */
 229 export function format(documentText: string, range: Range, options: FormattingOptions): Edit[];
 230
 231
 232 /**
 233  * Computes the edits needed to modify a value in the JSON document.
 234  *
 235  * @param documentText The input text
 236  * @param path The path of the value to change. The path represents either to the document root, a property or an array item.
 237  * If the path points to an non-existing property or item, it will be created.
 238  * @param value The new value for the specified property or item. If the value is undefined,
 239  * the property or item will be removed.
 240  * @param options Options
 241  * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
 242  * 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
 243  * text in the original document. However, multiple edits can have
 244  * 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.
 245  * To apply edits to an input, you can use `applyEdits`
 246  */
 247 export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): Edit[];
 248
 249 /**
 250  * Applies edits to a input string.
 251  */
 252 export function applyEdits(text: string, edits: Edit[]): string;
 253
 254 /**
 255  * Represents a text modification
 256  */
 257 export interface Edit {
 258         /**
 259          * The start offset of the modification.
 260          */
 261         offset: number;
 262         /**
 263          * The length of the modification. Must not be negative. Empty length represents an *insert*.
 264          */
 265         length: number;
 266         /**
 267          * The new content. Empty content represents a *remove*.
 268          */
 269         content: string;
 270 }
 271
 272 /**
 273  * A text range in the document
 274 */
 275 export interface Range {
 276         /**
 277          * The start offset of the range.
 278          */
 279         offset: number;
 280         /**
 281          * The length of the range. Must not be negative.
 282          */
 283         length: number;
 284 }
 285
 286 export interface FormattingOptions {
 287         /**
 288          * If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?
 289          */
 290         tabSize: number;
 291         /**
 292          * Is indentation based on spaces?
 293          */
 294         insertSpaces: boolean;
 295         /**
 296          * The default 'end of line' character
 297          */
 298         eol: string;
 299 }
 300
 301 ```
 302
 303
 304 License
 305 -------
 306
 307 (MIT License)
 308
 309 Copyright 2018, Microsoft