The `ys` Command

There are different ways to use YS but the most common is to use it via the YS command-line tool: ys; a very versatile tool indeed.

There's a lot you can do with ys including using it like you would use jq or yq one-liners:

$ jq .bar < <(echo '{"foo": 123, "bar": 456, "baz": 789}')
456
$ yq .bar < <(echo -e 'foo: 123\nbar: 456\nbaz: 789')
456
$ ys .bar < <(echo -e 'foo: 123\nbar: 456\nbaz: 789')
456

Each of these tools have their own advantages and we'll be diving deep into those waters soon enough.

Today let's just start by exploring the basic things you can do with the ys CLI.

Installing ys

ys is a standalone native binary executable for Mac and Linux (Windows coming soon) that has releases here  .

Try curl -sL getys.org/ys | bash for a simple install, or...

Read the ys installation instructions  for the all the installation details.

The ys Basics

Once you have ys installed, try:

$ ys

ys - The YS Command Line Tool - v0.1.97

Usage: ys [<option...>] [<file>]

Options:

  -e, --eval YSEXPR        Evaluate a YS expression
                             multiple -e values are joined by newline
  -l, --load               Output the (compact) JSON of YS evaluation
  -f, --file FILE          Explicitly indicate input file

  -c, --compile            Compile YS to Clojure
  -b, --binary             Compile to a native binary executable

  -p, --print              Print the final evaluation result value
  -o, --output FILE        Output file for --load, --compile or --binary
  -s, --stream             Output all results from a multi-document stream

  -T, --to FORMAT          Output format for --load:
                             json, yaml, csv, tsv, edn
  -J, --json               Output (pretty) JSON for --load
  -Y, --yaml               Output YAML for --load
  -U, --unordered          Mappings don't preserve key order (faster)

  -m, --mode MODE          Add a mode tag: code, data, or bare (for -e)
  -C, --clojure            Treat input as Clojure code

  -d                       Debug all compilation stages
  -D, --debug-stage STAGE  Debug a specific compilation stage:
                             parse, compose, resolve, build,
                             transform, construct, print
                           can be used multiple times
  -S, --stack-trace        Print full stack trace for errors
  -x, --xtrace             Print each expression before evaluation

      --install            Install the libyamlscript shared library
      --upgrade            Upgrade both ys and libyamlscript

      --version            Print version and exit
  -h, --help               Print this help and exit

Calling ys with no arguments is the same as ys --help.

Loading YAML with ys

Let's start first with the --load option.

It might sound strange to ask a CLI to "load" YAML. That's what a program does, right? It loads a YAML text into a native data structure inside the program. Where is a CLI going to load it into?

When you tell ys to --load YAML, it will load it internally into a native data structure, but then it has to show you the result on stdout.

The way it works is that ys --load will evaluate the YAML and then print the result as compact JSON!

Why JSON? Patience!

Let's start with this simple file:

# sample.yaml
name: Sammie
age: 10
favorite things:
- ice cream
- books
- playing outside

Now let's load it with ys:

$ ys --load sample.yaml
{"name":"Sammie","age":10,"favorite things":["cake","books","playing games"]}

You can also use -l (short for --load), -Y (short for --yaml), -J (short for --json) or --to=<format> for csv, tsv, edn and more.

Since all JSON is valid YAML, you can also do anything with a JSON file that you can do with a YAML file.

Let's pipe the above JSON output into ys again:

$ ys -l sample.yaml | ys -Y
name: Sammie
age: 10
favorite things:
- ice cream
- books
- playing outside

Looks like ys is a sweet little data file transformer!

The JSON Data Model

Loading YAML to JSON is a very important concept about YS...

When you use it to load YAML, the result must be expressible as JSON. YS thinks of JSON as the Lingua Franca of data models.

Let's get Dynamic!

Sammie has more than 3 favorite things, and honestly they are changing all the time.

Let's update the YAML file to include more favorite things:

!YS-v0

fun-things =::
- ice cream
- reading books
- playing outside
- jumping rope
- building blocks
- finger painting
- bubble blowing
- hide and seek
- coloring books
- toy cars
- dress up clothes
- board games
- stuffed animals

--- !data
name: Sammie
age: 10
favorite things::
  take 4:
    shuffle(fun-things)

Here we've added a code mode document before the document we want to load to define a list of fun things.

Let's see what happens when we load this file:

$ ys -Y sample.yaml
name: Sammie
age: 10
favorite things:
- finger painting
- board games
- hide and seek
- dress up clothes

Summer is Here!

I feel like I could write a book about the ys CLI.

Maybe I will!

But today is the first day of Summer!

Comments