Introduction
This is a reference manual for the CUE data constraint language.CUE, pronounced cue or Q, is a general-purpose and strongly typedconstraint-based language.It can be used for data templating, data validation, code generation, scripting,and many other applications involving structured data.The CUE tooling, layered on top of CUE, providesa general purpose scripting language for creating scripts as well assimple servers, also expressed in CUE.
CUE was designed with cloud configuration, and related systems, in mind,but is not limited to this domain.It derives its formalism from relational programming languages.This formalism allows for managing and reasoning over large amounts ofdata in a straightforward manner.
The grammar is compact and regular, allowing for easy analysis by automatictools such as integrated development environments.
This document is maintained by mpvl@golang.org.CUE has a lot of similarities with the Go language. This document draws heavilyfrom the Go specification as a result.
CUE draws its influence from many languages.Its main influences were BCL/ GCL (internal to Google),LKB (LinGO), Go, and JSON.Others are Swift, Typescript, Javascript, Prolog, NCL (internal to Google),Jsonnet, HCL, Flabbergast, Nix, JSONPath, Haskell, Objective-C, and Python.
Notation
The syntax is specified using Extended Backus-Naur Form (EBNF):
Production = production_name "=" [ Expression ] "." .Expression = Alternative { "|" Alternative } .Alternative = Term { Term } .Term = production_name | token [ "…" token ] | Group | Option | Repetition .Group = "(" Expression ")" .Option = "[" Expression "]" .Repetition = "{" Expression "}" .
Productions are expressions constructed from terms and the following operators,in increasing precedence:
| alternation() grouping[] option (0 or 1 times){} repetition (0 to n times)
Lower-case production names are used to identify lexical tokens. Non-terminalsare in CamelCase. Lexical tokens are enclosed in double quotes "" or back quotes``.
The form a … b represents the set of characters from a through b asalternatives. The horizontal ellipsis … is also used elsewhere in the spec toinformally denote various enumerations or code snippets that are not furtherspecified. The character … (as opposed to the three characters …) is not atoken of the CUE language.
Source code representation
Source code is Unicode text encoded in UTF-8.Unless otherwise noted, the text is not canonicalized, so a singleaccented code point is distinct from the same character constructed fromcombining an accent and a letter; those are treated as two code points.For simplicity, this document will use the unqualified term character to referto a Unicode code point in the source text.
Each code point is distinct; for instance, upper and lower case letters aredifferent characters.
Implementation restriction: For compatibility with other tools, a compiler maydisallow the NUL character (U+0000) in the source text.
Implementation restriction: For compatibility with other tools, a compiler mayignore a UTF-8-encoded byte order mark (U+FEFF) if it is the first Unicode codepoint in the source text. A byte order mark may be disallowed anywhere else inthe source.
Characters
The following terms are used to denote specific Unicode character classes:
newline = /* the Unicode code point U+000A */ .unicode_char = /* an arbitrary Unicode code point except newline */ .unicode_letter = /* a Unicode code point classified as "Letter" */ .unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ .
In The Unicode Standard 8.0, Section 4.5 “General Category” defines a set ofcharacter categories.CUE treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Loas Unicode letters, and those in the Number category Nd as Unicode digits.
Letters and digits
The underscore character _ (U+005F) is considered a letter.
letter = unicode_letter | "_" | "$" .decimal_digit = "0" … "9" .binary_digit = "0" … "1" .octal_digit = "0" … "7" .hex_digit = "0" … "9" | "A" … "F" | "a" … "f" .
Lexical elements
Comments
Comments serve as program documentation.CUE supports line comments that start with the character sequence //and stop at the end of the line.
A comment cannot start inside a string literal or inside a comment.A comment acts like a newline.
Tokens
Tokens form the vocabulary of the CUE language. There are four classes:identifiers, keywords, operators and punctuation, and literals. White space,formed from spaces (U+0020), horizontal tabs (U+0009), carriage returns(U+000D), and newlines (U+000A), is ignored except as it separates tokens thatwould otherwise combine into a single token. Also, a newline or end of file maytrigger the insertion of a comma. While breaking the input into tokens, thenext token is the longest sequence of characters that form a valid token.
Commas
The formal grammar uses commas “,” as terminators in a number of productions.CUE programs may omit most of these commas using the following two rules:
When the input is broken into tokens, a comma is automatically inserted intothe token stream immediately after a line’s final token if that token is
- an identifier, keyword, or bottom
- a number or string literal, including an interpolation
- one of the characters
)
,]
,}
, or?
- an ellipsis
...
Although commas are automatically inserted, the parser will requireexplicit commas between two list elements.
To reflect idiomatic use, examples in this document elide commas usingthese rules.
Identifiers
Identifiers name entities such as fields and aliases.An identifier is a sequence of one or more letters (which includes _
and $
)and digits, optionally preceded by #
or _#
.It may not be _
or $
.The first character in an identifier, or after an #
if it contains one,must be a letter.Identifiers starting with a #
or _
are reserved for definitions and hiddenfields.
identifier = [ "#" | "_#" ] letter { letter | unicode_digit } .
a_x9fieldNameαβ
Some identifiers are predeclared.
Keywords
CUE has a limited set of keywords.In addition, CUE reserves all identifiers starting with __
(double underscores)as keywords.These are typically targets of pre-declared identifiers.
All keywords may be used as labels (field names).Unless noted otherwise, they can also be used as identifiers to refer tothe same name.
Values
The following keywords are values.
null true false
These can never be used to refer to a field of the same name.This restriction is to ensure compatibility with JSON configuration files.
Preamble
The following keywords are used at the preamble of a CUE file.After the preamble, they may be used as identifiers to refer to namesake fields.
package import
Comprehension clauses
The following keywords are used in comprehensions.
for in if let
Operators and punctuation
The following character sequences represent operators and punctuation:
+ && == < = ( )- || != > : { }* & =~ <= ? [ ] ,/ | !~ >= ! _|_ ... .
Numeric literals
There are several kinds of numeric literals.
int_lit = decimal_lit | si_lit | octal_lit | binary_lit | hex_lit .decimal_lit = "0" | ( "1" … "9" ) { [ "_" ] decimal_digit } .decimals = decimal_digit { [ "_" ] decimal_digit } .si_it = decimals [ "." decimals ] multiplier | "." decimals multiplier .binary_lit = "0b" binary_digit { binary_digit } .hex_lit = "0" ( "x" | "X" ) hex_digit { [ "_" ] hex_digit } .octal_lit = "0o" octal_digit { [ "_" ] octal_digit } .multiplier = ( "K" | "M" | "G" | "T" | "P" ) [ "i" ]float_lit = decimals "." [ decimals ] [ exponent ] | decimals exponent | "." decimals [ exponent ].exponent = ( "e" | "E" ) [ "+" | "-" ] decimals .
An integer literal is a sequence of digits representing an integer value.An optional prefix sets a non-decimal base: 0o for octal,0x or 0X for hexadecimal, and 0b for binary.In hexadecimal literals, letters a-f and A-F represent values 10 through 15.All integers allow interstitial underscores “_";these have no meaning and are solely for readability.
Integer literals may have an SI or IEC multiplier.Multipliers can be used with fractional numbers.When multiplying a fraction by a multiplier, the result is truncatedtowards zero if it is not an integer.
421.5G // 1_000_000_0001.3Ki // 1.3 * 1024 = trunc(1331.2) = 1331170_141_183_460_469_231_731_687_303_715_884_105_7270xBad_Face0o7550b0101_0001
A decimal floating-point literal is a representation ofa decimal floating-point value (a float).It has an integer part, a decimal point, a fractional part, and anexponent part.The integer and fractional part comprise decimal digits; theexponent part is an e
or E
followed by an optionally signed decimal exponent.One of the integer part or the fractional part may be elided; one of the decimalpoint or the exponent may be elided.
0.72.40072.40 // == 72.402.718281.e+06.67428e-111E6.25.12345E+5
Neither a float_lit
nor an si_lit
may appear after a token that is:
- an identifier, keyword, or bottom
- a number or string literal, including an interpolation
- one of the characters
)
,]
,}
,?
, or.
.
String and byte sequence literals
A string literal represents a string constant obtained from concatenating asequence of characters.Byte sequences are a sequence of bytes.
String and byte sequence literals are character sequences between,respectively, double and single quotes, as in "bar"
and 'bar'
.Within the quotes, any character may appear except newline and,respectively, unescaped double or single quote.String literals may only be valid UTF-8.Byte sequences may contain any sequence of bytes.
Several escape sequences allow arbitrary values to be encoded as ASCII text.An escape sequence starts with an escape delimiter, which is \
by default.The escape delimiter may be altered to be \
plus a fixed number ofhash symbols #
by padding the start and end of a string or byte sequence literalwith this number of hash symbols.
There are four ways to represent the integer value as a numeric constant: \x
followed by exactly two hexadecimal digits; \u
followed by exactly fourhexadecimal digits; \U
followed by exactly eight hexadecimal digits, and aplain backslash \
followed by exactly three octal digits.In each case the value of the literal is the value represented by thedigits in the corresponding base.Hexadecimal and octal escapes are only allowed within byte sequences(single quotes).
Although these representations all result in an integer, they have differentvalid ranges.Octal escapes must represent a value between 0 and 255 inclusive.Hexadecimal escapes satisfy this condition by construction.The escapes \u
and \U
represent Unicode code points so within themsome values are illegal, in particular those above 0x10FFFF
.Surrogate halves are allowed,but are translated into their non-surrogate equivalent internally.
The three-digit octal (\nnn
) and two-digit hexadecimal (\xnn
) escapesrepresent individual bytes of the resulting string; all other escapes representthe (possibly multi-byte) UTF-8 encoding of individual characters.Thus inside a string literal \377
and \xFF
represent a single byte ofvalue 0xFF=255
, while ÿ
, \u00FF
, \U000000FF
and \xc3\xbf
representthe two bytes 0xc3 0xbf
of the UTF-8encoding of character U+00FF
.
\a U+0007 alert or bell\b U+0008 backspace\f U+000C form feed\n U+000A line feed or newline\r U+000D carriage return\t U+0009 horizontal tab\v U+000b vertical tab\/ U+002f slash (solidus)\\ U+005c backslash\' U+0027 single quote (valid escape only within single quoted literals)\" U+0022 double quote (valid escape only within double quoted literals)
The escape \(
is used as an escape for string interpolation.A \(
must be followed by a valid CUE Expression, followed by a )
.
All other sequences starting with a backslash are illegal inside literals.
escaped_char = `\` { `#` } ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | "/" | `\` | "'" | `"` ) .byte_value = octal_byte_value | hex_byte_value .octal_byte_value = `\` { `#` } octal_digit octal_digit octal_digit .hex_byte_value = `\` { `#` } "x" hex_digit hex_digit .little_u_value = `\` { `#` } "u" hex_digit hex_digit hex_digit hex_digit .big_u_value = `\` { `#` } "U" hex_digit hex_digit hex_digit hex_digit hex_digit hex_digit hex_digit hex_digit .unicode_value = unicode_char | little_u_value | big_u_value | escaped_char .interpolation = "\" { `#` } "(" Expression ")" .string_lit = simple_string_lit | multiline_string_lit | simple_bytes_lit | multiline_bytes_lit | `#` string_lit `#` .simple_string_lit = `"` { unicode_value | interpolation } `"` .simple_bytes_lit = `'` { unicode_value | interpolation | byte_value } `'` .multiline_string_lit = `"""` newline { unicode_value | interpolation | newline } newline `"""` .multiline_bytes_lit = "'''" newline { unicode_value | interpolation | byte_value | newline } newline "'''" .
Carriage return characters (\r
) inside string literals are discarded fromthe string value.
'a\000\xab''\007''\377''\xa' // illegal: too few hexadecimal digits"\n""\""'Hello, world!\n'"Hello, \( name )!""日本語""\u65e5本\U00008a9e"'\xff\u00FF'"\uD800" // illegal: surrogate half (TODO: probably should allow)"\U00110000" // illegal: invalid Unicode code point#"This is not an \(interpolation)"##"This is an \#(interpolation)"##"The sequence "\U0001F604" renders as \#U0001F604."#
These examples all represent the same string:
"日本語" // UTF-8 input text'日本語' // UTF-8 input text as byte sequence"\u65e5\u672c\u8a9e" // the explicit Unicode code points"\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points'\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e' // the explicit UTF-8 bytes
If the source code represents a character as two code points, such as acombining form involving an accent and a letter, the result will appear as twocode points if placed in a string literal.
Strings and byte sequences have a multiline equivalent.Multiline strings are like their single-line equivalent,but allow newline characters.
Multiline strings and byte sequences respectively start witha triple double quote ("""
) or triple single quote ('''
),immediately followed by a newline, which is discarded from the string contents.The string is closed by a matching triple quote, which must be by itselfon a newline, preceded by optional whitespace.The newline preceding the closing quote is discarded from the string contents.The whitespace before a closing triple quote must appear before any non-emptyline after the opening quote and will be removed from each of theselines in the string literal.A closing triple quote may not appear in the string.To include it is suffices to escape one of the quotes.
""" lily: out of the water out of itself bass picking bugs off the moon — Nick Virgilio, Selected Haiku, 1988 """
This represents the same string as:
"lily:\nout of the water\nout of itself\n\n" +"bass\npicking bugs\noff the moon\n" +" — Nick Virgilio, Selected Haiku, 1988"
Values
In addition to simple values like "hello"
and 42.0
, CUE has structs.A struct is a map from labels to values, like {a: 42.0, b: "hello"}
.Structs are CUE’s only way of building up complex values;lists, which we will see later,are defined in terms of structs.
All possible values are ordered in a lattice,a partial order where every two elements have a single greatest lower bound.A value a
is an instance of a value b
,denoted a ⊑ b
, if b == a
or b
is more general than a
,that is if a
orders before b
in the partial order(⊑
is not a CUE operator).We also say that b
subsumes a
in this case.In graphical terms, b
is “above” a
in the lattice.
At the top of the lattice is the single ancestor of all values, calledtop, denoted _
in CUE.Every value is an instance of top.
At the bottom of the lattice is the value called bottom, denoted _|_
.A bottom value usually indicates an error.Bottom is an instance of every value.
An atom is any value whose only instances are itself and bottom.Examples of atoms are 42.0
, "hello"
, true
, null
.
A value is concrete if it is either an atom, or a struct all of whosefield values are themselves concrete, recursively.
CUE’s values also include what we normally think of as types, like string
andfloat
.But CUE does not distinguish between types and values; only therelationship of values in the lattice is important.Each CUE “type” subsumes the concrete values that one would normally thinkof as part of that type.For example, “hello” is an instance of string
, and 42.0
is an instance offloat
.In addition to string
and float
, CUE has null
, int
, bool
and bytes
.We informally call these CUE’s “basic types”.
false ⊑ booltrue ⊑ booltrue ⊑ true5.0 ⊑ floatbool ⊑ __|_ ⊑ __|_ ⊑ _|__ ⋢ _|__ ⋢ boolint ⋢ boolbool ⋢ intfalse ⋢ truetrue ⋢ falsefloat ⋢ 5.05 ⋢ 6
Unification
The unification of values a
and b
is defined as the greatest lower bound of a
and b
. (That is, thevalue u
such that u ⊑ a
and u ⊑ b
,and for any other value v
for which v ⊑ a
and v ⊑ b
it holds that v ⊑ u
.)Since CUE values form a lattice, the unification of two CUE values isalways unique.
These all follow from the definition of unification:
- The unification of
a
with itself is alwaysa
. - The unification of values
a
andb
wherea ⊑ b
is alwaysa
. - The unification of a value with bottom is always bottom.
Unification in CUE is a binary expression, written a & b
.It is commutative and associative.As a consequence, order of evaluation is irrelevant, a property that is keyto many of the constructs in the CUE language as well as the tooling layeredon top of it.
Disjunction
The disjunction of values a
and b
is defined as the least upper bound of a
and b
.(That is, the value d
such that a ⊑ d
and b ⊑ d
,and for any other value e
for which a ⊑ e
and b ⊑ e
,it holds that d ⊑ e
.)This style of disjunctions is sometimes also referred to as sum types.Since CUE values form a lattice, the disjunction of two CUE values is always unique.
These all follow from the definition of disjunction:
- The disjunction of
a
with itself is alwaysa
. - The disjunction of a value
a
andb
wherea ⊑ b
is alwaysb
. - The disjunction of a value
a
with bottom is alwaysa
. - The disjunction of two bottom values is bottom.
Disjunction in CUE is a binary expression, written a | b
.It is commutative, associative, and idempotent.
The unification of a disjunction with another value is equal to the disjunctioncomposed of the unification of this value with all of the original elementsof the disjunction.In other words, unification distributes over disjunction.
(a_0 | ... |a_n) & b ==> a_0&b | ... | a_n&b.
Expression Result({a:1} | {b:2}) & {c:3} {a:1, c:3} | {b:2, c:3}(int | string) & "foo" "foo"("a" | "b") & "c" _|_
A disjunction is normalized if there is no elementa
for which there is an element b
such that a ⊑ b
.
Default values
Any value v
may be associated with a default value d
,where d
must be in instance of v
(d ⊑ v
).
Default values are introduced by means of disjunctions.Any element of a disjunction can be marked as a defaultby prefixing it with an asterisk *
(a unary expression).Syntactically consecutive disjunctions are considered to bepart of a single disjunction,whereby multiple disjuncts can be marked as default.A marked disjunction is one where any of its terms are marked.So a | b | *c | d
is a single marked disjunction of four terms,whereas a | (b | *c | d)
is an unmarked disjunction of two terms,one of which is a marked disjunction of three terms.During unification, if all the marked disjuncts of a marked disjunction areeliminated, then the remaining unmarked disjuncts are considered as if theyoriginated from an unmarked disjunction
As explained below, distinguishing the nesting of disjunctions like thisis only relevant when both an outer and nested disjunction are marked.
Intuitively, when an expression needs to be resolved for an operation otherthan unification or disjunction,non-starred elements are dropped in favor of starred ones if the starred onesdo not resolve to bottom.
To define the unification and disjunction operation we use the notation⟨v⟩
to denote a CUE value v
that is not associated with a defaultand the notation ⟨v, d⟩
to denote a value v
associated with a defaultvalue d
.
The rewrite rules for unifying such values are as follows:
U0: ⟨v1⟩ & ⟨v2⟩ => ⟨v1&v2⟩U1: ⟨v1, d1⟩ & ⟨v2⟩ => ⟨v1&v2, d1&v2⟩U2: ⟨v1, d1⟩ & ⟨v2, d2⟩ => ⟨v1&v2, d1&d2⟩
The rewrite rules for disjoining terms of unmarked disjunctions are
D0: ⟨v1⟩ | ⟨v2⟩ => ⟨v1|v2⟩D1: ⟨v1, d1⟩ | ⟨v2⟩ => ⟨v1|v2, d1⟩D2: ⟨v1, d1⟩ | ⟨v2, d2⟩ => ⟨v1|v2, d1|d2⟩
Terms of marked disjunctions are first rewritten according to the followingrules:
M0: ⟨v⟩ => ⟨v⟩ don't introduce defaults for unmarked termM1: *⟨v⟩ => ⟨v, v⟩ introduce identical default for marked termM2: *⟨v, d⟩ => ⟨v, d⟩ keep existing defaults for marked termM3: ⟨v, d⟩ => ⟨v⟩ strip existing defaults from unmarked term
Note that for any marked disjunction a
,the expressions a|a
, *a|a
and *a|*a
all resolve to a
.
Expression Value-default pair Rules applied*"tcp" | "udp" ⟨"tcp"|"udp", "tcp"⟩ M1, D1string | *"foo" ⟨string, "foo"⟩ M1, D1*1 | 2 | 3 ⟨1|2|3, 1⟩ M1, D1(*1|2|3) | (1|*2|3) ⟨1|2|3, 1|2⟩ M1, D1, D2(*1|2|3) | *(1|*2|3) ⟨1|2|3, 2⟩ M1, M2, M3, D1, D2(*1|2|3) | (1|*2|3)&2 ⟨1|2|3, 1|2⟩ M1, D1, U1, D2(*1|2) & (1|*2) ⟨1|2, _|_⟩ M1, D1, U2
The rules of subsumption for defaults can be derived from the above definitionsand are as follows.
⟨v2, d2⟩ ⊑ ⟨v1, d1⟩ if v2 ⊑ v1 and d2 ⊑ d1⟨v1, d1⟩ ⊑ ⟨v⟩ if v1 ⊑ v⟨v⟩ ⊑ ⟨v1, d1⟩ if v ⊑ d1
Expression Resolves to"tcp" | "udp" "tcp" | "udp"*"tcp" | "udp" "tcp"float | *1 1*string | 1.0 string(*1|2) + (2|*3) 4(*1|2|3) | (1|*2|3) 1|2(*1|2|3) & (1|*2|3) 1|2|3 // default is _|_(* >=5 | int) & (* <=5 | int) 5(*"tcp"|"udp") & ("udp"|*"tcp") "tcp"(*"tcp"|"udp") & ("udp"|"tcp") "tcp"(*"tcp"|"udp") & "tcp" "tcp"(*"tcp"|"udp") & (*"udp"|"tcp") "tcp" | "udp" // default is _|_(*true | false) & bool true(*true | false) & (true | false) true{a: 1} | {b: 1} {a: 1} | {b: 1}{a: 1} | *{b: 1} {b:1}*{a: 1} | *{b: 1} {a: 1} | {b: 1}({a: 1} | {b: 1}) & {a:1} {a:1} | {a: 1, b: 1}({a:1}|*{b:1}) & ({a:1}|*{b:1}) {b:1}
Bottom and errors
Any evaluation error in CUE results in a bottom value, represented bythe token _|_
.Bottom is an instance of every other value.Any evaluation error is represented as bottom.
Implementations may associate error strings with different instances of bottom;logically they all remain the same value.
bottom_lit = "_|_" .
Top
Top is represented by the underscore character _
, lexically an identifier.Unifying any value v
with top results v
itself.
Expr Result_ & 5 5_ & _ __ & _|_ _|__ | _|_ _
Null
The null value is represented with the keyword null
.It has only one parent, top, and one child, bottom.It is unordered with respect to any other value.
null_lit = "null" .
null & 8 _|_null & _ nullnull & _|_ _|_
Boolean values
A boolean type represents the set of Boolean truth values denoted bythe keywords true
and false
.The predeclared boolean type is bool
; it is a defined type and a separateelement in the lattice.
bool_lit = "true" | "false" .
bool & true truetrue & true truetrue & false _|_bool & (false|true) false | truebool & (true|false) true | false
Numeric values
The integer type represents the set of all integral numbers.The decimal floating-point type represents the set of all decimal floating-pointnumbers.They are two distinct types.Both are instances instances of a generic number
type.
The predeclared number, integer, decimal floating-point types arenumber
, int
and float
; they are defined types.
A decimal floating-point literal always has type float
;it is not an instance of int
even if it is an integral number.
Integer literals are always of type int
and don’t match type float
.
Numeric literals are exact values of arbitrary precision.If the operation permits it, numbers should be kept in arbitrary precision.
Implementation restriction: although numeric values have arbitrary precisionin the language, implementations may implement them using an internalrepresentation with limited precision.That said, every implementation must:
- Represent integer values with at least 256 bits.
- Represent floating-point values, with a mantissa of at least 256 bits anda signed binary exponent of at least 16 bits.
- Give an error if unable to represent an integer value precisely.
- Give an error if unable to represent a floating-point value due to overflow.
- Round to the nearest representable value if unable to representa floating-point value due to limits on precision.These requirements apply to the result of any expression except for builtinfunctions for which an unusual loss of precision must be explicitly documented.
Strings
The string type represents the set of UTF-8 strings,not allowing surrogates.The predeclared string type is string
; it is a defined type.
The length of a string s
(its size in bytes) can be discovered usingthe built-in function len
.
Bytes
The bytes type represents the set of byte sequences.A byte sequence value is a (possibly empty) sequence of bytes.The number of bytes is called the length of the byte sequenceand is never negative.The predeclared byte sequence type is bytes
; it is a defined type.
Bounds
A bound, syntactically a unary expression, definesan infinite disjunction of concrete values than can be representedas a single comparison.
For any comparison operator op
except ==
,op a
is the disjunction of every x
such that x op a
.
2 & >=2 & <=5 // 2, where 2 is either an int or float.2.5 & >=1 & <=5 // 2.52 & >=1.0 & <3.0 // 2.02 & >1 & <3.0 // 2.02.5 & int & >1 & <5 // _|_2.5 & float & >1 & <5 // 2.5int & 2 & >1.0 & <3.0 // _|_2.5 & >=(int & 1) & <5 // _|_>=0 & <=7 & >=3 & <=10 // >=3 & <=7!=null & 1 // 1>=5 & <=5 // 5
Structs
A struct is a set of elements called fields, each ofwhich has a name, called a label, and value.
We say a label is defined for a struct if the struct has a field with thecorresponding label.The value for a label f
of struct a
is denoted a.f
.A struct a
is an instance of b
, or a ⊑ b
, if for any label f
defined for b
, label f
is also defined for a
and a.f ⊑ b.f
.Note that if a
is an instance of b
it may have fields with labels thatare not defined for b
.
The (unique) struct with no fields, written {}
, has every struct as aninstance. It can be considered the type of all structs.
{a: 1} ⊑ {}{a: 1, b: 1} ⊑ {a: 1}{a: 1} ⊑ {a: int}{a: 1, b: 1.0} ⊑ {a: int, b: float}{} ⋢ {a: 1}{a: 2} ⋢ {a: 1}{a: 1} ⋢ {b: 1}
A field may be required or optional.The successful unification of structs a
and b
is a new struct c
whichhas all fields of both a
and b
, wherethe value of a field f
in c
is a.f & b.f
if f
is in both a
and b
,or just a.f
or b.f
if f
is in just a
or b
, respectively.If a field f
is in both a
and b
, c.f
is optional only if botha.f
and b.f
are optional.Any references to a
or b
in their respective field values need to be replaced with references to c
.The result of a unification is bottom (_|_
) if any of its non-optionalfields evaluates to bottom, recursively.
Syntactically, a field is marked as optional by following its label with a ?
.The question mark is not part of the field name.A struct literal may contain multiple fields withthe same label, the result of which is a single field with the same propertiesas defined as the unification of two fields resulting from unifying two structs.
These examples illustrate required fields only.Examples with optional fields follow below.
Expression Result (without optional fields){a: int, a: 1} {a: 1}{a: int} & {a: 1} {a: 1}{a: >=1 & <=7} & {a: >=5 & <=9} {a: >=5 & <=7}{a: >=1 & <=7, a: >=5 & <=9} {a: >=5 & <=7}{a: 1} & {b: 2} {a: 1, b: 2}{a: 1, b: int} & {b: 2} {a: 1, b: 2}{a: 1} & {a: 2} _|_
A struct may define constraints that apply to fields that are added when unifiedwith another struct using pattern or default constraints (Note: defaultconstraints are not yet implemented).
A pattern constraint, denoted [pattern]: value
, defines a pattern, whichis a value of type string, and a value to unify with fields whose labelmatch that pattern.When unifying structs a
and b
,a pattern constraint [p]: v
declared in a
defines that the value v
should unify with any field in the resulting struct c
whose label unifies with pattern p
.
Additionally, a default constraint, denoted ...value
, defines a valueto unify with any field for which there is no other declaration in a struct.When unifying structs a
and b
,a default constraint ...v
declared in a
defines that the value v
should unify with any field in the resulting struct c
whose label does not unify with any of the patterns of the patternconstraints defined for a
and for which there exists no field in a
with that label.The token ...
is a shorthand for ..._
.Note: default constraints are not yet implemented.
a: { foo: string // foo is a string [=~"^i"]: int // all other fields starting with i are integers [=~"^b"]: bool // all other fields starting with b are booleans ...string // all other fields must be a string. Note: default constraints are not yet implemented.}b: a & { i3: 3 bar: true other: "a string"}
Concrete field labels may be an identifier or string, the latter of which may beinterpolated.Fields with identifier labels can be referred to within the scope they aredefined, string labels cannot.References within such interpolated strings are resolved withinthe scope of the struct in which the label sequence isdefined and can reference concrete labels lexically precedingthe label within a label sequence.
StructLit = "{" { Declaration "," } "}" .Declaration = Field | Ellipsis | Embedding | LetClause | attribute .Ellipsis = "..." [ Expression ] .Embedding = Comprehension | AliasExpr .Field = Label ":" { Label ":" } AliasExpr { attribute } .Label = [ identifier "=" ] LabelExpr .LabelExpr = LabelName [ "?" ] | "[" AliasExpr "]" .LabelName = identifier | simple_string_lit .attribute = "@" identifier "(" attr_tokens ")" .attr_tokens = { attr_token | "(" attr_tokens ")" | "[" attr_tokens "]" | "{" attr_tokens "}" } .attr_token = /* any token except '(', ')', '[', ']', '{', or '}' */
Expression Result (without optional fields)a: { foo?: string } {}b: { foo: "bar" } { foo: "bar" }c: { foo?: *"bar" | string } {}d: a & b { foo: "bar" }e: b & c { foo: "bar" }f: a & c {}g: a & { foo?: number } {}h: b & { foo?: number } _|_i: c & { foo: string } { foo: "bar" }intMap: [string]: intintMap: { t1: 43 t2: 2.4 // error: 2.4 is not an integer}nameMap: [string]: { firstName: string nickName: *firstName | string}nameMap: hank: { firstName: "Hank" }
The optional field set defined by nameMap
matches every field,in this case just hank
, and unifies the associated constraintwith the matched field, resulting in:
nameMap: hank: { firstName: "Hank" nickName: "Hank"}
Closed structs
By default, structs are open to adding fields.Instances of an open struct p
may contain fields not defined in p
.This is makes it easy to add fields, but can lead to bugs:
S: { field1: string}S1: S & { field2: "foo" }// S1 is { field1: string, field2: "foo" }A: { field1: string field2: string}A1: A & { feild1: "foo" // "field1" was accidentally misspelled}// A1 is// { field1: string, field2: string, feild1: "foo" }// not the intended// { field1: "foo", field2: string }
A closed struct c
is a struct whose instances may not declare any fieldwith a name that does not match the name of a fieldor the pattern of a pattern constraint defined in c
.Hidden fields are excluded from this limitation.A struct that is the result of unifying any struct with a ...declaration is defined for all regular fields.Closing a struct is equivalent to adding ..._|_
to it.
Syntactically, structs are closed explicitly with the close
builtin orimplicitly and recursively by definitions.
A: close({ field1: string field2: string})A1: A & { feild1: string} // _|_ feild1 not defined for AA2: A & { for k,v in { feild1: string } { k: v }} // _|_ feild1 not defined for AC: close({ [_]: _})C2: C & { for k,v in { thisIsFine: string } { "\(k)": v }}D: close({ // Values generated by comprehensions are treated as embeddings. for k,v in { x: string } { "\(k)": v }})
Embedding
A struct may contain an embedded value, an operand used as a declaration.An embedded value of type struct is unified with the struct in which it isembedded, but disregarding the restrictions imposed by closed structs.So if an embedding resolves to a closed struct, the corresponding enclosingstruct will also be closed, but may have fields that are not allowed ifnormal rules for closed structs were observed.
If an embedded value is not of type struct, the struct may only havedefinitions or hidden fields. Regular fields are not allowed in such case.
The result of { A }
is A
for any A
(including definitions).
Syntactically, embeddings may be any expression.
S1: { a: 1 b: 2 { c: 3 }}// S1 is { a: 1, b: 2, c: 3 }S2: close({ a: 1 b: 2 { c: 3 }})// same as close(S1)S3: { a: 1 b: 2 close({ c: 3 })}// same as S2
Definitions and hidden fields
A field is a definition if its identifier starts with #
or _#
.A field is hidden if its identifier starts with a _
.All other fields are regular.
Definitions and hidden fields are not emitted when converting a CUE programto data and are never required to be concrete.
Referencing a definition will recursively close it.That is, a referenced definition will not unify with a structthat would add a field anywhere within the definition that it does notalready define or explicitly allow with a pattern constraint or ...
.Embeddings allow bypassing this check.
If referencing a definition would always result in an error, implementationsmay report this inconsistency at the point of its declaration.
#MyStruct: { sub: field: string}#MyStruct: { sub: enabled?: bool}myValue: #MyStruct & { sub: feild: 2 // error, feild not defined in #MyStruct sub: enabled: true // okay}#D: { #OneOf c: int // adds this field.}#OneOf: { a: int } | { b: int }D1: #D & { a: 12, c: 22 } // { a: 12, c: 22 }D2: #D & { a: 12, b: 33 } // _|_ // cannot define both `a` and `b`
#A: {a: int}B: { #A b: c: int}x: Bx: d: 3 // not allowed, as closed by embedded #Ay: B.by: d: 3 // allowed as nothing closes b#B: { #A b: c: int}z: #B.bz: d: 3 // not allowed, as referencing #B closes b
Attributes
Attributes allow associating meta information with values.Their primary purpose is to define mappings between CUE andother representations.Attributes do not influence the evaluation of CUE.
An attribute associates an identifier with a value, a balanced token sequence,which is a sequence of CUE tokens with balanced brackets (()
, []
, and {}
).The sequence may not contain interpolations.
Fields, structs and packages can be associated with a set of attributes.Attributes accumulate during unification, but implementations may removeduplicates that have the same source string representation.The interpretation of an attribute, including the handling of multipleattributes for a given identifier, is up to the consumer of the attribute.
Field attributes define additional information about a field,such as a mapping to a protocol buffer tag or alternativename of the field when mapping to a different language.
// Package attribute@protobuf(proto3)myStruct1: { // Struct attribute: @jsonschema(id="https://example.org/mystruct1.json") // Field attributes field: string @go(Field) attr: int @xml(,attr) @go(Attr)}myStruct2: { field: string @go(Field) attr: int @xml(a1,attr) @go(Attr)}Combined: myStruct1 & myStruct2// field: string @go(Field)// attr: int @xml(,attr) @xml(a1,attr) @go(Attr)
Aliases
Aliases name values that can be referred towithin the scope in which they are declared.The name of an alias must be unique within its scope.
AliasExpr = [ identifier "=" ] Expression .
Aliases can appear in several positions:
In front of a Label (X=label: value
):
- binds the identifier to the same value as
label
would be boundto if it were a valid identifier. - for optional fields (
foo?: bar
and[foo]: bar
),the bound identifier is only visible within the field value (bar
).
Before a value (foo: X=x
)
- binds the identifier to the value it precedes within the scope of that value.
Inside a bracketed label ([X=expr]: value
):
- binds the identifier to the concrete label that matches
expr
within the instances of the field value (value
).
Before a list element ([ X=value, X+1 ]
) (Not yet implemented)
- binds the identifier to the list element it precedes within the scope of thelist expression.
// A field aliasfoo: X // 4X="not an identifier": 4// A value aliasfoo: X={x: X.a}bar: foo & {a: 1} // {a: 1, x: 1}// A label alias[Y=string]: { name: Y }foo: { value: 1 } // outputs: foo: { name: "foo", value: 1 }
Let declarations
Let declarations bind an identifier to an expression.The identifier is visible within the scopein which it is declared.The identifier must be unique within its scope.
let x = expra: x + 1b: x + 2
Shorthand notation for nested structs
A field whose value is a struct with a single field may be written asa colon-separated sequence of the two field names,followed by a colon and the value of that single field.
job: myTask: replicas: 2
expands to
job: { myTask: { replicas: 2 }}
Lists
A list literal defines a new value of type list.A list may be open or closed.An open list is indicated with a ...
at the end of an element list,optionally followed by a value for the remaining elements.
The length of a closed list is the number of elements it contains.The length of an open list is the number of elements as a lower boundand an unlimited number of elements as its upper bound.
ListLit = "[" [ ElementList [ "," ] ] "]" .ElementList = Ellipsis | Embedding { "," Embedding } [ "," Ellipsis ] .
Lists can be thought of as structs:
List: *null | { Elem: _ Tail: List}
For closed lists, Tail
is null
for the last element, for open lists it is*null | List
, defaulting to the shortest variant.For instance, the open list [ 1, 2, … ] can be represented as:
open: List & { Elem: 1, Tail: { Elem: 2 } }
and the closed version of this list, [ 1, 2 ], as
closed: List & { Elem: 1, Tail: { Elem: 2, Tail: null } }
Using this representation, the subsumption rule for lists canbe derived from those of structs.Implementations are not required to implement lists as structs.The Elem
and Tail
fields are not special and len
will not work asexpected in these cases.
Declarations and Scopes
Blocks
A block is a possibly empty sequence of declarations.The braces of a struct literal { ... }
form a block, but there areothers as well:
- The universe block encompasses all CUE source text.
- Each package has a package blockcontaining all CUE source text in that package.
- Each file has a file block containing all CUE source text in that file.
- Each
for
andlet
clause in a comprehensionis considered to be its own implicit block.
Blocks nest and influence scoping.
Declarations and scope
A declaration may bind an identifier to a field, alias, or package.Every identifier in a program must be declared.Other than for fields,no identifier may be declared twice within the same block.For fields, an identifier may be declared more than once within the same block,resulting in a field with a value that is the result of unifying the valuesof all fields with the same identifier.String labels do not bind an identifier to the respective field.
The scope of a declared identifier is the extent of source text in which theidentifier denotes the specified field, alias, or package.
CUE is lexically scoped using blocks:
- The scope of a predeclared identifier is the universe block.
- The scope of an identifier denoting a fielddeclared at top level (outside any struct literal) is the package block.
- The scope of an identifier denoting an aliasdeclared at top level (outside any struct literal) is the file block.
- The scope of a let identifierdeclared at top level (outside any struct literal) is the file block.
- The scope of the package name of an imported package is the file block of thefile containing the import declaration.
- The scope of a field, alias or let identifier declared inside a structliteral is the innermost containing block.
An identifier declared in a block may be redeclared in an inner block.While the identifier of the inner declaration is in scope, it denotes the entitydeclared by the inner declaration.
The package clause is not a declaration;the package name does not appear in any scope.Its purpose is to identify the files belonging to the same packageand to specify the default name for import declarations.
Predeclared identifiers
CUE predefines a set of types and builtin functions.For each of these there is a corresponding keyword which is the nameof the predefined identifier, prefixed with __
.
Functionslen close and orTypesnull The null type and valuebool All boolean valuesint All integral numbersfloat All decimal floating-point numbersstring Any valid UTF-8 sequencebytes Any valid byte sequenceDerived Valuenumber int | floatuint >=0uint8 >=0 & <=255int8 >=-128 & <=127uint16 >=0 & <=65536int16 >=-32_768 & <=32_767rune >=0 & <=0x10FFFFuint32 >=0 & <=4_294_967_296int32 >=-2_147_483_648 & <=2_147_483_647uint64 >=0 & <=18_446_744_073_709_551_615int64 >=-9_223_372_036_854_775_808 & <=9_223_372_036_854_775_807uint128 >=0 & <=340_282_366_920_938_463_463_374_607_431_768_211_455int128 >=-170_141_183_460_469_231_731_687_303_715_884_105_728 & <=170_141_183_460_469_231_731_687_303_715_884_105_727float32 >=-3.40282346638528859811704183484516925440e+38 & <=3.40282346638528859811704183484516925440e+38float64 >=-1.797693134862315708145274237317043567981e+308 & <=1.797693134862315708145274237317043567981e+308
Exported identifiers
An identifier of a package may be exported to permit access to itfrom another package.All identifiers not starting with _
(so all regular fields and definitionsstarting with #
) are exported.Any identifier starting with _
is not visible outside the package and residesin a separate namespace than namesake identifiers of other packages.
package mypackagefoo: string // visible outside mypackage"bar": string // visible outside mypackage#Foo: { // visible outside mypackage a: 1 // visible outside mypackage _b: 2 // not visible outside mypackage #C: { // visible outside mypackage d: 4 // visible outside mypackage } _#E: foo // not visible outside mypackage}
Uniqueness of identifiers
Given a set of identifiers, an identifier is called unique if it is differentfrom every other in the set, after applying normalization followingUnicode Annex #31.Two identifiers are different if they are spelled differentlyor if they appear in different packages and are not exported.Otherwise, they are the same.
Field declarations
A field associates the value of an expression to a label within a struct.If this label is an identifier, it binds the field to that identifier,so the field’s value can be referenced by writing the identifier.String labels are not bound to fields.
a: { b: 2 "s": 3 c: b // 2 d: s // _|_ unresolved identifier "s" e: a.s // 3}
If an expression may result in a value associated with a default valueas described in default values, the field binds to thisvalue-default pair.
Let declarations
Within a struct, a let clause binds an identifier to the given expression.
Within the scope of the identifier, the identifier refers to thelocally declared expression.The expression is evaluated in the scope it was declared.
Expressions
An expression specifies the computation of a value by applying operators andbuilt-in functions to operands.
Expressions that require concrete values are called incomplete if any oftheir operands are not concrete, but define a value that would be legal forthat expression.Incomplete expressions may be left unevaluated until a concrete value isrequested at the application level.
Operands
Operands denote the elementary values in an expression.An operand may be a literal, a (possibly qualified) identifier denotingfield, alias, or let declaration, or a parenthesized expression.
Operand = Literal | OperandName | "(" Expression ")" .Literal = Basicl*t | ListLit | StructLit .Basicl*t = int_lit | float_lit | string_lit | null_lit | bool_lit | bottom_lit .OperandName = identifier | QualifiedIdent .
Qualified identifiers
A qualified identifier is an identifier qualified with a package name prefix.
QualifiedIdent = PackageName "." identifier .
A qualified identifier accesses an identifier in a different package,which must be imported.The identifier must be declared in the package block of that package.
math.Sin // denotes the Sin function in package math
References
An identifier operand refers to a field and is called a reference.The value of a reference is a copy of the expression associated with the fieldthat it is bound to,with any references within that expression bound to the respective copies ofthe fields they were originally bound to.Implementations may use a different mechanism to evaluate as long asthese semantics are maintained.
a: { place: string greeting: "Hello, \(place)!"}b: a & { place: "world" }c: a & { place: "you" }d: b.greeting // "Hello, world!"e: c.greeting // "Hello, you!"
Primary expressions
Primary expressions are the operands for unary and binary expressions.
PrimaryExpr =Operand |PrimaryExpr Selector |PrimaryExpr Index |PrimaryExpr Slice |PrimaryExpr Arguments .Selector = "." (identifier | simple_string_lit) .Index = "[" Expression "]" .Argument = Expression .Arguments = "(" [ ( Argument { "," Argument } ) [ "," ] ] ")" .
x2(s + ".txt")f(3.1415, true)m["foo"]obj.colorf.p[i].x
Selectors
For a primary expression x
that is not a package name,the selector expression
x.f
denotes the element of a struct x
identified by f
.
f
must be an identifier or a string literal identifyingany definition or regular non-optional field.The identifier f
is called the field selector.
If x
is a package name, see the section on qualified identifiers.
Otherwise, if x
is not a struct,or if f
does not exist in x
,the result of the expression is bottom (an error).In the latter case the expression is incomplete.The operand of a selector may be associated with a default.
T: { x: int y: 3 "x-y": 4}a: T.x // intb: T.y // 3c: T.z // _|_ // field 'z' not found in Td: T."x-y" // 4e: {a: 1|*2} | *{a: 3|*4}f: e.a // 4 (default value)
Index expressions
A primary expression of the form
a[x]
denotes the element of a list or struct a
indexed by x
.The value x
is called the index or field name, respectively.The following rules apply:
If a
is not a struct:
a
is a list (which need not be complete)- the index
x
unified withint
must be concrete. - the index
x
is in range if0 <= x < len(a)
, where only theexplicitly defined values of an open-ended list are considered,otherwise it is out of range
The result of a[x]
is
for a
of list type:
- the list element at index
x
, ifx
is within range - bottom (an error), otherwise
for a
of struct type:
- the index
x
unified withstring
must be concrete. - the value of the regular and non-optional field named
x
of structa
,if this field exists - bottom (an error), otherwise
[ 1, 2 ][1] // 2[ 1, 2 ][2] // _|_[ 1, 2, ...][2] // _|_
Both the operand and index value may be a value-default pair.
va[vi] => va[vi]va[(vi, di)] => (va[vi], va[di])(va, da)[vi] => (va[vi], da[vi])(va, da)[(vi, di)] => (va[vi], da[di])
Fields Resultx: [1, 2] | *[3, 4] ([1,2]|[3,4], [3,4])i: int | *1 (int, 1)v: x[i] (x[i], 4)
Operators
Operators combine operands into expressions.
Expression = UnaryExpr | Expression binary_op Expression .UnaryExpr = PrimaryExpr | unary_op UnaryExpr .binary_op = "|" | "&" | "||" | "&&" | "==" | rel_op | add_op | mul_op .rel_op = "!=" | "<" | "<=" | ">" | ">=" | "=~" | "!~" .add_op = "+" | "-" .mul_op = "*" | "/" .unary_op = "+" | "-" | "!" | "*" | rel_op .
Comparisons are discussed elsewhere.For any binary operators, the operand types must unify.
Operands of unary and binary expressions may be associated with a default usingthe following
Field Resulting Value-Default paira: *1|2 (1|2, 1)b: -a (-a, -1)c: a + 2 (a+2, 3)d: a + a (a+a, 2)
Operator precedence
Unary operators have the highest precedence.
There are eight precedence levels for binary operators.Multiplication operators binds strongest, followed byaddition operators, comparison operators,&&
(logical AND), ||
(logical OR), &
(unification),and finally |
(disjunction):
Precedence Operator 7 * / 6 + - 5 == != < <= > >= =~ !~ 4 && 3 || 2 & 1 |
Binary operators of the same precedence associate from left to right.For instance, x / y * z
is the same as (x / y) * z
.
+x23 + 3*x[i]x <= f()f() || g()x == y+1 && y == z-12 | int{ a: 1 } & { b: 2 }
Arithmetic operators
Arithmetic operators apply to numeric values and yield a result of the same typeas the first operand. The four standard arithmetic operators(+, -, *, /)
apply to integer and decimal floating-point types;+
and *
also apply to strings and bytes.
+ sum integers, floats, strings, bytes- difference integers, floats* product integers, floats, strings, bytes/ quotient integers, floats
For any operator that accepts operands of type float
, any operand may beof type int
or float
, in which case the result will be float
if it cannot be represented as an int
or if any of the operands are float
,or int
otherwise.So the result of 1 / 2
is 0.5
and is of type float
.
The result of division by zero is bottom (an error).
Integer division is implemented through the builtin functionsquo
, rem
, div
, and mod
.
The unary operators +
and -
are defined for numeric values as follows:
+x is 0 + x-x negation is 0 - x
String operators
Strings can be concatenated using the +
operator:
s: "hi " + name + " and good bye"
String addition creates a new string by concatenating the operands.
A string can be repeated by multiplying it:
s: "etc. "*3 // "etc. etc. etc. "
Comparison operators
Comparison operators compare two operands and yield an untyped boolean value.
== equal!= not equal< less<= less or equal> greater>= greater or equal=~ matches regular expression!~ does not match regular expression
In any comparison, the types of the two operands must unify or one of theoperands must be null.
The equality operators ==
and !=
apply to operands that are comparable.The ordering operators <
, <=
, >
, and >=
apply to operands that are ordered.The matching operators =~
and !~
apply to a string and regularexpression operand.These terms and the result of the comparisons are defined as follows:
- Null is comparable with itself and any other type.Two null values are always equal, null is unequal with anything else.
- Boolean values are comparable.Two boolean values are equal if they are either both true or both false.
- Integer values are comparable and ordered, in the usual way.
- Floating-point values are comparable and ordered, as per the definitionsfor binary coded decimals in the IEEE-754-2008 standard.
- Floating point numbers may be compared with integers.
- String and bytes values are comparable and ordered lexically byte-wise.
- Struct are not comparable.
- Lists are not comparable.
- The regular expression syntax is the one accepted by RE2,described in https://github.com/google/re2/wiki/Syntax,except for
\C
. s =~ r
is true ifs
matches the regular expressionr
.s !~ r
is true ifs
does not match regular expressionr
.
3 < 4 // true3 < 4.0 // truenull == 2 // falsenull != {} // true{} == {} // _|_: structs are not comparable against structs"Wild cats" =~ "cat" // true"Wild cats" !~ "dog" // true"foo" =~ "^[a-z]{3}$" // true"foo" =~ "^[a-z]{4}$" // false
Logical operators
Logical operators apply to boolean values and yield a result of the same typeas the operands. The right operand is evaluated conditionally.
&& conditional AND p && q is "if p then q else false"|| conditional OR p || q is "if p then true else q"! NOT !p is "not p"
Calls
Calls can be made to core library functions, called builtins.Given an expression f
of function type F,
f(a1, a2, … an)
calls f
with arguments a1, a2, … an. Arguments must be expressionsof which the values are an instance of the parameter types of F
and are evaluated before the function is called.
a: math.Atan2(x, y)
In a function call, the function value and arguments are evaluated in the usualorder.After they are evaluated, the parameters of the call are passed by valueto the function and the called function begins execution.The return parametersof the function are passed by value back to the calling function when thefunction returns.
Comprehensions
Lists and fields can be constructed using comprehensions.
Comprehensions define a clause sequence that consists of a sequence offor
, if
, and let
clauses, nesting from left to right.The sequence must start with a for
or if
clause.The for
and let
clauses each define a new scope in which new values arebound to be available for the next clause.
The for
clause binds the defined identifiers, on each iteration, to the nextvalue of some iterable value in a new scope.A for
clause may bind one or two identifiers.If there is one identifier, it binds it to the value ofa list element or struct field value.If there are two identifiers, the first value will be the key or index,if available, and the second will be the value.
For lists, for
iterates over all elements in the list after closing it.For structs, for
iterates over all non-optional regular fields.
An if
clause, or guard, specifies an expression that terminates the currentiteration if it evaluates to false.
The let
clause binds the result of an expression to the defined identifierin a new scope.
A current iteration is said to complete if the innermost block of the clausesequence is reached.Syntactically, the comprehension value is a struct.A comprehension can generate non-struct values by embedding such values withinthis struct.
Within lists, the values yielded by a comprehension are inserted in the listat the position of the comprehension.Within structs, the values yielded by a comprehension are embedded within thestruct.Both structs and lists may contain multiple comprehensions.
Comprehension = Clauses StructLit .Clauses = StartClause { [ "," ] Clause } .StartClause = ForClause | GuardClause .Clause = StartClause | LetClause .ForClause = "for" identifier [ "," identifier ] "in" Expression .GuardClause = "if" Expression .LetClause = "let" identifier "=" Expression .
a: [1, 2, 3, 4]b: [ for x in a if x > 1 { x+1 } ] // [3, 4, 5]c: { for x in a if x < 4 let y = 1 { "\(x)": x + y }}d: { "1": 2, "2": 3, "3": 4 }
String interpolation
String interpolation allows constructing strings by replacing placeholderexpressions with their string representation.String interpolation may be used in single- and double-quoted strings, as wellas their multiline equivalent.
A placeholder consists of “\(” followed by an expression and a “)”.The expression is evaluated in the scope within which the string is defined.
The result of the expression is substituted as follows:
- string: as is
- bool: the JSON representation of the bool
- number: a JSON representation of the number that preserves theprecision of the underlying binary coded decimal
- bytes: as if substituted within single quotes orconverted to valid UTF-8 replacing themaximal subpart of ill-formed subsequences with a singlereplacement character (W3C encoding standard) otherwise
- list: illegal
- struct: illegal
a: "World"b: "Hello \( a )!" // Hello World!
Builtin Functions
Built-in functions are predeclared. They are called like any other function.
len
The built-in function len
takes arguments of various types and returnsa result of type int.
Argument type Resultstring string length in bytesbytes length of byte sequencelist list length, smallest length for an open liststruct number of distinct data fields, excluding optional
Expression Resultlen("Hellø") 6len([1, 2, 3]) 3len([1, 2, ...]) >=2
close
The builtin function close
converts a partially defined, or open, structto a fully defined, or closed, struct.
and
The built-in function and
takes a list and returns the result of applyingthe &
operator to all elements in the list.It returns top for the empty list.
Expression: Resultand([a, b]) a & band([a]) aand([]) _
or
The built-in function or
takes a list and returns the result of applyingthe |
operator to all elements in the list.It returns bottom for the empty list.
Expression: Resultor([a, b]) a | bor([a]) aor([]) _|_
div
, mod
, quo
and rem
For two integer values x
and y
,the integer quotient q = div(x, y)
and remainder r = mod(x, y)
implement Euclidean division andsatisfy the following relationship:
r = x - y*q with 0 <= r < |y|
where |y|
denotes the absolute value of y
.
x y div(x, y) mod(x, y) 5 3 1 2-5 3 -2 1 5 -3 -1 2-5 -3 2 1
For two integer values x
and y
,the integer quotient q = quo(x, y)
and remainder r = rem(x, y)
implement truncated division andsatisfy the following relationship:
x = q*y + r and |r| < |y|
with quo(x, y)
truncated towards zero.
x y quo(x, y) rem(x, y) 5 3 1 2-5 3 -1 -2 5 -3 -1 2-5 -3 1 -2
A zero divisor in either case results in bottom (an error).
Cycles
Implementations are required to interpret or reject cycles encounteredduring evaluation according to the rules in this section.
Reference cycles
A reference cycle occurs if a field references itself, either directly orindirectly.
// x references itselfx: x// indirect cyclesb: cc: dd: b
Implementations should treat these as _
.Two particular cases are discussed below.
Expressions that unify an atom with an expression
An expression of the form a & e
, where a
is an atomand e
is an expression, always evaluates to a
or bottom.As it does not matter how we fail, we can assume the result to be a
and postpone validating a == e
until after all referencesin e
have been resolved.
// Config Evaluates to (requiring concrete values)x: { x: { a: b + 100 a: _|_ // cycle detected b: a - 100 b: _|_ // cycle detected} }y: x & { y: { a: 200 a: 200 // asserted that 200 == b + 100 b: 100} }
Field values
A field value of the form r & v
,where r
evaluates to a reference cycle and v
is a concrete value,evaluates to v
.Unification is idempotent and unifying a value with itself ad infinitum,which is what the cycle represents, results in this value.Implementations should detect cycles of this kind, ignore r
,and take v
as the result of unification.
Configuration Evaluated// c Cycles in nodes of type struct evaluate// ↙︎ ↖ to the fixed point of unifying their// a → b values ad infinitum.a: b & { x: 1 } // a: { x: 1, y: 2, z: 3 }b: c & { y: 2 } // b: { x: 1, y: 2, z: 3 }c: a & { z: 3 } // c: { x: 1, y: 2, z: 3 }// resolve a b & {x:1}// substitute b c & {y:2} & {x:1}// substitute c a & {z:3} & {y:2} & {x:1}// eliminate a (cycle) {z:3} & {y:2} & {x:1}// simplify {x:1,y:2,z:3}
This rule also applies to field values that are disjunctions of unificationoperations of the above form.
a: b&{x:1} | {y:1} // {x:1,y:3,z:2} | {y:1}b: {x:2} | c&{z:2} // {x:2} | {x:1,y:3,z:2}c: a&{y:3} | {z:3} // {x:1,y:3,z:2} | {z:3}// resolving a b&{x:1} | {y:1}// substitute b ({x:2} | c&{z:2})&{x:1} | {y:1}// simplify c&{z:2}&{x:1} | {y:1}// substitute c (a&{y:3} | {z:3})&{z:2}&{x:1} | {y:1}// simplify a&{y:3}&{z:2}&{x:1} | {y:1}// eliminate a (cycle) {y:3}&{z:2}&{x:1} | {y:1}// expand {x:1,y:3,z:2} | {y:1}
Note that all nodes that form a reference cycle to form a struct will evaluateto the same value.If a field value is a disjunction, any element that is part of a cycle willevaluate to this value.
Structural cycles
A structural cycle is when a node references one of its ancestor nodes.It is possible to construct a structural cycle by unifying two acyclic values:
// acyclicy: { f: h: g g: _}// acyclicx: { f: _ g: f}// introduces structural cyclez: x & y
Implementations should be able to detect such structural cycles dynamically.
A structural cycle can result in infinite structure or evaluation loops.
// infinite structurea: b: a// infinite evaluationf: { n: int out: n + (f & {n: 1}).out}
CUE must allow or disallow structural cycles under certain circ*mstances.
If a node a
references an ancestor node, we call it and any of itsfield values a.f
cyclic.So if a
is cyclic, all of its descendants are also regarded as cyclic.A given node x
, whose value is composed of the conjuncts c1 & ... & cn
,is valid if any of its conjuncts is not cyclic.
// Disallowed: a list of infinite length with all elements being 1.#List: { head: 1 tail: #List}// Disallowed: another infinite structure (a:{b:{d:{b:{d:{...}}}}}, ...).a: { b: c}c: { d: a}// #List defines a list of arbitrary length. Because the recursive reference// is part of a disjunction, this does not result in a structural cycle.#List: { head: _ tail: null | #List}// Usage of #List. The value of tail in the most deeply nested element will// be `null`: as the value of the disjunct referring to list is the only// conjunct, all conjuncts are cyclic and the value is invalid and so// eliminated from the disjunction.MyList: #List & { head: 1, tail: { head: 2 }}
Modules, instances, and packages
CUE configurations are constructed combining instances.An instance, in turn, is constructed from one or more source files belongingto the same package that together declare the data representation.Elements of this data representation may be exported and usedin other instances.
Source file organization
Each source file consists of an optional package clause defining collectionof files to which it belongs,followed by a possibly empty set of import declarations that declarepackages whose contents it wishes to use, followed by a possibly empty set ofdeclarations.
Like with a struct, a source file may contain embeddings.Unlike with a struct, the embedded expressions may be any value.If the result of the unification of all embedded values is not a struct,it will be output instead of its enclosing file when exporting CUEto a data format
SourceFile = { attribute "," } [ PackageClause "," ] { ImportDecl "," } { Declaration "," } .
"Hello \(#place)!"#place: "world"// Outputs "Hello world!"
Package clause
A package clause is an optional clause that defines the package to whicha source file the file belongs.
PackageClause = "package" PackageName .PackageName = identifier .
The PackageName must not be the blank identifier or a definition identifier.
package math
Modules and instances
A module defines a tree of directories, rooted at the module root.
All source files within a module with the same package belong to the samepackage.
A module may define multiple packages.
An instance of a package is any subset of files belongingto the same package.
It is interpreted as the concatenation of these files.
An implementation may impose conventions on the layout of package filesto determine which files of a package belongs to an instance.For example, an instance may be defined as the subset of package filesbelonging to a directory and all its ancestors.
Import declarations
An import declaration states that the source file containing the declarationdepends on definitions of the imported packageand enables access to exported identifiers of that package.The import names an identifier (PackageName) to be used for access and anImportPath that specifies the package to be imported.
ImportDecl = "import" ( ImportSpec | "(" { ImportSpec "," } ")" ) .ImportSpec = [ PackageName ] ImportPath .ImportLocation = { unicode_value } .ImportPath = `"` ImportLocation [ ":" identifier ] `"` .
The PackageName is used in qualified identifiers to accessexported identifiers of the package within the importing source file.It is declared in the file block.It defaults to the identifier specified in the package clause of the importedpackage, which must match either the last path component of ImportLocationor the identifier following it.
The interpretation of the ImportPath is implementation-dependent but it istypically either the path of a builtin package or a fully qualifying locationof a package within a source code repository.
An ImportLocation must be a non-empty string using only characters belonging toUnicode’s L, M, N, P, and S general categories(the Graphic characters without spaces)and may not include the characters !"#$%&'()*,:;<=>?[\]^`{|}or the Unicode replacement character U+FFFD.
Assume we have package containing the package clause “package math”,which exports function Sin at the path identified by “lib/math”.This table illustrates how Sin is accessed in filesthat import the package after the various types of import declaration.
Import declaration Local name of Sinimport "lib/math" math.Sinimport "lib/math:math" math.Sinimport m "lib/math" m.Sin
An import declaration declares a dependency relation between the importing andimported package. It is illegal for a package to import itself, directly orindirectly, or to directly import a package without referring to any of itsexported identifiers.
An example package
TODO