.\" Text automatically generated by txt2man
.TH jf  "1" "" ""
.SH USAGE

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

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

Template should render into valid YAML. It can contain the following placeholders:
.TP
.B
`%%`
a literal `%` character
.TP
.B
`%s`
`%q`                read positional argument
.TP
.B
`%\fB-s\fP`
`%\fB-q\fP`               read stdin
.TP
.B
`%(NAME)s`
`%(NAME)q`          read named value from argument
.TP
.B
`%(NAME=DEFAULT)s`
`%(NAME=DEFAULT)q`  placeholder with default value
.TP
.B
`%(NAME@FILE)s`
`%(NAME@FILE)q`     read default value from file path
.TP
.B
`%(NAME@-)s`
`%(NAME@-)q`        read default value from stdin
.TP
.B
`%(NAME?)s`
`%(NAME?)q`         nullable placeholder that defaults to null
.TP
.B
`%(NAME)?s`
`%(NAME)?q`         optional placeholder that defaults to blank
.TP
.B
`%*s`
`%*q`               expand positional args as array items
.TP
.B
`%*\fB-s\fP`
`%*\fB-q\fP`              expand stdin as array items
.TP
.B
`%**s`
`%**q`              expand positional args as key value pairs
.TP
.B
`%**\fB-s\fP`
`%**\fB-q\fP`             expand stdin as key value pairs
.TP
.B
`%(NAME)*s`
`%(NAME)*q`         expand named args as array items
.TP
.B
`%(NAME)**s`
`%(NAME)**q`        expand named args as key value pairs
.PP
Use placeholders with suffix `q` for safely quoted JSON string and `s` for JSON values
other than string.
.SH RULES

.IP \(bu 3
Pass values for positional placeholders in the same order as in the template.
.IP \(bu 3
Pass values for named placeholders using `NAME=VALUE` syntax.
.IP \(bu 3
Pass values for named array items using `NAME=ITEM_N` syntax.
.IP \(bu 3
Pass values for named key value pairs using `NAME=KEY_N NAME=VALUE_N` syntax.
.IP \(bu 3
Pass values to stdin following the order and separate them with null byte (`\0`).
.IP \(bu 3
Use `NAME@FILE` syntax to read from file where FILE can be `-` for stdin.
.IP \(bu 3
Do not pass positional values after named values.
.IP \(bu 3
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.
.SH EXAMPLES

.IP \(bu 3
Run: jf %s 1
.IP \(bu 3
Out: 1
.IP \(bu 3
Run: jf %q 1
.IP \(bu 3
Out: "1"
.IP \(bu 3
Run: jf '{%**q}' one 1 two 2 three 3
.IP \(bu 3
Out: {"one":"1","two":"2","three":"3"}
.IP \(bu 3
Run: seq 1 3 | xargs printf '%s\0' | jf '[%*\fB-s\fP]'
.IP \(bu 3
Out: [1,2,3]
.IP \(bu 3
Run: jf "{%q: %(value=default)q, %(bar)**q}" foo value=bar bar=biz bar=baz
.IP \(bu 3
Out: {"foo":"bar","biz":"baz"}
.IP \(bu 3
Run: jf "{str or bool: %(str)?q %(bool)?s, nullable: %(nullable?)q}" str=true
.IP \(bu 3
Out: {"str or bool":"true","nullable":null}
.IP \(bu 3
Run: jf '{1: %s, two: %q, 3: %(3)s, four: %(four=4)q, "%%": %(pct?)q}' 1 2 3=3
.IP \(bu 3
Out: {"1":1,"two":"2","3":3,"four":"4","%":null}
.SH SHELL ALIASES

You can set the following aliases in your shell:
.IP \(bu 3
alias str='jf %q'
.IP \(bu 3
alias arr='jf "[%*s]"'
.IP \(bu 3
alias obj='jf "{%**s}"'
.PP
Then you can use them like this:
.IP \(bu 3
Run: str 1
.IP \(bu 3
Out: "1"
.IP \(bu 3
Run: arr 1 2 3
.IP \(bu 3
Out: [1,2,3]
.IP \(bu 3
Run: obj one 1 two 2 three 3
.IP \(bu 3
Out: {"one":1,"two":2,"three":3}
.IP \(bu 3
Run: obj 1 2 3 $(arr 4 $(str 5))
.IP \(bu 3
Out: {"1":2,"3":[4,"5"]}