Users frequently need to load JSON, YAML, or other types of files into their CUE code.
Because CUE’s import
declarations only allow references to CUE packages,
some workflows resort to using the tooling layer
(cue cmd
)
to load non-CUE files. This can complicate the process if the tooling layer’s
advanced features aren’t otherwise needed.
The @embed()
attribute is designed to simplify workflows that require data to
be loaded at evaluation time.
Because the @embed()
attribute is experimental, its behaviour is subject to change.
Your feedback on this feature will help guide how it works: please use discussion #3264 to tell us about your experience with embedding.
Using @embed()
requires CUE version v0.10.0
or later.
This guide demonstrates the following version:
$ cue version
cue version v0.10.0
...
Embedding files in an evaluation
Enable the embed experiment:
$ export CUE_EXPERIMENT=embed
Include the @extern(embed)
directive at the top of each CUE file that uses the
@embed()
attribute. Use @embed()
to embed either a single named file, or a
glob identifying multiple files:
@extern(embed)
package p
oneFile: _ @embed(file=README.md,type=text)
manyFiles: _ @embed(glob=*.json)
{
"aField": "a value"
}
{
"aList": [
1,
2,
3
]
}
{
"anObject": {
"foo": "a",
"bar": "b",
"baz": "c"
}
}
# How to use this project
## Installation
Fetch the latest release from the official site,
and unpack it in your home directory. Next ...
By default, files are decoded using the encoding implied by their filename
extension, and it’s an error if the extension is not known. Files or globs with
an unknown filename extension can be loaded by adding the
type=<filetype>
parameter, where <filetype>
can be any type described in
cue help filetypes
.
Export the resulting configuration:
$ cue eval
oneFile: """
# How to use this project
## Installation
Fetch the latest release from the official site,
and unpack it in your home directory. Next ...
"""
manyFiles: {
"a.json": {
aField: "a value"
}
"b.json": {
aList: [1, 2, 3]
}
"c.json": {
anObject: {
foo: "a"
bar: "b"
baz: "c"
}
}
}
Next steps
The embedding proposal
contains more detail about the @embed()
feature. Your feedback on the proposal
is most welcome - please submit it via
discussion #3264.
Discussion #3264 will be updated when the embedding proposal is accepted or modified, and when feedback is posted: please subscribe to the discussion to receive these updates.