Lib.rs

Structs, the data structure service

Structs is a tool for interacting with structured data in shell scripts. Structs allows you to parse some JSON, maintain the data structure in memory, and arbitrarily access fields in a natural way. There are other ways to accomplish this in shell scripts, but they are mostly pretty clunky.

Define a data structure

A data structure can be defined via the set operation. The key for the newly-created structure is printed and can be used to fetch data.

$ structs set
{
  "numbers": {
    "one": {
        "cardinal": 1,
        "ordinal": "1st"
    },
    "two": {
        "cardinal": 2,
        "ordinal": "2nd"
    },
    "three": {
        "cardinal": 3,
        "ordinal": "3rd"
    }
  }
}
^D
woh7iu3tieB0

Fetch a structure

The entire data structure can be fetched using its key, or its fields can be refernced using common dot-notation.

$ structs get woh7iu3tieB0
{"numbers":{"one":{"cardinal":1,"ordinal":"1st"},"two":{"cardinal":2,"ordinal":"2nd"},"three":{"cardinal":3,"ordinal":"3rd"}}}

Fetch a sub-structure

Referencing a field will print a subset of the structure as JSON.

$ structs get woh7iu3tieB0.numbers.two
{"cardinal":2,"ordinal":"2nd"}

Structs can be used in collaboration with Jq for more elaborate processing.

$ structs get woh7iu3tieB0.numbers.two | jq -r 'map(.) | @csv'
2,"2nd"

Fetch an individual field

Referencing a primitive field (string, number, boolean) is usually more useful than fetching structures.

$ structs get woh7iu3tieB0.numbers.two.ordinal
"2nd"

By default, individual fields are formatted as JSON. Use the -r or --raw flag to print a field's value instead of its JSON representation.

$ structs get --raw woh7iu3tieB0.numbers.two.ordinal
2nd

Range over keys (or indexes)

Range over and print all the keys (or indexes) in an object or array. The keys or indexes are printed in raw form, suitable for use as a component in an expression.

$ structs range woh7iu3tieB0.numbers
one
two
three

$ for key in $(structs range woh7iu3tieB0.numbers); do echo "Ordinal: $(structs get -r woh7iu3tieB0.numbers.${key}.ordinal)"; done
Ordinal: 1st
Ordinal: 2nd
Ordinal: 3rd