{% include 'header.html.jinja' %}

<h1 id=cmdline_tool>Commandline Tool</h1>

<p>The commandline tool "jsonnet" will evaluate Jsonnet and emit JSON on stdout.  It can evaluate
snippets of code, or files (by filename).  It is actually a commandline wrapper around the C API, a
convenient way to evaluate Jsonnet code from shell scripts, build tools, or languages that do not
yet have a library binding.</p>

<h2 id=building>Building</h2>

<p>The commandline tool will be built by simply invoking 'make', as it is the sole default
target.  It can be built explicitly with 'make jsonnet'.</p>

<h2 id=usage>Usage</h2>

<p>The tool is self-documenting:</p>

<pre>
Usage:
Usage:
jsonnet {&lt;option&gt;} [&lt;filename&gt;]
where &lt;filename&gt; defaults to - (stdin)
and &lt;option&gt; can be:
  -h / --help             This message
  -e / --exec             Treat filename as code (requires explicit filename)
  -J / --jpath &lt;dir&gt;      Specify an additional library search dir
  -V / --var &lt;var&gt;=&lt;val&gt;  Specify an 'external' var to the given value
  -E / --env &lt;var&gt;        Bring in an environment var as an 'external' var
  -m / --multi            Write multiple files, list files on stdout
  -s / --max-stack &lt;n&gt;    Number of allowed stack frames
  -t / --max-trace &lt;n&gt;    Max length of stack trace before cropping
  --gc-min-objects &lt;n&gt;    Do not run garbage collector until this many
  --gc-growth-trigger &lt;n&gt; Run garbage collector after this amount of object growth
  --debug-ast             Unparse the parsed AST without executing it

  --version               Print version
Multichar options are expanded e.g. -abc becomes -a -b -c.
The -- option suppresses option processing for subsequent arguments.
Note that since jsonnet programs can begin with -, it is advised to
use -- with -e if the program is unknown, e.g. jsonnet -e -- "$CODE".
</pre>

<h2>Example</h2>

<p>Evaluating a file.</p>

<pre>
~/jsonnet/examples$ jsonnet landingpage.jsonnet
{
   "person1": {
      "name": "Alice",
      "welcome": "Hello Alice!"
   },
   "person2": {
      "name": "Bob",
      "welcome": "Hello Bob!"
   }
}
</pre>

<p>Evaluating a snippet.</p>

<pre>
~/jsonnet/examples$ jsonnet -e '{ x: 1 , y: self.x + 1 } { x: 10 }'
{
   "x": 10,
   "y": 11
}
</pre>

<h2 id=multi>Multiple file output</h2>

<p>The Jsonnet commandline tool has a special mode for generating multiple JSON files from a single
Jsonnet file.  This can be useful if you want to avoid writing lots of small Jsonnet files, or if
you want to take advantage of cross-references and interdependencies between the files.  The idea is
to create a single JSON structure, the top level of which defines the various files.  The following
example shows how to do it: </p>

<pre class="large"><code>// multiple_output.jsonnet
{
    "a.json": {
        x: 1,
        y: $["b.json"].y,
    },
    "b.json": {
        x: $["a.json"].x,
        y: 2,
    },
}
</code></pre>

<p>When executed using jsonnet -m, this will write the generated JSON to files a.json and b.json
instead of to stdout.  In order to integrate nicely with build tools like make, the files are not
touched if they already contain the content that would be written to them.  To stdout is printed the
list of files (either written or already containing the right data).  This makes it easy to drive
other tools that operate on the JSON files.</p>

<pre>
$ jsonnet -m multiple_output.jsonnet
a.json
b.json
$ cat a.json 
{
   "x": 1,
   "y": 2
}
$ cat b.json 
{
   "x": 1,
   "y": 2
}
</pre>

{% include 'footer.html.jinja' %}
