jqcpp

jqcpp is a small C++20 command-line JSON processor inspired by jq. It parses JSON from standard input or a file, evaluates a jq-like expression, and writes formatted JSON output.

The project is intentionally focused on a compact subset of jq syntax. It is useful as a lightweight JSON parser/evaluator example and as a starting point for experimenting with query language implementation in modern C++.

Features

• JSON tokenization, parsing, and pretty-printing
• Field access for objects, including nested paths
• Array indexing and slicing
• Identity filters
• Numeric addition and subtraction
• Pipe expressions
• Basic length and keys functions

Requirements

• CMake 3.14 or newer
• A C++20 compiler
• Catch2, only when building tests with ENABLE_TEST=ON

Build

Configure and build the command-line executable:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build

Install to a custom prefix:

cmake -S . -B build -DCMAKE_BUILD_TYPE=Release -DCMAKE_INSTALL_PREFIX=/path/to/install
cmake --build build --target install

The installed binary is available at:

/path/to/install/bin/jqcpp

Usage

jqcpp [options] <expression> [input-file]

Read JSON from standard input:

echo '{"name": "John", "age": 30}' | jqcpp '.name'

Read JSON from a file:

jqcpp '.users[0].name' input.json

Run interactively by providing an expression and then typing or pasting JSON. Press Ctrl+D to end input:

jqcpp '.'

Examples

Identity filter:

echo '{"name": "John"}' | jqcpp '.'

Object field access:

echo '{"name": "John", "age": 30}' | jqcpp '.name'

Nested object access:

echo '{"person": {"name": "John"}}' | jqcpp '.person.name'

Array index:

echo '[10, 20, 30]' | jqcpp '.[1]'

Array slice:

echo '[10, 20, 30, 40]' | jqcpp '.[1:3]'

Arithmetic:

echo '{"x": 10, "y": 5}' | jqcpp '.x + .y'

Pipe expressions:

echo '{"users": [{"name": "Alice"}, {"name": "Bob"}]}' | jqcpp '.users | .[0].name'

Built-in functions:

echo '{"a": 1, "b": 2}' | jqcpp 'keys'
echo '[1, 2, 3]' | jqcpp 'length'

Project Video

Watch a short introduction to jqcpp: https://youtu.be/kBTfxNWbcXU

Supported Expression Syntax

Expression	Description
.	Return the input unchanged
.field	Read an object field
.field.nested	Read nested object fields
.[index]	Read an array element by zero-based index
.[start:end]	Return an array slice
.[start:]	Return an array slice from start to the end
.[:end]	Return an array slice from the beginning to end
.[]	Iterate object values or array elements into an array result
<expr> + <expr>	Add numeric results
<expr> - <expr>	Subtract numeric results
`	`
length	Return the length of an array, string, or object
keys	Return object keys or array indexes

Tests

Build and run tests with Catch2 available to CMake:

cmake -S . -B build-tests -DENABLE_TEST=ON
cmake --build build-tests
ctest --test-dir build-tests --output-on-failure

The CMake project also defines a convenience target:

cmake --build build-tests --target run_tests

Project Layout

app/              Command-line entry point
include/jqcpp/    Public headers
src/              Parser, evaluator, tokenizer, and printer implementation
tests/            Catch2 test suite
demo              Installed demo script

Limitations

jqcpp implements a jq-like subset rather than full jq compatibility. Advanced jq features such as filters with multiple independent outputs, variables, conditionals, object construction, full function definitions, and regular expressions are not currently implemented.

Open-Source Publishing Notes

Before publishing, add a LICENSE file that matches the terms you want for external reuse. If you publish the existing git history, rewrite or replace the history first because earlier commits contain personal course-identification metadata and generated build artifacts.