This release fixes some bugs, improves some errors and adds API. This version also drops support for some old constructs that have not been supported in the CUE tool for some time now. The main reason to start being more “aggressive” about this is to avoid surprises as we’re inching towards a full backwards compatibility guarantee. Note that “aggressive” is probably a strong word, these constructs have not been supported for over a year.
Language additions
Value aliases
CUE now allows value aliases, as suggested in various proposals and remarks. This allows, for instance, users to rewrite:
foo: {
a: b + c
b: int
c: int
}
bar: foo & {b: 1, c: 2}
as
foo: X={
a: X.b + X.c
}
bar: foo & {b: 1, c: 2}
In this case the benefit may be small, but there are various cases where not having this ability results in significant inconvenience. Also the query proposal, the UX design around the usage of the proposed must builtin, as well as various other patterns, rely on this ability.
Note the subtle but important difference between this and using field aliases. Using a field alias here, say X=foo: a: X.b + X.c would be equivalent to foo: a: foo.b + foo.c. As a result, in bar: foo, X.b would still be bound to the original location and not resolve to any b specified in bar.
Which one to use depends on the application. As a general rule, field aliases should be used when defining “types”, whereas value aliases should be used when defining “values”. An example of where one wants to use field aliases:
List="my-list-type": {
value: _
next: List
}
Here, using a value alias would result in a list where every value must be the same. This is probably the most subtle aspect of CUE. The guideline of using values aliases when defining values, and field aliases when defining types, however, should give users a good steer on the matter.
Tooling
Tag variables to inject contextual system values
The injection mechanism now allows injecting specific variables, such as current time, username, or hostname, or a random number, into fields marked with a @tag attribute. For instance:
import "path"
_os: string @tag(os,var=os)
path.Base(dir, _os)
allows for an OS-specific Base operation. Except for cue cmd, the var will only be injected when the -T is explicitly specified on the command line.
This approach 1) allows packages to remain hermetic, 2) allows using such functionality without having to resort to cue cmd, and 3) avoids introducing another injection point.
See cue help injection for more details.
Binary file type
The cue tool now supports binary files. These are very much like the supported “text” files, but translate the file contents to a CUE binary literal, rather than a text literal.
There are no default file extensions to recognize a binary file. The binary: file qualifier can be used to read a file as binary. See cue help filetypes for more info.
To make loading binary files in bulk more useful when importing, the import command now supports the --ext flag, allowing certain file types to be interpreted as a certain format. This also works for other types. See cue help import for more info.
--force/-f
This flag is now allowed for any command that outputs files.
API additions
Context.NewList
Uses can now construct a new list cue.Value with Context.NewList. This is defined on Context to allow the creation of empty lists, which still need to be associated with a Context.
Value.FillPath
FillPath now accepts list indices. The Go-to-CUE are now documented in more detail.
Fillpath now also accepts the selectors AnyString and AnyIndex, which allows setting pattern constraints. For instance, v.FillPath(cue.MakePath(cue.Str("a"), cue.AnyString, x), adds a: [string]: x to v.
It also allows setting optional fields. For instance, v.FillPath(cue.MakePath(cue.Str("b").Optional()), 1) will add b?: 1 to v, using the usual rules for unifying such fields.
Context.Encode
The documentation of this method has been significantly improved. This also fixes some bugs that were uncovered in the process.
These are now also two additional options: InferBuiltins and ImportPath. These were exposed to support the cue command in using the new API, but thus also allows other tool writers to use the same kind of functionality.
CUE package additions
crypto/hmac
The new package hmac implements the Keyed-Hash Message Authentication Code (HMAC) as defined in U.S. Federal Information Processing Standards Publication 198.
uuid
The new package uuid defines functionality for creating UUIDs as defined in RFC 4122.
Currently only Version 5 (SHA1) and Version 3 (MD5) are supported. The new tag variable injection mechanism that was introduced in this release, however, also opens up the possibility to include other versions, if needed.
Backwards incompatible changes
Dropped support for old-style aliases
Aliases of the style X = 4 (now let X = 4) have been deprecated since v0.1.4. However, by setting the version or in API use, these aliases would still work. Support for them has been fully removed. Down the line, this syntax can be reused as value aliases as well, relaxing the places where value aliases can be used.
For the time being, cue fix can still be used to rewrite old-style aliases to their let equivalent. There was a bug that missed the detection of some forms of the deprecated alias type. This has now been fixed.
Dropped support for old-style comprehensions
Support for the old-style comprehensions (e.g. [ x+1 for x in foo]) has now been fully removed. Use an older version of CUE to rewrite such old-style comprehensions using cue fmt or cue fix.
Removed ast.TemplateLabel type from API
This has not been parsed, supported, or used for ages. The type has now been removed from the API.
Value.Expr
Value.Expr now translates the or and and builtins as if they were native | or & constructs. This fixes a bug in encoding/openapi and is likely to prevent many issues. If one was relying on detecting the use of these builtins, however, this now will no longer work.
Value.Decode
This method was reimplemented to not use Value.MarshalJSON. This fixes many bugs, but may cause issues if users were relying on old behavior. The new implementation still strictly adheres to the JSON encoding spec when this makes sense, but deviates in some important aspects. For instance, numbers like 1 are now integers in CUE, rather than float. Also binary values are now handled correctly.
Bug fixes
- hidden references used on the command line now resolve to hidden fields in the package under evaluation
- equality of null value
Changelog
5b14995 ci: debug tip trigger failures
24ce27e ci: fix broken tip and new version triggers
a8369ae ci: fix tip and new version curl and env problems
c143a3a ci: fix tip triggers with proper quoting
746e02e ci: more debugging of tip triggers
6c6b4e7 ci: trigger unity and cuelang.org builds/equivalent on tip/new versions
97cac92 cmd/cue/cmd: do not silently ignore unknown filetypes
89abc18 cmd/cue/cmd: fix resolution of hidden values across tools
4f7caea cmd/cue/cmd: move tag flags handling to central location
b9e7d90 cmd/cue/cmd: support binary file type
b449c0f cmd/cue: support --force for all commands that allow output flags
aa70399 cue/ast: fully remove support for old-style comprehensions
b73ab0b cue/ast: remove support for TemplateLabel
1f1c3f6 cue/load: provide reason for exclusion of files
975ba50 cue/load: remove unused code
bcdf277 cue/load: support injection of system variables
c2a68a9 cue/parser: allow pattern constraints unconditionally
3e10918 cue/parser: better error messages for use of deprecated constructs
3ef90b3 cue/testdata, doc, pkg: fix some it's/its typos
f60c88a cue: Value.Expr: process or and and builtins semantically.
d9af603 cue: add InferBuiltins EncodeOption
b49cbbd cue: add NewList
1f618f0 cue: align import with top-level package for -e
66efc67 cue: allow setting list elements in FillPath
67c6b6f cue: better document Context.Encode and friends
9d044f0 cue: hoist attribute-related functionality to separate file
ed5cdf0 cue: more path cleanup
3347302 cue: move Decode to separate file
c365513 cue: prepare API implementation for structure sharing
0457356 cue: properly decode "any" labels
819cf95 cue: reimplement Decode to not use MarshalJSON
5481b41 cue: remove use of isDef
2e1ac0f cue: support optional fields for FillPath
ac7e992 cue: undeprecate Iterator.Label
3316905 doc/ref/spec.md: introduction of value aliases
a31dd01 doc/ref/spec.md: remove "dead code"
2198ac3 docs: add link to Code of Conduct to CONTRIBUTING guide
f5213be github: add bug report template link to repro advice
1ad66ab internal/core/adt: fix null values equality
3cdf845 internal/core/adt: use Closed for checking recursive closedness
5cd76bb internal/core/comple: drop support for old-style aliases
8823e2a internal/core: support field value aliases
6d67b48 pkg/crypto/hmac: add crypto/hmac support
2118921 pkg/crypto/hmac: fix package documentation
a7d3987 pkg/time: fix documentation bug in Unix
fd05bf4 pkg/uuid: implementation of hermetic UUID functions