embed

Documentation

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 the directory in which the referring file resides. Only files in the same module containing the CUE file can be embedded, and parent directory references are not allowed.

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)

Index

• Constants
• func New() runtime.Interpreter
• type Embed
  • func EmbeddedPaths(filepath string, attrsByField map[*ast.Field]*internal.Attr) ([]*Embed, errors.Error)
  • func (e *Embed) FindAll(fs iofs.FS) ([]string, error)
  • func (e *Embed) IsGlob() bool
  • func (e *Embed) Matches(filepath string) bool

Constants

const EmbedKind = "embed"

Functions

func New

func New() runtime.Interpreter

New returns a new interpreter for embedded files as a cuelang.org/go/cue/cuecontext.ExternInterpreter suitable for passing to cuelang.org/go/cue/cuecontext.New.

Types

type Embed

type Embed struct {
	Field     *ast.Field
	Attribute *internal.Attr
	FilePath  string
	Type      string
	// contains filtered or unexported fields
}

func EmbeddedPaths

func EmbeddedPaths(filepath string, attrsByField map[*ast.Field]*internal.Attr) ([]*Embed, errors.Error)

EmbeddedPaths validates the provided attributes as embed attributes, returning a slice of Embed structs for attributes that were successfully validated, and errors for those which were not. The filepath should be the filepath of the file from which these attributes were extracted, and relative to whatever root is going to be used in calls to Embed.Matches and Embed.FindAll.

func (*Embed) FindAll

func (e *Embed) FindAll(fs iofs.FS) ([]string, error)

FindAll uses the provided fs to report all the filepaths that match this Embed attribute. The fs must be relative to the same root as the filepath provided to EmbeddedPaths. I.e. for the filepath provided to EmbeddedPaths, iofs.Stat(fs, filepath) should be accessing the same file which contained this Embed attribute.

func (*Embed) IsGlob

func (e *Embed) IsGlob() bool

IsGlob reports whether this Embed attribute represents a glob embedding.

func (*Embed) Matches

func (e *Embed) Matches(filepath string) bool

Matches reports whether the provided filepath is matched by this Embed attribute. The filepath should be relative to the same root as the filepath provided to EmbeddedPaths. E.g. if in `/wibble/foo/bar.cue` you have `@embed(filename=a/b.json)`, and `foo/bar.cue` is the filepath passed to EmbeddedPaths, then Embed.Matches will return true if called with `foo/a/b.json`.