# orcus-json

## Help output

    Usage: orcus-json [options] FILE

    The FILE must specify the path to an existing file.

    Options:
      -h [ --help ]              Print this help.
      --mode arg                 Mode of operation. Select one of the following
                                 options: convert, lint, map, map-gen, structure,
                                 or subtree.
      --resolve-refs             Resolve JSON references to external files.
      -o [ --output ] arg        Output file path.
      -f [ --output-format ] arg Specify the format of output file.  Supported
                                 format types are:

                                   * XML (xml)
                                   * JSON (json)
                                   * YAML (yaml)
                                   * flat tree dump (check)
                                   * no output (none)
      -m [ --map ] arg           Path to a map file.  This parameter is only used
                                 in map mode, and it is required in that mode.
      -i [ --indent ] arg        Number of whitespace characters to use for one
                                 indent level.  This is applicable when the command
                                 generates output in JSON format.
      -p [ --path ] arg          JSONPath expression specifying the root of a
                                 subtree to extract.  It is only used in subtree
                                 mode.

## Supported modes

This command supports the following modes:

- convert

- lint

- map

- map-gen

- structure

- subtree

### convert

The `convert` mode is used to perform simple conversion of a JSON document to a different format that supports similar property-tree structure, such as XML and YAML.

You can also “convert” a JSON document to JSON as well. This may seem pointless, but may be useful when the source JSON document contains JSON references, and you want to resolve them by specifying the `--resolve-refs` option. Note, however, that this command currently only supports resolving references to external files via relative paths. References to other resource types may be added in the future.

### lint

The `lint` mode is used to reformat a JSON document optionally with a different indent level.

### map and map-gen

The `map` and `map-gen` modes are related, and are typically used together. The `map` mode is used to map a JSON document to a spreadsheet document model with a used-defined mapping rule, and the `map-gen` mode is used to auto-generate a mapping rule based on the content of the source JSON document.

Refer to the Mapping JSON to spreadsheet section on a detailed example of how to use the these modes to map a JSON document to a spreadsheet document model.

### structure

The `structure` mode analyses the overall structure of the source JSON document, and prints paths to all identified “leaf-node” values to standard output. Each path is expressed in a JSONPath-like format. Refer to the Mapping JSON to spreadsheet section for the detailed description of this format.

### subtree

the `subtree` mode allows you to extract a subtree structure from a JSON document using a JSONPath expression to specify the root of the subtree. Note that this mode only supports a limited subset of the full JSONPath expression syntax. Both the dot notation and the bracket notation are supported, as well as the wildcard symbol.

## Example usage

### Reformat JSON document

You can use this command to re-format a JSON document by specifying `--mode` to `lint`, with an optional indent level via `--indent` option. The following command reformats the input JSON file in a “prettified” format with the indent level of 2:

    orcus-json --mode lint --indent 2 path/to/input.json

The command writes the output to standard output by default, or you can specify the `--output` option to have it written to a local file instead. If you don’t specify the `--indent` option, it defaults to the indent level of 4.

### Extract subtree from JSON document

To extract a subtree structure from a JSON document, use the `subtree` mode with the root of a desired subtree to extract:

    orcus-json --mode subtree -p "$.store.fruits[3]" -i 2 path/to/source.json

This command traverses the original JSON document by following the `store` and `fruits` object keys and taking the 4th element of an array as the new root of the tree, and writes it to stdout with the indent level of 2.

You can also use the wildcard expression to select all elements of an array, as in the following example:

    orcus-json --mode subtree -p "$.store.fruits[*].name" -i 2 path/to/source.json

This command traverses the original JSON document through the `store` and `fruits` objects keys as in the previous example, but selects all elements of the array, and in each element only grabs the `name` key of the object below it.

### Convert JSON document to YAML

To convert a JSON document to YAML, use the `convert` mode and specify the output format to `yaml` in the `--output-format` option or simply `-f`:

    orcus-json --mode convert -f yaml path/to/input.json

The command then writes the converted document to standard output. If you wish to write it to a local file, use the `--output` option to specify the path to output file the command can write to.