Crate json_query

👎Deprecated since 0.3.1: This is the final release of json-query. Future releases will be published as jq-rs.

Overview

jq is a command line tool which allows users to write small filter/transform programs with a special DSL to extract data from json.

This crate provides bindings to the C API internals to give us programmatic access to this tool.

For example, given a blob of json data, we can extract the values from the id field of a series of objects.

let data = r#"{
    "colors": [
        {"id": 12, "name": "cyan"},
        {"id": 34, "name": "magenta"},
        {"id": 56, "name": "yellow"},
        {"id": 78, "name": "black"}
    ]
}"#;

let output = json_query::run("[.colors[].id]", data).unwrap();
assert_eq!("[12,34,56,78]", &output);

For times where you want to run the same jq program against multiple inputs, compile() returns a handle to the compiled jq program.

let tv_shows = r#"[
    {"title": "Twilight Zone"},
    {"title": "X-Files"},
    {"title": "The Outer Limits"}
]"#;

let movies = r#"[
    {"title": "The Omen"},
    {"title": "Amityville Horror"},
    {"title": "The Thing"}
]"#;

let mut program = json_query::compile("[.[].title] | sort").unwrap();

assert_eq!(
    r#"["The Outer Limits","Twilight Zone","X-Files"]"#,
    &program.run(tv_shows).unwrap()
);

assert_eq!(
    r#"["Amityville Horror","The Omen","The Thing"]"#,
    &program.run(movies).unwrap()
);

The output from these jq programs are returned as a string (just as is the case if you were using jq from the command-line), so be prepared to parse the output as needed after this step.

Pairing this crate with something like serde_json might make a lot of sense.

See the jq site for details on the jq program syntax.

Linking to libjq

When the bundled feature is enabled (on by default) libjq is provided and linked statically by jq-sys and jq-src which require having autotools and gcc in PATH to build.

If you disable the bundled feature, you will need to ensure your crate links to libjq in order for the bindings to work. For this you may need to add a build.rs script if you don’t have one already.

Structs

JqProgramDeprecated

A pre-compiled jq program which can be run against different inputs.

Enums

ErrorDeprecated

Functions

compileDeprecated

Compile a jq program then reuse it, running several inputs against it.

runDeprecated

Run a jq program on a blob of json data.