From ecda3912bb88ff459349f2e26e7fe9ba326e7da9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Daniel=20Mart=C3=AD?= Date: Tue, 13 Aug 2024 17:20:05 +0100 Subject: [PATCH] cmd/cue: expand the embed help section MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Lifting text and examples from the proposal document, but in shorter format for the sake of a quick summary as well as dropping some details which don't matter to users. Fixes #3268. Signed-off-by: Daniel Martí Change-Id: I8b90923dd43b5c706b9f8cf9dd0bd82513c1ad1d Reviewed-on: https://review.gerrithub.io/c/cue-lang/cue/+/1199411 Reviewed-by: Matthew Sackman Unity-Result: CUE porcuepine TryBot-Result: CUEcueckoo --- cmd/cue/cmd/help.go | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/cmd/cue/cmd/help.go b/cmd/cue/cmd/help.go index d8f9f0da5ab..355d294869b 100644 --- a/cmd/cue/cmd/help.go +++ b/cmd/cue/cmd/help.go @@ -198,8 +198,34 @@ var embedHelp = &cobra.Command{ Use: "embed", Short: "file embedding", Long: ` -The @embed directive can be used to load files of any type as part of CUE -evaluation. +The @embed attribute can be used to load files as part of CUE evaluation. +Embedding must be enabled by a file-level @extern(embed) attribute. + +Embed a single file as follows, which must exist when evaluating: + + @extern(embed) + + package foo + + a: _ @embed(file=foo.json) + +Embed many files of the same type with a glob pattern, +which inserts one field per file matched: + + b: _ @embed(glob=images/*.*, type=binary) + b: [string]: bytes + +Note that "**" glob patterns are not supported at this time. + +If the file extension in "file" or "glob" does not imply a file type, +it must be specified with the "type" encoding as shown above. +See the "filetypes" help topic for more. + +Files containing multiple documents cannot be embedded directly. +For NDJSON or multi-document YAML files, embed as type=text +and use APIs like yaml.Extract to decode as a list. + +Note that embedding cue files is not supported at this time. Note: support for embed is experimental, and is enabled via CUE_EXPERIMENT=embed.