CUE is an expressive (but not Turing-complete) JSON superset, exportable to JSON or YAML. It supports optional types and many other conveniences for working with large configuration sets. The unification engine has roots in logic programming, and as such it provides a ready solution to modern configuration management problems.
When CUE is exported to JSON, values from every processed file are unified into one giant object. Consider these two files:
1//name.cue
2name: "Daniel"
1//disposition.cue
2disposition: "oblivious"
Now we can unify and export to JSON:
1% cue export name.cue disposition.cue
2{
3 "name": "Daniel",
4 "disposition": "oblivious"
5}
Or YAML:
1% cue export --out yaml name.cue disposition.cue
2name: Daniel
3disposition: oblivious
Notice the C-style comments are not in the output. Also notice that the keys in CUE syntax did not require quotes. Some special characters do require quotes:
1works_fine: true
2"needs-quotes": true
Unification doesn’t just unify across files, it is also a global merge of all types and values. The following fails, because the types are different.
1//string_value.cue
2foo: "baz"
1//integer_value.cue
2foo: 100
1% cue export string_value.cue integer_value.cue
2foo: conflicting values "baz" and 100 (mismatched types string and int):
3 integer_value.cue:1:6
4 string_value.cue:1:6
But even if we quote the integer, it still fails, because the values conflict and there is no way to unify everything into a top-level object.
1//string_value.cue
2foo: "baz"
1//integer_value.cue
2foo: "100" // a string now
1% cue export string_value.cue integer_value.cue
2foo: conflicting values "100" and "baz":
3 integer_value.cue:1:6
4 string_value.cue:1:6
Types in CUE are values; special ones that the unification engine knows have certain behavior relative to other values. During unification it requires that values match the specified types, and when concrete values are required, you will get an error if there’s only a type. So this is fine:
1street: "1 Infinite Loop"
2street: string
While cue export produces YAML or JSON, cue eval produces CUE. This is useful for converting YAML or JSON to CUE, or for inspecting the unified output in CUE itself. It’s fine to be missing concrete values in CUE (though it prefers concrete values when emitting CUE when both are available and match),
1//type-only.cue
2amount: float
1% cue eval type-only.cue
2amount: float
but you need concrete values if you want to export (or if you tell eval to require them with -c):
1% cue export type-only.cue
2amount: incomplete value float
Give it a value that unifies with the type, and all is well.
1//concrete-value.cue
2amount: 3.14
1% cue export type-only.cue concrete-value.cue
2{
3 "amount": 3.14
4}
The method of unifying concrete values with types that share a common syntax is very powerful, and much more compact than, e.g., JSON Schema. This way, schema, defaults, and data are all expressible in CUE.
Default values may be supplied with a type using an asterisk:
1// default-port.cue
2port: int | *8080
1% cue eval default-port.cue
2port: 8080
Enum-style options («disjunctions» in CUE) may be specified with an | separator:
1//severity-enum.cue
2severity: "high" | "medium" | "low"
3severity: "unknown"
1% cue eval severity-enum.cue
2severity: 3 errors in empty disjunction:
3severity: conflicting values "high" and "unknown":
4 ./severity-enum.cue:1:11
5 ./severity-enum.cue:1:48
6severity: conflicting values "low" and "unknown":
7 ./severity-enum.cue:1:31
8 ./severity-enum.cue:1:48
9severity: conflicting values "medium" and "unknown":
10 ./severity-enum.cue:1:20
11 ./severity-enum.cue:1:48
You can even have disjunctions of structs (not shown, but it works like you’d expect).
CUE has «definitions», and you can use them like you would variable declarations in other languages. They are also for defining struct types. You can apply a struct of type definitions to some concrete value(s) with &. Also notice you can say «a list with type #Whatever» using [...#Whatever].
1// definitions.cue
2
3#DashboardPort: 1337
4
5configs: {
6 host: "localhost"
7 port: #DashboardPort
8}
9
10#Address: {
11 street: string
12 city: string
13 zip?: int // ? makes zip optional
14}
15
16some_address: #Address & {
17 street: "1 Rocket Rd"
18 city: "Hawthorne"
19}
20
21more_addresses: [...#Address] & [
22 {street: "1600 Amphitheatre Parkway", city: "Mountain View", zip: "94043"},
23 {street: "1 Hacker Way", city: "Menlo Park"}
24]
1% cue export --out yaml definitions.cue
2configs:
3 host: localhost
4 port: 1337
5some_address:
6 street: 1 Rocket Rd
7 city: Hawthorne
8more_addresses:
9 - street: 1600 Amphitheatre Parkway
10 city: Mountain View
11 zip: "94043"
12 - street: 1 Hacker Way
13 city: Menlo Park
CUE supports more complex values and validation:
1#Country: {
2 name: =~"^\\p{Lu}" // Must start with an upper-case letter
3 pop: >800 & <9_000_000_000 // More than 800, fewer than 9 billion
4}
5
6vatican_city: #Country & {
7 name: "Vatican City"
8 pop: 825
9}
CUE may save you quite a bit of time with all the sugar it provides on top of mere JSON. Here we’re defining, «modifying», and validating a nested structure in three lines: (Notice the [] syntax used around string to signal to the engine that string is a constraint, not a string in this case.)
1//paths.cue
2
3// path-value pairs
4outer: middle1: inner: 3
5outer: middle2: inner: 7
6
7// collection-constraint pair
8outer: [string]: inner: int
1% cue export paths.cue
2{
3 "outer": {
4 "middle1": {
5 "inner": 3
6 },
7 "middle2": {
8 "inner": 7
9 }
10 }
11}
In the same vein, CUE supports «templates», which are a bit like functions of a single argument. Here Name is bound to each string key immediately under container while the struct underneath that is evaluated.
1//templates.cue
2
3container: [Name=_]: {
4 name: Name
5 replicas: uint | *1
6 command: string
7}
8
9container: sidecar: command: "envoy"
10
11container: service: {
12 command: "fibonacci"
13 replicas: 2
14}
1% cue eval templates.cue
2container: {
3 sidecar: {
4 name: "sidecar"
5 replicas: 1
6 command: "envoy"
7 }
8 service: {
9 name: "service"
10 command: "fibonacci"
11 replicas: 2
12 }
13}
And while we’re talking about references like that, CUE supports scoped references.
1//scopes-and-references.cue
2v: "top-level v"
3b: v // a reference
4a: {
5 b: v // matches the top-level v
6}
7
8let V = v
9a: {
10 v: "a's inner v"
11 c: v // matches the inner v
12 d: V // matches the top-level v now shadowed by a.v
13}
14av: a.v // matches a's v
1% cue eval --out yaml scopes-and-references.cue
1v: top-level v
2b: top-level v
3a:
4 b: top-level v
5 v: a's inner v
6 c: a's inner v
7 d: top-level v
8av: a's inner v
I changed the order of the keys in the output for clarity. Order doesn’t actually matter, and notice that duplicate keys at a given level are all unified.
You can hide fields be prefixing them with _ (quote the field if you need a _ prefix in an emitted field)
1//hiddens.cue
2"_foo": 2
3_foo: 3
4foo: 4
5_#foo: 5
6#foo : 6
1% cue eval hiddens.cue
2"_foo": 2
3foo: 4
4#foo: 6
5
6% cue export hiddens.cue
7{
8 "_foo": 2,
9 "foo": 4
10}
Notice the difference between eval and export with respect to definitions. If you want to hide a definition in CUE, you can prefix that with _.
Interpolation of values and fields:
1//interpolation.cue
2
3#expense: 90
4#revenue: 100
5message: "Your profit was $\( #revenue - #expense)"
6
7cat: {
8 type: "Cuddly"
9 "is\(type)": true
10}
1% cue export interpolation.cue
2{
3 "message": "Your profit was $10",
4 "cat": {
5 "type": "Cuddly",
6 "isCuddly": true
7 }
8}
Operators, list comprehensions, conditionals, imports…:
1//getting-out-of-hand-now.cue
2import "strings" // we'll come back to this
3
4// operators are nice
5g: 5 / 3 // CUE can do math
6h: 3 * "blah" // and Python-like string repetition
7i: 3 * [1, 2, 3] // with lists too
8j: 8 < 10 // and supports boolean ops
9
10// conditionals are also nice
11price: number
12// Require a justification if price is too high
13if price > 100 {
14 justification: string
15}
16price: 200
17justification: "impulse buy"
18
19// list comprehensions are powerful and compact
20#items: [ 1, 2, 3, 4, 5, 6, 7, 8, 9]
21comp: [ for x in #items if x rem 2 == 0 {x*x}]
22
23// and... well you can do this too
24#a: [ "Apple", "Google", "SpaceX"]
25for k, v in #a {
26 "\( strings.ToLower(v) )": {
27 pos: k + 1
28 name: v
29 nameLen: len(v)
30 }
31}
1% cue export getting-out-of-hand-now.cue
1{
2 "g": 1.66666666666666666666667,
3 "h": "blahblahblah",
4 "i": [1, 2, 3, 1, 2, 3, 1, 2, 3],
5 "j": true,
6 "apple": {
7 "pos": 1,
8 "name": "Apple",
9 "nameLen": 5
10 },
11 "google": {
12 "pos": 2,
13 "name": "Google",
14 "nameLen": 6
15 },
16 "price": 200,
17 "justification": "impulse buy",
18 "comp": [
19 4,
20 16,
21 36,
22 64
23 ],
24 "spacex": {
25 "pos": 3,
26 "name": "SpaceX",
27 "nameLen": 6
28 }
29}
At this point it’s worth mentioning that CUE may not be Turing-complete, but it is powerful enough for you to shoot yourself in the foot, so do try to keep it clear. It’s easy to go off the deep end and make your config harder to work with if you’re not careful. Make use of those comments, at least, and/or…
To that end, CUE supports packages and modules. CUE files are standalone by default, but if you put a package clause at the top, you’re saying that file is unifiable with other files «in» the same package.
1//a.cue
2package config
3
4foo: 100
5bar: int
1//b.cue
2package config
3
4bar: 200
If you create these two files in a new directory and run cue eval (no arguments), it will unify them like you’d expect. It searches the current directory for .cue files, and if they all have the same package, they will be unified.
Packages are more clear in the context of «modules». Modules are the largest unit of organization. Basically every time you have a project that spans multiple files, you should create a module and name it with something that looks like the domain and path of a URL, e.g., example.com/something. When you import anything from this module, even from within the module, you must do so using the fully-qualified module path which will be prefixed with this module name.
You can create a new module like so:
1mkdir mymodule && cd mymodule
2cue mod init example.com/mymodule
This creates a cue.mod/ subdirectory within that mymodule directory, and cue.mod/ contains the following file and subdirectories:
module.cue(which defines your module name, in this case withmodule: "example.com/mymodule")- pkg/
- gen/
- usr/
For a different perspective on this and details about what’s in there, see cuelang.org/docs/concepts/packages/. For my purposes here, I’ll say you don’t need to think about the contents of this directory at all, except that your module name will be the prefix for all imports within your module.
Where will your module file hierarchy go? All files and directories for your module are rooted in mymodule/, the directory that also contains cue.mod/. If you want to import a package, you’ll prefix it with example.com/mymodule, followed by a relative path rooted in mymodule/.
To make it concrete, consider the following:
mymodule
├── config
│ ├── a.cue
│ └── b.cue
├── cue.mod
│ ├── module.cue
│ ├── pkg
│ └── usr
└── main.cue
cue.mod/ and the files underneath it were created by cue mod init example.com/mymodule. I then created the config/ subdirectory with a.cue and b.cue inside. Then I created main.cue to act as my top-level file to rule them all.
Running eval (no arguments) checks to see if there’s only one package in all .cue files in the current directory, and if so, it unifies them and outputs the result. In this case, there’s only main.cue with package main (nothing special about «main» there, it just seemed appropriate), so that’s the one.
1% cue eval
2configuredBar: 200
The contents of main.cue is:
1//main.cue
2
3package main
4import "example.com/mymodule/config"
5
6configuredBar: config.bar
config/a.cue and config/b.cue are files from earlier, except now they’ve both got package config at the top:
1//a.cue
2package config
3
4foo: 100
5bar: int
1//b.cue
2package config
3
4bar: 200
So there you go. If you want to verify that it’s actually unifying both files under config/, you can change bar: int to bar: string in a.cue and re-run cue eval to get a nice type error:
cue eval 2022-01-06 17:51:24
configuredBar: conflicting values string and 200 (mismatched types string and int):
./config/a.cue:4:6
./config/b.cue:3:6
./main.cue:5:16
That’s it for now. I understand there are more package management features coming in the future and the design decisions around cue.mod are looking ahead to that.
Finally, CUE has built-in modules with powerful functionality. We saw one of these earlier, when we imported «strings» and used strings.ToLower. Imports without fully-qualified module names are assumed to be built-ins. The full list and documentation for each is here: pkg.go.dev/cuelang.org/go/pkg
This has been a condensation of the official docs and tutorials, so go give the source material some love: cuelang.org/docs/tutorials/