XQ

JQ reimplemented purely in Rust.

Caution

This program is under development. You probably want to use the original implementation of jq, or pure Go implementation of it called gojq built by itchyny instead.

Current state

• Most of the jq components that require syntactical support are, hmm, implemented and tested against queries taken from the jq user manual. Exceptions are imports and module headers.
• Many builtin functions are missing, include those require intrinsic implementation.
• Need more unit tests. Most of the CLI options are missing.
• JSON and YAML formats are supported.

Goals

• Learn jq.

Ideas

• Since we use serde to deserialize input / serialize output, we should be able to support any format which has serde implementation (and has multi-document support) without too much effort, except those require scheme (protobuf, thrift, etc.).

• As a library, we should be able to make anything that implements Serialize as the input type, and anything implements Deserialize as the output type. So in theory, we should be able to write a library that can handle following;

  #[derive(Serialize)]
  struct GitHubRepo {
      user_name: String,
      repo_name: String,
      stars: usize,
  }
  #[derive(Deserialize)]
  struct User {
      name: String,
      total_stars: usize,
  }
  let repos: Vec<GitHubRepo> = fetch_repos();
  let users: Vec<User> = xq::somefunction_slurp<GitHubRepo, User>(repos, r#"
      group_by(.user_name)[]
      | { name: .[0].user_name, total_stars: ([.[].stars] | add) }
  "#).collect();

  I mean, it's not something that one should really use. It's just something possible and interesting... isn't it?

Install and run

Are you sure you want to use this??? It's not a daily-usable stage. Though if you want to try, you can install it via

$ cargo install xq
$ cat whatever.json | xq 'query goes here'

. If you'd rather want to download a pre-built binary, either download it manually from the latest release, or use cargo-binstall. Either way, the license texts of the dependencies are in about.html file in the downloaded archive.

You can also clone this repository to your local and run

$ cargo install --path path-to-cloned-dir
$ cat whatever.json | xq 'query goes here'

. Alternatively,

$ cat whatever.json | cargo run -- 'query goes here'

in the cloned directory to try out them without installing.

Uninstall

$ cargo uninstall xq

if you've installed via cargo install. Also remove the cloned directory if you've cloned the repository.

Publish new version

Note for myself.

$ git switch master                 # make sure you're on the master branch
$ cargo release patch               # to dry-run the release
$ cargo release patch --execute     # to actually execute the release

Pass --workspace to publish workspace members as well.

Acknowledgements

• Although this isn't a direct translation at all, I referred to jq built by Stephen Dolan and gojq built by itchyny. Thank you for the interesting product!

Credits

• Test cases in tests/from_manual are taken from the jq user manual, distributed under CC BY 3.0, Copyright (C) 2012 Stephen Dolan. Please refer to mod.rs there for more detail.

Author

Mi_Sawa

LICENSE

MIT. Please refer to LICENSE file.