embed

Overview ¶

Package embed provides capabilities to CUE to embed any file that resides within a CUE module into CUE either verbatim or decoded.

This package is EXPERIMENTAL and subject to change.

Overview ¶

To enable file embedding, a file must include the file-level @extern(embed) attribute. This allows a quick glance to see if a file embeds any files at all. This allows the @embed attribute to be used to load a file within a CUE module into a field.

References to files are always relative to directory in which the referring file resides. Only files that exist within the CUE module are accessible.

The @embed attribute ¶

There are two main ways to embed files which are distinguished by the file and glob arguments. The @embed attribute supports the following arguments:

file=$filename

The use of the file argument tells embed to load a single file into the field. This argument many not be used in conjunction with the glob argument.

glob=$pattern

The use of the glob argument tells embed to load multiple files into the field as a map of file paths to the decoded values. The paths are normalized to use forward slashes. This argument may not be used in conjunction with the file argument.

type=$type

By default, the file type is interpreted based on the file extension. This behavior can be overridden by the type argument. See cue help filetypes for the list of supported types. This field is required if a file extension is unknown, or if a wildcard is used for the file extension in the glob pattern.

allowEmptyGlob

By default, a glob pattern that matches no files results in an error. When allowEmptyGlob is present, a glob pattern with no matches will return an empty struct instead of an error. This option is only supported with glob patterns.

Limitations ¶

The embed interpreter currently does not support: - stream values, such as .ndjson or YAML streams. - schema-based decoding, such as needed for textproto

Example ¶

@extern(embed)

package foo

// interpreted as JSON
a: _ @embed(file="file1.json") // the quotes are optional here

// interpreted the same file as JSON schema
#A: _ @embed(file=file1.json, type=jsonschema)

// interpret a proprietary extension as OpenAPI represented as YAML
b: _ @embed(file="file2.crd", type=openapi+yaml)

// include all YAML files in the x directory interpreted as YAML
// The result is a map of file paths to the decoded YAML values.
files: _ @embed(glob=x/*.yaml)

// include all files in the y directory as a map of file paths to binary
// data. The entries are unified into the same map as above.
files: _ @embed(glob=y/*.*, type=binary)

// include all YAML files in the z directory, but allow empty result
// if no files match (returns empty struct instead of error)
optionalFiles: _ @embed(glob=z/*.yaml, allowEmptyGlob)