this repo has no description
doc/tutorial/basics: generate testscript cases
And add generator for Hugo docs. The resulting
file are to be mounted in cuelang.org
Change-Id: Ie1b8f1c5ff68b304d4d3d35a7fb5c6cec1577c98
Reviewed-on: https://cue-review.googlesource.com/c/cue/+/3264
Reviewed-by: Marcel van Lohuizen <mpvl@golang.org>
+1381
-15
+37
doc/tutorial/basics/aliases.txt
+37
doc/tutorial/basics/aliases.txt
···
1
+
cue eval alias.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Aliases"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
An alias defines a local macro.
10
+
11
+
A typical use case is to provide access to a shadowed field.
12
+
13
+
Aliases are not members of a struct. They can be referred to only within the
14
+
struct, and they do not appear in the output.
15
+
16
+
-- alias.cue --
17
+
A = a // A is an alias for a
18
+
a: {
19
+
d: 3
20
+
}
21
+
b: {
22
+
a: {
23
+
// A provides access to the outer "a" which would
24
+
// otherwise be hidden by the inner one.
25
+
c: A.d
26
+
}
27
+
}
28
+
29
+
-- expect-stdout-cue --
30
+
a: {
31
+
d: 3
32
+
}
33
+
b: {
34
+
a: {
35
+
c: 3
36
+
}
37
+
}
+35
doc/tutorial/basics/bottom.txt
+35
doc/tutorial/basics/bottom.txt
···
1
+
cue eval -i bottom.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Bottom / Error"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Specifying duplicate fields with conflicting values results in an error
10
+
or bottom.
11
+
_Bottom_ is a special value in CUE, denoted `_|_`, that indicates an
12
+
error such as conflicting values.
13
+
Any error in CUE results in `_|_`.
14
+
Logically all errors are equal, although errors may be associated with
15
+
metadata such as an error message.
16
+
17
+
Note that an error is different from `null`: `null` is a valid value,
18
+
whereas `_|_` is not.
19
+
20
+
-- bottom.cue --
21
+
a: 4
22
+
a: 5
23
+
24
+
l: [ 1, 2 ]
25
+
l: [ 1, 3 ]
26
+
27
+
list: [0, 1, 2]
28
+
val: list[3]
29
+
30
+
-- expect-stdout-cue --
31
+
list: [0, 1, 2]
32
+
a: _|_ // conflicting values 4 and 5
33
+
l: [1, _|_, // conflicting values 2 and 3
34
+
]
35
+
val: _|_ // index 3 out of bounds
+24
doc/tutorial/basics/bytes.txt
+24
doc/tutorial/basics/bytes.txt
···
1
+
cue export bytes.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Bytes"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE distinguishes between a `string` and a `bytes` type.
10
+
Bytes are converted to base64 when emitting JSON.
11
+
Byte literals are defined with single quotes.
12
+
The following additional escape sequences are allowed in byte literals:
13
+
14
+
\xnn // arbitrary byte value defined as a 2-digit hexadecimal number
15
+
\nnn // arbitrary byte value defined as a 3-digit octal number
16
+
<!-- jba: this contradicts the spec, which has \nnn (no leading zero) -->
17
+
18
+
-- bytes.cue --
19
+
a: '\x03abc'
20
+
21
+
-- expect-stdout-cue --
22
+
{
23
+
"a": "A2FiYw=="
24
+
}
+44
doc/tutorial/basics/coalesce.txt
+44
doc/tutorial/basics/coalesce.txt
···
1
+
cue eval coalesce.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Null Coalescing"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
<!-- jba: the terms here are confusing. "Null coalescing" is actually not
10
+
that, but then there is something called "actual null coalescing."
11
+
12
+
Just say that because _|_ | X evaluates to X, you can use disjunction
13
+
to represent fallback values.
14
+
15
+
And then you can use that to effectively type-check with a default value.
16
+
-->
17
+
18
+
With null coalescing we really mean error, or bottom, coalescing.
19
+
The defaults mechanism for disjunctions can also be
20
+
used to provide fallback values in case an expression evaluates to bottom.
21
+
22
+
In the example the fallback values are specified
23
+
for `a` and `b` in case the list index is out of bounds.
24
+
25
+
To do actual null coalescing one can unify a result with the desired type
26
+
to force an error.
27
+
In that case the default will be used if either the lookup fails or
28
+
the result is not of the desired type.
29
+
30
+
-- coalesce.cue --
31
+
list: [ "Cat", "Mouse", "Dog" ]
32
+
33
+
a: *list[0] | "None"
34
+
b: *list[5] | "None"
35
+
36
+
n: [null]
37
+
v: *n[0]&string | "default"
38
+
39
+
-- expect-stdout-cue --
40
+
list: ["Cat", "Mouse", "Dog"]
41
+
a: "Cat"
42
+
b: "None"
43
+
n: [null]
44
+
v: "default"
+31
doc/tutorial/basics/commas.txt
+31
doc/tutorial/basics/commas.txt
···
1
+
cue export commas.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Commas are Optional after Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Commas are optional at the end of fields.
10
+
This is also true for the last field.
11
+
The convention is to omit them.
12
+
13
+
<!-- Side Note -->
14
+
_CUE borrows a trick from Go to achieve this: the formal grammar still
15
+
requires commas, but the scanner inserts commas according to a small set
16
+
of simple rules._
17
+
18
+
-- commas.cue --
19
+
{
20
+
one: 1
21
+
two: 2
22
+
23
+
"two-and-a-half": 2.5
24
+
}
25
+
26
+
-- expect-stdout-cue --
27
+
{
28
+
"one": 1,
29
+
"two": 2,
30
+
"two-and-a-half": 2.5
31
+
}
+24
doc/tutorial/basics/commaslists.txt
+24
doc/tutorial/basics/commaslists.txt
···
1
+
cue export commas2.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Commas are Still Required in Lists"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Commas are still required as separators in lists.
10
+
The last element of a list may also have a comma.
11
+
12
+
-- commas2.cue --
13
+
[
14
+
1,
15
+
2,
16
+
3,
17
+
]
18
+
19
+
-- expect-stdout-cue --
20
+
[
21
+
1,
22
+
2,
23
+
3
24
+
]
+20
doc/tutorial/basics/comments.txt
+20
doc/tutorial/basics/comments.txt
···
1
+
cue export comments.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Comments"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE supports C-style line comments.
10
+
11
+
-- comments.cue --
12
+
// a doc comment
13
+
one: 1
14
+
two: 2 // a line comment
15
+
16
+
-- expect-stdout-cue --
17
+
{
18
+
"one": 1,
19
+
"two": 2
20
+
}
+27
doc/tutorial/basics/conditional.txt
+27
doc/tutorial/basics/conditional.txt
···
1
+
cue eval conditional.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Conditional Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Field comprehensions can also be used to
10
+
add a single field conditionally.
11
+
12
+
Converting the resulting configuration to JSON results in an error
13
+
as `justification` is required yet no concrete value is given.
14
+
15
+
-- conditional.cue --
16
+
price: number
17
+
18
+
// Require a justification if price is too high
19
+
if price > 100 {
20
+
justification: string
21
+
}
22
+
23
+
price: 200
24
+
25
+
-- expect-stdout-cue --
26
+
price: 200
27
+
justification: string
+24
doc/tutorial/basics/curly.txt
+24
doc/tutorial/basics/curly.txt
···
1
+
cue export curly.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Curly Braces"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
The outer curly braces may be omitted for the top-level struct.
10
+
CUE also allows both, which has a specific meaning.
11
+
[We will come back to that later](emit.md).
12
+
13
+
-- curly.cue --
14
+
one: 1
15
+
two: 2
16
+
17
+
"two-and-a-half": 2.5
18
+
19
+
-- expect-stdout-cue --
20
+
{
21
+
"one": 1,
22
+
"two": 2,
23
+
"two-and-a-half": 2.5
24
+
}
+33
doc/tutorial/basics/cycle.txt
+33
doc/tutorial/basics/cycle.txt
···
1
+
cue eval -i -c cycle.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Reference Cycles"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE can handle many types of cycles just fine.
10
+
Because all values are final, a field with a concrete value of, say `200`,
11
+
can only be valid if it is that value.
12
+
So if it is unified with another expression, we can delay the evaluation of
13
+
this until later.
14
+
15
+
By postponing that evaluation, we can often break cycles.
16
+
This is very useful for template writers that may not know what fields
17
+
a user will want to fill out.
18
+
19
+
-- cycle.cue --
20
+
// CUE knows how to resolve the following:
21
+
x: 200
22
+
x: y + 100
23
+
y: x - 100
24
+
25
+
// If a cycle is not broken, CUE will just report it.
26
+
a: b + 100
27
+
b: a - 100
28
+
29
+
-- expect-stdout-cue --
30
+
x: 200
31
+
y: 100
32
+
a: _|_ // cycle detected
33
+
b: _|_ // cycle detected
+29
doc/tutorial/basics/cycleref.txt
+29
doc/tutorial/basics/cycleref.txt
···
1
+
cue eval cycleref.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Cycles in Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Also, we know that unifying a field with itself will result in the same value.
10
+
Thus if we have a cycle between some fields, all we need to do is ignore
11
+
the cycle and unify their values once to achieve the same result as
12
+
merging them ad infinitum.
13
+
14
+
-- cycleref.cue --
15
+
labels: selectors
16
+
labels: {app: "foo"}
17
+
18
+
selectors: labels
19
+
selectors: {name: "bar"}
20
+
21
+
-- expect-stdout-cue --
22
+
labels: {
23
+
name: "bar"
24
+
app: "foo"
25
+
}
26
+
selectors: {
27
+
name: "bar"
28
+
app: "foo"
29
+
}
+29
doc/tutorial/basics/defaults.txt
+29
doc/tutorial/basics/defaults.txt
···
1
+
cue eval defaults.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Default Values"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Elements of a disjunction may be marked as preferred.
10
+
If there is only one mark, or the users constraints a field enough such that
11
+
only one mark remains, that value is the default value.
12
+
13
+
In the example, `replicas` defaults to `1`.
14
+
In the case of `protocol`, however, there are multiple definitions with
15
+
different, mutually incompatible defaults.
16
+
In that case, both `"tcp"` and `"udp"` are preferred and one must explicitly
17
+
specify either `"tcp"` or `"udp"` as if no marks were given.
18
+
19
+
-- defaults.cue --
20
+
// any positive number, 1 is the default
21
+
replicas: uint | *1
22
+
23
+
// the default value is ambiguous
24
+
protocol: *"tcp" | "udp"
25
+
protocol: *"udp" | "tcp"
26
+
27
+
-- expect-stdout-cue --
28
+
replicas: 1
29
+
protocol: "tcp" | "udp" | *_|_
+25
doc/tutorial/basics/disjunctions.txt
+25
doc/tutorial/basics/disjunctions.txt
···
1
+
-- frontmatter.toml --
2
+
title = "Disjunctions"
3
+
description = ""
4
+
5
+
-- text.md --
6
+
Disjunctions, or sum types, define a new type that is one of several things.
7
+
8
+
In the example, `conn` defines a `protocol` field that must be one of two
9
+
values: `"tcp"` or `"udp"`.
10
+
It is an error for a concrete `conn`
11
+
to define anything else than these two values.
12
+
13
+
-- disjunctions.cue --
14
+
conn: {
15
+
address: string
16
+
port: int
17
+
protocol: "tcp" | "udp"
18
+
}
19
+
20
+
lossy: conn & {
21
+
address: "1.2.3.4"
22
+
port: 8888
23
+
protocol: "udp"
24
+
}
25
+
+38
doc/tutorial/basics/duplicates.txt
+38
doc/tutorial/basics/duplicates.txt
···
1
+
cue eval dup.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Duplicate Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE allows duplicated field definitions as long as they don't conflict.
10
+
11
+
For values of basic types this means they must be equal.
12
+
13
+
For structs, fields are merged and duplicated fields are handled recursively.
14
+
15
+
For lists, all elements must match accordingly
16
+
([we discuss open-ended lists later](lists.md).)
17
+
18
+
-- dup.cue --
19
+
a: 4
20
+
a: 4
21
+
22
+
s: {
23
+
x: 1
24
+
}
25
+
s: {
26
+
y: 2
27
+
}
28
+
29
+
l: [ 1, 2 ]
30
+
l: [ 1, 2 ]
31
+
32
+
-- expect-stdout-cue --
33
+
a: 4
34
+
s: {
35
+
x: 1
36
+
y: 2
37
+
}
38
+
l: [1, 2]
+22
doc/tutorial/basics/emit.txt
+22
doc/tutorial/basics/emit.txt
···
1
+
cue eval emit.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Emit Values"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
By default all top-level fields are emitted when evaluating a configuration.
10
+
Embedding a value at top-level will cause that value to be emitted instead.
11
+
12
+
Emit values allow CUE configurations, like JSON,
13
+
to define any type, instead of just structs, while keeping the common case
14
+
of defining structs light.
15
+
16
+
-- emit.cue --
17
+
"Hello \(who)!"
18
+
19
+
who: "world"
20
+
21
+
-- expect-stdout-cue --
22
+
"Hello world!"
+44
doc/tutorial/basics/fieldcomp.txt
+44
doc/tutorial/basics/fieldcomp.txt
···
1
+
cue eval fieldcomp.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Field Comprehensions"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE also supports comprehensions for fields.
10
+
11
+
One cannot refer to generated fields with references.
12
+
Instead, one must use indexing.
13
+
14
+
-- fieldcomp.cue --
15
+
import "strings"
16
+
17
+
a: [ "Barcelona", "Shanghai", "Munich" ]
18
+
19
+
{
20
+
for k, v in a {
21
+
"\( strings.ToLower(v) )": {
22
+
pos: k + 1
23
+
name: v
24
+
nameLen: len(v)
25
+
}
26
+
}
27
+
}
28
+
29
+
-- expect-stdout-cue --
30
+
barcelona: {
31
+
name: "Barcelona"
32
+
pos: 1
33
+
nameLen: 9
34
+
}
35
+
shanghai: {
36
+
name: "Shanghai"
37
+
pos: 2
38
+
nameLen: 8
39
+
}
40
+
munich: {
41
+
name: "Munich"
42
+
pos: 3
43
+
nameLen: 6
44
+
}
+29
doc/tutorial/basics/fieldname.txt
+29
doc/tutorial/basics/fieldname.txt
···
1
+
cue export fieldname.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Quotes are Optional for Field Names"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
JSON objects are called structs in CUE.
10
+
An object member is called a field.
11
+
12
+
13
+
Double quotes may be omitted from field names if their name contains no
14
+
special characters and does not start with a number:
15
+
16
+
-- fieldname.cue --
17
+
{
18
+
one: 1,
19
+
two: 2,
20
+
21
+
"two-and-a-half": 2.5
22
+
}
23
+
24
+
-- expect-stdout-cue --
25
+
{
26
+
"one": 1,
27
+
"two": 2,
28
+
"two-and-a-half": 2.5
29
+
}
+21
doc/tutorial/basics/fold.txt
+21
doc/tutorial/basics/fold.txt
···
1
+
cue export fold.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Folding of Single-Field Structs"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE allows a shorthand for structs with single members.
10
+
11
+
-- fold.cue --
12
+
outer middle inner: 3
13
+
14
+
-- expect-stdout-cue --
15
+
{
16
+
"outer": {
17
+
"middle": {
18
+
"inner": 3
19
+
}
20
+
}
21
+
}
+28
doc/tutorial/basics/foldany.txt
+28
doc/tutorial/basics/foldany.txt
···
1
+
cue export foldany.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Folding all Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
This also works if a struct has more than one member.
10
+
11
+
In general, any JSON object can be expressed as a collection of
12
+
path-leaf pairs without using any curly braces.
13
+
14
+
-- foldany.cue --
15
+
outer middle1 inner: 3
16
+
outer middle2 inner: 7
17
+
18
+
-- expect-stdout-cue --
19
+
{
20
+
"outer": {
21
+
"middle1": {
22
+
"inner": 3
23
+
},
24
+
"middle2": {
25
+
"inner": 7
26
+
}
27
+
}
28
+
}
+34
doc/tutorial/basics/imports.txt
+34
doc/tutorial/basics/imports.txt
···
1
+
cue eval imports.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Imports"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
A CUE file may import definitions from builtin or user-defined packages.
10
+
A CUE file does not need to be part of a package to use imports.
11
+
12
+
The example here shows the use of builtin packages.
13
+
14
+
This code groups the imports into a parenthesized, "factored" import statement.
15
+
16
+
You can also write multiple import statements, like:
17
+
18
+
```
19
+
import "encoding/json"
20
+
import "math"
21
+
```
22
+
23
+
But it is good style to use the factored import statement.
24
+
25
+
-- imports.cue --
26
+
import (
27
+
"encoding/json"
28
+
"math"
29
+
)
30
+
31
+
data: json.Marshal({ a: math.Sqrt(7) })
32
+
33
+
-- expect-stdout-cue --
34
+
data: "{\"a\":2.6457513110645907}"
+4
doc/tutorial/basics/instances.txt
+4
doc/tutorial/basics/instances.txt
+21
doc/tutorial/basics/interpolation.txt
+21
doc/tutorial/basics/interpolation.txt
···
1
+
cue eval interpolation.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Interpolation"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
String and bytes literals support interpolation.
10
+
11
+
Any valid CUE expression may be used inside the escaped parentheses.
12
+
Interpolation may also be used in multiline string and byte literals.
13
+
14
+
-- interpolation.cue --
15
+
"You are \( cost - budget ) dollars over budget!"
16
+
17
+
cost: 102
18
+
budget: 88
19
+
20
+
-- expect-stdout-cue --
21
+
"You are 14 dollars over budget!"
+27
doc/tutorial/basics/interpolfield.txt
+27
doc/tutorial/basics/interpolfield.txt
···
1
+
cue eval -i genfield.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Interpolation of Field Names"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
String interpolations may also be used in field names.
10
+
11
+
One cannot refer to generated fields with references.
12
+
13
+
-- genfield.cue --
14
+
sandwich: {
15
+
type: "Cheese"
16
+
"has\(type)": true
17
+
hasButter: true
18
+
butterAndCheese: hasButter && hasCheese
19
+
}
20
+
21
+
-- expect-stdout-cue --
22
+
sandwich: {
23
+
type: "Cheese"
24
+
hasButter: true
25
+
butterAndCheese: _|_ // reference "hasCheese" not found
26
+
hasCheese: true
27
+
}
+4
doc/tutorial/basics/json.txt
+4
doc/tutorial/basics/json.txt
+19
doc/tutorial/basics/listcomp.txt
+19
doc/tutorial/basics/listcomp.txt
···
1
+
cue eval listcomp.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "List Comprehensions"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Lists can be created with list comprehensions.
10
+
11
+
The example shows the use of `for` loops and `if` guards.
12
+
13
+
-- listcomp.cue --
14
+
[ x*x for x in items if x rem 2 == 0]
15
+
16
+
items: [ 1, 2, 3, 4, 5, 6, 7, 8, 9 ]
17
+
18
+
-- expect-stdout-cue --
19
+
[4, 16, 36, 64]
+41
doc/tutorial/basics/lists.txt
+41
doc/tutorial/basics/lists.txt
···
1
+
cue eval -i lists.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Lists"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Lists define arbitrary sequences of CUE values.
10
+
A list can be closed or open ended.
11
+
Open-ended lists may have some predefined elements, but may have
12
+
additional, possibly typed elements.
13
+
14
+
In the example we define `IP` to be a list of `4` elements of type `uint8`, which
15
+
is a predeclared value of `>=0 & <=255`.
16
+
`PrivateIP` defines the IP ranges defined for private use.
17
+
Note that as it is already defined to be an `IP`, the length of the list
18
+
is already fixed at `4` and we do not have to specify a value for all elements.
19
+
Also note that instead of writing `...uint8`, we could have written `...`
20
+
as the type constraint is already already implied by `IP`.
21
+
22
+
The output contains a valid private IP address (`myIP`)
23
+
and an invalid one (`yourIP`).
24
+
25
+
-- lists.cue --
26
+
IP: 4 * [ uint8 ]
27
+
28
+
PrivateIP: IP
29
+
PrivateIP: [10, ...uint8] | [192, 168, ...] | [172, >=16 & <=32, ...]
30
+
31
+
myIP: PrivateIP
32
+
myIP: [10, 2, 3, 4]
33
+
34
+
yourIP: PrivateIP
35
+
yourIP: [11, 1, 2, 3]
36
+
37
+
-- expect-stdout-cue --
38
+
IP: [uint8, uint8, uint8, uint8]
39
+
PrivateIP: [10, uint8, uint8, uint8] | [192, 168, uint8, uint8] | [172, >=16 & <=32 & uint8, uint8, uint8]
40
+
myIP: [10, 2, 3, 4]
41
+
yourIP: _|_ // empty disjunction: [((10 & (int & >=0 & int & <=255)) & 11),((int & >=0 & int & <=255) & 1),((int & >=0 & int & <=255) & 2),((int & >=0 & int & <=255) & 3)]
+25
doc/tutorial/basics/numberlit.txt
+25
doc/tutorial/basics/numberlit.txt
···
1
+
cue export numlit.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Number Literals"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE adds a variety of sugar for writing numbers.
10
+
11
+
-- numlit.cue --
12
+
[
13
+
1_234, // 1234
14
+
5M, // 5_000_000
15
+
1.5Gi, // 1_610_612_736
16
+
0x1000_0000, // 268_435_456
17
+
]
18
+
19
+
-- expect-stdout-cue --
20
+
[
21
+
1234,
22
+
5000000,
23
+
1610612736,
24
+
268435456
25
+
]
+35
doc/tutorial/basics/numbers.txt
+35
doc/tutorial/basics/numbers.txt
···
1
+
cue eval -i numbers.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Numbers"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE defines two kinds of numbers.
10
+
Integers, denoted `int`, are whole, or integral, numbers.
11
+
Floats, denoted `float`, are decimal floating point numbers.
12
+
13
+
An integer literal (e.g. `4`) can be of either type, but defaults to `int`.
14
+
A floating point literal (e.g. `4.0`) is only compatible with `float`.
15
+
16
+
In the example, the result of `b` is a `float` and cannot be
17
+
used as an `int` without conversion.
18
+
19
+
-- numbers.cue --
20
+
a: int
21
+
a: 4 // type int
22
+
23
+
b: number
24
+
b: 4.0 // type float
25
+
26
+
c: int
27
+
c: 4.0
28
+
29
+
d: 4 // will evaluate to type int (default)
30
+
31
+
-- expect-stdout-cue --
32
+
a: 4
33
+
b: 4.0
34
+
c: _|_ // conflicting values int and 4.0 (mismatched types int and float)
35
+
d: 4
+30
doc/tutorial/basics/operators.txt
+30
doc/tutorial/basics/operators.txt
···
1
+
cue eval -i op.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Operators"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE supports many common arithmetic and boolean operators.
10
+
11
+
The operators for division and remainder are different for `int` and `float`.
12
+
For `float` CUE supports the `/` and `%` operators with the usual meaning.
13
+
For `int` CUE supports both Euclidean division (`div` and `mod`)
14
+
and truncated division (`quo` and `rem`).
15
+
16
+
-- op.cue --
17
+
a: 3 / 2 // type float
18
+
b: 3 div 2 // type int: Euclidean division
19
+
20
+
c: 3 * "blah"
21
+
d: 3 * [1, 2, 3]
22
+
23
+
e: 8 < 10
24
+
25
+
-- expect-stdout-cue --
26
+
a: 1.5
27
+
b: 1
28
+
c: "blahblahblah"
29
+
d: [1, 2, 3, 1, 2, 3, 1, 2, 3]
30
+
e: true
+34
doc/tutorial/basics/packages.txt
+34
doc/tutorial/basics/packages.txt
···
1
+
cue eval a.cue b.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Packages"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
A CUE file is a standalone file by default.
10
+
A `package` clause allows a single configuration to be split across multiple
11
+
files.
12
+
13
+
The configuration for a package is defined by the concatenation of all its
14
+
files, after stripping the package clauses and not considering imports.
15
+
16
+
Duplicate definitions are treated analogously to duplicate definitions within
17
+
the same file.
18
+
The order in which files are loaded is undefined, but any order will result
19
+
in the same outcome, given that order does not matter.
20
+
21
+
-- a.cue --
22
+
package config
23
+
24
+
foo: 100
25
+
bar: int
26
+
27
+
-- b.cue --
28
+
package config
29
+
30
+
bar: 200
31
+
32
+
-- expect-stdout-cue --
33
+
foo: 100
34
+
bar: 200
+45
doc/tutorial/basics/rangedef.txt
+45
doc/tutorial/basics/rangedef.txt
···
1
+
cue eval -i range.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Predefined Ranges"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE numbers have arbitrary precision.
10
+
Also there is no unsigned integer type.
11
+
12
+
CUE defines the following predefined identifiers to restrict the ranges of
13
+
integers to common values.
14
+
15
+
```
16
+
uint >=0
17
+
uint8 >=0 & <=255
18
+
int8 >=-128 & <=127
19
+
uint16 >=0 & <=65536
20
+
int16 >=-32_768 & <=32_767
21
+
rune >=0 & <=0x10FFFF
22
+
uint32 >=0 & <=4_294_967_296
23
+
int32 >=-2_147_483_648 & <=2_147_483_647
24
+
uint64 >=0 & <=18_446_744_073_709_551_615
25
+
int64 >=-9_223_372_036_854_775_808 & <=9_223_372_036_854_775_807
26
+
int128 >=-170_141_183_460_469_231_731_687_303_715_884_105_728 &
27
+
<=170_141_183_460_469_231_731_687_303_715_884_105_727
28
+
uint128 >=0 & <=340_282_366_920_938_463_463_374_607_431_768_211_455
29
+
```
30
+
31
+
-- range.cue --
32
+
positive: uint
33
+
byte: uint8
34
+
word: int32
35
+
36
+
{
37
+
a: positive & -1
38
+
b: byte & 128
39
+
c: word & 2_000_000_000
40
+
}
41
+
42
+
-- expect-stdout-cue --
43
+
a: _|_ // invalid value -1 (out of bound int & >=0)
44
+
b: 128
45
+
c: 2000000000
+39
doc/tutorial/basics/ranges.txt
+39
doc/tutorial/basics/ranges.txt
···
1
+
cue eval -i bounds.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Bounds"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Bounds define a lower bound, upper bound, or inequality for a certain value.
10
+
They work on numbers, strings, bytes, and and null.
11
+
12
+
The bound is defined for all values for which the corresponding comparison
13
+
operation is define.
14
+
For instance `>5.0` allows all floating point values greater than `5.0`,
15
+
whereas `<0` allows all negative numbers (int or float).
16
+
17
+
-- bounds.cue --
18
+
rn: >=3 & <8 // type int | float
19
+
ri: >=3 & <8 & int // type int
20
+
rf: >=3 & <=8.0 // type float
21
+
rs: >="a" & <"mo"
22
+
23
+
{
24
+
a: rn & 3.5
25
+
b: ri & 3.5
26
+
c: rf & 3
27
+
d: rs & "ma"
28
+
e: rs & "mu"
29
+
30
+
r1: rn & >=5 & <10
31
+
}
32
+
33
+
-- expect-stdout-cue --
34
+
a: 3.5
35
+
b: _|_ // conflicting values ri and 3.5 (mismatched types int and float)
36
+
c: 3
37
+
d: "ma"
38
+
e: _|_ // invalid value "mu" (out of bound <"mo")
39
+
r1: >=5 & <8
+34
doc/tutorial/basics/regexp.txt
+34
doc/tutorial/basics/regexp.txt
···
1
+
cue eval -i regexp.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Regular expressions"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
The `=~` and `!~` operators can be used to check against regular expressions.
10
+
11
+
The expression `a =~ b` is true if `a` matches `b`, while
12
+
`a !~ b` is true if `a` does _not_ match `b`.
13
+
14
+
Just as with comparison operators, these operators may be used
15
+
as unary versions to define a set of strings.
16
+
17
+
-- regexp.cue --
18
+
a: "foo bar" =~ "foo [a-z]{3}"
19
+
b: "maze" !~ "^[a-z]{3}$"
20
+
21
+
c: =~"^[a-z]{3}$" // any string with lowercase ASCII of length 3
22
+
23
+
d: c
24
+
d: "foo"
25
+
26
+
e: c
27
+
e: "foo bar"
28
+
29
+
-- expect-stdout-cue --
30
+
a: true
31
+
b: true
32
+
c: =~"^[a-z]{3}$"
33
+
d: "foo"
34
+
e: _|_ // invalid value "foo bar" (does not match =~"^[a-z]{3}$")
+35
doc/tutorial/basics/scopes.txt
+35
doc/tutorial/basics/scopes.txt
···
1
+
cue eval scopes.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "References and Scopes"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
A reference refers to the value of the field defined within nearest
10
+
enclosing scope.
11
+
12
+
If no field matches the reference within the file, it may match a top-level
13
+
field defined in any other file of the same package.
14
+
15
+
If there is still no match, it may match a predefined value.
16
+
17
+
-- scopes.cue --
18
+
v: 1
19
+
a: {
20
+
v: 2
21
+
b: v // matches the inner v
22
+
}
23
+
a: {
24
+
c: v // matches the top-level v
25
+
}
26
+
b: v
27
+
28
+
-- expect-stdout-cue --
29
+
v: 1
30
+
a: {
31
+
v: 2
32
+
b: 2
33
+
c: 1
34
+
}
35
+
b: 1
+25
doc/tutorial/basics/script_test.go
+25
doc/tutorial/basics/script_test.go
···
1
+
package basics
2
+
3
+
import (
4
+
"flag"
5
+
"os"
6
+
"testing"
7
+
8
+
"cuelang.org/go/cmd/cue/cmd"
9
+
"github.com/rogpeppe/testscript"
10
+
)
11
+
12
+
var update = flag.Bool("update", false, "update the test files")
13
+
14
+
func TestScript(t *testing.T) {
15
+
testscript.Run(t, testscript.Params{
16
+
Dir: "",
17
+
UpdateScripts: *update,
18
+
})
19
+
}
20
+
21
+
func TestMain(m *testing.M) {
22
+
os.Exit(testscript.RunMain(m, map[string]func() int{
23
+
"cue": cmd.Main,
24
+
}))
25
+
}
+27
doc/tutorial/basics/selectors.txt
+27
doc/tutorial/basics/selectors.txt
···
1
+
cue eval selectors.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Accessing Fields"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
Selectors access fields within a struct using the `.` notation.
10
+
This only works if a field name is a valid identifier and it is not computed.
11
+
For other cases one can use the indexing notation.
12
+
13
+
-- selectors.cue --
14
+
a: {
15
+
b: 2
16
+
"c-e": 5
17
+
}
18
+
v: a.b
19
+
w: a["c-e"]
20
+
21
+
-- expect-stdout-cue --
22
+
a: {
23
+
b: 2
24
+
"c-e": 5
25
+
}
26
+
v: 2
27
+
w: 5
+33
doc/tutorial/basics/stringlit.txt
+33
doc/tutorial/basics/stringlit.txt
···
1
+
cue export stringlit.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "String Literals"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE strings allow a richer set of escape sequences than JSON.
10
+
11
+
CUE also supports multi-line strings, enclosed by a pair of triple quotes `"""`.
12
+
The opening quote must be followed by a newline.
13
+
The closing quote must also be on a newline.
14
+
The whitespace directly preceding the closing quote must match the preceding
15
+
whitespace on all other lines and is removed from these lines.
16
+
17
+
Strings may also contain [interpolations](interpolation.md).
18
+
19
+
-- stringlit.cue --
20
+
// 21-bit unicode characters
21
+
a: "\U0001F60E" // 😎
22
+
23
+
// multiline strings
24
+
b: """
25
+
Hello
26
+
World!
27
+
"""
28
+
29
+
-- expect-stdout-cue --
30
+
{
31
+
"a": "😎",
32
+
"b": "Hello\nWorld!"
33
+
}
+38
doc/tutorial/basics/stringraw.txt
+38
doc/tutorial/basics/stringraw.txt
···
1
+
cue eval stringraw.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "\"Raw\" Strings"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE does not support raw strings in the strictest sense.
10
+
Instead it allows modifying the escape delimiter by requiring
11
+
an arbitrary number of hash `#` signs after the backslash by
12
+
enclosing a string literal in an equal number of hash signs on either end.
13
+
14
+
This works for normal and interpolated strings.
15
+
Quotes do not have to be escaped in such strings.
16
+
17
+
-- stringraw.cue --
18
+
msg1: #"The sequence "\U0001F604" renders as \#U0001F604."#
19
+
20
+
msg2: ##"""
21
+
A regular expression can conveniently be written as:
22
+
23
+
#"\d{3}"#
24
+
25
+
This construct works for bytes, strings and their
26
+
multi-line variants.
27
+
"""##
28
+
29
+
-- expect-stdout-cue --
30
+
msg1: "The sequence \"\\U0001F604\" renders as 😄."
31
+
msg2: """
32
+
A regular expression can conveniently be written as:
33
+
34
+
#\"\\d{3}\"#
35
+
36
+
This construct works for bytes, strings and their
37
+
multi-line variants.
38
+
"""
+26
doc/tutorial/basics/sumstruct.txt
+26
doc/tutorial/basics/sumstruct.txt
···
1
+
-- frontmatter.toml --
2
+
title = "Disjunctions of Structs"
3
+
description = ""
4
+
5
+
-- text.md --
6
+
Disjunctions work for any type.
7
+
8
+
In this example we see that a `floor` of some specific house
9
+
has an exit on level 0 and 1, but not on any other floor.
10
+
11
+
-- sumstruct.cue --
12
+
// floor defines the specs of a floor in some house.
13
+
floor: {
14
+
level: int // the level on which this floor resides
15
+
hasExit: bool // is there a door to exit the house?
16
+
}
17
+
18
+
// constraints on the possible values of floor.
19
+
floor: {
20
+
level: 0 | 1
21
+
hasExit: true
22
+
} | {
23
+
level: -1 | 2 | 3
24
+
hasExit: false
25
+
}
26
+
+46
doc/tutorial/basics/templates.txt
+46
doc/tutorial/basics/templates.txt
···
1
+
cue eval templates.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Templates"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
<!-- jba: this is not in the spec, aside from the TemplateLabel grammar rule. -->
10
+
11
+
One of CUE's most powerful features is templates.
12
+
A template defines a value to be unified with each field of a struct.
13
+
14
+
The template's identifier (in angular brackets) is bound to name of each
15
+
of its sibling fields and is visible within the template value
16
+
that is unified with each of the siblings.
17
+
18
+
-- templates.cue --
19
+
// The following struct is unified with all elements in job.
20
+
// The name of each element is bound to Name and visible in the struct.
21
+
job <Name>: {
22
+
name: Name
23
+
replicas: uint | *1
24
+
command: string
25
+
}
26
+
27
+
job list command: "ls"
28
+
29
+
job nginx: {
30
+
command: "nginx"
31
+
replicas: 2
32
+
}
33
+
34
+
-- expect-stdout-cue --
35
+
job: {
36
+
list: {
37
+
name: "list"
38
+
replicas: 1
39
+
command: "ls"
40
+
}
41
+
nginx: {
42
+
name: "nginx"
43
+
replicas: 2
44
+
command: "nginx"
45
+
}
46
+
}
+49
-15
doc/tutorial/basics/tut_test.go
+49
-15
doc/tutorial/basics/tut_test.go
···
15
15
package basics
16
16
17
17
import (
18
-
"bytes"
18
+
"fmt"
19
19
"io/ioutil"
20
20
"os"
21
21
"path/filepath"
···
23
23
"testing"
24
24
25
25
"cuelang.org/go/internal/cuetest"
26
+
"github.com/rogpeppe/testscript/txtar"
26
27
)
27
28
28
29
func TestTutorial(t *testing.T) {
29
-
// t.Skip()
30
+
t.Skip()
30
31
31
32
err := filepath.Walk(".", func(path string, f os.FileInfo, err error) error {
32
-
if strings.HasSuffix(path, ".md") {
33
+
if strings.HasSuffix(path, ".md") && !strings.Contains(path, "/") {
33
34
t.Run(path, func(t *testing.T) { simulateFile(t, path) })
34
35
}
35
36
return nil
···
45
46
t.Fatalf("failed to open file %q: %v", path, err)
46
47
}
47
48
48
-
dir, err := ioutil.TempDir("", "tutbasics")
49
-
if err != nil {
50
-
t.Fatal(err)
49
+
if path == "Readme.md" {
50
+
return
51
51
}
52
-
defer os.Remove(dir)
52
+
53
+
archive := &txtar.Archive{}
54
+
55
+
addFile := func(filename string, body string) {
56
+
archive.Files = append(archive.Files, txtar.File{
57
+
Name: filename,
58
+
Data: []byte(strings.TrimSpace(body) + "\n\n"),
59
+
})
60
+
}
61
+
62
+
var (
63
+
baseName = path[:len(path)-len(".md")]
64
+
txtFile = baseName + ".txt"
65
+
)
66
+
67
+
defer func() {
68
+
err = ioutil.WriteFile(txtFile, txtar.Format(archive), 0644)
69
+
}()
53
70
54
71
c := cuetest.NewChunker(t, b)
55
72
56
-
// collect files
57
-
for c.Find("<!-- CUE editor -->") {
73
+
c.Find("\n")
74
+
c.Next("_", "_")
75
+
section := c.Text()
76
+
sub := strings.ToLower(strings.Fields(section)[0])
77
+
sub = strings.TrimRight(sub, ",")
78
+
79
+
c.Next("# ", "\n")
80
+
addFile("frontmatter.toml", fmt.Sprintf(`title = %q
81
+
description = ""
82
+
`, c.Text()))
83
+
84
+
for i := 0; c.Find("<!-- CUE editor -->"); i++ {
85
+
if i == 0 {
86
+
addFile("text.md", c.Text())
87
+
}
58
88
if !c.Next("_", "_") {
59
89
continue
60
90
}
···
63
93
if !c.Next("```", "```") {
64
94
t.Fatalf("No body for filename %q in file %q", filename, path)
65
95
}
66
-
b := bytes.TrimSpace(c.Bytes())
67
-
68
-
ioutil.WriteFile(filepath.Join(dir, filename), b, 0644)
96
+
addFile(filename, c.Text())
69
97
}
70
98
71
99
if !c.Find("<!-- result -->") {
···
75
103
if !c.Next("`$ ", "`") {
76
104
t.Fatalf("No command for result section in file %q", path)
77
105
}
78
-
command := c.Text()
106
+
archive.Comment = []byte(c.Text())
107
+
archive.Comment = append(archive.Comment, `
108
+
cmp stdout expect-stdout-cue
109
+
110
+
`...)
79
111
80
112
if !c.Next("```", "```") {
81
-
t.Fatalf("No body for result section in file %q", path)
113
+
return
82
114
}
83
115
gold := c.Text()
84
116
if p := strings.Index(gold, "\n"); p > 0 {
85
117
gold = gold[p+1:]
86
118
}
87
119
88
-
cuetest.Run(t, dir, command, &cuetest.Config{Golden: gold})
120
+
gold = strings.TrimSpace(gold) + "\n"
121
+
// TODO: manually adjust file type and stderr.
122
+
addFile("expect-stdout-cue", gold)
89
123
}
+64
doc/tutorial/basics/types.txt
+64
doc/tutorial/basics/types.txt
···
1
+
cue eval types.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Basic Types"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
CUE defines the following basic types
10
+
11
+
```
12
+
null bool string bytes int float
13
+
```
14
+
in addition to the error type mentioned in the previous section.
15
+
16
+
CUE does not distinguish between types and values.
17
+
A field value can be a type (using one of the above names), a concrete value,
18
+
or, in case of composite types (lists and structs), anything in between.
19
+
20
+
In the example, `point` defines an arbitrary point, while `xaxis` and `yaxis`
21
+
define the points on the respective lines.
22
+
We say that `point`, `xaxis`, and `yaxis` are abstract points, as these
23
+
points are underspecified.
24
+
Such abstract values cannot be represented as JSON,
25
+
which requires all values to be concrete.
26
+
27
+
The only concrete point is `origin`.
28
+
The `origin` is defined to be both on the x-axis and y-axis, which means it
29
+
must be at `0, 0`.
30
+
Here we see constraints in action:
31
+
`origin` evalutes to `0, 0`, even though we did not specify its coordinates
32
+
explicitly.
33
+
34
+
-- types.cue --
35
+
point: {
36
+
x: number
37
+
y: number
38
+
}
39
+
40
+
xaxis: point
41
+
xaxis x: 0
42
+
43
+
yaxis: point
44
+
yaxis y: 0
45
+
46
+
origin: xaxis & yaxis
47
+
48
+
-- expect-stdout-cue --
49
+
point: {
50
+
x: number
51
+
y: number
52
+
}
53
+
xaxis: {
54
+
x: 0
55
+
y: number
56
+
}
57
+
yaxis: {
58
+
x: number
59
+
y: 0
60
+
}
61
+
origin: {
62
+
x: 0
63
+
y: 0
64
+
}
+56
doc/tutorial/basics/unification.txt
+56
doc/tutorial/basics/unification.txt
···
1
+
cue eval -i unification.cue
2
+
cmp stdout expect-stdout-cue
3
+
4
+
-- frontmatter.toml --
5
+
title = "Order is Irrelevant"
6
+
description = ""
7
+
8
+
-- text.md --
9
+
As mentioned before, values of duplicates fields are combined.
10
+
This process is called unification.
11
+
Unification can also be written explicitly with the `&` operator.
12
+
13
+
There is always a single unique result, possibly bottom,
14
+
for unifying any two CUE values.
15
+
16
+
Unification is commutative, associative, and idempotent.
17
+
In other words, order doesn't matter and unifying a given set of values
18
+
in any order always gives the same result.
19
+
20
+
-- unification.cue --
21
+
a: { x: 1, y: 2 }
22
+
b: { y: 2, z: 3 }
23
+
c: { x: 1, z: 4 }
24
+
25
+
q: a & b & c
26
+
r: b & c & a
27
+
s: c & b & a
28
+
29
+
-- expect-stdout-cue --
30
+
a: {
31
+
x: 1
32
+
y: 2
33
+
}
34
+
b: {
35
+
y: 2
36
+
z: 3
37
+
}
38
+
c: {
39
+
x: 1
40
+
z: 4
41
+
}
42
+
q: {
43
+
x: 1
44
+
y: 2
45
+
z: _|_ // conflicting values 3 and 4
46
+
}
47
+
r: {
48
+
x: 1
49
+
y: 2
50
+
z: _|_ // conflicting values 3 and 4
51
+
}
52
+
s: {
53
+
x: 1
54
+
y: 2
55
+
z: _|_ // conflicting values 4 and 3
56
+
}