example/jsonptr/README.md

# jsonptr

This program has two goals:

1. be a production-quality [JSON](https://json.org/) formatter (pretty-printer)
   that supports the JSON Pointer (RFC 6901) query syntax.
2. demonstrate how to use [Wuffs' low-level JSON parsing C
   API](https://nigeltao.github.io/blog/2020/jsonptr.html). An alternative,
   higher-level C++ API is used in the sibling
   [example/jsonfindptrs](/example/jsonfindptrs) program.


## Building

It has no dependencies other than Wuffs.

    $ gcc -O3 jsonptr.cc -o jsonptr


## Example

    $ grep foo                ../../test/data/rfc-6901-json-pointer.json
       "foo": ["bar", "baz"],
    $ ./jsonptr -query=/foo/1 ../../test/data/rfc-6901-json-pointer.json
    "baz"

It also supports the JWCC ([JSON With Commas and
Comments](https://nigeltao.github.io/blog/2021/json-with-commas-comments.html))
syntax.

    $ echo '/* Note the commas. */[1,2,[30,31]]' | ./jsonptr -jwcc
    /* Note the commas. */
    [
        1,
        2,
        [
            30,
            31,
        ],
    ]


## Usage

    $ ./jsonptr -help
    Usage: jsonptr -flags input.json
    
    Flags:
        -c      -compact-output
        -d=NUM  -max-output-depth=NUM
        -q=STR  -query=STR
        -s=NUM  -spaces=NUM
        -t      -tabs
                -fail-if-unsandboxed
                -input-allow-comments
                -input-allow-extra-comma
                -input-allow-inf-nan-numbers
                -input-jwcc
                -jwcc
                -output-comments
                -output-extra-comma
                -output-inf-nan-numbers
                -strict-json-pointer-syntax
    
    The input.json filename is optional. If absent, it reads from stdin.
    
    ----
    
    jsonptr is a JSON formatter (pretty-printer) that supports the JSON
    Pointer (RFC 6901) query syntax. It reads UTF-8 JSON from stdin and
    writes canonicalized, formatted UTF-8 JSON to stdout.
    
    Canonicalized means that e.g. "abc\u000A\tx\u0177z" is re-written
    as "abc\n\txŷz". It does not sort object keys, nor does it reject
    duplicate keys. Canonicalization does not imply Unicode normalization.
    
    Formatted means that arrays' and objects' elements are indented, each
    on its own line. Configure this with the -c / -compact-output, -s=NUM /
    -spaces=NUM (for NUM ranging from 0 to 8) and -t / -tabs flags.
    
    The -input-allow-comments flag allows "/*slash-star*/" and
    "//slash-slash" C-style comments within JSON input. Such comments are
    stripped from the output unless -output-comments was also set.
    
    The -input-allow-extra-comma flag allows input like "[1,2,]", with a
    comma after the final element of a JSON list or dictionary.
    
    The -input-allow-inf-nan-numbers flag allows non-finite floating point
    numbers (infinities and not-a-numbers) within JSON input. This flag
    requires that -output-inf-nan-numbers also be set.
    
    The -output-comments flag copies any input comments to the output. It
    has no effect unless -input-allow-comments was also set. Comments look
    better after commas than before them, but a closing "]" or "}" can
    occur after arbitrarily many comments, so -output-comments also requires
    that one or both of -compact-output and -output-extra-comma be set.
    
    With -output-comments, consecutive blank lines collapse to a single
    blank line. Without that flag, all blank lines are removed.
    
    The -output-extra-comma flag writes output like "[1,2,]", with a comma
    after the final element of a JSON list or dictionary. Such commas are
    non-compliant with the JSON specification but many parsers accept them
    and they can produce simpler line-based diffs. This flag is ignored when
    -compact-output is set.
    
    Combining some of those flags results in speaking JWCC (JSON With Commas
    and Comments), not plain JSON. For convenience, the -input-jwcc or -jwcc
    flags enables the first two or all four of:
                -input-allow-comments
                -input-allow-extra-comma
                -output-comments
                -output-extra-comma
    
    ----
    
    The -q=STR or -query=STR flag gives an optional JSON Pointer query, to
    print a subset of the input. For example, given RFC 6901 section 5's
    sample input (https://tools.ietf.org/rfc/rfc6901.txt), this command:
        jsonptr -query=/foo/1 rfc-6901-json-pointer.json
    will print:
        "baz"
    
    An absent query is equivalent to the empty query, which identifies the
    entire input (the root value). Unlike a file system, the "/" query
    does not identify the root. Instead, "" is the root and "/" is the
    child (the value in a key-value pair) of the root whose key is the empty
    string. Similarly, "/xyz" and "/xyz/" are two different nodes.
    
    If the query found a valid JSON value, this program will return a zero
    exit code even if the rest of the input isn't valid JSON. If the query
    did not find a value, or found an invalid one, this program returns a
    non-zero exit code, but may still print partial output to stdout.
    
    The JSON specification (https://json.org/) permits implementations that
    allow duplicate keys, as this one does. This JSON Pointer implementation
    is also greedy, following the first match for each fragment without
    back-tracking. For example, the "/foo/bar" query will fail if the root
    object has multiple "foo" children but the first one doesn't have a
    "bar" child, even if later ones do.
    
    The -strict-json-pointer-syntax flag restricts the -query=STR string to
    exactly RFC 6901, with only two escape sequences: "~0" and "~1" for
    "~" and "/". Without this flag, this program also lets "~n",
    "~r" and "~t" escape the New Line, Carriage Return and Horizontal
    Tab ASCII control characters, which can work better with line oriented
    (and tab separated) Unix tools that assume exactly one record (e.g. one
    JSON Pointer string) per line.
    
    ----
    
    The -d=NUM or -max-output-depth=NUM flag gives the maximum (inclusive)
    output depth. JSON containers ([] arrays and {} objects) can hold other
    containers. When this flag is set, containers at depth NUM are replaced
    with "[…]" or "{…}". A bare -d or -max-output-depth is equivalent to
    -d=1. The flag's absence is equivalent to an unlimited output depth.
    
    The -max-output-depth flag only affects the program's output. It doesn't
    affect whether or not the input is considered valid JSON. The JSON
    specification permits implementations to set their own maximum input
    depth. This JSON implementation sets it to 1024.
    
    Depth is measured in terms of nested containers. It is unaffected by the
    number of spaces or tabs used to indent.
    
    When both -max-output-depth and -query are set, the output depth is
    measured from when the query resolves, not from the input root. The
    input depth (measured from the root) is still limited to 1024.
    
    ----
    
    The -fail-if-unsandboxed flag causes the program to exit if it does not
    self-impose a sandbox. On Linux, it self-imposes a SECCOMP_MODE_STRICT
    sandbox, regardless of whether this flag was set.