CUE Configuration Language

CUE (pronounced 'cue' or 'Q') is a general-purpose, strongly typed, constraint-based language. It is designed for managing and reasoning over structured data, making it suitable for:

• Data templating
• Data validation
• Code generation
• Scripting
• Cloud configuration

CUE derives its formalism from relational programming languages, allowing for straightforward management of large datasets. The CUE tooling provides a scripting language for creating scripts and simple servers, also expressed in CUE.

CUE source code is represented as Unicode text encoded in UTF-8.

Key characteristics of CUE source text:

• Non-canonicalization: Accented characters are treated as distinct code points. For example, a single accented code point is different from a character constructed using a combining accent and a letter.
• Case sensitivity: Upper and lower case letters are distinct characters.
• NUL character: Compilers may disallow the NUL character (U+0000) for compatibility.
• Byte Order Mark (BOM): A UTF-8-encoded BOM (U+FEFF) may be ignored if it is the first code point, but may be disallowed elsewhere.

An embedded value is an operand used as a declaration within a struct. If the embedded value is a struct, it is unified with the enclosing struct.

Key behaviors:

• Bypassing Closure: Embedding allows you to bypass the restrictions of closed structs. If an embedding resolves to a closed struct, the enclosing struct becomes closed, but it may still contain fields that would otherwise be disallowed by standard closure rules.
• Non-struct embeddings: If an embedded value is not a struct, the enclosing struct may only contain definitions (#) or hidden fields (_), not regular fields.

S1: {
    a: 1
    b: 2
    { // This is an embedded value
        c: 3
    }
}
// S1 is { a: 1, b: 2, c: 3 }

S2: close({
    a: 1
    b: 2
    { 
        c: 3
    }
})
// S2 is equivalent to close(S1)

Comments are used for program documentation. CUE supports line comments starting with // that continue until the end of the line. A comment cannot start inside a string literal or inside another comment, and it acts like a newline.

// This is a line comment

A bound is a unary expression that defines a range of values using comparison operators (e.g., >= 2). In CUE, bounds act as a logical disjunction of all values that satisfy the comparison.

You can use bounds to constrain values during unification.

// Constraining a value within a range
2 & >=1 & <=5           // Result: 2
2.5 & int & >1 & <5     // Result: _|_ (bottom, because 2.5 is not an int)
>=0 & <=7 & >=3 & <=10  // Result: >=3 & <=7

The incorrect positional flag can be added to any assertion directive (e.g., eq, err, kind, closed). It marks an assertion as documenting the current known-incorrect behavior of a field.

• If the assertion passes: The test does NOT fail. The runner logs a NOTE stating that the documented incorrect behavior is still present.
• If the assertion fails: The test DOES FAIL. This indicates the behavior has changed, which may be a fix or a new regression.

It is commonly used alongside a :todo directive to document what the correct behavior should eventually be.

// Documents that the field currently produces 42 (wrong), and that it
// should eventually produce an error.
x: 42 @test(eq, 42, incorrect) @test(err:todo, p=1, code=eval)

Any :todo directive (such as eq:todo, err:todo, or @test(todo)) can include a p=N key-value argument to indicate the priority of the fix. This is purely informational and is included in log output; it does not affect pass/fail behavior.

• p=0: Critical (must fix immediately)
• p=1: Important (fix soon)
• p=2: Good to have (fix when convenient)

Higher integers indicate lower urgency.

x: 42 @test(eq:todo, 99, p=1)
x: 1/0 @test(err:todo, p=0, code=eval)
result: bad @test(eq, bad) @test(todo, p=2, why="low-priority cleanup")

Unification is the process of finding the greatest lower bound of two values a and b. In CUE, this is performed using the binary expression a & b.

Properties:

• Commutative: a & b == b & a
• Associative: (a & b) & c == a & (b & c)
• Idempotent: a & a == a
• Order of evaluation: Because of the properties above, the order in which you unify values does not change the result.

Unification Rules:

• The unification of a with itself is a.
• If a ⊑ b, then a & b is a.
• The unification of any value with bottom (_|_) is bottom.

({a:1} | {b:2}) & {c:3}   // Result: {a:1, c:3} | {b:2, c:3}
(int | string) & "foo"    // Result: "foo"
("a" | "b") & "c"         // Result: _|_

Selectors allow you to access fields within a struct. If the field exists, the selector returns its value. If the field does not exist, the expression results in bottom (_|_).

When using selectors on values with associated defaults, CUE selects the default value if the field is not explicitly present. This behavior applies to disjunctions as well: the selector is applied to each element in the disjunction.

Note that for quoted field names containing special characters (like hyphens), you must use string selector notation.

T: {
    x:     int
    y:     3
    "x-y": 4
}

a: T.x     // int
b: T.y     // 3
c: T.z     // _|_ (field 'z' not found)
d: T."x-y" // 4

e: {a: 1|*2} | *{a: 3|*4}
f: e.a  // 4 (default value selected)