+2 -1

README.md

reviewed

··· 13 13 aimed at improving the overall experience of putting 14 14 configurations to good use. 15 15 16 16 - Features highlights: 16 16 + Some highlights: 17 17 18 18 - JSON superset: get started quickly 19 19 - convert existing YAML and JSON 20 20 + - arbitrary-precision arithmetic 20 21 - reformatter 21 22 - automatically simplify configurations 22 23 - powerful scripting

+487

doc/cmd/cue.md

reviewed

··· 1 1 + # `cue` command reference 2 2 + 3 3 + This documentation is a formatted from of the builtin documentation of the 4 4 + cue help command. 5 5 + 6 6 + ## General usage 7 7 + 8 8 + ``` 9 9 + cue [command] 10 10 + ``` 11 11 + 12 12 + The commands are: 13 13 + 14 14 + ``` 15 15 + cmd run a user-defined shell command 16 16 + eval evaluate a configuration file 17 17 + export outputs an evaluated configuration in a standard format 18 18 + extract 19 19 + fmt formats Cue configuration files. 20 20 + help Help about any command 21 21 + import convert other data formats to CUE files 22 22 + list list packages or modules 23 23 + serve starts a builtin or user-defined service 24 24 + 25 25 + Flags: 26 26 + --config string config file (default is $HOME/.cue) 27 27 + --debug give detailed error info 28 28 + -h, --help help for cue 29 29 + --pkg string CUE package to evaluate 30 30 + --root load a Cue package from its root 31 31 + ``` 32 32 + 33 33 + ## Start a bug report 34 34 + 35 35 + TODO 36 36 + 37 37 + ## Evaluate a CUE file 38 38 + 39 39 + ``` 40 40 + Flags: 41 41 + --pkg string Cue package to evaluate 42 42 + ``` 43 43 + 44 44 + ## Formatting CUE files 45 45 + 46 46 + `fmt` formats the given files or the files for the given packages in place. 47 47 + 48 48 + Usage: 49 49 + ``` 50 50 + cue fmt [-s] [packages] [flags] 51 51 + ``` 52 52 + Flags: 53 53 + ``` 54 54 + --config string config file (default is $HOME/.cue) 55 55 + --debug give detailed error info 56 56 + -n, --dryrun only run simulation 57 57 + -p, --package string Cue package to evaluate 58 58 + -s, --simplify simplify output 59 59 + ``` 60 60 + 61 61 + ## Exporting results 62 62 + 63 63 + `export` evaluates the configuration found in the current directory 64 64 + and prints the emit value to stdout. 65 65 + 66 66 + Examples: 67 67 + Evaluated and emit 68 68 + 69 69 + ``` 70 70 + # a single file 71 71 + cue export config.cue 72 72 + 73 73 + # multiple files: these are combined at the top-level. 74 74 + # Order doesn't matter. 75 75 + cue export file1.cue foo/file2.cue 76 76 + 77 77 + # all files within the "mypkg" package: this includes all files 78 78 + # in the current directory and its ancestor directories that are marked 79 79 + # with the same package. 80 80 + cue export -p cloud 81 81 + 82 82 + # the -p flag can be omitted if the directory only contains files for 83 83 + # the "mypkg" package. 84 84 + cue export 85 85 + ``` 86 86 + 87 87 + ### Emit value 88 88 + 89 89 + For CUE files, the generated configuration is derived from the top-level single expression, the emit value. For example, the file 90 90 + 91 91 + ``` 92 92 + // config.cue 93 93 + arg1: 1 94 94 + arg2: "my string" 95 95 + 96 96 + { 97 97 + a: arg1 98 98 + b: arg2 99 99 + } 100 100 + ``` 101 101 + yields the following JSON: 102 102 + ``` 103 103 + { 104 104 + "a": 1, 105 105 + "b": "my string" 106 106 + } 107 107 + ``` 108 108 + In absence of arguments, the current directory is loaded as a package instance. 109 109 + A package instance for a directory contains all files in the directory and its 110 110 + ancestor directories, up to the module root, belonging to the same package. 111 111 + 112 112 + If the package is not explicitly defined by the '-p' flag, it must be uniquely 113 113 + defined by the files in the current directory. 114 114 + 115 115 + ## Import files in another format 116 116 + 117 117 + `import` converts other data formats, like JSON and YAML to CUE files. 118 118 + The following file formats are currently supported: 119 119 + 120 120 + ``` 121 121 + Format Extensions 122 122 + JSON .json .jsonl .ndjson 123 123 + YAML .yaml .yml 124 124 + ``` 125 125 + 126 126 + Files can either be specified explicitly, or inferred from the specified 127 127 + packages. 128 128 + In either case, the file extension is replaced with `.cue`. 129 129 + It will fail if the file already exists by default. 130 130 + The -f flag overrides this. 131 131 + 132 132 + Examples: 133 133 + 134 134 + ``` 135 135 + # Convert individual files: 136 136 + $ cue import foo.json bar.json # create foo.yaml and bar.yaml 137 137 + 138 138 + # Convert all json files in the indicated directories: 139 139 + $ cue import ./... -type=json 140 140 + ``` 141 141 + 142 142 + 143 143 + ### The `--path` flag 144 144 + 145 145 + By default the parsed files are included as emit values. 146 146 + This default can be overridden by specifying a path, which has two forms: 147 147 + 148 148 + ``` 149 149 + -p ident* 150 150 + ``` 151 151 + 152 152 + and 153 153 + ``` 154 154 + -p ident "->" expr* 155 155 + ``` 156 156 + 157 157 + The first form specifies a fixed path. 158 158 + The empty path indicates including the value at the root. 159 159 + The second form allows expressing the path in terms of the imported value. 160 160 + An unbound identifier in the second form denotes a fixed name. 161 161 + Packages may be included with the -imports flag. 162 162 + Imports for top-level core packages are elided. 163 163 + 164 164 + 165 165 + ### Handling multiple documents or streams 166 166 + 167 167 + To handle Multi-document files, such as concatenated JSON objects or YAML files 168 168 + with document separators (---) the user must specify either the -path, -list, or 169 169 + -files flag. 170 170 + The -path flag assign each element to a path (identical paths are 171 171 + treated as usual); -list concatenates the entries, and -files causes each entry 172 172 + to be written to a different file. 173 173 + The -files flag may only be used if files are explicitly imported. 174 174 + The -list flag may be used in combination with the -path 175 175 + flag, concatenating each entry to the mapped location. 176 176 + 177 177 + Examples: 178 178 + 179 179 + ``` 180 180 + $ cat <<EOF > foo.yaml 181 181 + kind: Service 182 182 + name: booster 183 183 + EOF 184 184 + 185 185 + # include the parsed file as an emit value: 186 186 + $ cue import foo.yaml 187 187 + $ cat foo.cue 188 188 + { 189 189 + kind: Service 190 190 + name: booster 191 191 + } 192 192 + 193 193 + # include the parsed file at the root of the Cue file: 194 194 + $ cue import -f -p "" foo.yaml 195 195 + $ cat foo.cue 196 196 + kind: Service 197 197 + name: booster 198 198 + 199 199 + # include the import config at the mystuff path 200 200 + $ cue import -f -p mystuff foo.yaml 201 201 + $ cat foo.cue 202 202 + myStuff: { 203 203 + kind: Service 204 204 + name: booster 205 205 + } 206 206 + 207 207 + # append another object to the input file 208 208 + $ cat <<EOF >> foo.yaml 209 209 + --- 210 210 + kind: Deployment 211 211 + name: booster 212 212 + replicas: 1 213 213 + 214 214 + # base the path values on th input 215 215 + $ cue import -f -p "x -> strings.ToLower(x.kind) x.name" foo.yaml 216 216 + $ cat foo.cue 217 217 + service booster: { 218 218 + kind: "Service" 219 219 + name: "booster" 220 220 + } 221 221 + 222 222 + deployment booster: { 223 223 + kind: "Deployment" 224 224 + name: "booster 225 225 + replicas: 1 226 226 + } 227 227 + 228 228 + # base the path values on th input 229 229 + $ cue import -f -list -foo.yaml 230 230 + $ cat foo.cue 231 231 + [{ 232 232 + kind: "Service" 233 233 + name: "booster" 234 234 + }, { 235 235 + kind: "Deployment" 236 236 + name: "booster 237 237 + replicas: 1 238 238 + }] 239 239 + 240 240 + # base the path values on th input 241 241 + $ cue import -f -list -p "x->strings.ToLower(x.kind)" foo.yaml 242 242 + $ cat foo.cue 243 243 + service: [{ 244 244 + kind: "Service" 245 245 + name: "booster" 246 246 + } 247 247 + deployment: [{ 248 248 + kind: "Deployment" 249 249 + name: "booster 250 250 + replicas: 1 251 251 + }] 252 252 + ``` 253 253 + 254 254 + Usage: 255 255 + ``` 256 256 + cue import [flags] 257 257 + ``` 258 258 + 259 259 + Flags: 260 260 + ``` 261 261 + --dryrun force overwriting existing files 262 262 + --files force overwriting existing files 263 263 + --fix string apply given fix 264 264 + -f, --force force overwriting existing files 265 265 + -h, --help help for import 266 266 + --list concatenate multiple objects into a list 267 267 + -n, --name string glob filter for file names 268 268 + -o, --out string alternative output or - for stdout 269 269 + -p, --path string path to include root 270 270 + --type string only apply to files of this type 271 271 + ``` 272 272 + 273 273 + ## Extracting CUE files from source code 274 274 + 275 275 + TODO: doc 276 276 + 277 277 + ## Running scripts with CUE 278 278 + 279 279 + `cmd` executes user-defined named commands for each of the listed instances. 280 280 + 281 281 + Commands define actions on instances. 282 282 + For instance, they may define how to upload a configuration to Kubernetes. 283 283 + Commands are defined in cue files ending with `_tool.cue` while otherwise using 284 284 + the same packaging rules: tool files must have a matching package clause and 285 285 + the same rules as for normal files define which will be included in which 286 286 + package. 287 287 + Tool files have access to the package scope, but none of the fields defined 288 288 + in a tool file influence the output of a package. 289 289 + Tool files are typically defined at the module root so that they apply 290 290 + to all instances. 291 291 + 292 292 + 293 293 + ### Tasks 294 294 + 295 295 + Each command consists of one or more tasks. 296 296 + A task may load or write a file, consult a user on the command line, 297 297 + or fetch a web page, and so on. 298 298 + Each task has inputs and outputs. 299 299 + Outputs are typically are typically filled out by the task implementation as 300 300 + the task completes. 301 301 + 302 302 + Inputs of tasks my refer to outputs of other tasks. 303 303 + The cue tool does a static analysis of the configuration and only starts tasks 304 304 + that are fully specified. 305 305 + Upon completion of each task, cue rewrites the instance, 306 306 + filling in the completed task, and reevaluates which other tasks can now start, 307 307 + and so on until all tasks have completed. 308 308 + 309 309 + 310 310 + ### Command definition 311 311 + 312 312 + Commands are defined at the top-level of the configuration and all follow the 313 313 + following pattern: 314 314 + 315 315 + ``` 316 316 + command <Name>: { // from "cue/tool".Command 317 317 + // usage gives a short usage pattern of the command. 318 318 + // Example: 319 319 + // fmt [-n] [-x] [packages] 320 320 + usage: Name | string 321 321 + 322 322 + // short gives a brief on-line description of the command. 323 323 + // Example: 324 324 + // reformat package sources 325 325 + short: "" | string 326 326 + 327 327 + // long gives a detailed description of the command, including 328 328 + // a description of flags usage and examples. 329 329 + long: "" | string 330 330 + 331 331 + // A task defines a single action to be run as part of this command. 332 332 + // Each task can have inputs and outputs, depending on the type 333 333 + // task. The outputs are initially unspecified, but are filled out 334 334 + // by the tooling 335 335 + // 336 336 + task <Name>: { // from "cue/tool".Task 337 337 + // supported fields depend on type 338 338 + } 339 339 + 340 340 + VarValue = string | bool | int | float | [...string|int|float] 341 341 + 342 342 + // var declares values that can be set by command line flags or 343 343 + // environment variables. 344 344 + // 345 345 + // Example: 346 346 + // // environment to run in 347 347 + // var env: "test" | "prod" 348 348 + // The tool would print documentation of this flag as: 349 349 + // Flags: 350 350 + // --env string environment to run in: test(default) or prod 351 351 + var <Name>: VarValue 352 352 + 353 353 + // flag defines a command line flag. 354 354 + // 355 355 + // Example: 356 356 + // var env: "test" | "prod" 357 357 + // 358 358 + // // augment the flag information for var 359 359 + // flag env: { 360 360 + // shortFlag: "e" 361 361 + // description: "environment to run in" 362 362 + // } 363 363 + // 364 364 + // The tool would print documentation of this flag as: 365 365 + // Flags: 366 366 + // -e, --env string environment to run in: test(default), staging, or prod 367 367 + // 368 368 + flag <Name>: { // from "cue/tool".Flag 369 369 + // value defines the possible values for this flag. 370 370 + // The default is string. Users can define default values by 371 371 + // using disjunctions. 372 372 + value: env[Name].value | VarValue 373 373 + 374 374 + // name, if set, allows var to be set with the command-line flag 375 375 + // of the given name. null disables the command line flag. 376 376 + name: Name | null | string 377 377 + 378 378 + // short defines an abbreviated version of the flag. 379 379 + // Disabled by default. 380 380 + short: null | string 381 381 + } 382 382 + 383 383 + // populate flag with the default values for 384 384 + flag: { "\(k)": { value: v } | null for k, v in var } 385 385 + 386 386 + // env defines environment variables. It is populated with values 387 387 + // for var. 388 388 + // 389 389 + // To specify a var without an equivalent environment variable, 390 390 + // either specify it as a flag directly or disable the equally 391 391 + // named env entry explicitly: 392 392 + // 393 393 + // var foo: string 394 394 + // env foo: null // don't use environment variables for foo 395 395 + // 396 396 + env <Name>: { 397 397 + // name defines the environment variable that sets this flag. 398 398 + name: "CUE_VAR_" + strings.Upper(Name) | string | null 399 399 + 400 400 + // The value retrieved from the environment variable or null 401 401 + // if not set. 402 402 + value: null | string | bytes 403 403 + } 404 404 + env: { "\(k)": { value: v } | null for k, v in var } 405 405 + } 406 406 + ``` 407 407 + 408 408 + Available tasks can be found in the package documentation at 409 409 + 410 410 + ``` 411 411 + cmd/cue/tool/tasks. 412 412 + ``` 413 413 + 414 414 + More on tasks can be found in the tasks topic. 415 415 + 416 416 + Examples 417 417 + A simple file using command line execution: 418 418 + 419 419 + hello.cue: 420 420 + ``` 421 421 + package foo 422 422 + 423 423 + import "cue/tool/tasks/exec" 424 424 + 425 425 + city: "Amsterdam" 426 426 + ``` 427 427 + 428 428 + hello_tool.cue: 429 429 + ``` 430 430 + package foo 431 431 + 432 432 + // Say hello! 433 433 + command hello: { 434 434 + // whom to say hello to 435 435 + var who: "World" | string 436 436 + 437 437 + task print: exec.Run({ 438 438 + cmd: "echo Hello \(var.who)! Welcome to \(city)." 439 439 + }) 440 440 + } 441 441 + ``` 442 442 + 443 443 + Invoking the script on the command line: 444 444 + 445 445 + ``` 446 446 + $ cue cmd echo 447 447 + Hello World! Welcome to Amsterdam. 448 448 + 449 449 + $ cue cmd echo -who you 450 450 + Hello you! Welcome to Amsterdam. 451 451 + ``` 452 452 + An example with tasks depending on each other: 453 453 + 454 454 + ``` 455 455 + package foo 456 456 + 457 457 + import "cue/tool/tasks/exec" 458 458 + 459 459 + city: "Amsterdam" 460 460 + 461 461 + // Say hello! 462 462 + command hello: { 463 463 + var file: "out.txt" | string // save transcript to this file 464 464 + 465 465 + task ask: cli.Ask({ 466 466 + prompt: "What is your name?" 467 467 + response: string 468 468 + }) 469 469 + 470 470 + // starts after ask 471 471 + task echo: exec.Run({ 472 472 + cmd: "echo Hello \(task.ask.response)!"] 473 473 + stdout: string // capture stdout 474 474 + }) 475 475 + 476 476 + // starts after echo 477 477 + task write: file.Append({ 478 478 + filename: var.file 479 479 + contents: task.echo.stdout 480 480 + }) 481 481 + 482 482 + // also starts after echo 483 483 + task print: cli.Print({ 484 484 + contents: task.echo.stdout 485 485 + }) 486 486 + } 487 487 + ```

+6 -6

doc/contribute.md

reviewed

··· 256 256 257 257 <p> 258 258 Whether you already know what contribution to make, or you are searching for 259 259 - an idea, the <a href="https://github.com/cuelang/core/issues">issue tracker</a> is 259 259 + an idea, the <a href="https://github.com/cuelang/cue/issues">issue tracker</a> is 260 260 always the first place to go. 261 261 Issues are triaged to categorize them and manage the workflow. 262 262 </p> ··· 290 290 291 291 <ul> 292 292 <li> 293 293 - Issues that need investigation: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation"><code>is:issue is:open label:NeedsInvestigation</code></a> 293 293 + Issues that need investigation: <a href="https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsInvestigation"><code>is:issue is:open label:NeedsInvestigation</code></a> 294 294 </li> 295 295 <li> 296 296 - Issues that need a fix: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix"><code>is:issue is:open label:NeedsFix</code></a> 296 296 + Issues that need a fix: <a href="https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix"><code>is:issue is:open label:NeedsFix</code></a> 297 297 </li> 298 298 <li> 299 299 - Issues that need a fix and have a CL: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix "cuelang.org/cl"</code></a> 299 299 + Issues that need a fix and have a CL: <a href="https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix "cuelang.org/cl"</code></a> 300 300 </li> 301 301 <li> 302 302 - Issues that need a fix and do not have a CL: <a href="https://github.com/cuelang/core/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix NOT "cuelang.org/cl"</code></a> 302 302 + Issues that need a fix and do not have a CL: <a href="https://github.com/cuelang/cue/issues?q=is%3Aissue+is%3Aopen+label%3ANeedsFix+NOT+%22golang.org%2Fcl%22"><code>is:issue is:open label:NeedsFix NOT "cuelang.org/cl"</code></a> 303 303 </li> 304 304 </ul> 305 305 ··· 882 882 Files in the CUE repository don't list author names, both to avoid clutter 883 883 and to avoid having to keep the lists up to date. 884 884 Instead, your name will appear in the 885 885 - <a href="https://cue.googlesource.com/core/+log">change log</a> and in the <a 885 885 + <a href="https://cue.googlesource.com/cue/+log">change log</a> and in the <a 886 886 href="/CONTRIBUTORS"><code>CONTRIBUTORS</code></a> file and perhaps the <a 887 887 href="/AUTHORS"><code>AUTHORS</code></a> file. 888 888 These files are automatically generated from the commit logs periodically.

+38

doc/install.md

reviewed

··· 1 1 + # Getting Started 2 2 + 3 3 + Currently CUE can only be installed from source. 4 4 + 5 5 + ## Install CUE from source 6 6 + 7 7 + ### Prerequisites 8 8 + 9 9 + Go 1.10 or higher (see below) 10 10 + 11 11 + ### Installing CUE 12 12 + 13 13 + To download and install the `cue` command line tool run 14 14 + 15 15 + ``` 16 16 + go get -u cuelang.org/go/cmd/cue 17 17 + ``` 18 18 + 19 19 + And make sure the install directory is in your path. 20 20 + 21 21 + To also download the API and documentation, run 22 22 + 23 23 + ``` 24 24 + go get -u cuelang.org/go/cue 25 25 + ``` 26 26 + 27 27 + 28 28 + ### Installing Go 29 29 + 30 30 + #### Download Go 31 31 + 32 32 + You can load the binary for Windows, MacOS X, and Linux at https://golang.org/dl/. If you use a different OS you can install Go from source. 33 33 + 34 34 + #### Install Go 35 35 + 36 36 + Follow the instructions at https://golang.org/doc/install#install. 37 37 + Make sure the go binary is in your path. 38 38 + CUE uses Go modules, so there is no need to set up a GOPATH.

+2516

doc/ref/spec.md

reviewed

··· 1 1 + # The CUE Language Specification 2 2 + 3 3 + ## Introduction 4 4 + 5 5 + This is a reference manual for the CUE configuration language. 6 6 + CUE, pronounced cue or Q, is a general-purpose and strongly typed 7 7 + configuration language. 8 8 + The CUE tooling, layered on top of CUE, converts this language to 9 9 + a general purpose scripting language for creating scripts as well as 10 10 + simple servers. 11 11 + 12 12 + CUE was designed with cloud configuration, and related systems, in mind, 13 13 + but is not limited to this domain. 14 14 + It derives its formalism from relational programming languages. 15 15 + This formalism allows for managing and reasoning over large amounts of 16 16 + configuration in a straightforward manner. 17 17 + 18 18 + The grammar is compact and regular, allowing for easy analysis by automatic 19 19 + tools such as integrated development environments. 20 20 + 21 21 + This document is maintained by mpvl@golang.org. 22 22 + CUE has a lot of similarities with the Go language. This document draws heavily 23 23 + from the Go specification as a result, Copyright 2009–2018, The Go Authors. 24 24 + 25 25 + CUE draws its influence from many languages. 26 26 + Its main influences were BCL/ GCL (internal to Google), 27 27 + LKB (LinGO), Go, and JSON. 28 28 + Others are Swift, Javascript, Prolog, NCL (internal to Google), Jsonnet, HCL, 29 29 + Flabbergast, JSONPath, Haskell, Objective-C, and Python. 30 30 + 31 31 + 32 32 + ## Notation 33 33 + 34 34 + The syntax is specified using Extended Backus-Naur Form (EBNF): 35 35 + 36 36 + ``` 37 37 + Production = production_name "=" [ Expression ] "." . 38 38 + Expression = Alternative { "|" Alternative } . 39 39 + Alternative = Term { Term } . 40 40 + Term = production_name | token [ "…" token ] | Group | Option | Repetition . 41 41 + Group = "(" Expression ")" . 42 42 + Option = "[" Expression "]" . 43 43 + Repetition = "{" Expression "}" . 44 44 + ``` 45 45 + 46 46 + Productions are expressions constructed from terms and the following operators, 47 47 + in increasing precedence: 48 48 + 49 49 + ``` 50 50 + | alternation 51 51 + () grouping 52 52 + [] option (0 or 1 times) 53 53 + {} repetition (0 to n times) 54 54 + ``` 55 55 + 56 56 + Lower-case production names are used to identify lexical tokens. Non-terminals 57 57 + are in CamelCase. Lexical tokens are enclosed in double quotes "" or back quotes 58 58 + ``. 59 59 + 60 60 + The form a … b represents the set of characters from a through b as 61 61 + alternatives. The horizontal ellipsis … is also used elsewhere in the spec to 62 62 + informally denote various enumerations or code snippets that are not further 63 63 + specified. The character … (as opposed to the three characters ...) is not a 64 64 + token of the Go language. 65 65 + 66 66 + 67 67 + ## Source code representation 68 68 + 69 69 + Source code is Unicode text encoded in UTF-8. 70 70 + Unless otherwise noted, the text is not canonicalized, so a single 71 71 + accented code point is distinct from the same character constructed from 72 72 + combining an accent and a letter; those are treated as two code points. 73 73 + For simplicity, this document will use the unqualified term character to refer 74 74 + to a Unicode code point in the source text. 75 75 + 76 76 + Each code point is distinct; for instance, upper and lower case letters are 77 77 + different characters. 78 78 + 79 79 + Implementation restriction: For compatibility with other tools, a compiler may 80 80 + disallow the NUL character (U+0000) in the source text. 81 81 + 82 82 + Implementation restriction: For compatibility with other tools, a compiler may 83 83 + ignore a UTF-8-encoded byte order mark (U+FEFF) if it is the first Unicode code 84 84 + point in the source text. A byte order mark may be disallowed anywhere else in 85 85 + the source. 86 86 + 87 87 + 88 88 + ### Characters 89 89 + 90 90 + The following terms are used to denote specific Unicode character classes: 91 91 + 92 92 + ``` 93 93 + newline = /* the Unicode code point U+000A */ . 94 94 + unicode_char = /* an arbitrary Unicode code point except newline */ . 95 95 + unicode_letter = /* a Unicode code point classified as "Letter" */ . 96 96 + unicode_digit = /* a Unicode code point classified as "Number, decimal digit" */ . 97 97 + ``` 98 98 + 99 99 + In The Unicode Standard 8.0, Section 4.5 "General Category" defines a set of 100 100 + character categories. 101 101 + CUE treats all characters in any of the Letter categories Lu, Ll, Lt, Lm, or Lo 102 102 + as Unicode letters, and those in the Number category Nd as Unicode digits. 103 103 + 104 104 + 105 105 + ### Letters and digits 106 106 + 107 107 + The underscore character _ (U+005F) is considered a letter. 108 108 + 109 109 + ``` 110 110 + letter = unicode_letter | "_" . 111 111 + decimal_digit = "0" … "9" . 112 112 + octal_digit = "0" … "7" . 113 113 + hex_digit = "0" … "9" | "A" … "F" | "a" … "f" . 114 114 + ``` 115 115 + 116 116 + 117 117 + ## Lexical elements 118 118 + 119 119 + ### Comments 120 120 + Comments serve as program documentation. There are two forms: 121 121 + 122 122 + 1. Line comments start with the character sequence // and stop at the end of the line. 123 123 + 2. General comments start with the character sequence /* and stop with the first subsequent character sequence */. 124 124 + 125 125 + A comment cannot start inside string literal or inside a comment. 126 126 + A general comment containing no newlines acts like a space. 127 127 + Any other comment acts like a newline. 128 128 + 129 129 + 130 130 + ### Tokens 131 131 + 132 132 + Tokens form the vocabulary of the CUE language. There are four classes: 133 133 + identifiers, keywords, operators and punctuation, and literals. White space, 134 134 + formed from spaces (U+0020), horizontal tabs (U+0009), carriage returns 135 135 + (U+000D), and newlines (U+000A), is ignored except as it separates tokens that 136 136 + would otherwise combine into a single token. Also, a newline or end of file may 137 137 + trigger the insertion of a comma. While breaking the input into tokens, the 138 138 + next token is the longest sequence of characters that form a valid token. 139 139 + 140 140 + 141 141 + ### Commas 142 142 + 143 143 + The formal grammar uses commas "," as terminators in a number of productions. 144 144 + CUE programs may omit most of these commas using the following two rule: 145 145 + 146 146 + When the input is broken into tokens, a comma is automatically inserted into 147 147 + the token stream immediately after a line's final token if that token is 148 148 + 149 149 + - an identifier 150 150 + - null, true, false, bottom, an integer, a floating-point, or string literal 151 151 + - one of the punctuation ), ], or } 152 152 + 153 153 + 154 154 + Although commas are automatically inserted, the parser will require 155 155 + explicit commas between two list elements. 156 156 + 157 157 + To reflect idiomatic use, examples in this document elide commas using 158 158 + these rules. 159 159 + 160 160 + 161 161 + ### Identifiers 162 162 + 163 163 + Identifiers name entities such as fields and aliases. 164 164 + An identifier is a sequence of one or more letters and digits. 165 165 + It may not be `_`. 166 166 + The first character in an identifier must be a letter. 167 167 + 168 168 + <!-- 169 169 + TODO: allow identifiers as defined in Unicode UAX #31 170 170 + (https://unicode.org/reports/tr31/). 171 171 + 172 172 + Identifiers are normalized using the NFC normal form. 173 173 + --> 174 174 + 175 175 + ``` 176 176 + identifier = letter { letter | unicode_digit } . 177 177 + ``` 178 178 + 179 179 + ``` 180 180 + a 181 181 + _x9 182 182 + fieldName 183 183 + αβ 184 184 + ``` 185 185 + 186 186 + <!-- TODO: Allow Unicode identifiers TR 32 http://unicode.org/reports/tr31/ --> 187 187 + 188 188 + Some identifiers are [predeclared]. 189 189 + 190 190 + 191 191 + ### Keywords 192 192 + 193 193 + CUE has a limited set of keywords. 194 194 + All keywords may be used as labels (field names). 195 195 + They cannot, however, be used as identifiers to refer to the same name. 196 196 + 197 197 + 198 198 + #### Values 199 199 + 200 200 + The following keywords are values. 201 201 + 202 202 + ``` 203 203 + null true false 204 204 + ``` 205 205 + 206 206 + These can never be used to refer to a field of the same name. 207 207 + This restriction is to ensure compatibility with JSON configuration files. 208 208 + 209 209 + 210 210 + #### Preamble 211 211 + 212 212 + The following pseudo keywords are used at the preamble of a CUE file. 213 213 + After the preamble, they may be used as identifiers to refer to namesake fields. 214 214 + 215 215 + ``` 216 216 + package import 217 217 + ``` 218 218 + 219 219 + 220 220 + #### Comprehension clauses 221 221 + 222 222 + The following pseudo keywords are used in comprehensions. 223 223 + 224 224 + ``` 225 225 + for in if let 226 226 + ``` 227 227 + 228 228 + The pseudo keywords `for`, `if` and `let` cannot be used as identifiers to 229 229 + refer to fields. All others can. 230 230 + 231 231 + <!-- 232 232 + TODO: 233 233 + reduce [to] 234 234 + order [by] 235 235 + --> 236 236 + 237 237 + 238 238 + #### Arithmetic 239 239 + 240 240 + The following pseudo keywords can be used as operators in expressions. 241 241 + 242 242 + ``` 243 243 + div mod quo rem 244 244 + ``` 245 245 + 246 246 + These may be used as identifiers to refer to fields in all other contexts. 247 247 + 248 248 + 249 249 + ### Operators and punctuation 250 250 + 251 251 + The following character sequences represent operators and punctuation: 252 252 + 253 253 + ``` 254 254 + + & && == != ( ) 255 255 + - | || < <= [ ] 256 256 + * : ! > >= { } 257 257 + / :: ; = ... .. . 258 258 + div mod quo rem _|_ <- , 259 259 + ``` 260 260 + Optional: 261 261 + ``` 262 262 + -> ⊥ 263 263 + ``` 264 264 + 265 265 + 266 266 + ### Integer literals 267 267 + 268 268 + An integer literal is a sequence of digits representing an integer value. 269 269 + An optional prefix sets a non-decimal base: 0 for octal, 270 270 + 0x or 0X for hexadecimal, and 0b for binary. 271 271 + In hexadecimal literals, letters a-f and A-F represent values 10 through 15. 272 272 + All integers allow intersticial underscores "_"; 273 273 + these have no meaning and are solely for readability. 274 274 + 275 275 + Decimal integers may have a SI or IEC multiplier. 276 276 + Multipliers can be used with fractional numbers. 277 277 + The result of multiplying the fraction with the multiplier is truncated 278 278 + towards zero if the result is not an integer. 279 279 + 280 280 + ``` 281 281 + int_lit = decimal_lit | octal_lit | binary_lit | hex_lit . 282 282 + decimals = ( "0" … "9" ) { [ "_" ] decimal_digit } . 283 283 + decimal_lit = ( "1" … "9" ) { [ "_" ] decimal_digit } [ [ "." decimals ] multiplier ] | 284 284 + "." decimals multiplier. 285 285 + octal_lit = "0" octal_digit { [ "_" ] octal_digit } . 286 286 + binary_lit = "0b" binary_digit { binary_digit } . 287 287 + hex_lit = "0" ( "x" | "X" ) hex_digit { [ "_" ] hex_digit } . 288 288 + multiplier = "k" | "Ki" | ( "M" | "G" | "T" | "P" | "E" | "Y" | "Z" ) [ "i" ] 289 289 + ``` 290 290 + <!-- 291 291 + TODO: consider 0o766 notation for octal. 292 292 + ---> 293 293 + 294 294 + ``` 295 295 + 42 296 296 + 1.5Gi 297 297 + 0600 298 298 + 0xBad_Face 299 299 + 170_141_183_460_469_231_731_687_303_715_884_105_727 300 300 + ``` 301 301 + 302 302 + ### Decimal floating-point literals 303 303 + 304 304 + A decimal floating-point literal is a representation of 305 305 + a decimal floating-point value. 306 306 + We will refer to those as floats. 307 307 + It has an integer part, a decimal point, a fractional part, and an 308 308 + exponent part. 309 309 + The integer and fractional part comprise decimal digits; the 310 310 + exponent part is an `e` or `E` followed by an optionally signed decimal exponent. 311 311 + One of the integer part or the fractional part may be elided; one of the decimal 312 312 + point or the exponent may be elided. 313 313 + 314 314 + ``` 315 315 + decimal_lit = decimals "." [ decimals ] [ exponent ] | 316 316 + decimals exponent | 317 317 + "." decimals [ exponent ] . 318 318 + exponent = ( "e" | "E" ) [ "+" | "-" ] decimals . 319 319 + ``` 320 320 + 321 321 + ``` 322 322 + 0. 323 323 + 72.40 324 324 + 072.40 // == 72.40 325 325 + 2.71828 326 326 + 1.e+0 327 327 + 6.67428e-11 328 328 + 1E6 329 329 + .25 330 330 + .12345E+5 331 331 + ``` 332 332 + 333 333 + 334 334 + ### String literals 335 335 + A string literal represents a string constant obtained from concatenating a 336 336 + sequence of characters. There are three forms: raw string literals and 337 337 + interpreted strings and bytes sequences. 338 338 + 339 339 + Raw string literals are character sequences between back quotes, as in 340 340 + ``` 341 341 + `foo` 342 342 + ``` 343 343 + Within the quotes, any character may appear except back quote. The value of a 344 344 + raw string literal is the string composed of the uninterpreted (implicitly 345 345 + UTF-8-encoded) characters between the quotes; in particular, backslashes have no 346 346 + special meaning and the string may contain newlines. Carriage return characters 347 347 + (`\r`) inside raw string literals are discarded from the raw string value. 348 348 + 349 349 + Interpreted string and byte sequence literals are character sequences between, 350 350 + respectively, double and single quotes, as in `"bar"` and `'bar'`. 351 351 + Within the quotes, any character may appear except newline and, 352 352 + respectively, unescaped double or single quote. 353 353 + String literals may only be valid UTF-8. 354 354 + Byte sequences may contain any sequence of bytes. 355 355 + 356 356 + Several backslash escapes allow arbitrary values to be encoded as ASCII text 357 357 + in interpreted strings. 358 358 + There are four ways to represent the integer value as a numeric constant: `\x` 359 359 + followed by exactly two hexadecimal digits; \u followed by exactly four 360 360 + hexadecimal digits; `\U` followed by exactly eight hexadecimal digits, and a 361 361 + plain backslash `\` followed by exactly three octal digits. 362 362 + In each case the value of the literal is the value represented by the 363 363 + digits in the corresponding base. 364 364 + Hexadecimal and octal escapes are only allowed within byte sequences 365 365 + (single quotes). 366 366 + 367 367 + Although these representations all result in an integer, they have different 368 368 + valid ranges. 369 369 + Octal escapes must represent a value between 0 and 255 inclusive. 370 370 + Hexadecimal escapes satisfy this condition by construction. 371 371 + The escapes `\u` and `\U` represent Unicode code points so within them 372 372 + some values are illegal, in particular those above `0x10FFFF`. 373 373 + Surrogate halves are allowed to be compatible with JSON, 374 374 + but are translated into their non-surrogate equivalent internally. 375 375 + 376 376 + The three-digit octal (`\nnn`) and two-digit hexadecimal (`\xnn`) escapes 377 377 + represent individual bytes of the resulting string; all other escapes represent 378 378 + the (possibly multi-byte) UTF-8 encoding of individual characters. 379 379 + Thus inside a string literal `\377` and `\xFF` represent a single byte of 380 380 + value `0xFF=255`, while `ÿ`, `\u00FF`, `\U000000FF` and `\xc3\xbf` represent 381 381 + the two bytes `0xc3 0xbf` of the UTF-8 382 382 + encoding of character `U+00FF`. 383 383 + 384 384 + After a backslash, certain single-character escapes represent special values: 385 385 + 386 386 + ``` 387 387 + \a U+0007 alert or bell 388 388 + \b U+0008 backspace 389 389 + \f U+000C form feed 390 390 + \n U+000A line feed or newline 391 391 + \r U+000D carriage return 392 392 + \t U+0009 horizontal tab 393 393 + \v U+000b vertical tab 394 394 + \\ U+005c backslash 395 395 + \' U+0027 single quote (valid escape only within single quoted literals) 396 396 + \" U+0022 double quote (valid escape only within double quoted literals) 397 397 + ``` 398 398 + 399 399 + The escape `\(` is used as an escape for string interpolation. 400 400 + A `\(` must be followed by a valid CUE Expression, followed by a `)`. 401 401 + 402 402 + All other sequences starting with a backslash are illegal inside literals. 403 403 + 404 404 + ``` 405 405 + escaped_char = `\` ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | `\` | "'" | `"` ) . 406 406 + unicode_value = unicode_char | little_u_value | big_u_value | escaped_char . 407 407 + byte_value = octal_byte_value | hex_byte_value . 408 408 + octal_byte_value = `\` octal_digit octal_digit octal_digit . 409 409 + hex_byte_value = `\` "x" hex_digit hex_digit . 410 410 + little_u_value = `\` "u" hex_digit hex_digit hex_digit hex_digit . 411 411 + big_u_value = `\` "U" hex_digit hex_digit hex_digit hex_digit 412 412 + hex_digit hex_digit hex_digit hex_digit . 413 413 + 414 414 + string_lit = raw_string_lit | 415 415 + interpreted_string_lit | 416 416 + interpreted_bytes_lit | 417 417 + multiline_lit . 418 418 + interpolation = "\(" Expression ")" . 419 419 + raw_string_lit = "`" { unicode_char | newline } "`" . 420 420 + interpreted_string_lit = `"` { unicode_value | interpolation } `"` . 421 421 + interpreted_bytes_lit = `"` { unicode_value | interpolation | byte_value } `"` . 422 422 + ``` 423 423 + 424 424 + ``` 425 425 + `abc` // same as "abc" 426 426 + `\n 427 427 + \n` // same as "\\n\n\\n" 428 428 + 'a\000\xab' 429 429 + '\007' 430 430 + '\377' 431 431 + '\xa' // illegal: too few hexadecimal digits 432 432 + "\n" 433 433 + "\"" // same as `"` 434 434 + 'Hello, world!\n' 435 435 + "Hello, \( name )!" 436 436 + "日本語" 437 437 + "\u65e5本\U00008a9e" 438 438 + "\xff\u00FF" 439 439 + "\uD800" // illegal: surrogate half 440 440 + "\U00110000" // illegal: invalid Unicode code point 441 441 + ``` 442 442 + 443 443 + These examples all represent the same string: 444 444 + 445 445 + ``` 446 446 + "日本語" // UTF-8 input text 447 447 + '日本語' // UTF-8 input text as byte sequence 448 448 + `日本語` // UTF-8 input text as a raw literal 449 449 + "\u65e5\u672c\u8a9e" // the explicit Unicode code points 450 450 + "\U000065e5\U0000672c\U00008a9e" // the explicit Unicode code points 451 451 + "\xe6\x97\xa5\xe6\x9c\xac\xe8\xaa\x9e" // the explicit UTF-8 bytes 452 452 + ``` 453 453 + 454 454 + If the source code represents a character as two code points, such as a 455 455 + combining form involving an accent and a letter, the result will appear as two 456 456 + code points if placed in a string literal. 457 457 + 458 458 + Each of the interpreted string variants have a multiline equivalent. 459 459 + Multiline interpreted strings are like their single-line equivalent, 460 460 + but allow newline characters. 461 461 + Carriage return characters (`\r`) inside raw string literals are discarded from 462 462 + the raw string value. 463 463 + 464 464 + Multiline interpreted strings and byte sequences respectively start with 465 465 + a triple double quote (`"""`) or triple single quote (`'''`), 466 466 + immediately followed by a newline, which is discarded from the string contents. 467 467 + The string is closed by a matching triple quote, which must be by itself 468 468 + on a newline, preceded by optional whitespace. 469 469 + The whitespace before a closing triple quote must appear before any non-empty 470 470 + line after the opening quote and will be removed from each of these 471 471 + lines in the string literal. 472 472 + A closing triple quote may not appear in the string. 473 473 + To include it is suffices to escape one of the quotes. 474 474 + 475 475 + ``` 476 476 + multiline_lit = multiline_string_lit | multiline_bytes_lit . 477 477 + multiline_string_lit = `"""` newline 478 478 + { unicode_char | interpolation | newline } 479 479 + newline `"""` . 480 480 + multiline_bytes_lit = "'''" newline 481 481 + { unicode_char | interpolation | newline | byte_value } 482 482 + newline "'''" . 483 483 + ``` 484 484 + 485 485 + ``` 486 486 + """ 487 487 + lily: 488 488 + out of the water 489 489 + out of itself 490 490 + 491 491 + bass 492 492 + picking bugs 493 493 + off the moon 494 494 + — Nick Virgilio, Selected Haiku, 1988 495 495 + """ 496 496 + ``` 497 497 + 498 498 + This represents the same string as: 499 499 + 500 500 + ``` 501 501 + "lily:\nout of the water\nout of itself\n\n" + 502 502 + "bass\npicking bugs\noff the moon\n" + 503 503 + " — Nick Virgilio, Selected Haiku, 1988" 504 504 + ``` 505 505 + 506 506 + <!-- TODO: other values 507 507 + 508 508 + Support for other values: 509 509 + - Duration literals 510 510 + - regualr expessions: `re("[a-z]")` 511 511 + --> 512 512 + 513 513 + ## Prototypes 514 514 + 515 515 + CUE defines basic types and structs. The _basic types_ are null, bool, 516 516 + int, float, string, and bytes. 517 517 + A _struct_ is a map from a label to a value, where the value may be of any 518 518 + type. 519 519 + Lists, provided by CUE as a convenience, are special cases of structs and 520 520 + are not included in the definition of the type system. 521 521 + 522 522 + In CUE, all possible types and values are partially ordered in a lattice. 523 523 + CUE does not distinguish between types and values, only between 524 524 + concrete and partially defined instances of a certain type. 525 525 + 526 526 + For example `string` is the identifier used to set of all possible strings. 527 527 + The string `"hello"` is an instance of such a string and ordered below 528 528 + this string. The value `42` is not an instance of `string`. 529 529 + 530 530 + 531 531 + ### Ordering and lattices 532 532 + 533 533 + All possible prototypes are ordered in a lattice, 534 534 + a partial order where every two elements have a single greatest lower bound. 535 535 + A value `a` is said to be _greater_ than `b` if `a` orders before `b` in this 536 536 + partial order. 537 537 + At the top of this lattice is the single ancestor of all values, called 538 538 + _top_, denoted `_` in CUE. 539 539 + At the bottom of this lattice is the value called _bottom_, denoted `_|_`. 540 540 + A bottom value usually indicates an error. 541 541 + 542 542 + We say that for any two prototypes `a` and `b` that `a` is an _instance_ of `b`, 543 543 + denoted `a ⊑ b`, if `b == a` or `b` is more general than `a` 544 544 + that is if `a` orders before `b` in the partial order 545 545 + (`⊑` is _not_ a CUE operator). 546 546 + We also say that `b` subsumes `a` in this case. 547 547 + 548 548 + 549 549 + An _atom_ is any value whose only instance is itself and bottom. Examples of 550 550 + atoms are `42`, `"hello"`, `true`, `null`. 551 551 + 552 552 + A _type_ is any value which is only an instance of itself or top. 553 553 + This includes `null`: the null value, `bool`: all possible boolean values, 554 554 + `int`: all integral numbers, `float`, `string`, `bytes`, and `{}`. 555 555 + 556 556 + A _concrete value_ is any atom or struct with fields of which the values 557 557 + are itself concrete values, recursively. 558 558 + A concrete value corresponds to a valid JSON value 559 559 + 560 560 + A _prototype_ is any concrete value, type, or any instance of a type 561 561 + that is not a concrete value. 562 562 + We will informally refer to a prototype as _value_. 563 563 + 564 564 + 565 565 + ``` 566 566 + false ⊑ bool 567 567 + true ⊑ bool 568 568 + true ⊑ true 569 569 + 5 ⊑ int 570 570 + bool ⊑ _ 571 571 + ⊥ ⊑ _ 572 572 + ⊥ ⊑ ⊥ 573 573 + 574 574 + _ ⋢ ⊥ 575 575 + _ ⋢ bool 576 576 + int ⋢ bool 577 577 + bool ⋢ int 578 578 + false ⋢ true 579 579 + true ⋢ false 580 580 + int ⋢ 5 581 581 + 5 ⋢ 6 582 582 + ``` 583 583 + 584 584 + 585 585 + ### Unification 586 586 + 587 587 + The _unification_ of values `a` and `b`, denoted as `a & b` in CUE, 588 588 + is defined as the value `u` such that `u ⊑ a` and `u ⊑ b`, 589 589 + while for any other value `u'` for which `u' ⊑ a` and `u' ⊑ b` 590 590 + it holds that `u' ⊑ u`. 591 591 + The value `u` is also called the _greatest lower bound_ of `a` and `b`. 592 592 + The greatest lower bound is, given the nature of lattices, always unique. 593 593 + The unification of `a` with itself is always `a`. 594 594 + The unification of a value `a` and `b` where `a ⊑ b` is always `a`. 595 595 + 596 596 + Unification is commutative, transitive, and reflexive. 597 597 + As a consequence, order of evaluation is irrelevant, a property that is key 598 598 + to many of the constructs in the CUE language as well as the tooling layered 599 599 + on top of it. 600 600 + 601 601 + Syntactically, unification is a [binary expression]. 602 602 + 603 603 + 604 604 + ### Disjunction 605 605 + 606 606 + A _disjunction_ of two values `a` and `b`, denoted as `a | b` in CUE, 607 607 + is defined as the smallest value `d` such that `a ⊑ d` and `b ⊑ d`. 608 608 + The disjunction of `a` with itself is always `a`. 609 609 + The disjunction of a value `a` and `b` where `a ⊑ b` is always `b`. 610 610 + 611 611 + Syntactically, disjunction is a [binary expression]. 612 612 + 613 613 + Implementations should report an error if for a disjunction `a | ... | b`, 614 614 + `b` is an instance of `a`, as `b` will be superfluous and can never 615 615 + be selected as a default. 616 616 + 617 617 + A value that evaluates to bottom is removed from the disjunction. 618 618 + A disjunction evaluates to bottom if all of its values evaluate to bottom. 619 619 + 620 620 + If a disjunction is used in any operation other than unification or another 621 621 + disjunction, the default value is chosen before operating on it. 622 622 + 623 623 + ``` 624 624 + Expression Result (without picking default) 625 625 + (int | string) & "foo" "foo" 626 626 + ("a" | "b") & "c" _|_ 627 627 + 628 628 + (3 | 5) + 2 5 629 629 + ``` 630 630 + 631 631 + If the values of a disjunction are unambiguous, its first value may be taken 632 632 + as a default value. 633 633 + The default value for a disjunction is selected when: 634 634 + 635 635 + 1. passing it to an argument of a call or index value, 636 636 + 1. using it in any unary or binary expression except for unification or disjunction, 637 637 + 1. using it as the receiver of a call, index, slice, or selector expression, and 638 638 + 1. a value is taken for a configuration. 639 639 + 640 640 + A value is unambiguous if a disjunction has never been unified with another 641 641 + disjunction, or if the first element is the result of unifying two first 642 642 + values of a disjunction. 643 643 + 644 644 + 645 645 + ``` 646 646 + Expression Default 647 647 + ("tcp"|"udp") & ("tcp"|"udp") "tcp" // default chosen 648 648 + ("tcp"|"udp") & ("udp"|"tcp") _|_ // no unique default 649 649 + 650 650 + ("a"|"b") & ("b"|"a") & "a" "a" // single value after evaluation 651 651 + ``` 652 652 + 653 653 + 654 654 + ### Bottom and errors 655 655 + Any evaluation error in CUE results in a bottom value, respresented by 656 656 + the identifier '⊥' or token '_|_', the latter mostly used for user input. 657 657 + Bottom is an instance of every other prototype. 658 658 + Any evaluation error is represented as bottom. 659 659 + 660 660 + Implementations may associate error strings with different instances of bottom; 661 661 + logically they remain all the same value. 662 662 + 663 663 + ``` 664 664 + Expr Result 665 665 + 1 & 2 _|_ 666 666 + int & bool _|_ 667 667 + _|_ | 1 1 668 668 + _|_ & 2 _|_ 669 669 + _|_ & _|_ _|_ 670 670 + ``` 671 671 + 672 672 + 673 673 + ### Top 674 674 + Top is represented by the underscore character '_', lexically an identifier. 675 675 + Unifying any value `v` with top results `v` itself. 676 676 + 677 677 + ``` 678 678 + Expr Result 679 679 + _ & 5 5 680 680 + _ & _ _ 681 681 + _ & _|_ _|_ 682 682 + _ | _|_ _ 683 683 + ``` 684 684 + 685 685 + 686 686 + ### Null 687 687 + 688 688 + The _null value_ is represented with the pseudo keyword `null`. 689 689 + It has only one parent, top, and one child, bottom. 690 690 + It is unordered with respect to any other prototype. 691 691 + 692 692 + ``` 693 693 + null_lit = "null" 694 694 + ``` 695 695 + 696 696 + ``` 697 697 + null & 8 ⊥ 698 698 + ``` 699 699 + 700 700 + 701 701 + ### Boolean values 702 702 + 703 703 + A _boolean type_ represents the set of Boolean truth values denoted by 704 704 + the pseudo keywords `true` and `false`. 705 705 + The predeclared boolean type is `bool`; it is a defined type and a separate 706 706 + element in the lattice. 707 707 + 708 708 + ``` 709 709 + boolean_lit = "true" | "false" 710 710 + ``` 711 711 + 712 712 + ``` 713 713 + bool & true true 714 714 + bool | true true 715 715 + true | false true | false 716 716 + true & true true 717 717 + true & false ⊥ 718 718 + ``` 719 719 + 720 720 + 721 721 + ### Numeric values 722 722 + 723 723 + An _integer type_ represents the set of all integral numbers. 724 724 + A _decimal floating-point type_ represents of all decimal floating-point 725 725 + numbers. 726 726 + They are two distinct types. 727 727 + The predeclared integer and decimal floating-point type are `int` and `float`; 728 728 + they are a defined type. 729 729 + 730 730 + A decimal floating-point literal always has type `float`; 731 731 + it is not an instance of `int` even if it is an integral number. 732 732 + 733 733 + An integer literal has both type `int` and `float`, with the integer variant 734 734 + being the default if no other constraints are applied. 735 735 + Expressed in terms of disjunction and [type conversion], 736 736 + the literal `1`, for instance, is defined as `int(1) | float(1)`. 737 737 + 738 738 + Numeric values are exact values of arbitrary precision and do not overflow. 739 739 + Consequently, there are no constants denoting the IEEE-754 negative zero, 740 740 + infinity, and not-a-number values. 741 741 + 742 742 + Implementation restriction: Although numeric values have arbitrary precision 743 743 + in the language, implementations may implement them using an internal 744 744 + representation with limited precision. That said, every implementation must: 745 745 + 746 746 + Represent integer values with at least 256 bits. 747 747 + Represent floating-point values, with a mantissa of at least 256 bits and 748 748 + a signed binary exponent of at least 16 bits. 749 749 + Give an error if unable to represent an integer value precisely. 750 750 + Give an error if unable to represent a floating-point value due to overflow. 751 751 + Round to the nearest representable value if unable to represent 752 752 + a floating-point value due to limits on precision. 753 753 + These requirements apply to the result of any expression except builtin 754 754 + expressions where the loss of precision is remarked. 755 755 + 756 756 + 757 757 + ### Strings 758 758 + 759 759 + The _string type_ represents the set of all possible UTF-8 strings, 760 760 + not allowing surrogates. 761 761 + The predeclared string type is `string`; it is a defined type. 762 762 + 763 763 + Strings are designed to be unicode-safe. 764 764 + Comparisson is done using canonical forms ("é" == "e\u0301"). 765 765 + A string element is an extended grapheme cluster, which is an approximation 766 766 + of a human readable character. 767 767 + The length of a string is its number of extended grapheme clusters, and can 768 768 + be discovered using the built-in function `len`. 769 769 + 770 770 + The length of a string `s` (its size in bytes) can be discovered using 771 771 + the built-in function len. 772 772 + A string's extended grapheme cluster can be accessed by integer index 773 773 + 0 through len(s)-1 for any byte that is part of that grapheme cluster. 774 774 + To access the individual bytes of a string one should convert it to 775 775 + a sequence of bytes first. 776 776 + 777 777 + 778 778 + ### Ranges 779 779 + 780 780 + A _range type_, syntactically a [binary expression], defines 781 781 + a disjunction of concrete values that can be represented as a contiguous range. 782 782 + Ranges can be defined on numbers and strings. 783 783 + 784 784 + The type of range `a..b` is the unification of the type of `a` and `b`. 785 785 + Note that this may be more than one type. 786 786 + 787 787 + A range of numbers `a..b` defines an inclusive range for integers and 788 788 + floating-point numbers. 789 789 + 790 790 + Remember that an integer literal represents both an `int` and `float`: 791 791 + ``` 792 792 + 2 & 1..5 // 2, where 2 is either an int or float. 793 793 + 2.5 & 1..5 // 2.5 794 794 + 2.5 & int & 1..5 // ⊥ 795 795 + 2.5 & (int & 1)..5 // ⊥ 796 796 + 2.5 & float & 1..5 // 2.5 797 797 + 0..7 & 3..10 // 3..7 798 798 + ``` 799 799 + 800 800 + A range of strings `a..b` defines a set of strings that includes any `s` 801 801 + for which `NFC(a) <= NFC(s)` and `NFC(s) <= NFC(b)` in a byte-wise comparison, 802 802 + where `NFC` is the respective Unicode normal form. 803 803 + 804 804 + 805 805 + ### Structs 806 806 + 807 807 + A _struct_ is a set of named elements, called _fields_, each of 808 808 + which has a name, called a _label_, and value. 809 809 + Structs and fields respectively correspond to JSON objects and members. 810 810 + 811 811 + We say a label is defined for a struct if the struct has a field with the 812 812 + corresponding label. 813 813 + We denote the value for a label `f` defined for `a` as `δ(f, a)`. 814 814 + 815 815 + A struct `a` is an instance of `b`, or `a ⊑ b`, if for any label `f` 816 816 + defined for `b` label `f` is also defiend for `a` and `δ(f, a) ⊑ δ(f, b)`. 817 817 + Note that if `a` is an instance of `b` it may have fields with labels that 818 818 + are not defined for `b`. 819 819 + 820 820 + The unification of structs `a` and `b` is defined as a new struct `c` which 821 821 + has all fields of `a` and `b` where the value is either the unification of the 822 822 + respective values where a field is contained in both or the original value 823 823 + for the respective fields of `a` or `b` otherwise. 824 824 + Any [references] to `a` or `b` in their respective field values need to be 825 825 + replaced with references to `c`. 826 826 + 827 827 + Syntactically, a struct literal may contain multiple fields with 828 828 + the same label, the result of which is a single field with a value 829 829 + that is the result of unifying the values of those fields. 830 830 + 831 831 + ``` 832 832 + StructLit = "{" [ { Declaration "," } Declaration ] "}" . 833 833 + Declaration = FieldDecl | AliasDecl . 834 834 + FieldDecl = Label { Label } ":" Expression . 835 835 + 836 836 + AliasDecl = Label "=" Expression . 837 837 + Label = identifier | json_string | TemplateLabel | ExprLabel. 838 838 + TemplateLabel = "<" identifier ">" . 839 839 + ExprLabel = "[" Expression "]" . 840 840 + Tag = "#" identifier [ ":" json_string ] . 841 841 + json_string = `"` { unicode_value } `"` 842 842 + ``` 843 843 + 844 844 + <!-- 845 845 + TODO: consider using string interpolations for ExprLabel, instead of [] 846 846 + So "\(k)" for [k] 847 847 + ---> 848 848 + 849 849 + 850 850 + ``` 851 851 + {a: 1} ⊑ {} 852 852 + {a: 1, b: 1} ⊑ {a: 1} 853 853 + {a: 1} ⊑ {a: int} 854 854 + {a: 1, b: 1} ⊑ {a: int, b: float} 855 855 + 856 856 + {} ⋢ {a: 1} 857 857 + {a: 2} ⋢ {a: 1} 858 858 + {a: 1} ⋢ {b: 1} 859 859 + ``` 860 860 + 861 861 + ``` 862 862 + Expression Result 863 863 + {a: int, a: 1} {a: int(1)} 864 864 + {a: int} & {a: 1} {a: 1} 865 865 + {a: 1..7} & {a: 5..9} {a: 5..7} 866 866 + {a: 1..7, a: 5..9} {a: 5..7} 867 867 + 868 868 + {a: 1} & {b: 2} {a: 1, b: 2} 869 869 + {a: 1, b: int} & {b: 2} {a: 1, b: 2} 870 870 + 871 871 + {a: 1} & {a: 2} ⊥ 872 872 + ``` 873 873 + 874 874 + A struct literal may, besides fields, also define aliases. 875 875 + Aliases declare values that can be referred to within the [scope] of their 876 876 + definition, but are not part of the struct: aliases are irrelevant to 877 877 + the partial ordering of values and are not emitted as part of any 878 878 + generated data. 879 879 + The name of an alias must be unique within the struct literal. 880 880 + 881 881 + ``` 882 882 + // An empty object. 883 883 + {} 884 884 + 885 885 + // An object with 3 fields and 1 alias. 886 886 + { 887 887 + alias = 3 888 888 + 889 889 + foo: 2 890 890 + bar: "a string" 891 891 + 892 892 + "not an ident": 4 893 893 + } 894 894 + ``` 895 895 + 896 896 + A field with as value a struct with a single field may be written as 897 897 + a sequence of the two field names, 898 898 + followed by a colon and the value of that single field. 899 899 + 900 900 + ``` 901 901 + job myTask: { 902 902 + replicas: 2 903 903 + } 904 904 + ``` 905 905 + expands to the following JSON: 906 906 + ``` 907 907 + "job": { 908 908 + "myTask": { 909 909 + "replicas": 2 910 910 + } 911 911 + } 912 912 + ``` 913 913 + 914 914 + 915 915 + A field declaration may be followed by an optional field tag, 916 916 + which becomes a key value pair for all equivalent fields in structs with which 917 917 + it is unified. 918 918 + If two structs are unified which both define a field for a label and both 919 919 + fields have a tag for that field with the same key, 920 920 + implementations may require that their value match. 921 921 + The tags are made visible through CUE's API and are 922 922 + not visible within the language itself. 923 923 + 924 924 + 925 925 + ### Lists 926 926 + 927 927 + A list literal defines a new prototype of type list. 928 928 + A list may be open or closed. 929 929 + An open list is indicated with a `...` at the end of an element list, 930 930 + optionally followed by a prototype for the remaining elements. 931 931 + 932 932 + The length of a closed list is the number of elements it contains. 933 933 + The length of an open list is the its number of elements as a lower bound 934 934 + and an unlimited number of elements as its upper bound. 935 935 + 936 936 + ``` 937 937 + ListLit = "[" [ ElementList [ "," [ "..." [ Element ] ] ] "]" . 938 938 + ElementList = Element { "," Element } . 939 939 + Element = Expression | LiteralValue . 940 940 + ``` 941 941 + <!--- 942 942 + KeyedElement = Element . 943 943 + ---> 944 944 + 945 945 + A list can be represented as a struct: 946 946 + 947 947 + ``` 948 948 + List: null | { 949 949 + Elem: _ 950 950 + Tail: List 951 951 + } 952 952 + ``` 953 953 + 954 954 + For closed lists, `Tail` is `null` for the last element, for open lists it is 955 955 + `null | List`. 956 956 + For instance, the closed list [ 1, 2, ... ] can be represented as: 957 957 + ``` 958 958 + open: List & { Elem: 1, Tail: { Elem: 2 } } 959 959 + ``` 960 960 + and the closed version of this list, [ 1, 2 ], as 961 961 + ``` 962 962 + closed: List & { Elem: 1, Tail: { Elem: 2, Tail: null } } 963 963 + ``` 964 964 + 965 965 + Using this definition, the subsumption and unification rules for lists can 966 966 + be derived from those of structs. 967 967 + Implementations are not required to implement lists as structs. 968 968 + 969 969 + 970 970 + ## Declarations and Scopes 971 971 + 972 972 + 973 973 + ### Blocks 974 974 + 975 975 + A _block_ is a possibly empty sequence of declarations. 976 976 + A block is mostly corresponds with the brace brackets of a struct literal 977 977 + `{ ... }`, but also includes the following, 978 978 + 979 979 + - The _universe block_ encompases all CUE source text. 980 980 + - Each package has a _package block_ containing all CUE source text in that package. 981 981 + - Each file has a _file block_ containing all CUE source text in that file. 982 982 + - Each `for` and `let` clause in a comprehension is considered to be 983 983 + its own implicit block. 984 984 + - Each function value is considered to be its own implicit block. 985 985 + 986 986 + Blocks nest and influence [scoping]. 987 987 + 988 988 + 989 989 + ### Declarations and scope 990 990 + 991 991 + A _declaration_ binds an identifier to a field, alias, or package. 992 992 + Every identifier in a program must be declared. 993 993 + Other than for fields, 994 994 + no identifier may be declared twice within the same block. 995 995 + For fields an identifier may be declared more than once within the same block, 996 996 + resulting in a field with a value that is the result of unifying the values 997 997 + of all fields with the same identifier. 998 998 + 999 999 + ``` 1000 1000 + TopLevelDecl = Declaration | Emit . 1001 1001 + Emit = Operand . 1002 1002 + ``` 1003 1003 + 1004 1004 + The _scope_ of a declared identifier is the extent of source text in which the 1005 1005 + identifier denotes the specified field, alias, function, or package. 1006 1006 + 1007 1007 + CUE is lexically scoped using blocks: 1008 1008 + 1009 1009 + 1. The scope of a [predeclared identifier] is the universe block. 1010 1010 + 1. The scope of an identifier denoting a field or alias 1011 1011 + declared at top level (outside any struct literal) is the file block. 1012 1012 + 1. The scope of the package name of an imported package is the file block of the 1013 1013 + file containing the import declaration. 1014 1014 + 1. The scope of a field or alias identifier declared inside a struct literal 1015 1015 + is the innermost containing block. 1016 1016 + 1017 1017 + An identifier declared in a block may be redeclared in an inner block. 1018 1018 + While the identifier of the inner declaration is in scope, it denotes the entity 1019 1019 + declared by the inner declaration. 1020 1020 + 1021 1021 + The package clause is not a declaration; 1022 1022 + the package name do not appear in any scope. 1023 1023 + Its purpose is to identify the files belonging to the same package 1024 1024 + and tospecify the default name for import declarations. 1025 1025 + 1026 1026 + 1027 1027 + ### Predeclared identifiers 1028 1028 + 1029 1029 + ``` 1030 1030 + Functions 1031 1031 + len required close open 1032 1032 + 1033 1033 + Types 1034 1034 + null The null type and value 1035 1035 + bool All boolean values 1036 1036 + int All integral numbers 1037 1037 + float All decimal floating-point numbers 1038 1038 + string Any valid UTF-8 sequence 1039 1039 + bytes A blob of bytes representing arbitrary data 1040 1040 + 1041 1041 + Derived Value 1042 1042 + number int | float 1043 1043 + uint 0..int 1044 1044 + uint8 0..255 1045 1045 + byte uint8 1046 1046 + int8 -128..127 1047 1047 + uint16 0..65536 1048 1048 + int16 -32_768...32_767 1049 1049 + rune 0..0x10FFFF 1050 1050 + uint32 0..4_294_967_296 1051 1051 + int32 -2_147_483_648..2_147_483_647 1052 1052 + uint64 0..18_446_744_073_709_551_615 1053 1053 + int64 -9_223_372_036_854_775_808..9_223_372_036_854_775_807 1054 1054 + uint128 340_282_366_920_938_463_463_374_607_431_768_211_455 1055 1055 + 1056 1056 + "int128": mkIntRange( 1057 1057 + "-170141183460469231731687303715884105728", 1058 1058 + "170141183460469231731687303715884105727"), 1059 1059 + 1060 1060 + // Do not include an alias for "byte", as it would be too easily confused 1061 1061 + // with the builtin "bytes". 1062 1062 + "uint8": mkIntRange("0", "255"), 1063 1063 + "uint16": mkIntRange("0", "65535"), 1064 1064 + "uint32": mkIntRange("0", "4294967295"), 1065 1065 + "uint64": mkIntRange("0", "18446744073709551615"), 1066 1066 + } 1067 1067 + ``` 1068 1068 + 1069 1069 + 1070 1070 + ### Exported and manifested identifiers 1071 1071 + 1072 1072 + An identifier of a package may be exported to permit access to it 1073 1073 + from another package. 1074 1074 + An identifier is exported if both: 1075 1075 + the first character of the identifier's name is not a Unicode lower case letter 1076 1076 + (Unicode class "Ll") or the underscore "_"; and 1077 1077 + the identifier is declared in the file block. 1078 1078 + All other identifiers are not exported. 1079 1079 + 1080 1080 + An identifier that starts with the underscore "_" is not 1081 1081 + emitted in any data output. 1082 1082 + Quoted labels that start with an underscore are emitted nonetheless. 1083 1083 + 1084 1084 + ### Uniqueness of identifiers 1085 1085 + 1086 1086 + Given a set of identifiers, an identifier is called unique if it is different 1087 1087 + from every other in the set, after applying normalization following 1088 1088 + Unicode Annex #31. 1089 1089 + Two identifiers are different if they are spelled differently. 1090 1090 + <!-- 1091 1091 + or if they appear in different packages and are not exported. 1092 1092 + ---> 1093 1093 + Otherwise, they are the same. 1094 1094 + 1095 1095 + 1096 1096 + ### Field declarations 1097 1097 + 1098 1098 + A field declaration binds a label (the names of the field) to an expression. 1099 1099 + The name for a quoted string used as label is the string it represents. 1100 1100 + Tne name for an identifier used as a label is the identifier itself. 1101 1101 + Quoted strings and identifiers can be used used interchangeably, with the 1102 1102 + exception of identifiers starting with an underscore '_'. 1103 1103 + The latter represent hidden fields and are treated in a different namespace. 1104 1104 + 1105 1105 + 1106 1106 + ### Alias declarations 1107 1107 + 1108 1108 + An alias declaration binds an identifier to the given expression. 1109 1109 + 1110 1110 + Within the scope of the identifier, it serves as an _alias_ for that 1111 1111 + expression. 1112 1112 + The expression is evaluated in the scope as it was declared. 1113 1113 + 1114 1114 + 1115 1115 + ### Function declarations 1116 1116 + 1117 1117 + NOTE: this is an internal construction. 1118 1118 + 1119 1119 + A function declaration binds an identifier, the function name, to a function. 1120 1120 + 1121 1121 + ``` 1122 1122 + FunctionDecl = FunctionName Parameters "->" FunctionValue . 1123 1123 + FunctionName = identifier . 1124 1124 + FunctionValue = Expression . 1125 1125 + Result = Parameters . 1126 1126 + Parameters = "(" [ ParameterList [ "," ] ] ")" . 1127 1127 + ParameterList = ParameterDecl { "," ParameterDecl } . 1128 1128 + ParameterDecl = identifier [ ":" Type ] . 1129 1129 + ``` 1130 1130 + 1131 1131 + 1132 1132 + ## Expressions 1133 1133 + 1134 1134 + An expression specifies the computation of a value by applying operators and 1135 1135 + functions to operands. 1136 1136 + 1137 1137 + 1138 1138 + ### Operands 1139 1139 + 1140 1140 + Operands denote the elementary values in an expression. 1141 1141 + An operand may be a literal, a (possibly [qualified]) identifier denoting 1142 1142 + field, alias, function, or a parenthesized expression. 1143 1143 + 1144 1144 + ``` 1145 1145 + Operand = Literal | OperandName | ListComprehension | "(" Expression ")" . 1146 1146 + Literal = BasicLit | ListLit | StructLit . 1147 1147 + BasicLit = int_lit | float_lit | string_lit | 1148 1148 + null_lit | bool_lit | bottom_lit | top_lit . 1149 1149 + OperandName = identifier | QualifiedIdent. 1150 1150 + ``` 1151 1151 + 1152 1152 + ### Qualified identifiers 1153 1153 + 1154 1154 + A qualified identifier is an identifier qualified with a package name prefix. 1155 1155 + 1156 1156 + ``` 1157 1157 + QualifiedIdent = PackageName "." identifier . 1158 1158 + ``` 1159 1159 + 1160 1160 + A qualified identifier accesses an identifier in a different package, 1161 1161 + which must be [imported]. 1162 1162 + The identifier must be declared in the [package block] of that package. 1163 1163 + 1164 1164 + ``` 1165 1165 + math.Sin // denotes the Sin function in package math 1166 1166 + ``` 1167 1167 + 1168 1168 + 1169 1169 + ### Primary expressions 1170 1170 + 1171 1171 + Primary expressions are the operands for unary and binary expressions. 1172 1172 + 1173 1173 + ``` 1174 1174 + PrimaryExpr = 1175 1175 + Operand | 1176 1176 + Conversion | 1177 1177 + PrimaryExpr Selector | 1178 1178 + PrimaryExpr Index | 1179 1179 + PrimaryExpr Slice | 1180 1180 + PrimaryExpr Arguments . 1181 1181 + 1182 1182 + Selector = "." identifier . 1183 1183 + Index = "[" Expression "]" . 1184 1184 + Slice = "[" [ Expression ] ":" [ Expression ] "]" 1185 1185 + Argument = Expression . 1186 1186 + Arguments = "(" [ ( Argument { "," Argument } ) [ "..." ] [ "," ] ] ")" . 1187 1187 + ``` 1188 1188 + <!--- 1189 1189 + Argument = Expression | ( identifer ":" Expression ). 1190 1190 + ---> 1191 1191 + 1192 1192 + ``` 1193 1193 + x 1194 1194 + 2 1195 1195 + (s + ".txt") 1196 1196 + f(3.1415, true) 1197 1197 + m["foo"] 1198 1198 + s[i : j + 1] 1199 1199 + obj.color 1200 1200 + f.p[i].x 1201 1201 + ``` 1202 1202 + 1203 1203 + 1204 1204 + ### Selectors 1205 1205 + 1206 1206 + For a [primary expression] `x` that is not a [package name], 1207 1207 + the selector expression 1208 1208 + 1209 1209 + ``` 1210 1210 + x.f 1211 1211 + ``` 1212 1212 + 1213 1213 + denotes the field `f` of the value `x`. 1214 1214 + The identifier `f` is called the field selector. 1215 1215 + The type of the selector expression is the type of `f`. 1216 1216 + If `x` is a package name, see the section on [qualified identifiers]. 1217 1217 + 1218 1218 + Otherwise, if `x` is not a struct, or if `f` does not exist in `x`, 1219 1219 + the result of the expression is bottom (an error). 1220 1220 + 1221 1221 + ``` 1222 1222 + T: { 1223 1223 + x: int 1224 1224 + y: 3 1225 1225 + } 1226 1226 + 1227 1227 + a: T.x // int 1228 1228 + b: T.y // 3 1229 1229 + c: T.z // ⊥ // field 'z' not found in T 1230 1230 + ``` 1231 1231 + 1232 1232 + 1233 1233 + ### Index expressions 1234 1234 + 1235 1235 + A primary expression of the form 1236 1236 + 1237 1237 + ``` 1238 1238 + a[x] 1239 1239 + ``` 1240 1240 + 1241 1241 + denotes the element of the list, string, or struct `a` indexed by `x`. 1242 1242 + The value `x` is called the index or field name, respectively. 1243 1243 + The following rules apply: 1244 1244 + 1245 1245 + If `a` is not a struct: 1246 1246 + 1247 1247 + - the index `x` must be of integer type 1248 1248 + - the index `x` is in range if `0 <= x < len(a)`, otherwise it is out of range 1249 1249 + 1250 1250 + The result of `a[x]` is 1251 1251 + 1252 1252 + for `a` of list type (including single quoted strings, which are lists of bytes): 1253 1253 + 1254 1254 + - the list element at index `x`, if `x` is within range 1255 1255 + - bottom (an error), otherwise 1256 1256 + 1257 1257 + for `a` of string type: 1258 1258 + 1259 1259 + - the grapheme cluster at the `x`th byte (type string), if `x` is within range 1260 1260 + - bottom (an error), otherwise 1261 1261 + 1262 1262 + for `a` of struct type: 1263 1263 + 1264 1264 + - the value of the field named `x` of struct `a`, if this field exists 1265 1265 + - bottom (an error), otherwise 1266 1266 + 1267 1267 + ``` 1268 1268 + [ 1, 2 ][1] // 2 1269 1269 + [ 1, 2 ][2] // ⊥ 1270 1270 + "He\u0300?"[0] // "H" 1271 1271 + "He\u0300?"[1] // "e\u0300" 1272 1272 + "He\u0300?"[2] // "e\u0300" 1273 1273 + "He\u0300?"[3] // "e\u0300" 1274 1274 + "He\u0300?"[4] // "?" 1275 1275 + "He\u0300?"[5] // ⊥ 1276 1276 + ``` 1277 1277 + 1278 1278 + 1279 1279 + ### Slice expressions 1280 1280 + 1281 1281 + Slice expressions construct a substring or slice from a string or list. 1282 1282 + 1283 1283 + For strings or lists, the primary expression 1284 1284 + ``` 1285 1285 + a[low : high] 1286 1286 + ``` 1287 1287 + constructs a substring or slice. The indices `low` and `high` select 1288 1288 + which elements of operand a appear in the result. The result has indices 1289 1289 + starting at 0 and length equal to `high` - `low`. 1290 1290 + After slicing the list `a` 1291 1291 + 1292 1292 + ``` 1293 1293 + a := [1, 2, 3, 4, 5] 1294 1294 + s := a[1:4] 1295 1295 + ``` 1296 1296 + the list s has length 3 and elements 1297 1297 + ``` 1298 1298 + s[0] == 2 1299 1299 + s[1] == 3 1300 1300 + s[2] == 4 1301 1301 + ``` 1302 1302 + For convenience, any of the indices may be omitted. 1303 1303 + A missing `low` index defaults to zero; a missing `high` index defaults 1304 1304 + to the length of the sliced operand: 1305 1305 + ``` 1306 1306 + a[2:] // same as a[2 : len(a)] 1307 1307 + a[:3] // same as a[0 : 3] 1308 1308 + a[:] // same as a[0 : len(a)] 1309 1309 + ``` 1310 1310 + 1311 1311 + Indices are in range if `0 <= low <= high <= len(a)`, 1312 1312 + otherwise they are out of range. 1313 1313 + For strings, the indices selects the start of the extended grapheme cluster 1314 1314 + at byte position indicated by the index. 1315 1315 + If any of the slice values is out of range or if `low > high`, the result of 1316 1316 + a slice is bottom (error). 1317 1317 + 1318 1318 + ``` 1319 1319 + "He\u0300?"[:2] // "He\u0300" 1320 1320 + "He\u0300?"[1:2] // "e\u0300" 1321 1321 + "He\u0300?"[4:5] // "e\u0300?" 1322 1322 + ``` 1323 1323 + 1324 1324 + 1325 1325 + The result of a successful slice operation is a value of the same type 1326 1326 + as the operand. 1327 1327 + 1328 1328 + 1329 1329 + ### Operators 1330 1330 + 1331 1331 + Operators combine operands into expressions. 1332 1332 + 1333 1333 + ``` 1334 1334 + Expression = UnaryExpr | Expression binary_op Expression . 1335 1335 + UnaryExpr = PrimaryExpr | unary_op UnaryExpr . 1336 1336 + 1337 1337 + binary_op = "|" | "&" | "||" | "&&" | rel_op | add_op | mul_op | ".." . 1338 1338 + rel_op = "==" | "!=" | "<" | "<=" | ">" | ">=" . 1339 1339 + add_op = "+" | "-" . 1340 1340 + mul_op = "*" | "/" | "div" | "mod" | "quo" | "rem" . 1341 1341 + 1342 1342 + unary_op = "+" | "-" | "!" . 1343 1343 + ``` 1344 1344 + 1345 1345 + Comparisons are discussed [elsewhere]. For other binary operators, the operand 1346 1346 + types must be [identical] unless the operation involves untyped [constants] 1347 1347 + or durations. For operations involving constants only, see the section on 1348 1348 + [constant expressions]. 1349 1349 + 1350 1350 + Except for duration operations, if one operand is an untyped [literal] and the 1351 1351 + other operand is not, the constant is [converted] to the type of the other 1352 1352 + operand. 1353 1353 + 1354 1354 + 1355 1355 + #### Operator precedence 1356 1356 + 1357 1357 + Unary operators have the highest precedence. 1358 1358 + 1359 1359 + There are eight precedence levels for binary operators. 1360 1360 + The `..` operator (range) binds strongest, followed by 1361 1361 + multiplication operators, addition operators, comparison operators, 1362 1362 + `&&` (logical AND), `||` (logical OR), `&` (unification), 1363 1363 + and finally `|` (disjunction): 1364 1364 + 1365 1365 + ``` 1366 1366 + Precedence Operator 1367 1367 + 8 .. 1368 1368 + 7 * / div mod quo rem 1369 1369 + 6 + - 1370 1370 + 5 == != < <= > >= 1371 1371 + 4 && 1372 1372 + 3 || 1373 1373 + 2 & 1374 1374 + 1 | 1375 1375 + ``` 1376 1376 + 1377 1377 + Binary operators of the same precedence associate from left to right. 1378 1378 + For instance, `x / y * z` is the same as `(x / y) * z`. 1379 1379 + 1380 1380 + ``` 1381 1381 + +x 1382 1382 + 23 + 3*x[i] 1383 1383 + x <= f() 1384 1384 + f() || g() 1385 1385 + x == y+1 && y == z-1 1386 1386 + 2 | int 1387 1387 + { a: 1 } & { b: 2 } 1388 1388 + ``` 1389 1389 + 1390 1390 + #### Arithmetic operators 1391 1391 + 1392 1392 + Arithmetic operators apply to numeric values and yield a result of the same type 1393 1393 + as the first operand. The three of the four standard arithmetic operators 1394 1394 + `(+, -, *)` apply to integer and decimal floating-point types; 1395 1395 + `+` and `*` also applies to lists and strings. 1396 1396 + `/` only applies to decimal floating-point types and 1397 1397 + `div`, `mod`, `quo`, and `rem` only apply to integer types. 1398 1398 + 1399 1399 + ``` 1400 1400 + + sum integers, floats, lists, strings 1401 1401 + - difference integers, floats 1402 1402 + * product integers, floats, lists, strings 1403 1403 + / quotient floats 1404 1404 + div division integers 1405 1405 + mod modulo integers 1406 1406 + quo quotient integers 1407 1407 + rem remainder integers 1408 1408 + ``` 1409 1409 + 1410 1410 + #### Integer operators 1411 1411 + 1412 1412 + For two integer values `x` and `y`, 1413 1413 + the integer quotient `q = x div y` and remainder `r = x mod y ` 1414 1414 + satisfy the following relationships: 1415 1415 + 1416 1416 + ``` 1417 1417 + r = x - y*q with 0 <= r < |y| 1418 1418 + ``` 1419 1419 + where `|y|` denotes the absolute value of `y`. 1420 1420 + 1421 1421 + ``` 1422 1422 + x y x div y x mod y 1423 1423 + 5 3 1 2 1424 1424 + -5 3 -2 1 1425 1425 + 5 -3 -1 2 1426 1426 + -5 -3 2 1 1427 1427 + ``` 1428 1428 + 1429 1429 + For two integer values `x` and `y`, 1430 1430 + the integer quotient `q = x quo y` and remainder `r = x rem y ` 1431 1431 + satisfy the following relationships: 1432 1432 + 1433 1433 + ``` 1434 1434 + x = q*y + r and |r| < |y| 1435 1435 + ``` 1436 1436 + 1437 1437 + with `x quo y` truncated towards zero. 1438 1438 + 1439 1439 + ``` 1440 1440 + x y x quo y x rem y 1441 1441 + 5 3 1 2 1442 1442 + -5 3 -1 -2 1443 1443 + 5 -3 -1 2 1444 1444 + -5 -3 1 -2 1445 1445 + ``` 1446 1446 + 1447 1447 + A zero divisor in either case results in bottom (an error). 1448 1448 + 1449 1449 + For integer operands, the unary operators `+` and `-` are defined as follows: 1450 1450 + 1451 1451 + ``` 1452 1452 + +x is 0 + x 1453 1453 + -x negation is 0 - x 1454 1454 + ``` 1455 1455 + 1456 1456 + 1457 1457 + #### Decimal floating-point operators 1458 1458 + 1459 1459 + For decimal floating-point numbers, `+x` is the same as `x`, 1460 1460 + while -x is the negation of x. 1461 1461 + The result of a floating-point division by zero is bottom (an error). 1462 1462 + 1463 1463 + An implementation may combine multiple floating-point operations into a single 1464 1464 + fused operation, possibly across statements, and produce a result that differs 1465 1465 + from the value obtained by executing and rounding the instructions individually. 1466 1466 + 1467 1467 + 1468 1468 + #### List operators 1469 1469 + 1470 1470 + Lists can be concatenated using the `+` operator. 1471 1471 + For, list `a` and `b` 1472 1472 + ``` 1473 1473 + a + b 1474 1474 + ``` 1475 1475 + will produce an open list if `b` is open. 1476 1476 + If list `a` is open, only the existing elements will be involved in the 1477 1477 + concatenation. 1478 1478 + 1479 1479 + ``` 1480 1480 + [ 1, 2 ] + [ 3, 4 ] // [ 1, 2, 3, 4 ] 1481 1481 + [ 1, 2, ... ] + [ 3, 4 ] // [ 1, 2, 3, 4 ] 1482 1482 + [ 1, 2 ] + [ 3, 4, ... ] // [ 1, 2, 3, 4, ... ] 1483 1483 + ``` 1484 1484 + 1485 1485 + Lists can be multiplied using the `*` operator. 1486 1486 + ``` 1487 1487 + 3*[1,2] // [1, 2, 1, 2, 1, 2] 1488 1488 + 1489 1489 + [1, 2, ...int] // open list of two elements with element type int 1490 1490 + 4*[byte] // [byte, byte, byte, byte] 1491 1491 + [...byte] // byte list or arbitrary length 1492 1492 + (0..5)*[byte] // byte list of size 0 through 5 1493 1493 + 1494 1494 + // list with alternating elements of type string and int 1495 1495 + uint*[string, int] 1496 1496 + ``` 1497 1497 + 1498 1498 + The following illustrate how typed lists can be encoded as structs: 1499 1499 + ``` 1500 1500 + ip: 4*[byte] 1501 1501 + ipT: { 1502 1502 + Elem: byte 1503 1503 + Tail: { 1504 1504 + Elem: byte 1505 1505 + Tail: { 1506 1506 + Elem: byte 1507 1507 + Tail: { 1508 1508 + Elem: byte 1509 1509 + Tail: null 1510 1510 + } 1511 1511 + } 1512 1512 + } 1513 1513 + } 1514 1514 + 1515 1515 + rangeList: (1..2)*[int] 1516 1516 + rangeListT: null | { 1517 1517 + Elem: int 1518 1518 + Tail: { 1519 1519 + Elem: int 1520 1520 + Tail: null | { 1521 1521 + Elem: int 1522 1522 + Tail: null 1523 1523 + } 1524 1524 + } 1525 1525 + } 1526 1526 + 1527 1527 + strIntList: uint*[string, int] 1528 1528 + strIntListT: null | { 1529 1529 + Elem: string 1530 1530 + Tail: { 1531 1531 + Elem: int 1532 1532 + Tail: strIntListT 1533 1533 + } 1534 1534 + } 1535 1535 + ``` 1536 1536 + 1537 1537 + #### String operators 1538 1538 + 1539 1539 + Strings can be concatenated using the `+` operator: 1540 1540 + ``` 1541 1541 + s := "hi " + name + " and good bye" 1542 1542 + ``` 1543 1543 + String addition creates a new string by concatenating the operands. 1544 1544 + 1545 1545 + A string can be repeated by multiplying it: 1546 1546 + 1547 1547 + ``` 1548 1548 + s: "etc. "*3 // "etc. etc. etc. " 1549 1549 + ``` 1550 1550 + 1551 1551 + ##### Comparison operators 1552 1552 + 1553 1553 + Comparison operators compare two operands and yield an untyped boolean value. 1554 1554 + 1555 1555 + ``` 1556 1556 + == equal 1557 1557 + != not equal 1558 1558 + < less 1559 1559 + <= less or equal 1560 1560 + > greater 1561 1561 + >= greater or equal 1562 1562 + ``` 1563 1563 + 1564 1564 + In any comparison, the types of the two operands must unify. 1565 1565 + 1566 1566 + The equality operators `==` and `!=` apply to operands that are comparable. 1567 1567 + The ordering operators `<`, `<=`, `>`, and `>=` apply to operands that are ordered. 1568 1568 + These terms and the result of the comparisons are defined as follows: 1569 1569 + 1570 1570 + - Boolean values are comparable. 1571 1571 + Two boolean values are equal if they are either both true or both false. 1572 1572 + - Integer values are comparable and ordered, in the usual way. 1573 1573 + - Floating-point values are comparable and ordered, as per the definitions 1574 1574 + for binary coded decimals in the IEEE-754-2008 standard. 1575 1575 + - String values are comparable and ordered, lexically byte-wise. 1576 1576 + - Struct are not comparable. 1577 1577 + Two struct values are equal if their corresponding non-blank fields are equal. 1578 1578 + - List are not comparable. 1579 1579 + Two array values are equal if their corresponding elements are equal. 1580 1580 + ``` 1581 1581 + c: 3 < 4 1582 1582 + 1583 1583 + x: int 1584 1584 + y: int 1585 1585 + 1586 1586 + b3: x == y // b3 has type bool 1587 1587 + ``` 1588 1588 + 1589 1589 + #### Logical operators 1590 1590 + 1591 1591 + Logical operators apply to boolean values and yield a result of the same type 1592 1592 + as the operands. The right operand is evaluated conditionally. 1593 1593 + 1594 1594 + ``` 1595 1595 + && conditional AND p && q is "if p then q else false" 1596 1596 + || conditional OR p || q is "if p then true else q" 1597 1597 + ! NOT !p is "not p" 1598 1598 + ``` 1599 1599 + 1600 1600 + 1601 1601 + <!-- 1602 1602 + ### TODO TODO TODO 1603 1603 + 1604 1604 + 3.14 / 0.0 // illegal: division by zero 1605 1605 + Illegal conversions always apply to CUE. 1606 1606 + 1607 1607 + Implementation restriction: A compiler may use rounding while computing untyped floating-point or complex constant expressions; see the implementation restriction in the section on constants. This rounding may cause a floating-point constant expression to be invalid in an integer context, even if it would be integral when calculated using infinite precision, and vice versa. 1608 1608 + --> 1609 1609 + 1610 1610 + ### Conversions 1611 1611 + Conversions are expressions of the form `T(x)` where `T` and `x` are 1612 1612 + expressions. 1613 1613 + The result is always an instance of `T`. 1614 1614 + 1615 1615 + ``` 1616 1616 + Conversion = Expression "(" Expression [ "," ] ")" . 1617 1617 + ``` 1618 1618 + 1619 1619 + <!--- 1620 1620 + 1621 1621 + A literal value `x` can be converted to type T if `x` is representable by a 1622 1622 + value of `T`. 1623 1623 + 1624 1624 + As a special case, an integer literal `x` can be converted to a string type 1625 1625 + using the same rule as for non-constant x. 1626 1626 + 1627 1627 + Converting a literal yields a typed value as result. 1628 1628 + 1629 1629 + ``` 1630 1630 + uint(iota) // iota value of type uint 1631 1631 + float32(2.718281828) // 2.718281828 of type float32 1632 1632 + complex128(1) // 1.0 + 0.0i of type complex128 1633 1633 + float32(0.49999999) // 0.5 of type float32 1634 1634 + float64(-1e-1000) // 0.0 of type float64 1635 1635 + string('x') // "x" of type string 1636 1636 + string(0x266c) // "♬" of type string 1637 1637 + MyString("foo" + "bar") // "foobar" of type MyString 1638 1638 + string([]byte{'a'}) // not a constant: []byte{'a'} is not a constant 1639 1639 + (*int)(nil) // not a constant: nil is not a constant, *int is not a boolean, numeric, or string type 1640 1640 + int(1.2) // illegal: 1.2 cannot be represented as an int 1641 1641 + string(65.0) // illegal: 65.0 is not an integer constant 1642 1642 + ``` 1643 1643 + ---> 1644 1644 + 1645 1645 + A conversion is always allowed if `x` is of the same type as `T` and `x` 1646 1646 + is an instance of `T`. 1647 1647 + 1648 1648 + If `T` and `x` of different underlying type, a conversion if 1649 1649 + `x` can be converted to a value `x'` of `T`'s type, and 1650 1650 + `x'` is an instance of `T`. 1651 1651 + A value `x` can be converted to the type of `T` in any of these cases: 1652 1652 + 1653 1653 + - `x` is of type struct and is subsumed by `T` ignoring struct tags. 1654 1654 + - `x` and `T` are both integer or floating point types. 1655 1655 + - `x` is an integer or a list of bytes or runes and `T` is a string type. 1656 1656 + - `x` is a string and `T` is a list of bytes or runes. 1657 1657 + 1658 1658 + 1659 1659 + [Field tags] are ignored when comparing struct types for identity 1660 1660 + for the purpose of conversion: 1661 1661 + 1662 1662 + ``` 1663 1663 + person: { 1664 1664 + name: string #xml:"Name" 1665 1665 + address: null | { 1666 1666 + street: string #xml:"Street" 1667 1667 + city: string #xml:"City" 1668 1668 + } #xml:"Address" 1669 1669 + } 1670 1670 + 1671 1671 + person2: { 1672 1672 + name: string 1673 1673 + address: null | { 1674 1674 + street: string 1675 1675 + city: string 1676 1676 + } 1677 1677 + } 1678 1678 + 1679 1679 + p2 = person(person2) // ignoring tags, the underlying types are identical 1680 1680 + ``` 1681 1681 + 1682 1682 + Specific rules apply to conversions between numeric types, structs, 1683 1683 + or to and from a string type. These conversions may change the representation 1684 1684 + of `x`. 1685 1685 + All other conversions only change the type but not the representation of x. 1686 1686 + 1687 1687 + 1688 1688 + #### Conversions between numeric ranges 1689 1689 + For the conversion of numeric values, the following rules apply: 1690 1690 + 1691 1691 + 1. Any integer prototype can be converted into any other integer prototype 1692 1692 + provided that it is within range. 1693 1693 + 2. When converting a decimal floating-point number to an integer, the fraction 1694 1694 + is discarded (truncation towards zero). TODO: or disallow truncating? 1695 1695 + 1696 1696 + ``` 1697 1697 + a: uint16(int(1000)) // uint16(1000) 1698 1698 + b: uint8(1000) // ⊥ // overflow 1699 1699 + c: int(2.5) // 2 TODO: TBD 1700 1700 + ``` 1701 1701 + 1702 1702 + 1703 1703 + 1704 1704 + #### Conversions to and from a string type 1705 1705 + 1706 1706 + Converting a signed or unsigned integer value to a string type yields a string 1707 1707 + containing the UTF-8 representation of the integer. Values outside the range of 1708 1708 + valid Unicode code points are converted to `"\uFFFD"`. 1709 1709 + 1710 1710 + ``` 1711 1711 + string('a') // "a" 1712 1712 + string(-1) // "\ufffd" == "\xef\xbf\xbd" 1713 1713 + string(0xf8) // "\u00f8" == "ø" == "\xc3\xb8" 1714 1714 + 1715 1715 + MyString(0x65e5) // "\u65e5" == "日" == "\xe6\x97\xa5" 1716 1716 + ``` 1717 1717 + 1718 1718 + Converting a list of bytes to a string type yields a string whose successive 1719 1719 + bytes are the elements of the slice. 1720 1720 + Invalid UTF-8 is converted to `"\uFFFD"`. 1721 1721 + 1722 1722 + ``` 1723 1723 + string('hell\xc3\xb8') // "hellø" 1724 1724 + string(bytes([0x20])) // " " 1725 1725 + ``` 1726 1726 + 1727 1727 + As string value is always convertible to a list of bytes. 1728 1728 + 1729 1729 + ``` 1730 1730 + bytes("hellø") // 'hell\xc3\xb8' 1731 1731 + bytes("") // '' 1732 1732 + ``` 1733 1733 + 1734 1734 + <!--- 1735 1735 + #### Conversions between list types 1736 1736 + 1737 1737 + Conversions between list types are possible only if `T` strictly subsumes `x` 1738 1738 + and the result will be the unification of `T` and `x`. 1739 1739 + 1740 1740 + <!--- 1741 1741 + If we introduce named types this would be different from IP & [10, ...] 1742 1742 + 1743 1743 + Consider removing this until it has a different meaning. 1744 1744 + 1745 1745 + ``` 1746 1746 + IP: 4*[byte] 1747 1747 + Private10: IP([10, ...]) // [10, byte, byte, byte] 1748 1748 + ``` 1749 1749 + ---> 1750 1750 + 1751 1751 + #### Convesions between struct types 1752 1752 + 1753 1753 + A conversion from `x` to `T` 1754 1754 + is applied using the following rules: 1755 1755 + 1756 1756 + 1. `x` must be an instance of `T`, 1757 1757 + 2. all fields defined for `x` that are not defined for `T` are removed from 1758 1758 + the result of the conversion, recursively. 1759 1759 + 1760 1760 + ``` 1761 1761 + T: { 1762 1762 + a: { b: 1..10 } 1763 1763 + } 1764 1764 + 1765 1765 + x1: { 1766 1766 + a: { b: 8, c: 10 } 1767 1767 + d: 9 1768 1768 + } 1769 1769 + 1770 1770 + c1: T(x1) // { a: { b: 8 } } 1771 1771 + c2: T({}) // ⊥ // missing field 'a' in '{}' 1772 1772 + c3: T({ a: {b: 0} }) // ⊥ // field a.b does not unify (0 & 1..10) 1773 1773 + ``` 1774 1774 + 1775 1775 + 1776 1776 + ### Calls 1777 1777 + 1778 1778 + Given an expression `f` of function type F, 1779 1779 + ``` 1780 1780 + f(a1, a2, … an) 1781 1781 + ``` 1782 1782 + calls `f` with arguments a1, a2, … an. Arguments must be expressions 1783 1783 + of which the values are an instance of the parameter types of `F` 1784 1784 + and are evaluated before the function is called. 1785 1785 + 1786 1786 + ``` 1787 1787 + a: math.Atan2(x, y) 1788 1788 + ``` 1789 1789 + <!--- 1790 1790 + 1791 1791 + // FUNCTIONS ARE DISABLED: 1792 1792 + Point: { 1793 1793 + Scale(a: float) -> Point({ Value: Point.Value * a }) 1794 1794 + Value: float 1795 1795 + } 1796 1796 + pt: Point 1797 1797 + pt: { Value: a } 1798 1798 + 1799 1799 + ptp: pt.Scale(3.5) 1800 1800 + ---> 1801 1801 + 1802 1802 + 1803 1803 + In a function call, the function value and arguments are evaluated in the usual 1804 1804 + order. After they are evaluated, the parameters of the call are passed by value 1805 1805 + to the function and the called function begins execution. The return parameters 1806 1806 + of the function are passed by value back to the calling function when the 1807 1807 + function returns. 1808 1808 + 1809 1809 + <!--- 1810 1810 + TODO: 1811 1811 + 1812 1812 + Passing arguments to ... parameters 1813 1813 + If f is variadic with a final parameter p of type ...T, then within f the type of p is equivalent to type []T. If f is invoked with no actual arguments for p, the value passed to p is nil. Otherwise, the value passed is a new slice of type []T with a new underlying array whose successive elements are the actual arguments, which all must be assignable to T. The length and capacity of the slice is therefore the number of arguments bound to p and may differ for each call site. 1814 1814 + 1815 1815 + Given the function and calls 1816 1816 + 1817 1817 + func Greeting(prefix string, who ...string) 1818 1818 + Greeting("nobody") 1819 1819 + Greeting("hello:", "Joe", "Anna", "Eileen") 1820 1820 + within Greeting, who will have the value nil in the first call, and []string{"Joe", "Anna", "Eileen"} in the second. 1821 1821 + 1822 1822 + If the final argument is assignable to a slice type []T, it may be passed unchanged as the value for a ...T parameter if the argument is followed by .... In this case no new slice is created. 1823 1823 + 1824 1824 + Given the slice s and call 1825 1825 + 1826 1826 + s := []string{"James", "Jasmine"} 1827 1827 + Greeting("goodbye:", s...) 1828 1828 + within Greeting, who will have the same value as s with the same underlying array. 1829 1829 + ---> 1830 1830 + 1831 1831 + 1832 1832 + ### Comprehensions 1833 1833 + 1834 1834 + Lists and structs can be constructed using comprehensions. 1835 1835 + 1836 1836 + Each define a clause sequence that consists of a sequence of `for`, `if`, and 1837 1837 + `let` clauses, nesting from left to right. 1838 1838 + The `for` and `let` clauses each define a new scope in which new values are 1839 1839 + bound to be available for the next clause. 1840 1840 + 1841 1841 + The `for` clause binds the defined identifiers, on each iteration, to the next 1842 1842 + value of some iterable value in a new scope. 1843 1843 + A `for` clause may bind one or two identifiers. 1844 1844 + If there is one identifier, it binds it to the value, for instance 1845 1845 + a list element, a struct field value or a range element. 1846 1846 + If there are more two identifies, the first value will be the key or index, 1847 1847 + if available, and the second will be the value. 1848 1848 + 1849 1849 + An `if` clause, or guard, specifies an expression that terminates the current 1850 1850 + iteration if it evaluates to false. 1851 1851 + 1852 1852 + The `let` clause binds the result of an expression to the defined identifier 1853 1853 + in a new scope. 1854 1854 + 1855 1855 + A current iteration is said to complete if the inner-most block of the clause 1856 1856 + sequence is reached. 1857 1857 + 1858 1858 + List comprehensions specify a single expression that is evaluated and included 1859 1859 + in the list for each completed iteration. 1860 1860 + 1861 1861 + Struct comprehensions specify two expressions, one for the label and one for 1862 1862 + the value, that each get evaluated and included as a field in the struct 1863 1863 + for each completed iteration. 1864 1864 + 1865 1865 + ``` 1866 1866 + ComprehensionDecl = Field [ "<-" ] Clauses . 1867 1867 + ListComprehension = "[" Expression "<-" Clauses "]" . 1868 1868 + 1869 1869 + Clauses = Clause { Clause } . 1870 1870 + Clause = ForClause | GuardClause | LetClause . 1871 1871 + ForClause = "for" identifier [ ", " identifier] "in" Expression . 1872 1872 + GuardClause = "if" Expression . 1873 1873 + LetClause = "let" identifier "=" Expression . 1874 1874 + ``` 1875 1875 + 1876 1876 + ``` 1877 1877 + a: [1, 2, 3, 4] 1878 1878 + b: [ x+1 for x in a if x > 1] // [3, 4, 5] 1879 1879 + 1880 1880 + c: { ("\(x)"): x + y for x in a if x < 4 let y = 1 } 1881 1881 + d: { "1": 2, "2": 3, "3": 4 } 1882 1882 + ``` 1883 1883 + 1884 1884 + <!--- 1885 1885 + The above examples could be expressed as struct unification as follows: 1886 1886 + 1887 1887 + ``` 1888 1888 + b: [ ] 1889 1889 + bc: { 1890 1890 + x1: _ 1891 1891 + next: { 1892 1892 + x2: true & x1 > 1 1893 1893 + next: { 1894 1894 + x3: x1+1 1895 1895 + } 1896 1896 + } 1897 1897 + result: next.next.x3 | [] 1898 1898 + } 1899 1899 + ``` 1900 1900 + 1901 1901 + Struct comprehensions cannot be expressed as such as there is not equivalent 1902 1902 + in the language to have computed field labels. 1903 1903 + ---> 1904 1904 + 1905 1905 + 1906 1906 + ### String interpolation 1907 1907 + 1908 1908 + Strings interpolation allows constructing strings by replacing placeholder 1909 1909 + expressions included in strings to be replaced with their string representation. 1910 1910 + String interpolation may be used in single- and double-quoted strings, as well 1911 1911 + as their multiline equivalent. 1912 1912 + 1913 1913 + A placeholder is demarked by a enclosing parentheses prefixed with 1914 1914 + a backslash `\`. 1915 1915 + Within the parentheses may be any expression to be 1916 1916 + evaluated within the scope within which the string is defined. 1917 1917 + 1918 1918 + ``` 1919 1919 + a: "World" 1920 1920 + b: "Hello \( a )!" // Hello World! 1921 1921 + ``` 1922 1922 + 1923 1923 + 1924 1924 + ## Builtin Functions 1925 1925 + 1926 1926 + Built-in functions are predeclared. They are called like any other function. 1927 1927 + 1928 1928 + The built-in functions cannot be used as function values. 1929 1929 + 1930 1930 + ### `len` 1931 1931 + 1932 1932 + The built-in function `len` takes arguments of various types and return 1933 1933 + a result of type int. 1934 1934 + 1935 1935 + ``` 1936 1936 + Argument type Result 1937 1937 + 1938 1938 + string string length in bytes 1939 1939 + list list length 1940 1940 + struct number of distinct fields 1941 1941 + ``` 1942 1942 + 1943 1943 + 1944 1944 + ### `required` 1945 1945 + 1946 1946 + The built-in function `required` discards the default mechanism of 1947 1947 + a disjunction. 1948 1948 + 1949 1949 + ``` 1950 1950 + "tcp" | "udp" // default is "tcp" 1951 1951 + required("tcp" | "udp") // no default, user must specify either "tcp" or "udp" 1952 1952 + ``` 1953 1953 + 1954 1954 + 1955 1955 + ## Modules, instances, and packages 1956 1956 + 1957 1957 + CUE configurations are constructed combining _instances_. 1958 1958 + An instance, in turn, is constructed from one or more source files belonging 1959 1959 + to the same _package_ that together declare the data representation. 1960 1960 + Elements of this data representation may be exported and used 1961 1961 + in other instances. 1962 1962 + 1963 1963 + ### Source file organization 1964 1964 + 1965 1965 + Each source file consists of an optional package clause defining collection 1966 1966 + of files to which it belongs, 1967 1967 + followed by a possibly empty set of import declarations that declare 1968 1968 + packages whose contents it wishes to use, followed by a possibly empty set of 1969 1969 + declarations. 1970 1970 + 1971 1971 + 1972 1972 + ``` 1973 1973 + SourceFile = [ PackageClause "," ] { ImportDecl "," } { TopLevelDecl "," } . 1974 1974 + ``` 1975 1975 + 1976 1976 + ### Package clause 1977 1977 + 1978 1978 + A package clause is an optional clause that defines the package to which 1979 1979 + a source file the file belongs. 1980 1980 + 1981 1981 + ``` 1982 1982 + PackageClause = "package" PackageName . 1983 1983 + PackageName = identifier . 1984 1984 + ``` 1985 1985 + 1986 1986 + The PackageName must not be the blank identifier. 1987 1987 + 1988 1988 + ``` 1989 1989 + package math 1990 1990 + ``` 1991 1991 + 1992 1992 + ### Modules and instances 1993 1993 + A _module_ defines a tree directories, rooted at the _module root_. 1994 1994 + 1995 1995 + All source files within a module with the same package belong to the same 1996 1996 + package. 1997 1997 + A module may define multiple package. 1998 1998 + 1999 1999 + An _instance_ of a package is any subset of files within a module belonging 2000 2000 + to the same package. 2001 2001 + It is interpreted as the concatanation of these files. 2002 2002 + 2003 2003 + An implementation may impose conventions on the layout of package files 2004 2004 + to determine which files of a package belongs to an instance. 2005 2005 + For instance, an instance may be defined as the subset of package files 2006 2006 + belonging to a directory and all its ancestors. 2007 2007 + 2008 2008 + 2009 2009 + ### Import declarations 2010 2010 + 2011 2011 + An import declaration states that the source file containing the declaration 2012 2012 + depends on definitions of the _imported_ package (§Program initialization and 2013 2013 + execution) and enables access to exported identifiers of that package. 2014 2014 + The import names an identifier (PackageName) to be used for access and an 2015 2015 + ImportPath that specifies the package to be imported. 2016 2016 + 2017 2017 + ``` 2018 2018 + ImportDecl = "import" ( ImportSpec | "(" { ImportSpec ";" } ")" ) . 2019 2019 + ImportSpec = [ "." | PackageName ] ImportPath . 2020 2020 + ImportPath = `"` { unicode_value } `"` . 2021 2021 + ``` 2022 2022 + 2023 2023 + The PackageName is used in qualified identifiers to access exported identifiers 2024 2024 + of the package within the importing source file. 2025 2025 + It is declared in the file block. 2026 2026 + If the PackageName is omitted, it defaults to the identifier specified in the 2027 2027 + package clause of the imported instance. 2028 2028 + If an explicit period (.) appears instead of a name, all the instances's 2029 2029 + exported identifiers declared in that instances's package block will be declared 2030 2030 + in the importing source file's file block 2031 2031 + and must be accessed without a qualifier. 2032 2032 + 2033 2033 + The interpretation of the ImportPath is implementation-dependent but it is 2034 2034 + typically either the path of a builtin package or a fully qualifying location 2035 2035 + of an instance within a source code repository. 2036 2036 + 2037 2037 + Implementation restriction: An interpreter may restrict ImportPaths to non-empty 2038 2038 + strings using only characters belonging to Unicode's L, M, N, P, and S general 2039 2039 + categories (the Graphic characters without spaces) and may also exclude the 2040 2040 + characters !"#$%&'()*,:;<=>?[\]^`{|} and the Unicode replacement character 2041 2041 + U+FFFD. 2042 2042 + 2043 2043 + Assume we have package containing the package clause package math, 2044 2044 + which exports function Sin at the path identified by "lib/math". 2045 2045 + This table illustrates how Sin is accessed in files 2046 2046 + that import the package after the various types of import declaration. 2047 2047 + 2048 2048 + ``` 2049 2049 + Import declaration Local name of Sin 2050 2050 + 2051 2051 + import "lib/math" math.Sin 2052 2052 + import m "lib/math" m.Sin 2053 2053 + import . "lib/math" Sin 2054 2054 + ``` 2055 2055 + 2056 2056 + An import declaration declares a dependency relation between the importing and 2057 2057 + imported package. It is illegal for a package to import itself, directly or 2058 2058 + indirectly, or to directly import a package without referring to any of its 2059 2059 + exported identifiers. 2060 2060 + 2061 2061 + 2062 2062 + ### An example package 2063 2063 + 2064 2064 + TODO 2065 2065 + 2066 2066 + ## Interpretation 2067 2067 + 2068 2068 + CUE was inspired by a formalism known as 2069 2069 + typed attribute structures [Carpenter 1992] or 2070 2070 + typed feature structures [Copestake 2002], 2071 2071 + which are used in linguistics to encode grammars and 2072 2072 + lexicons. Being able to effectively encode large amounts of data in a rigorous 2073 2073 + manner, this formalism seemed like a great fit for large-scale configuration. 2074 2074 + 2075 2075 + Although CUE configurations are specified as trees, not graphs, implementations 2076 2076 + can benefit from considering them as graphs when dealing with cycles, 2077 2077 + and effectively turning them into graphs when applying techniques like 2078 2078 + structure sharing. 2079 2079 + Dealing with cycles is well understood for typed attribute structures 2080 2080 + and as CUE configurations are formally closely related to them, 2081 2081 + we can benefit from this knowledge without reinventing the wheel. 2082 2082 + 2083 2083 + 2084 2084 + ### Formal definition 2085 2085 + 2086 2086 + <!-- 2087 2087 + The previous section is equivalent to the below text with the main difference 2088 2088 + that it is only defined for trees. Technically, structs are more akin dags, 2089 2089 + but that is hard to explain at this point and also unnecessarily pedantic. 2090 2090 + We keep the definition closer to trees and will layer treatment 2091 2091 + of cycles on top of these definitions to achieve the same result (possibly 2092 2092 + without the benefits of structure sharing of a dag). 2093 2093 + 2094 2094 + A _field_ is a field name, or _label_ and a protype. 2095 2095 + A _struct_ is a set of _fields_ with unique labels for each field. 2096 2096 + --> 2097 2097 + 2098 2098 + A CUE configuration can be defined in terms of constraints, which are 2099 2099 + analogous to typed attribute structures referred to above. 2100 2100 + 2101 2101 + #### Definition of basic prototypes 2102 2102 + 2103 2103 + > A _basic prototype_ is any CUE prototype that is not a struct (or, by 2104 2104 + > extension, a list). 2105 2105 + > All basic prototypes are paritally ordered in a lattice, such that for any 2106 2106 + > basic prototype `a` and `b` there is a unique greatest lower bound 2107 2107 + > defined for the subsumption relation `a ⊑ b`. 2108 2108 + 2109 2109 + ``` 2110 2110 + Basic prototypes 2111 2111 + null 2112 2112 + true 2113 2113 + bool 2114 2114 + 3.14 2115 2115 + string 2116 2116 + "Hello" 2117 2117 + 0..10 2118 2118 + <8 2119 2119 + re("Hello .*!") 2120 2120 + ``` 2121 2121 + 2122 2122 + The basic prototypes correspond to their respective types defined earlier. 2123 2123 + 2124 2124 + Struct (and by extension lists), are represented by the abstract notion of 2125 2125 + a constraint structure. 2126 2126 + Each node in a configuration, including the root node, 2127 2127 + is associated with a constraint. 2128 2128 + 2129 2129 + 2130 2130 + #### Definition of a typed feature structures and substructures 2131 2131 + 2132 2132 + > A typed feature structure_ defined for a finite set of labels `Label` 2133 2133 + > is directed acyclic graph with labeled 2134 2134 + > arcs and values, represented by a tuple `C = <Q, q0, υ, δ>`, where 2135 2135 + > 2136 2136 + > 1. `Q` is the finite set of nodes, 2137 2137 + > 1. `q0 ∈ Q`, is the root node, 2138 2138 + > 1. `υ: Q → T` is the total node typing function, 2139 2139 + > for a finite set of possible terms `T`. 2140 2140 + > 1. `δ: Label × Q → Q` is the partial feature function, 2141 2141 + > 2142 2142 + > subject to the following conditions: 2143 2143 + > 2144 2144 + > 1. there is no node `q` or label `l` such that `δ(q, l) = q0` (root) 2145 2145 + > 2. for every node `q` in `Q` there is a path `π` (i.e. a sequence of 2146 2146 + > members of Label) such that `δ(q0, π) = q` (unique root, correctness) 2147 2147 + > 3. there is no node `q` or path `π` such that `δ(q, π) = q` (no cycles) 2148 2148 + > 2149 2149 + > where `δ` is extended to be defined on paths as follows: 2150 2150 + > 2151 2151 + > 1. `δ(q, ϵ) = q`, where `ϵ` is the empty path 2152 2152 + > 2. `δ(q, l∙π) = δ(δ(l, q), π)` 2153 2153 + > 2154 2154 + > The _substructures_ of a typed feature structure are the 2155 2155 + > typed feature structures rooted at each node in the structure. 2156 2156 + > 2157 2157 + > The set of all possible typed feature structures for a given label 2158 2158 + > set is denoted as `𝒞`<sub>`Label`</sub>. 2159 2159 + > 2160 2160 + > The set of _terms_ for label set `Label` is recursively defined as 2161 2161 + > 2162 2162 + > 1. every basic prototype: `P ⊆ T` 2163 2163 + > 2. every constraint in `𝒞`<sub>`Label`</sub> is a term: `𝒞`<sub>`Label`</sub>` ⊆ T` 2164 2164 + > 3. for every `n` prototypes `t₁, ..., tₙ`, and every `n`-ary function symbol 2165 2165 + > `f ∈ F_n`, the prototye `f(t₁,...,tₙ) ∈ T`. 2166 2166 + > 2167 2167 + 2168 2168 + 2169 2169 + This definition has been taken and modified from [Carpenter, 1992] 2170 2170 + and [Copestake, 2002]. 2171 2171 + 2172 2172 + Without loss of generality, we will henceforth assume that the given set 2173 2173 + of labels is constant and denote `𝒞`<sub>`Label`</sub> as `𝒞`. 2174 2174 + 2175 2175 + In CUE configurations, the abstract constraints implicated by `υ` 2176 2176 + are CUE exressions. 2177 2177 + Literal structs can be treated as part of the original typed feature structure 2178 2178 + and do not need evaluation. 2179 2179 + Any other expression is evaluated and unified with existing values of that node. 2180 2180 + 2181 2181 + References in expressions refer to other nodes within the `C` and represent 2182 2182 + a copy of such a `C`. 2183 2183 + The functions defined by `F` correspond to the binary and unary operators 2184 2184 + and interpolation construct of CUE, as well as builtin functions. 2185 2185 + 2186 2186 + CUE allows duplicate labels within a struct, while the definition of 2187 2187 + typed feature structures does not. 2188 2188 + A duplicate label `l` with respective values `a` and `b` is represented in 2189 2189 + a constraint as a single label with term `&(a, b)`, 2190 2190 + the unification of `a` and `b`. 2191 2191 + Multiple labels may be recursively combined in any order. 2192 2192 + 2193 2193 + <!-- unnecessary, probably. 2194 2194 + #### Definition of evaluated prototype 2195 2195 + 2196 2196 + > A fully evaluated prototype, `T_evaluated ⊆ T` is a subset of `T` consisting 2197 2197 + > only of atoms, typed attribute structures and constraint functions. 2198 2198 + > 2199 2199 + > A prototype is called _ground_ if it is an atom or typed attribute structure. 2200 2200 + 2201 2201 + #### Unification of evaluated prototypes 2202 2202 + 2203 2203 + > A fully evaluated prototype, `T_evaluated ⊆ T` is a subset of `T` consisting 2204 2204 + > only of atoms, typed attribute structures and constraint functions. 2205 2205 + > 2206 2206 + > A prototype is called _ground_ if it is an atom or typed attribute structure. 2207 2207 + --> 2208 2208 + 2209 2209 + #### Definition of subsumption and unification on typed attribute structure 2210 2210 + 2211 2211 + > For a given collection of constraints `𝒞`, 2212 2212 + > we define `π ≡`<sub>`C`</sub> `π'` to mean that constraint structure `C ∈ 𝒞` 2213 2213 + > contains path equivalence between the paths `π` and `π'` 2214 2214 + > (i.e. `δ(q0, π) = δ(q0, π')`, where `q0` is the root node of `C`); 2215 2215 + > and `𝒫`<sub>`C`</sub>`(π) = c` to mean that 2216 2216 + > the constraint structure at the path `π` in `C` 2217 2217 + > is `c` (i.e. `𝒫`<sub>`C`</sub>`(π) = c` if and only if `υ(δ(q0, π)) == c`, 2218 2218 + > where `q0` is the root node of `C`). 2219 2219 + > Subsumption is then defined as follows: 2220 2220 + > `C ∈ 𝒞` subsumes `C' ∈ 𝒞`, written `C' ⊑ C`, if and only if: 2221 2221 + > 2222 2222 + > - `π ≡`<sub>`C`</sub> `π'` implies `π ≡`<sub>`C'`</sub> `π'` 2223 2223 + > - `𝒫`<sub>`C`</sub>`(π) = c` implies`𝒫`<sub>`C'`</sub>`(π) = c` and `c' ⊑ c` 2224 2224 + > 2225 2225 + > The unification of `C` and `C'`, denoted `C ⊓ C'`, 2226 2226 + > is the greatest lower bound of `C` and `C'` in `𝒞` ordered by subsumption. 2227 2227 + 2228 2228 + Like with the subsumption relation for basic prototypes, 2229 2229 + the subsumption relation for constraints determines the mutual placement 2230 2230 + of constraints within the partial order of all values. 2231 2231 + 2232 2232 + 2233 2233 + #### Evaluation function 2234 2234 + 2235 2235 + > The evaluation function is given by `E: T -> 𝒞`. 2236 2236 + > The unification of two constraint structures is evaluated as defined above. 2237 2237 + > All other functions are evaluated according to the definitions found earlier 2238 2238 + > in this spec. 2239 2239 + > An error is indicated by `⊥`. 2240 2240 + 2241 2241 + #### Definition of well-formedness 2242 2242 + 2243 2243 + > We say that a given constraint structure `C = <Q, q0, υ, δ> ∈ 𝒞` is 2244 2244 + > a _well-formed_ constraint structure if and only if for all nodes `q ∈ Q`, 2245 2245 + > the substructure `C'` rooted at `q`, 2246 2246 + > is such that `E(υ(q)) ∈ 𝒞` and `C' = <Q', q, δ', υ'> ⊑ E(υ(q))`. 2247 2247 + 2248 2248 + <!-- Also, like Copestake, define appropriate features? 2249 2249 + Appropriate features are useful for detecting unused variables. 2250 2250 + 2251 2251 + Appropriate features could be introduced by distinguishing between: 2252 2252 + 2253 2253 + a: MyStruct // appropriate features are MyStruct 2254 2254 + a: {a : 1} 2255 2255 + 2256 2256 + and 2257 2257 + 2258 2258 + a: MyStruct & { a: 1 } // appropriate features are those of MyStruct + 'a' 2259 2259 + 2260 2260 + This is way to suttle, though. 2261 2261 + 2262 2262 + Alternatively: use Haskell's approach: 2263 2263 + 2264 2264 + a :: MyStruct // define a to be MyStruct any other features are allowed but 2265 2265 + // discarded from the model. Unused features are an error. 2266 2266 + 2267 2267 + Let's first try to see if we can get away with static usage analysis. 2268 2268 + A variant would be to define appropriate features unconditionally, but enforce 2269 2269 + them only for unused variables, with some looser definition of unused. 2270 2270 + --> 2271 2271 + 2272 2272 + The _evaluation_ of a CUE configuration represented by `C` 2273 2273 + is defined as the process of making `C` well-formed. 2274 2274 + 2275 2275 + <!-- 2276 2276 + ore abstractly, we can define this structure as the tuple 2277 2277 + `<≡, 𝒫>`, where 2278 2278 + 2279 2279 + - `≡ ⊆ Path × Path` where `π ≡ π'` if and only if `Δ(π, q0) = Δ(π', q0)` (path equivalence) 2280 2280 + - `P: Path → ℙ` is `υ(Δ(π, q))` (path value). 2281 2281 + 2282 2282 + A struct `a = <≡, 𝒫>` subsumes a struct `b = <≡', 𝒫'>`, or `a ⊑ b`, 2283 2283 + if and only if 2284 2284 + 2285 2285 + - `π ≡ π'` implied `π ≡' π'`, and 2286 2286 + - `𝒫(π) = v` implies `𝒫'(π) = v'` and `v' ⊑ v` 2287 2287 + --> 2288 2288 + 2289 2289 + #### References 2290 2290 + Theory: 2291 2291 + - [1992] Bob Carpenter, "The logic of typed feature structures."; 2292 2292 + Cambridge University Press, ISBN:0-521-41932-8 2293 2293 + - [2002] Ann Copestake, "Implementing Typed Feature Structure Grammars."; 2294 2294 + CSLI Publications, ISBN 1-57586-261-1 2295 2295 + 2296 2296 + Some graph unification algorithms: 2297 2297 + 2298 2298 + - [1985] Fernando C. N. Pereira, "A structure-sharing representation for 2299 2299 + unification-based grammar formalisms."; In Proc. of the 23rd Annual Meeting of 2300 2300 + the Association for Computational Linguistics. Chicago, IL 2301 2301 + - [1991] H. Tomabechi, "Quasi-destructive graph unifications.."; In Proceedings 2302 2302 + of the 29th Annual Meeting of the ACL. Berkeley, CA 2303 2303 + - [1992] Hideto Tomabechi, "Quasi-destructive graph ynifications with structure- 2304 2304 + sharing."; In Proceedings of the 15th International Conference on 2305 2305 + Computational Linguistics (COLING-92), Nantes, France. 2306 2306 + - [2001] Marcel van Lohuizen, "Memory-efficient and thread-safe 2307 2307 + quasi-destructive graph unification."; In Proceedings of the 38th Meeting of 2308 2308 + the Association for Computational Linguistics. Hong Kong, China. 2309 2309 + 2310 2310 + 2311 2311 + ### Evaluation 2312 2312 + 2313 2313 + The _evaluation_ of a CUE configuration `C` is defined as the process of 2314 2314 + making `C` well-formed. 2315 2315 + 2316 2316 + This document does not define any operational semantics. 2317 2317 + As the unification operation is communitive, transitive, and reflexive, 2318 2318 + implementations have a considerable amount of leeway in 2319 2319 + chosing an evaluation strategy. 2320 2320 + Although most algorithms for the unification of typed attribute structure 2321 2321 + that have been proposed are `O(n)`, there can be considerable performance 2322 2322 + benefits of chosing one of the many proposed evaluation strategies over the 2323 2323 + other. 2324 2324 + Implementations will need to be verified against the above formal definition. 2325 2325 + 2326 2326 + 2327 2327 + 2328 2328 + #### Constraint functions 2329 2329 + 2330 2330 + A _constraint function_ is a unary function `f` which for any input `a` only 2331 2331 + returns values that are an instance of `a`. For instance, the constraint 2332 2332 + function `f` for `string` returns `"foo"` for `f("foo")` and `_|_` for `f(1)`. 2333 2333 + Constraint functions may take other constraint functions as arguments to 2334 2334 + produce a more restricting constraint function. 2335 2335 + For instance, the constraint function `f` for `0..8` returns `5` for `f(5)`, 2336 2336 + `5..8` for `f(5..10)`, and `_|_` for `f("foo")`. 2337 2337 + 2338 2338 + 2339 2339 + Constraint functions play a special role in unification. 2340 2340 + The unification function `&(a, b)` is defined as 2341 2341 + 2342 2342 + - `a & b` if `a` and `b` are two atoms 2343 2343 + - `a & b` if `a` and `b` are two nodes, respresenting struct 2344 2344 + - `a(b)` or `b(a)` if either `a` or `b` is a constraint function, respectively. 2345 2345 + 2346 2346 + Implementations are free to pick which constraint function is applied if 2347 2347 + both `a` and `b` are constraint functions, as the properties of unification 2348 2348 + will ensure this produces identical results. 2349 2349 + 2350 2350 + #### Manifestation 2351 2351 + 2352 2352 + TODO: a prototype which is a function invocation that cannot be evaluated 2353 2353 + or for which the result is not an atom or a struct is called _incomplete_. 2354 2354 + 2355 2355 + 2356 2356 + 2357 2357 + ### Validation 2358 2358 + 2359 2359 + TODO: when to proactively do recursive validation 2360 2360 + 2361 2361 + #### References 2362 2362 + 2363 2363 + A distinguising feature of CUE's unification algorithm is the use of references. 2364 2364 + In conventional graph unification for typed feature structures, the structures 2365 2365 + that are unified into the existing graph are independent and pre-evaluated. 2366 2366 + In CUE, the constraint structures indicated by references may still need to 2367 2367 + be evaluated. 2368 2368 + Some conventional evaluation strategy may not cope well with references that 2369 2369 + refer to each other. 2370 2370 + The simple solution is to deploy a bread-first evaluation strategy, rather than 2371 2371 + the more traditional depth-first approach. 2372 2372 + Other approaches are possible, however, and implementations are free to choose 2373 2373 + which approach is deployed. 2374 2374 + 2375 2375 + ### Cycles 2376 2376 + 2377 2377 + TODO: describe precisely which cycles must be resolved by implementations. 2378 2378 + 2379 2379 + Rules: 2380 2380 + 2381 2381 + - Unification of atom value `a` with non-concrete atom `b` for node `q`: 2382 2382 + - set `q` to `a` and schedule the evalution `a == b` at the end of 2383 2383 + evaluating `q`: `C` is only correct under the assumption that `q` is `a` 2384 2384 + so evaluate later. 2385 2385 + 2386 2386 + A direct cyclic reference between nodes defines a shared node for the paths 2387 2387 + of the original nodes. 2388 2388 + 2389 2389 + - Unification of cycle of references of struct, 2390 2390 + for instance: `{ a: b, b: c, c: a }` 2391 2391 + - ignore the cycle and continue evaluating not including the last unification: 2392 2392 + a unification of a value with itself is itself. As `a` was already included, 2393 2393 + ignoring the cycle will produce the same result. 2394 2394 + 2395 2395 + ``` 2396 2396 + Configuration Evaluated 2397 2397 + // c Cycles in nodes of type struct evaluate 2398 2398 + // ↙︎ ↖ to the fixed point of unifying their. 2399 2399 + // a → b values 2400 2400 + 2401 2401 + a: b // a: { x: 1, y: 3 } 2402 2402 + b: c // b: { x: 1, y: 3 } 2403 2403 + c: a // c: { x: 1, y: 3 } 2404 2404 + 2405 2405 + a: { x: 1 } 2406 2406 + b: { y: 3 } 2407 2407 + ``` 2408 2408 + 2409 2409 + 2410 2410 + 1. Cycle breaking 2411 2411 + 1. Cycle detection 2412 2412 + 1. Assertion checks 2413 2413 + 1. Validation 2414 2414 + 2415 2415 + The preparation step loads all the relevant CUE sources and merges duplicate 2416 2416 + by creating unification expressions until each field is unique within its scope. 2417 2417 + 2418 2418 + 2419 2419 + For fields of type struct any cycle that does not result in an infinite 2420 2420 + structure is allowed. 2421 2421 + An expresion of type struct only allows unification and disjunction operations. 2422 2422 + 2423 2423 + Unification of structs is done by unifying a copy of each of the input structs. 2424 2424 + A copy of a referenced input struct may itself contain references which are 2425 2425 + handled with the following rules: 2426 2426 + - a reference bound to a field that it is being copied is replaced 2427 2427 + with a new reference pointing to the respective copy, 2428 2428 + - a reference bound to a field that is not being copied refers to the 2429 2429 + original field. 2430 2430 + 2431 2431 + 2432 2432 + #### Self-referential cycles 2433 2433 + 2434 2434 + A graph unification algorithm like Tomabechi [] or Van Lohuizen [] can be used 2435 2435 + to handle the reference replacement rules and minimize the cost of 2436 2436 + copying and cycle detection. 2437 2437 + 2438 2438 + Unification of lists, which are expressible as structs, follow along the same 2439 2439 + lines. 2440 2440 + 2441 2441 + For an expression `a & b` of any scalar type where exactly one of `a` or `b` is 2442 2442 + a concrete value, the result may be replaced by this concrete value while 2443 2443 + adding the expression `a == b` to the list of assertions. 2444 2444 + 2445 2445 + ``` 2446 2446 + // Config Evaluates to 2447 2447 + x: { x: { 2448 2448 + a: b + 100 a: ⊥ // cycle detected 2449 2449 + b: a - 100 b: ⊥ // cycle detected 2450 2450 + } } 2451 2451 + 2452 2452 + y: x & { y: { 2453 2453 + a: 200 a: 200 // asserted that 200 == b + 100 2454 2454 + b: 100 2455 2455 + } } 2456 2456 + ``` 2457 2457 + 2458 2458 + During the evaluation of a field which expression is being evaluated is marked as such. 2459 2459 + 2460 2460 + A field `f` with unification expression `e` where `e` contains reference that in turn 2461 2461 + point to `a` can be handled as follows: 2462 2462 + 2463 2463 + #### Evaluation cycles 2464 2464 + 2465 2465 + For structs, cycles are disallowed 2466 2466 + 2467 2467 + Disallowed cycles: 2468 2468 + 2469 2469 + A field `a` is _reachable_ from field `b` if there is a selector sequence 2470 2470 + from `a` to `b`. 2471 2471 + 2472 2472 + A reference used in field `a` may not refer to a value that recursively 2473 2473 + refers to a value that is reachable from `a`. 2474 2474 + 2475 2475 + ``` 2476 2476 + a: b & { c: 3 } 2477 2477 + 2478 2478 + b: a.c // illegal reference 2479 2479 + 2480 2480 + ``` 2481 2481 + 2482 2482 + #### Structural cycles 2483 2483 + 2484 2484 + A reference to `Δ(π, q0)` may not recursively refer to `Δ(π', q)`, 2485 2485 + where `π` is a prefix to `π'`. 2486 2486 + 2487 2487 + 2488 2488 + a: b & { b: _ } 2489 2489 + 2490 2490 + 2491 2491 + ### Validation 2492 2492 + 2493 2493 + Implementations are allowed to postpone recursive unification of structures 2494 2494 + except for in the following cases: 2495 2495 + 2496 2496 + - Unification within disjunctions: 2497 2497 + 2498 2498 + 2499 2499 + <!-- 2500 2500 + ### Inference 2501 2501 + 2502 2502 + There is currently no logical inference for values of references prescribed. 2503 2503 + It mostly relies on users defining the value of all variables. 2504 2504 + The main reason for this is to keep control over run time complexity. 2505 2505 + However, implementations may be free to do so. 2506 2506 + Also, later versions of the language may strengthen requirements for resolution. 2507 2507 + 2508 2508 + TODO: examples of situations where variables could be resolved but are not. 2509 2509 + --> 2510 2510 + 2511 2511 + ### Unused values 2512 2512 + 2513 2513 + TODO: rules for detection of unused variables 2514 2514 + 2515 2515 + 1. Any alias value must be used 2516 2516 +