~evhan/sq

#sq

sq is a jq wrapper for S-expressions.

Specifically, it round-trips SRFI-180-formatted inputs through jq, allowing you to use that program's filters and flags to manipulate Scheme data.

Think of it like yq, but for S-expressions instead of YAML.

#Resources

Sources: https://hg.sr.ht/~evhan/sq
Issues: https://todo.sr.ht/~evhan/sq

#Installation

Use your distribution's package manager to install CHICKEN 5.2 or newer, then run:

chicken-install sq

Because sq calls jq internally, you will also need to install jq according to the download instructions for your platform.

Nix users can build the application with the following commands:

nix-shell --run "chicken-install"
nix-build

The result will be linked from ./result and can be called via ./result/bin/sq. This derivation includes jq, so there's no need to install it separately.

Alternatively, you can produce a static binary with the following command:

nix-shell --run "chicken-install -feature static-executable" --arg musl true

The resulting executable will be placed in the current directory at ./sq, but can be freely relocated. Note this method does not include jq automatically.

#Usage

Invoke sq just like you would jq. It accepts either S-expressions or JSON as input. When S-expressions are used, they must follow the format described by SRFI-180, for which the mapping between JSON types and Scheme objects is the following:

null → the symbol null
true → #t
false → #f
number → number
string → string
array → vector
object → association list with keys that are symbols

By default, sq generates S-expressions:

$ echo '{"greeting": "hello"}'  | sq
((greeting . "hello"))
$ echo '((greeting . "hello"))' | sq
((greeting . "hello"))

To generate JSON instead, pass the -j or --json flag:

$ echo '{"greeting": "hello"}'  | sq --json
{
  "greeting": "hello"
}
$ echo '((greeting . "hello"))' | sq --json
{
  "greeting": "hello"
}

Any other flags (apart from --help and --version) are passed directly through to jq. For example, use the -r or --raw-output flag to output string values:

$ echo '{"greeting": "hello"}'  | sq --raw-output .greeting
hello
$ echo '((greeting . "hello"))' | sq --raw-output .greeting
hello

Note that not all flags will work with sq. For example, the --color-output flag will only work when combined with --json, and the --null-input flag is obviously useless since sq works by sending input to jq.

#Development

To build this program you can run chicken-install -no-install.

To run the tests, install shelltestrunner and run chicken-install -no-install -test.

Nix users can enter a development shell with nix-shell.

#Known Problems

Parsing is slow for large JSON outputs generated by jq.
The program should probably just execute jq when --json is used with JSON inputs.
There is no validation of command line flags for compatibility.
Error messages for invalid S-expression inputs are not very helpful.
Inputs must be entirely in one format, you cannot mix JSON and S-expressions.
It is not currently possible to specify the format of the input.

#License

This software is provided under the terms of the 3-clause BSD license. See LICENSE for details.

heads

clone