Embedding files in a CUE evaluation | CUE

Jonathan Matthews

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, and is available by default from version v0.12.0 of CUE onwards. This guide demonstrates the following version:

TERMINAL

$ cue version
cue version v0.12.0
...

Embedding files in an evaluation

Initialize a CUE module, or use an existing module if that’s appropriate in your situation:

TERMINAL

$ cue mod init

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:

TERMINAL

$ cue export --out yaml
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

Reference: cue help embed
Reference: cue help filetypes

Embedding files in an evaluation

Related content