jsonc-pragma

A simple, yet powerful pragma analyzer and utility library for JSON with Comments

Installation

$ yarn add jsonc-pragma

or

$ npm install jsonc-pragma

Usage

scan()

@param contents

Type: string | Buffer

This is the contents of the JSON document.

@example

import { scan } from "jsonc-pragma";
 
const contents = `{
    // @foo bar=5
    "example": "...",
 
    // @baz foo=test bar=abc
    "object": {
        "example": "..."
    }
}`;
 
scan(contents);
 
/* Returns:
 
[
    {
        start: 2,
        end: 2,
        args: { bar: "5" },
        name: "foo"
    },
    {
        start: 5,
        end: 7,
        args: { foo: "test", bar: "abc" },
        name: "baz"
    }
] 
 
*/

@returns

Array<ISection>

comment()

@param contents

Type: string | Buffer

This is the contents of the JSON document.

@param selector

OPTIONAL

Type: (section: ISection) => boolean

This is a function that receives a section and determines whether that section should be commented by returning true (comment) or false (don't comment).

If omitted, all sections will be commented.

@example

import { comment } from "jsonc-pragma";
 
const contents = `{
    // @foo bar=5
    "example": "...",
 
    // @foo bar=7
    "object": {
        "example": "..."
    },
 
    // @baz bar=7
    "notCommented": "..."
}`;
 
comment(
    contents,
    section => section.name === "foo" && Number(section.args.bar) > 6
);
 
/* Returns:
 
`{
    // @foo bar=5
    "example": "...",
 
    // @foo bar=7
    // "object": {
    //   "example": "..."
    // },
 
    // @baz bar=7
    "notCommented": "..."
}`
 
*/

@returns string

uncomment()

@param contents

Type: string | Buffer

This is the contents of the JSON document.

@param selector

OPTIONAL

Type: (section: ISection) => boolean

This is a function that receives a section and determines whether that section should be uncommented by returning true (uncomment) or false (don't uncomment).

If omitted, all sections will be uncommented.

@example

import { uncomment } from "jsonc-pragma";
 
const contents = `{
    // @foo bar=5
    // "example": "...",
 
    // @foo bar=7
    // "object": {
    //   "example": "..."
    // }
}`;
 
uncomment(contents, section => Number(section.args.bar) > 6);
 
/* Returns:
 
`{
    // @foo bar=5
    // "example": "...",
 
    // @foo bar=7
    "object": {
        "example": "..."
    }
}`
 
*/

@returns string

@typedef

interface ISection {
    start: number;
    end: number;
    args: { [key: string]: string | undefined };
    name: string;
}