search

cue-lang / docs-and-content

A place to discuss, plan, and track documentation on cuelang.org
5 stars 1 forks source link

`--with-context` and the `data` field: use cases and implications #54

Open jpluscplusm opened 7 months ago

jpluscplusm commented 7 months ago

In a Slack thread a user needed to import data at a location taken from a top-level field in the data that had a field name that wasn't a valid CUE identifier, transforming:

---
schema-version: v2
team: foo
---
schema-version: v3
team: bar

... into ...

v2: {
  "schema-version": v2
  team: "foo"
}
v3: {
  "schema-version": v3
  team: "bar"
}

This required the use of --with-context to gain access to the data field, but only because data["schema-version"]'s index-form was required.

Another use of data is forced on us by this passage from cue flags:

The --with-context flag can be used to evaluate the label expression within a struct of contextual data, instead of within the value itself.

In other words, once we add --with-context to a CLI invocation, all -l params cannot refer to the data in the evaluation space by bare name (cue import file.yml -l 'aFieldName'), but instead must refer to data (cue import file.yml --with-context -l 'data.aFieldName') - regardless of if any other context is being used by -l or not. So adding --with-context for filename access forces the use of data if values from the underlying data are being used to place the content at a specific location.

What's the right doc type and use case example to demonstrate why data exists, and the change in behaviour once --with-context is included in a CLI invocation? The thread's example ("field name is not a valid identifier") is perhaps not the ideal candidate, but its use case does need documenting in isolation. What's the right doc type for --with-context to be explained? A concept guide, perhaps?

Thread content Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706129432105289) Is there an escape character I need to include when passing in a label with a hypen: e.g. `cue import foo.yaml -l 'my-label'` ? 19 replies Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706129890447929?thread_ts=1706129432.105289&cid=C012UU8B72M) `-l '"my-label":'` from memory :eyes: 1 Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706129987133249?thread_ts=1706129432.105289&cid=C012UU8B72M) drats that didn’t seem to work Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130134467459?thread_ts=1706129432.105289&cid=C012UU8B72M) Works for me, here. CUE 0.7.0. Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130137842969?thread_ts=1706129432.105289&cid=C012UU8B72M) ``` $ cat sample.yaml --- schema-version: v2 team: foo $ cue import sample.yaml -l '"schema-version":' -o - "schema-version": { "schema-version": "v2" team: "foo" } ``` Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130195846119?thread_ts=1706129432.105289&cid=C012UU8B72M) That seems to be correct. What did you expect to see? Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130255597829?thread_ts=1706129432.105289&cid=C012UU8B72M) `-l` says "place the data under this path". Were you expecting it to select only the data that /exists/ at that location? Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130438442159?thread_ts=1706129432.105289&cid=C012UU8B72M) I was hoping to handle multiple objects like: ``` "v2": { "schema-version": "v2" team: "foo" } "v3": { "schema-version": "v3" team: "bar" } ``` Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130462361639?thread_ts=1706129432.105289&cid=C012UU8B72M) ``` --- schema-version: v2 team: foo --- schema-version: v3 team: bar ``` Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130536299569?thread_ts=1706129432.105289&cid=C012UU8B72M) Oh, you need `--with-context`, and the data field. Check out `cue help flags`: https://alpha.cuelang.org/docs/reference/cli/cue-flags/ Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130641817799?thread_ts=1706129432.105289&cid=C012UU8B72M) wow! Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130644023409?thread_ts=1706129432.105289&cid=C012UU8B72M) yes, that’s it Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130644333259?thread_ts=1706129432.105289&cid=C012UU8B72M) `cue export foo.yml --with-context -l 'data["schema-version"]'` should do what you need. Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130779351279?thread_ts=1706129432.105289&cid=C012UU8B72M) :+1: (edited) Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706130804200419?thread_ts=1706129432.105289&cid=C012UU8B72M) now `--with-context` makes more sense to me Saved for later Jonathan Matthews [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706131365801969?thread_ts=1706129432.105289&cid=C012UU8B72M) This is definitely a corner case, IMHO. You only need `--with-context` because you need a way to index via a field name that's not a valid identifier - which you need to do with `data`. If your field were a valid cue identifier, you could remove `with-context` and `data` and reference it directly, more simply: ``` cue export foo.yaml -l 'someValidIdentifer' ``` (edited) Tahir Butt [12 days ago](https://cuelang.slack.com/archives/C012UU8B72M/p1706131406906889?thread_ts=1706129432.105289&cid=C012UU8B72M) thanks for the clarification! :+1: 1