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:
export function createScanner(text:string, ignoreTrivia:boolean = false):JSONScanner;
export interface JSONScanner {
setPosition(pos: number): any;
scan(): SyntaxKind;
getPosition(): number;
getToken(): SyntaxKind;
getTokenValue(): string;
getTokenOffset(): number;
getTokenLength(): number;
getTokenStartLine(): number;
getTokenStartCharacter(): number;
getTokenError(): ScanError;
}
Parser:
export interface ParseOptions {
disallowComments?: boolean;
}
export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;
export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;
export interface JSONVisitor {
onObjectBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
onObjectProperty?: (property: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
onObjectEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
onArrayBegin?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
onArrayEnd?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
onLiteralValue?: (value: any, offset: number, length: number, startLine: number, startCharacter: number) => void;
onSeparator?: (character: string, offset: number, length: number, startLine: number, startCharacter: number) => void;
onComment?: (offset: number, length: number, startLine: number, startCharacter: number) => void;
onError?: (error: ParseErrorCode, offset: number, length: number, startLine: number, startCharacter: number) => void;
}
export declare function parseTree(text: string, errors?: ParseError[], options?: ParseOptions): Node;
export declare type NodeType = "object" | "array" | "property" | "string" | "number" | "boolean" | "null";
export interface Node {
type: NodeType;
value?: any;
offset: number;
length: number;
colonOffset?: number;
parent?: Node;
children?: Node[];
}
Utilities:
export declare function stripComments(text: string, replaceCh?: string): string;
export declare function getLocation(text: string, position: number): Location;
export declare type Segment = string | number;
export interface Location {
previousNode?: Node;
path: Segment[];
matches: (patterns: Segment[]) => boolean;
isAtPropertyKey: boolean;
}
export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;
export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node | undefined;
export function getNodePath(node: Node) : JSONPath;
export function getNodeValue(node: Node): any;
export function format(documentText: string, range: Range, options: FormattingOptions): Edit[];
export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): Edit[];
export function applyEdits(text: string, edits: Edit[]): string;
export interface Edit {
offset: number;
length: number;
content: string;
}
export interface Range {
offset: number;
length: number;
}
export interface FormattingOptions {
tabSize: number;
insertSpaces: boolean;
eol: string;
}
License
(MIT License)
Copyright 2018, Microsoft