diff --git a/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/en.md b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/en.md new file mode 100644 index 000000000..7669c5db9 --- /dev/null +++ b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/en.md @@ -0,0 +1,227 @@ +--- +title: Removing list arithmetic operators in CUE 0.11 +authors: [jpluscplusm] +toc_hide: true +--- + +{{{with _script_ "en" "HIDDEN: set up access to CUE v0.11 before release"}}} +export PATH=/cues/$CUELANG_CUE_TIP:$PATH +{{{end}}} + +In early versions, the CUE language explicitly allowed lists to be used with +the arithmetic operators "`+`" and "`*`". +This feature was removed from the language specification +[several years ago](https://review.gerrithub.io/plugins/gitiles/cue-lang/cue/+/172f0060cd405f30c5873b793e44300e1a3588cb%5E%21/), +and its removal is now being completed in CUE version 0.11. +This FAQ answers some of your questions about what's changed. + +All the `cue` commands shown here use the following pre-release version: + +{{{with script "en" "cue version"}}} +#ellipsis 1 +cue version +{{{end}}} + +## What's being removed, and from where? + +**The list arithmetic operators `*` and `+` no longer work +in CUE evaluated by the `cue` command and the Go API.** + +These operators are affected **only** when used with a list value on their left +or right side - they will continue to work as expected in all other situations +(such as numeric arithmetic and string composition). For example: + +{{}} +**This CUE no longer works:** +{{{with upload "en" "removed behaviour"}}} +-- list-arithmetic.cue -- +A: [1, 2, 3] * 2 // Invalid CUE! +B: [1, 2, 3] + [4, 5, 6] // Invalid CUE! +{{{end}}} +{{{with script "en" "removed behaviour"}}} +#FIXME: this will start failing when the site's +#CUE tip is upgraded past +#https://review.gerrithub.io/c/cue-lang/cue/+/1200221 +! cue eval missing.file.cue list-arithmetic.cue +{{{end}}} +{{}} +**This CUE will continue working as before:** +{{{with upload "en" "existing behaviour"}}} +-- numbers-strings.cue -- +C: 1 + 2*3 +D: 2*"X." + 3*"O.." +{{{end}}} +{{{with script "en" "existing behaviour"}}} +cue eval numbers-strings.cue +{{{end}}} +{{}} + +## Why are list arithmetic operators being removed? + +The commit that removed them from the CUE language specification in 2021 +[explained the project's reasoning](https://review.gerrithub.io/plugins/gitiles/cue-lang/cue/+/172f0060cd405f30c5873b793e44300e1a3588cb%5E%21/): + +{{}} +List operators are confusing [and] unnecessary. +For instance, is the result of [a,...]+[b,...] open or closed? +What about [a]+[b,...]? +{{}} + +## Why were list arithmetic operators supported until now? + +The CUE project takes its compatibility responsibilities to its users +seriously. A capability that's made available in a released version of CUE (as +list arithmetic operators were) shouldn't be removed the instant that it's +deprecated, even though CUE is still pre-version-1.0 and such an immediate +removal might seem generally allowable under +[semantic versioning guidelines](https://semver.org/#spec-item-5). + +Some users might have written working, supported CUE that relied on list +arithmetic operators, so the CUE tooling supported it up to and including +version 0.10 -- which was released over 3½ years after the feature stopped +being mentioned. + +Enough time has now passed *without* it being mentioned in the CUE language +specification or official documentation that we believe we can safely remove +it, as it's unlikely still to be in use. + +## Which versions of CUE don't support list arithmetic operators? + +Any release or pre-release of CUE that has a version string which *starts* with +`v0.11` or later does not support list arithmetic operators. + +This includes the 0.11 pre-release alphas (`v0.11.0-alpha...`), the 0.11 +release candidates (`v0.11.0-rc...`), and all 0.11 patch releases including +`v0.11.0`, `v0.11.1`, and so on. It also includes all releases that come after +0.11, whatever version number they might be given. + +## What are the replacements for list arithmetic operators? + +In all scenarios: + +- the "`*`" list operator can be replaced with + [`list.Repeat()`](/go/pkg/list#Repeat) +- the "`+`" list operator can be replaced with + [`list.Concat()`](/go/pkg/list#Concat) or a nested `for` loop + +Here are some examples: + +{{{with code "en" "replacements"}}} +exec cue eval replacements.cue +cmp stdout out +-- replacements.cue -- +import "list" + +// Rewrite "[1, 2, 3] * 2" like this: +A: list.Repeat([1, 2, 3], 2) + +// Rewrite "[1, 2, 3] + [4, 5, 6]" like this: +B: list.Concat([[1, 2, 3], [4, 5, 6]]) + +// Alternatively, rewrite "[1, 2, 3] + [4, 5, 6]" +// like this: +B: [for i in [1, 2, 3] {i}, for i in [4, 5, 6] {i}] +-- out -- +A: [1, 2, 3, 1, 2, 3] +B: [1, 2, 3, 4, 5, 6] +{{{end}}} + + +## Am I affected? + +The easiest way to check if your CUE needs to be updated is to use the `cue` +command: + +{{{with step}}} + +**Use CUE 0.10 to confirm that your CUE is valid.** + +Start by installing and using a previous version of the `cue` command that +**does** support list arithmetic operators (such as +[`v0.10.0`](/releases/v0.10.0)) to check that your CUE evaluates successfully. +Use the [`cue vet`]({{< relref "/docs/reference/command/cue-help-vet" >}}) +command on your CUE packages and/or files. + +If `cue vet` succeeds, continue with the next step. +If it fails, you *must* first fix any problems with your CUE. +{{{end}}} + +{{{with step}}} +**Check if CUE 0.11 also validates your CUE.** + +Install a version of `cue` that doesn't support list arithmetic operators, such +as FIXME, and run the same `cue vet` command as before. If your CUE contains +list arithmetic operators then you'll see errors like this, and you must update +your CUE: + +{{{with upload "en" "cue vet error"}}} +#force +-- list-arithmetic.cue -- +A: [1, 2, 3] * 2 // Invalid CUE! +B: [1, 2, 3] + [4, 5, 6] // Invalid CUE! +{{{end}}} +{{{with script "en" "cue vet error"}}} +#FIXME: error after https://review.gerrithub.io/c/cue-lang/cue/+/1200221. +! cue vet missing.file.cue list-arithmetic.cue +{{{end}}} +{{{end}}} + +## I *am* affected! How can I fix my CUE? + +The [`cue fix`]({{< relref "/docs/reference/command/cue-help-fix" >}}) command +can automatically check and update CUE files, packages, and entire modules. +It updates them to use current CUE syntax. Make sure you use a `cue` command of +at least version FIXME -- earlier versions didn't know how to update the list +arithmetic operators. + +{{{with upload "en" "cue fix"}}} +#force +-- list-arithmetic.cue -- +A: [1, 2, 3] * 2 +B: [1, 2, 3] + [4, 5, 6] +{{{end}}} +{{{with script "en" "cue fix"}}} +#FIXME: error after https://review.gerrithub.io/c/cue-lang/cue/+/1200221. +# The file shown above contains invalid CUE: +! cue vet missing.file.cue list-arithmetic.cue +# "cue fix" is silent when it succeeds: +cue fix list-arithmetic.cue +# The file has been updated to use current CUE syntax: +cat list-arithmetic.cue +# The CUE now evaluates correctly: +cue eval list-arithmetic.cue +{{{end}}} + +There are some scenarios that `cue fix` can't help with. + +Specifically, `cue fix` can only replace the `*` and `+` list arithmetic +operators when they're used with literal lists, and not references. In other +words, `cue fix` only updates these operators when they are used *directly* +with list values such as `[1, 2, 3]`. + +This means that when the following CUE causes `cue vet` to fail, it must then +be updated manually: + +{{{with upload "en" "references"}}} +-- references.cue -- +x: [1, 2, 3] +y: [4, 5, 6] + +A: x * 2 // Invalid CUE! +B: x + y // Invalid CUE! +{{{end}}} +{{{with script "en" "references"}}} +# "cue vet" correctly flags the file as needing an update: +! cue vet missing.file.cue references.cue +# "cue fix" runs successfully ... +cue fix references.cue +# ... but "cue fix" didn't perform the updates: +cat references.cue +{{{end}}} + +## Related content + +- {{}} +- {{}} +- Standard library: [`list.Repeat()`](/go/pkg/list#Repeat) +- Standard library: [`list.Concat()`](/go/pkg/list#Concat) diff --git a/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/gen_cache.cue b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/gen_cache.cue new file mode 100644 index 000000000..1b5b9776e --- /dev/null +++ b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/gen_cache.cue @@ -0,0 +1,136 @@ +package site +{ + content: { + docs: { + concept: { + faq: { + "removing-list-arithmetic-operators-v0.11": { + page: { + cache: { + upload: { + "removed behaviour": "NyfFI1WeUxZKK4dZqorCEcxydRpu9SWntUp+eTFomng=" + "existing behaviour": "2gi8XBiobY0f6L+LkggBwMtCPFamg296pRYhmnOFV/c=" + "cue vet error": "EL3MinbvU7NEPnlo4FXCcQyl/GirBGcRUa4wooQPMtc=" + "cue fix": "Li+e1q5WjG30PqTPtD41YiuXbIGI9oS5AEFDL5q1ASY=" + references: "ZnhV9LFkR6McnvVAE8puEQTjpFGf26JpDn0RIzcJALk=" + } + code: { + replacements: "uvmUs/Dw7PATeKDTPEQUOBr4B4u7yCtjTD2etmWccB4=" + } + multi_step: { + hash: "1EOOUBM897R574V91B9S1B5EGQ1UVU8422RGI6P8TGLC4ODQJVTG====" + scriptHash: "KJBEVVUPS5M0GAIB0LSR0GGULUUFO9FL0P75JLOCRVULNHECT63G====" + steps: [{ + doc: "" + cmd: "export PATH=/cues/v0.11.0-0.dev.0.20240902110846-1440b9eae7fa:$PATH" + exitCode: 0 + output: "" + }, { + doc: "#ellipsis 1" + cmd: "cue version" + exitCode: 0 + output: """ + cue version v0.11.0-0.dev.0.20240902110846-1440b9eae7fa + ... + + """ + }, { + doc: """ + #FIXME: this will start failing when the site's + #CUE tip is upgraded past + #https://review.gerrithub.io/c/cue-lang/cue/+/1200221 + """ + cmd: "cue eval missing.file.cue list-arithmetic.cue" + exitCode: 1 + output: """ + could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + + """ + }, { + doc: "" + cmd: "cue eval numbers-strings.cue" + exitCode: 0 + output: """ + C: 7 + D: "X.X.O..O..O.." + + """ + }, { + doc: "#FIXME: error after https://review.gerrithub.io/c/cue-lang/cue/+/1200221." + cmd: "cue vet missing.file.cue list-arithmetic.cue" + exitCode: 1 + output: """ + could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + + """ + }, { + doc: """ + #FIXME: error after https://review.gerrithub.io/c/cue-lang/cue/+/1200221. + # The file shown above contains invalid CUE: + """ + cmd: "cue vet missing.file.cue list-arithmetic.cue" + exitCode: 1 + output: """ + could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + + """ + }, { + doc: "# \"cue fix\" is silent when it succeeds:" + cmd: "cue fix list-arithmetic.cue" + exitCode: 0 + output: "" + }, { + doc: "# The file has been updated to use current CUE syntax:" + cmd: "cat list-arithmetic.cue" + exitCode: 0 + output: """ + import "list" + + A: list.Repeat([1, 2, 3], 2) + B: list.Concat([[1, 2, 3], [4, 5, 6]]) + + """ + }, { + doc: "# The CUE now evaluates correctly:" + cmd: "cue eval list-arithmetic.cue" + exitCode: 0 + output: """ + A: [1, 2, 3, 1, 2, 3] + B: [1, 2, 3, 4, 5, 6] + + """ + }, { + doc: "# \"cue vet\" correctly flags the file as needing an update:" + cmd: "cue vet missing.file.cue references.cue" + exitCode: 1 + output: """ + could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + + """ + }, { + doc: "# \"cue fix\" runs successfully ..." + cmd: "cue fix references.cue" + exitCode: 0 + output: "" + }, { + doc: "# ... but \"cue fix\" didn't perform the updates:" + cmd: "cat references.cue" + exitCode: 0 + output: """ + x: [1, 2, 3] + y: [4, 5, 6] + + A: x * 2 // Invalid CUE! + B: x + y // Invalid CUE! + + """ + }] + } + } + } + } + } + } + } + } +} diff --git a/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/page.cue b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/page.cue new file mode 100644 index 000000000..6f9a2ef89 --- /dev/null +++ b/content/docs/concept/faq/removing-list-arithmetic-operators-v0.11/page.cue @@ -0,0 +1,3 @@ +package site + +content: docs: concept: faq: "removing-list-arithmetic-operators-v0.11": page: _ diff --git a/hugo/content/en/docs/concept/faq/removing-list-arithmetic-operators-v0.11/index.md b/hugo/content/en/docs/concept/faq/removing-list-arithmetic-operators-v0.11/index.md new file mode 100644 index 000000000..293e2cafe --- /dev/null +++ b/hugo/content/en/docs/concept/faq/removing-list-arithmetic-operators-v0.11/index.md @@ -0,0 +1,240 @@ +--- +title: Removing list arithmetic operators in CUE 0.11 +authors: [jpluscplusm] +toc_hide: true +--- + +In early versions, the CUE language explicitly allowed lists to be used with +the arithmetic operators "`+`" and "`*`". +This feature was removed from the language specification +[several years ago](https://review.gerrithub.io/plugins/gitiles/cue-lang/cue/+/172f0060cd405f30c5873b793e44300e1a3588cb%5E%21/), +and its removal is now being completed in CUE version 0.11. +This FAQ answers some of your questions about what's changed. + +All the `cue` commands shown here use the following pre-release version: + +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIHZlcnNpb24=" } +$ cue version +cue version v0.11.0-0.dev.0.20240902110846-1440b9eae7fa +... +``` + +## What's being removed, and from where? + +**The list arithmetic operators `*` and `+` no longer work +in CUE evaluated by the `cue` command and the Go API.** + +These operators are affected **only** when used with a list value on their left +or right side - they will continue to work as expected in all other situations +(such as numeric arithmetic and string composition). For example: + +{{}} +**This CUE no longer works:** +{{< code-tabs >}} +{{< code-tab name="list-arithmetic.cue" language="cue" area="top-left" >}} +A: [1, 2, 3] * 2 // Invalid CUE! +B: [1, 2, 3] + [4, 5, 6] // Invalid CUE! +{{< /code-tab >}}{{< /code-tabs >}} +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIGV2YWwgbWlzc2luZy5maWxlLmN1ZSBsaXN0LWFyaXRobWV0aWMuY3Vl" } +$ cue eval missing.file.cue list-arithmetic.cue +could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory +``` +{{}} +**This CUE will continue working as before:** +{{< code-tabs >}} +{{< code-tab name="numbers-strings.cue" language="cue" area="top-left" >}} +C: 1 + 2*3 +D: 2*"X." + 3*"O.." +{{< /code-tab >}}{{< /code-tabs >}} +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIGV2YWwgbnVtYmVycy1zdHJpbmdzLmN1ZQ==" } +$ cue eval numbers-strings.cue +C: 7 +D: "X.X.O..O..O.." +``` +{{}} + +## Why are list arithmetic operators being removed? + +The commit that removed them from the CUE language specification in 2021 +[explained the project's reasoning](https://review.gerrithub.io/plugins/gitiles/cue-lang/cue/+/172f0060cd405f30c5873b793e44300e1a3588cb%5E%21/): + +{{}} +List operators are confusing [and] unnecessary. +For instance, is the result of [a,...]+[b,...] open or closed? +What about [a]+[b,...]? +{{}} + +## Why were list arithmetic operators supported until now? + +The CUE project takes its compatibility responsibilities to its users +seriously. A capability that's made available in a released version of CUE (as +list arithmetic operators were) shouldn't be removed the instant that it's +deprecated, even though CUE is still pre-version-1.0 and such an immediate +removal might seem generally allowable under +[semantic versioning guidelines](https://semver.org/#spec-item-5). + +Some users might have written working, supported CUE that relied on list +arithmetic operators, so the CUE tooling supported it up to and including +version 0.10 -- which was released over 3½ years after the feature stopped +being mentioned. + +Enough time has now passed *without* it being mentioned in the CUE language +specification or official documentation that we believe we can safely remove +it, as it's unlikely still to be in use. + +## Which versions of CUE don't support list arithmetic operators? + +Any release or pre-release of CUE that has a version string which *starts* with +`v0.11` or later does not support list arithmetic operators. + +This includes the 0.11 pre-release alphas (`v0.11.0-alpha...`), the 0.11 +release candidates (`v0.11.0-rc...`), and all 0.11 patch releases including +`v0.11.0`, `v0.11.1`, and so on. It also includes all releases that come after +0.11, whatever version number they might be given. + +## What are the replacements for list arithmetic operators? + +In all scenarios: + +- the "`*`" list operator can be replaced with + [`list.Repeat()`](/go/pkg/list#Repeat) +- the "`+`" list operator can be replaced with + [`list.Concat()`](/go/pkg/list#Concat) or a nested `for` loop + +Here are some examples: + +{{< code-tabs >}} +{{< code-tab name="replacements.cue" language="cue" area="top-left" >}} +import "list" + +// Rewrite "[1, 2, 3] * 2" like this: +A: list.Repeat([1, 2, 3], 2) + +// Rewrite "[1, 2, 3] + [4, 5, 6]" like this: +B: list.Concat([[1, 2, 3], [4, 5, 6]]) + +// Alternatively, rewrite "[1, 2, 3] + [4, 5, 6]" +// like this: +B: [for i in [1, 2, 3] {i}, for i in [4, 5, 6] {i}] +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" area="top-right" type="terminal" codetocopy="Y3VlIGV2YWwgcmVwbGFjZW1lbnRzLmN1ZQ==" >}} +$ cue eval replacements.cue +A: [1, 2, 3, 1, 2, 3] +B: [1, 2, 3, 4, 5, 6] +{{< /code-tab >}} +{{< /code-tabs >}} + + +## Am I affected? + +The easiest way to check if your CUE needs to be updated is to use the `cue` +command: + +{{< step stepNumber="1" >}} + +**Use CUE 0.10 to confirm that your CUE is valid.** + +Start by installing and using a previous version of the `cue` command that +**does** support list arithmetic operators (such as +[`v0.10.0`](/releases/v0.10.0)) to check that your CUE evaluates successfully. +Use the [`cue vet`]({{< relref "/docs/reference/command/cue-help-vet" >}}) +command on your CUE packages and/or files. + +If `cue vet` succeeds, continue with the next step. +If it fails, you *must* first fix any problems with your CUE. +{{< /step >}} + +{{< step stepNumber="2" >}} +**Check if CUE 0.11 also validates your CUE.** + +Install a version of `cue` that doesn't support list arithmetic operators, such +as FIXME, and run the same `cue vet` command as before. If your CUE contains +list arithmetic operators then you'll see errors like this, and you must update +your CUE: + +{{< code-tabs >}} +{{< code-tab name="list-arithmetic.cue" language="cue" area="top-left" >}} +A: [1, 2, 3] * 2 // Invalid CUE! +B: [1, 2, 3] + [4, 5, 6] // Invalid CUE! +{{< /code-tab >}}{{< /code-tabs >}} +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIHZldCBtaXNzaW5nLmZpbGUuY3VlIGxpc3QtYXJpdGhtZXRpYy5jdWU=" } +$ cue vet missing.file.cue list-arithmetic.cue +could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory +``` +{{< /step >}} + +## I *am* affected! How can I fix my CUE? + +The [`cue fix`]({{< relref "/docs/reference/command/cue-help-fix" >}}) command +can automatically check and update CUE files, packages, and entire modules. +It updates them to use current CUE syntax. Make sure you use a `cue` command of +at least version FIXME -- earlier versions didn't know how to update the list +arithmetic operators. + +{{< code-tabs >}} +{{< code-tab name="list-arithmetic.cue" language="cue" area="top-left" >}} +A: [1, 2, 3] * 2 +B: [1, 2, 3] + [4, 5, 6] +{{< /code-tab >}}{{< /code-tabs >}} +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIHZldCBtaXNzaW5nLmZpbGUuY3VlIGxpc3QtYXJpdGhtZXRpYy5jdWUKY3VlIGZpeCBsaXN0LWFyaXRobWV0aWMuY3VlCmNhdCBsaXN0LWFyaXRobWV0aWMuY3VlCmN1ZSBldmFsIGxpc3QtYXJpdGhtZXRpYy5jdWU=" } +# The file shown above contains invalid CUE: +$ cue vet missing.file.cue list-arithmetic.cue +could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + +# "cue fix" is silent when it succeeds: +$ cue fix list-arithmetic.cue + +# The file has been updated to use current CUE syntax: +$ cat list-arithmetic.cue +import "list" + +A: list.Repeat([1, 2, 3], 2) +B: list.Concat([[1, 2, 3], [4, 5, 6]]) + +# The CUE now evaluates correctly: +$ cue eval list-arithmetic.cue +A: [1, 2, 3, 1, 2, 3] +B: [1, 2, 3, 4, 5, 6] +``` + +There are some scenarios that `cue fix` can't help with. + +Specifically, `cue fix` can only replace the `*` and `+` list arithmetic +operators when they're used with literal lists, and not references. In other +words, `cue fix` only updates these operators when they are used *directly* +with list values such as `[1, 2, 3]`. + +This means that when the following CUE causes `cue vet` to fail, it must then +be updated manually: + +{{< code-tabs >}} +{{< code-tab name="references.cue" language="cue" area="top-left" >}} +x: [1, 2, 3] +y: [4, 5, 6] + +A: x * 2 // Invalid CUE! +B: x + y // Invalid CUE! +{{< /code-tab >}}{{< /code-tabs >}} +```text { title="TERMINAL" type="terminal" codeToCopy="Y3VlIHZldCBtaXNzaW5nLmZpbGUuY3VlIHJlZmVyZW5jZXMuY3VlCmN1ZSBmaXggcmVmZXJlbmNlcy5jdWUKY2F0IHJlZmVyZW5jZXMuY3Vl" } +# "cue vet" correctly flags the file as needing an update: +$ cue vet missing.file.cue references.cue +could not find file /home/runner/missing.file.cue: stat: stat /home/runner/missing.file.cue: no such file or directory + +# "cue fix" runs successfully ... +$ cue fix references.cue + +# ... but "cue fix" didn't perform the updates: +$ cat references.cue +x: [1, 2, 3] +y: [4, 5, 6] + +A: x * 2 // Invalid CUE! +B: x + y // Invalid CUE! +``` + +## Related content + +- {{}} +- {{}} +- Standard library: [`list.Repeat()`](/go/pkg/list#Repeat) +- Standard library: [`list.Concat()`](/go/pkg/list#Concat)