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.

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:

TERMINAL

$ cue version
cue version v0.12.0-alpha.1.0.20241220130530-e4c4b8e8a15f
...

Embedding files in an evaluation

Enable the embed experiment:

TERMINAL

$ export CUE_EXPERIMENT=embed

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 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.