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 parse function evaluates the JavaScipt object represented by JSON string in a fault tolerant fashion.
• the visit function implements a 'SAX' style parser with callbacks for the encountered properties and values

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 tolen 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;
    /**
     * Invoked on an error.
     */
    onError?: (error: ParseErrorCode, offset: number, length: number) => void;
}

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 a location is either a property names or an array accessors.
 */
export declare function getLocation(text: string, position: number): Location;

License

(MIT License)

Copyright 2016, Microsoft