jsongrep 0.2.0

A JSONPath-inspired query language for JSON documents
Documentation

jsongrep (jg)

jsongrep is a JSONPath-inspired query language over JSON documents.

Table of Contents

Installation

jsongrep can be installed using cargo:

cargo install jsongrep

The jg binary will be installed to ~/.cargo/bin.

Usage

A JSONPath-inspired query language for JSON documents

Usage: jg [OPTIONS] [QUERY] [FILE] [COMMAND]

Commands:
  generate  Generate additional documentation and/or completions
  help      Print this message or the help of the given subcommand(s)

Arguments:
  [QUERY]  Query string (e.g., "**.name")
  [FILE]   Optional path to JSON file. If omitted, reads from STDIN

Options:
      --compact     Do not pretty-print the JSON output, instead use compact
      --count       Display count of number of matches
      --depth       Display depth of the input document
  -n, --no-display  Do not display matched JSON values
  -h, --help        Print help
  -V, --version     Print version

Query Syntax

The query engine allows you to query JSON data using a simple DSL. It supports the following operators:

  • Field accesses: foo
  • Array accesses (0-indexed): [0] | [start: end]
  • Field and array wild cards: foo.*, foo[*]
  • Optional chaining: foo?.bar
  • Kleene star: foo*
  • Disjunction: foo | bar
  • Sequence: foo.bar.baz

Notes:

  • Sequences use . to chain steps: foo.bar.baz

  • Fields can be unquoted (foo) or quoted ("foo bar")

  • The * modifier after a step is different from the * field wildcard — the modifier repeats the preceding step.

The complete grammar for the query language can be found in the grammar directory.

Example: Pass input file by path

simple.json:

{
  "name": {
    "first": "John",
    "last": "Doe"
  },
  "age": 32,
  "hobbies": ["fishing", "yoga"]
}

The following query will follow an arbitrary amount of filed accesses followed by a wildcard array access:

jg "**.[*]" simple.json

Output:

[
  "fishing",
  "yoga"
]

Example: Pipe input from STDIN

curl https://api.nobelprize.org/v1/prize.json | jg "prizes[4].laureates[1].motivation"

Output:

[
  "\"for foundational discoveries and inventions that enable machine learning with artificial neural networks\""
]

Example: Check number of matches without displaying them

Again, using the simple.json file:

jg "**.[*]" simple.json --count --no-display

Output:

Found matches: 2

The jsongrep::query::ast module defines the QueryBuilder fluent API for building queries. It allows you to construct queries using a builder pattern.

Example Usage:

// Construct the query "foo[0].bar.*.baz"
use jsongrep::query::engine::QueryBuilder;
let query = QueryBuilder::new()
    .field("foo")
    .index(0)
    .field("bar")
    .field_wildcard()
    .field("baz")
    .build();

Examples

Examples of using the jsongrep crate can be found in the examples directory.

Shell Completions

To generate completions for your shell, you can use the jg generate shell subcommand. By default, the completions will be printed to /dev/stdout and can be redirected to your shell's expected completion location:

  • Bash

    # Source the completion script in your .bashrc
echo 'source /path/to/jg.bash' >> ~/.bashrc

# Or copy to the system-wide bash completion directory
jg generate shell bash > jg.bash && sudo mv jg.bash /etc/bash_completion.d/

  • Zsh

    mkdir -p ~/.zsh/completions
jg generate shell zsh > ~/.zsh/completions/_jg

# Add the directory to fpath in your .zshrc before compinit
echo 'fpath=(~/.zsh/completions $fpath)' >> ~/.zshrc
echo 'autoload -Uz compinit && compinit' >> ~/.zshrc

  • Fish

    jg generate shell fish > ~/.config/fish/completions/jg.fish

Man Page

To generate a Man page for jg, you can use the jg generate man subcommand to generate to a specified output directory with the -o/--output-dir options (defaults to current directory):

mkdir -p ~/.local/share/man/man1/
jg generate man -o ~/.local/share/man/man1/

Browse the generated Man pages with man jg.

Contributing

Contributions are welcome! Please see the CONTRIBUTING.md file for more details.

License

This project is licensed under the MIT License - see the LICENSE.md file for details.