exoncue

README

Exoncue - Export data unified with stored CUE ... right on cue!

exoncue takes the CUE that you specify (a schema; some data; some constraints; whatever) and builds an executable binary that stores the CUE.

When executed, the binary that's produced either displays the stored CUE, or accepts any number of JSON or YAML file arguments and emit the result of unifying the CUE with all the data files simultaneously (if they unify successfully).

Install

The exoncue command requires a working go installation to build its my.binary command. Because a working go installation can be assumed, go install is used to install exoncue:

$ go install git.sr.ht/~jonathanmatthews/exoncue@latest

Building my.binary

[TODO: allow name to be changed during build]

To build a my.binary executable, invoke exoncue with a CUE file as its sole argument. This CUE file will be stored and used verbatim, therefore it cannot import any non-builtin CUE packages [TODO: permit imports].

$ cat some.cue
x!: int
y?: string
$ exoncue some.cue
Executable created: /home/user/my.binary

Using my.binary

The my.binary file can be renamed as required. Use its --help flag for information about the operations it can perform:

$ mv my.binary schemaCheck
$ ./schemaCheck --help
Export stored CUE, unified with arbitrary data files.

Usage: ./schemaCheck [--help|--cue] <data-file> [<data-file>...] [--json]

Flags:
  --help             Print this help text
  --cue              Print stored CUE to stderr
  --json (optional)  Unify stored CUE and all data-files, then print the result as JSON to stdout

To view the stored CUE, use the --cue flag:

$ ./schemaCheck --cue
x!: int
y?: string

To export the stored CUE in isolation, invoke the executable with no arguments (or just the --json flag). This will only succeed if the stored CUE has a concrete form (e.g. it only contains data, or has defaults which provide any missing data):

$ ./schemaCheck --json
$ echo $?
1

[TODO: surface error messages about non-concrete fields]

To unify the stored CUE with one or more data files, provide the files as arguments. The CUE is unified with all the files in turn, so the result is validated against the stored CUE's schema/policy/etc. This will only succeed if the result of all the unifications is concrete:

$ ./schemaCheck --cue
x!: int
y?: string
$ cat bad-data.yml 
x: "hello"
y: 42
$ ./schemaCheck bad-data.yml --json
$ echo $?
1

[TODO: surface error messages]

If the unification produces a concrete result, it is emitted as JSON on stdout:

$ cat good-data.json 
{ "x": 42 }
$ cat good-data.yml
y: "some string"
z: 4.2
$ ./schemaCheck good-data.yml good-data.json --json
{"x":42,"y":"some string","z":4.2}

Tip: all JSON is YAML. If you need this data in a YAML file, just ... put it in a .yaml file! [TODO: add --yaml flag allowing for idiomatic YAML formatting]