Jf is both an executable binary that can be run, and a library that can be used in Rust programs.

Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install jf

It will make the jf command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall jf uninstalls.

Adding `jf` library as a dependency

Run this command in a terminal, in your project's directory:

cargo add jf

To add it manually, edit your project's Cargo.toml file and add to the [dependencies] section:

jf = "1.0.0"

The jf library will be automatically available globally. Read the jf library documentation.

Back to the crate overview.

Readme

jf

jf is a jo alternative, A small utility to safely format and print JSON objects in the commandline.

However, unlike jo, where you build the JSON object by nesting jo outputs, jf works similar to printf, i.e. it expects the template in YAML format as the first argument, and then the values for the placeholders as subsequent arguments.

For example:

jf "{one: %s, two: %q, three: [%(four)s, %(five=5)q]}" 1 2 four=4
# {"one":1,"two":"2","three":[4,"5"]}

INSTALL

Homebrew (3rd party)

brew install gromgit/tools/jf

Cargo

As a CLI tool

cargo install jf

Or as a library:

cargo add jf

Nixpkgs

nix-shell -p jf

Binaries

USAGE

jf [OPTION]... [--] TEMPLATE [VALUE]... [NAME=VALUE]... [NAME@FILE]...

Docker

docker pull docker.io/sayanarijit/jf
podman pull quay.io/sayanarijit/jf

OPTIONS

option	help
-	alias for `-f -`, i.e. read template from stdin
--	stop parsing CLI options
-r, --raw	print the raw rendered value without formatting
-p, --pretty	pretty print the JSON formatted output
-y, --yaml	print the output as YAML instead of JSON
-h, --help	print this help message
-v, --version	print the version number
-f, --file	treat the template argument as a file to read from

TEMPLATE

Template should render into valid YAML. It can contain the following placeholders:

%% a literal % character
%s %q read positional argument
%-s %-q read stdin
%(NAME)s %(NAME)q read named value from argument
%(NAME=DEFAULT)s %(NAME=DEFAULT)q placeholder with default value
%(NAME@FILE)s %(NAME@FILE)q read default value from file path
%(NAME@-)s %(NAME@-)q read default value from stdin
%(NAME?)s %(NAME?)q nullable placeholder that defaults to null
%(NAME)?s %(NAME)?q optional placeholder that defaults to blank
%*s %*q expand positional args as array items
%*-s %*-q expand stdin as array items
%**s %**q expand positional args as key value pairs
%**-s %**-q expand stdin as key value pairs
%(NAME)*s %(NAME)*q expand named args as array items
%(NAME)**s %(NAME)**q expand named args as key value pairs

Use placeholders with suffix q for safely quoted JSON string and s for JSON values other than string.

RULES

Pass values for positional placeholders in the same order as in the template.
Pass values for named placeholders using NAME=VALUE syntax.
Pass values for named array items using NAME=ITEM_N syntax.
Pass values for named key value pairs using NAME=KEY_N NAME=VALUE_N syntax.
Pass values to stdin following the order and separate them with null byte (\0).
Use NAME@FILE syntax to read from file where FILE can be - for stdin.
Do not pass positional values after named values.
To allow merging arrays and objects via expansion, trailing comma after s and q, if any, will be auto removed if no value is passed for the expandable placeholder.

EXAMPLES

jf %s 1
# 1

jf %q 1
# "1"

jf '{%**q}' one 1 two 2 three 3
# {"one":"1","two":"2","three":"3"}

seq 1 3 | xargs printf '%s\0' | jf '[%*-s]'
# [1,2,3]

jf "{%q: %(value=default)q, %(bar)**q}" foo value=bar bar=biz bar=baz
# {"foo":"bar","biz":"baz"}

jf "{str or bool: %(str)?q %(bool)?s, nullable: %(nullable?)q}" str=true
# {"str or bool":"true","nullable":null}

jf '{1: %s, two: %q, 3: %(3)s, four: %(four=4)q, "%%": %(pct?)q}' 1 2 3=3
# {"1":1,"two":"2","3":3,"four":"4","%":null}

SHELL ALIASES

You can set the following aliases in your shell:

alias str='jf %q'
alias arr='jf "[%*s]"'
alias obj='jf "{%**s}"'

Then you can use them like this:

str 1
# "1"

arr 1 2 3
# [1,2,3]

obj one 1 two 2 three 3
# {"one":1,"two":2,"three":3}

obj 1 2 3 "$(arr 4 "$(str 5)")"
# {"1":2,"3":[4,"5"]}

RUST LIBRARY

let json = match jf::format(["%q", "JSON Formatted"].map(Into::into)) {
    Ok(value) => value,
    Err(jf::Error::Jf(e)) => bail!("mytool: {e}"),
    Err(jf::Error::Json(e)) => bail!("mytool: json: {e}"),
    Err(jf::Error::Yaml(e)) => bail!("mytool: yaml: {e}"),
};

Installing the command-line executable

Adding jf library as a dependency

Adding `jf` library as a dependency