jsonc-parser

What is jsonc-parser?

The jsonc-parser npm package is used for parsing and manipulating JSONC (JSON with Comments) files. It provides functionality to parse JSONC content, extract errors, and visit nodes within the JSONC structure. It also allows for modifications and formatting of the JSONC content.

What are jsonc-parser's main functionalities?

Parsing JSONC

This feature allows you to parse JSONC content, which includes comments, without stripping them out. It can handle both single-line and multi-line comments.

{"text": "// This is a comment\n{\"key\": \"value\"}"}

Extracting Errors

jsonc-parser can extract errors from JSONC content, which is useful for validating and providing feedback on the correctness of the JSONC.

{"text": "{\"key\": \"value\", // invalid comment\n}"}

Visiting Nodes

This feature allows you to visit nodes within the JSONC structure and perform operations or analysis on them, such as logging property names.

{"text": "{\"key\": {\"nestedKey\": \"nestedValue\"}}", "visitor": {"onObjectProperty": (property, visitContext) => { console.log(property); }}}

Modifying JSONC

jsonc-parser provides functionality to modify the JSONC content by specifying the path to the node and the new value.

{"text": "{\"key\": \"value\"}", "modifications": [{"path": [\"key\"], "value": \"newValue\"}]}

Formatting JSONC

This feature allows you to format JSONC content according to specified formatting options, such as using spaces or tabs for indentation.

{"text": "{\"key\":\"value\"}", "options": {"insertSpaces": true, "tabSize": 2}}

Other packages similar to jsonc-parser

strip-json-comments

This package is used to strip comments from JSON or JSONC content, allowing you to parse it with standard JSON parsers. It differs from jsonc-parser as it does not retain comments and does not provide functionality for visiting nodes or extracting errors.

comment-json

comment-json is similar to jsonc-parser in that it allows for parsing and stringifying JSONC. However, its API and feature set may differ, and it may not have the same focus on providing detailed error information or node visiting capabilities.

README

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:

/**
 * Creates a JSON scanner on the given text.
 * If ignoreTrivia is set, whitespaces or comments are ignored.
 */
export function createScanner(text:string, ignoreTrivia:boolean = false):JSONScanner;
    
/**
 * The scanner object, representing a JSON scanner at a position in the input string.
 */
export interface JSONScanner {
    /**
     * Sets the scan position to a new offset. A call to 'scan' is needed to get the first token.
     */
    setPosition(pos: number): any;
    /**
     * Read the next token. Returns the token code.
     */
    scan(): SyntaxKind;
    /**
     * Returns the current scan position, which is after the last read token.
     */
    getPosition(): number;
    /**
     * Returns the last read token.
     */
    getToken(): SyntaxKind;
    /**
     * 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.
     */
    getTokenValue(): string;
    /**
     * The start offset of the last read token.
     */
    getTokenOffset(): number;
    /**
     * The length of the last read token.
     */
    getTokenLength(): number;
    /**
     * An error code of the last scan.
     */
    getTokenError(): ScanError;
}

Parser:

export interface ParseOptions {
    disallowComments?: boolean;
}
/**
 * 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.
 * Therefore always check the errors list to find out if the input was valid.
 */
export declare function parse(text: string, errors?: {error: ParseErrorCode;}[], options?: ParseOptions): any;

/**
 * Parses the given text and invokes the visitor functions for each object, array and literal reached.
 */
export declare function visit(text: string, visitor: JSONVisitor, options?: ParseOptions): any;

export interface JSONVisitor {
    /**
     * Invoked when an open brace is encountered and an object is started. The offset and length represent the location of the open brace.
     */
    onObjectBegin?: (offset: number, length: number) => void;
    /**
     * Invoked when a property is encountered. The offset and length represent the location of the property name.
     */
    onObjectProperty?: (property: string, offset: number, length: number) => void;
    /**
     * Invoked when a closing brace is encountered and an object is completed. The offset and length represent the location of the closing brace.
     */
    onObjectEnd?: (offset: number, length: number) => void;
    /**
     * Invoked when an open bracket is encountered. The offset and length represent the location of the open bracket.
     */
    onArrayBegin?: (offset: number, length: number) => void;
    /**
     * Invoked when a closing bracket is encountered. The offset and length represent the location of the closing bracket.
     */
    onArrayEnd?: (offset: number, length: number) => void;
    /**
     * Invoked when a literal value is encountered. The offset and length represent the location of the literal value.
     */
    onLiteralValue?: (value: any, offset: number, length: number) => void;
    /**
     * Invoked when a comma or colon separator is encountered. The offset and length represent the location of the separator.
     */
    onSeparator?: (charcter: string, offset: number, length: number) => void;
	/**
	 * When comments are allowed, invoked when a line or block comment is encountered. The offset and length represent the location of the comment.
	 */
	onComment?: (offset: number, length: number) => void;    
    /**
     * Invoked on an error.
     */
    onError?: (error: ParseErrorCode, offset: number, length: number) => void;
}

/**
 * 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.
 */
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:

/**
 * Takes JSON with JavaScript-style comments and remove
 * them. Optionally replaces every none-newline character
 * of comments with a replaceCharacter
 */
export declare function stripComments(text: string, replaceCh?: string): string;

/**
 * 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.
 */
export declare function getLocation(text: string, position: number): Location;

export declare type Segment = string | number;
export interface Location {
    /**
     * The previous property key or literal value (string, number, boolean or null) or undefined.
     */
    previousNode?: Node;
    /**
     * The path describing the location in the JSON document. The path consists of a sequence strings
     * representing an object property or numbers for array indices.
     */
    path: Segment[];
    /**
     * Matches the locations path against a pattern consisting of strings (for properties) and numbers (for array indices).
     * '*' will match a single segment, of any property name or index.
     * '**' will match a sequece of segments or no segment, of any property name or index.
     */
    matches: (patterns: Segment[]) => boolean;
    /**
     * If set, the location's offset is at a property key.
     */
    isAtPropertyKey: boolean;
}

/**
 * Finds the node at the given path in a JSON DOM.
 */
export function findNodeAtLocation(root: Node, path: JSONPath): Node | undefined;

/**
 * Finds the most inner node at the given offset. If includeRightBound is set, also finds nodes that end at the given offset.
 */
export function findNodeAtOffset(root: Node, offset: number, includeRightBound?: boolean) : Node | undefined;

/**
 * Gets the JSON path of the given JSON DOM node
 */
export function getNodePath(node: Node) : JSONPath;

/**
 * Evaluates the JavaScript object of the given JSON DOM node 
 */
export function getNodeValue(node: Node): any;

/**
 * Computes the edits needed to format a JSON document. 
 * 
 * @param documentText The input text 
 * @param range The range to format or `undefined` to format the full content
 * @param options The formatting options
 * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
 * 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
 * text in the original document. However, multiple edits can have
 * 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.
 * To apply edits to an input, you can use `applyEdits`
 */
export function format(documentText: string, range: Range, options: FormattingOptions): Edit[];


/**
 * Computes the edits needed to modify a value in the JSON document.
 * 
 * @param documentText The input text 
 * @param path The path of the value to change. The path represents either to the document root, a property or an array item.
 * If the path points to an non-existing property or item, it will be created. 
 * @param value The new value for the specified property or item. If the value is undefined,
 * the property or item will be removed.
 * @param options Options
 * @returns A list of edit operations describing the formatting changes to the original document. Edits can be either inserts, replacements or
 * 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
 * text in the original document. However, multiple edits can have
 * 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.
 * To apply edits to an input, you can use `applyEdits`
 */
export function modify(text: string, path: JSONPath, value: any, options: ModificationOptions): Edit[];

/**
 * Applies edits to a input string.
 */
export function applyEdits(text: string, edits: Edit[]): string;

/**
 * Represents a text modification
 */
export interface Edit {
	/**
	 * The start offset of the modification.
	 */
	offset: number;
	/**
	 * The length of the modification. Must not be negative. Empty length represents an *insert*.
	 */
	length: number;
	/**
	 * The new content. Empty content represents a *remove*.
	 */
	content: string;
}

/**
 * A text range in the document
*/
export interface Range {
	/**
	 * The start offset of the range. 
	 */
	offset: number;
	/**
	 * The length of the range. Must not be negative.  
	 */
	length: number;
}

export interface FormattingOptions {
	/**
	 * If indentation is based on spaces (`insertSpaces` = true), then what is the number of spaces that make an indent?
	 */
	tabSize: number;
	/**
	 * Is indentation based on spaces?
	 */
	insertSpaces: boolean;
	/**
	 * The default 'end of line' character
	 */
	eol: string;
}

License

(MIT License)

Copyright 2018, Microsoft