Skip to content

Welcome to rjq

rjq is a simple and lightweight CLI JSON filtering tool designed for Windows and Linux.

Flags

  • --load - Loads JSON data from file.
  • --query - Query to be performed on the dataset.
  • --params - Selects specific fields that will be returned as result.

Commands

  • rjq --load="<file name>" - Loads JSON data from file and returns all the data as result.
  • rjq --query="<query string>" - Sets query string.
  • rjq --params="<comma separated field names>" - Sets fileds for the result

Usage

  • rjq --load="test.json" --query="<query string>" --params="<comma separated field names>" - Loads data from file, applies the query, returns array of objects with fields specified by '--params' flag.

  • stto --json cpython | rjq --query="<query string>" --params="<comma separated field names>" - Piping output from other program.

    N.B. stto is a line of code counter used as an example here.

Query structure

Query is set by --query flag, e.g. --query="age > 30 && percentage >= 50.0". rjq has a simple query structure, it follows [field_name] [operator] [Value] pattern.

  • field_name - It is the field name from the supplied dataset. For nested objects '.' operator should be used for accessing values, e.g. to access 'town' value from the following json:

    { "_id": "88L33FM4VQBB1QYH", "address": { "postode": "CR45 9NE", "street": "3137 Stich Avenue", "town": "Swanley" } }

    use address.town in the field_name of the query.

    N.B. field_name should not be wrapped in any quotes.

  • Operator - The following operators are supported for now:

    • = - equal_to operator, checks if both sides are same.
    • != - not_equals operator, checks if both sides are NOT same.
    • > - greather_than operator, checks if left is greater than to right.
    • < - less_than operator, checks if left is lesser than to right.
    • >= - greather_than_or_equal operator, checks if left is greater than to right or same.
    • <= - less_than_or_equal operator, checks if left is lesser than to right or same.
    • && - and operator, joins two Binary expressions, e.g. age > 18 && percentage < 34.0.
    • || - or operator, joins two Binary expressions, e.g. age > 18 || percentage < 34.0.
  • Value - rjq supports 3 types of values, string, boolean & number.
    • String - strings should be wrapped in single quotes (') only, e.g. 'name', 'address' etc.
    • Boolean - true/false without any quotes.
    • Number - Any number without quotes. For comparing decimal numbers decimal point should be provided, e.g. for quering age & percentage of the following - { "age": 30, ... "percentage": 56.34, ... } use something like age > 18 && percentage > 50.0.

Parameters

Output parameters are set by --params flag e.g. --params="name, address.town". Dot walking is supported for nested object fields.

Project layout

LICENSE                     # License file
README.md                   # Gitgub ReadMe file
Cargo.toml                  # Project Config file
src/
├── main.rs                 # Entry point for the program.
├── query
│   ├── interpreter.rs      # Interprets the AST and returns boolean value after evaluating the query.
│   ├── lexer.rs            # Lexer of the program, tokenizes the query string.
│   └── parser.rs           # Parser of the program, creates Abstract syntax tree from the tokens generated by the lexer.
├── query.rs                # Wrapper file
└── utils.rs                # Utility file.