From f3d99fe3de995bf23807a32d7a510d4d810ef27d Mon Sep 17 00:00:00 2001 From: Jonathan Matthews Date: Thu, 24 Oct 2024 16:58:12 +0100 Subject: [PATCH] docs/howto: combine conditions using chained ifs This adds a guide that demonstrates a pair of scenarios where the && operator cannot be used, and where chained if clauses are necessary. Closes cue-lang/docs-and-content#185. Preview-Path: /docs/howto/combine-conditions-using-chained-if/ Signed-off-by: Jonathan Matthews Change-Id: I899019354b0b31c66dcff8a2458812011499f384 Dispatch-Trailer: {"type":"trybot","CL":1203075,"patchset":5,"ref":"refs/changes/75/1203075/5","targetBranch":"master"} --- .../combine-conditions-using-chained-if/en.md | 72 ++++++++++++++++++ .../gen_cache.cue | 18 +++++ .../page.cue | 3 + .../index.md | 73 +++++++++++++++++++ 4 files changed, 166 insertions(+) create mode 100644 content/docs/howto/combine-conditions-using-chained-if/en.md create mode 100644 content/docs/howto/combine-conditions-using-chained-if/gen_cache.cue create mode 100644 content/docs/howto/combine-conditions-using-chained-if/page.cue create mode 100644 hugo/content/en/docs/howto/combine-conditions-using-chained-if/index.md diff --git a/content/docs/howto/combine-conditions-using-chained-if/en.md b/content/docs/howto/combine-conditions-using-chained-if/en.md new file mode 100644 index 000000000..25da9846f --- /dev/null +++ b/content/docs/howto/combine-conditions-using-chained-if/en.md @@ -0,0 +1,72 @@ +--- +title: 'Combining conditions using chained "if" clauses' +authors: [jpluscplusm] +toc_hide: true +--- + +The CUE language allows conditional tests to decide if certain fields are +included in data. It provides different ways to combine conditions, which +*usually* produce equivalent results. + +However, in some situations a specific mechanism must be used to combine +conditions by chaining them together using multiple `if` clauses. This is +because the alternative (CUE's `&&` operator) doesn't prematurely stop (or +"short circuit") a failing compound condition that includes it. + +This guide demonstrates some situations that require the use of chained `if` +clauses. + +{{{with code "en" "cc"}}} +exec cue export +cmp stdout out +-- file.cue -- +package example + +A: "foo" +B: 42 + +// Either of these 2 methods of combining +// conditions can be used if a type check +// is not required: +if A == "foo" && B < 100 {C: true} +if A == "foo" if B < 100 {C: true} + +// When a type check is required, chained "if" +// clauses must be used: +if (B & int) != _|_ if B < 100 {D: true} + +// This would fail if uncommented because the type +// check does not stop the inequality being tested: +// if (A & int) != _|_ && A < 100 {D: true} + +#X: { + a!: string + b!: int +} +X: c: 4.2 + +// If this type check is required it must be +// combined with the inequality test using a +// chained "if" clause: +if (X & #X) != _|_ if X.b < 100 {E: true} + +// This would cause an evaluation failure if +// uncommented because X.b does not exist: +// if (X & #X) != _|_ && X.b < 100 {E: true} +-- out -- +{ + "A": "foo", + "B": 42, + "C": true, + "D": true, + "X": { + "c": 4.2 + } +} +{{{end}}} + +## Related content + +- {{< linkto/related/tour "expressions/conditional" >}} +- {{< linkto/related/tour "expressions/listcomp" >}} +- {{< linkto/related/tour "expressions/fieldcomp" >}} diff --git a/content/docs/howto/combine-conditions-using-chained-if/gen_cache.cue b/content/docs/howto/combine-conditions-using-chained-if/gen_cache.cue new file mode 100644 index 000000000..e16a1eadc --- /dev/null +++ b/content/docs/howto/combine-conditions-using-chained-if/gen_cache.cue @@ -0,0 +1,18 @@ +package site +{ + content: { + docs: { + howto: { + "combine-conditions-using-chained-if": { + page: { + cache: { + code: { + cc: "OqOrijTcgvetg3Q9l02SChwMJLm8UP7fIvqPNePn22E=" + } + } + } + } + } + } + } +} diff --git a/content/docs/howto/combine-conditions-using-chained-if/page.cue b/content/docs/howto/combine-conditions-using-chained-if/page.cue new file mode 100644 index 000000000..91bbfaee4 --- /dev/null +++ b/content/docs/howto/combine-conditions-using-chained-if/page.cue @@ -0,0 +1,3 @@ +package site + +content: docs: howto: "combine-conditions-using-chained-if": page: _ diff --git a/hugo/content/en/docs/howto/combine-conditions-using-chained-if/index.md b/hugo/content/en/docs/howto/combine-conditions-using-chained-if/index.md new file mode 100644 index 000000000..0da4252b2 --- /dev/null +++ b/hugo/content/en/docs/howto/combine-conditions-using-chained-if/index.md @@ -0,0 +1,73 @@ +--- +title: 'Combining conditions using chained "if" clauses' +authors: [jpluscplusm] +toc_hide: true +--- + +The CUE language allows conditional tests to decide if certain fields are +included in data. It provides different ways to combine conditions, which +*usually* produce equivalent results. + +However, in some situations a specific mechanism must be used to combine +conditions by chaining them together using multiple `if` clauses. This is +because the alternative (CUE's `&&` operator) doesn't prematurely stop (or +"short circuit") a failing compound condition that includes it. + +This guide demonstrates some situations that require the use of chained `if` +clauses. + +{{< code-tabs >}} +{{< code-tab name="file.cue" language="cue" area="top-left" >}} +package example + +A: "foo" +B: 42 + +// Either of these 2 methods of combining +// conditions can be used if a type check +// is not required: +if A == "foo" && B < 100 {C: true} +if A == "foo" if B < 100 {C: true} + +// When a type check is required, chained "if" +// clauses must be used: +if (B & int) != _|_ if B < 100 {D: true} + +// This would fail if uncommented because the type +// check does not stop the inequality being tested: +// if (A & int) != _|_ && A < 100 {D: true} + +#X: { + a!: string + b!: int +} +X: c: 4.2 + +// If this type check is required it must be +// combined with the inequality test using a +// chained "if" clause: +if (X & #X) != _|_ if X.b < 100 {E: true} + +// This would cause an evaluation failure if +// uncommented because X.b does not exist: +// if (X & #X) != _|_ && X.b < 100 {E: true} +{{< /code-tab >}} +{{< code-tab name="TERMINAL" language="" area="top-right" type="terminal" codetocopy="Y3VlIGV4cG9ydA==" >}} +$ cue export +{ + "A": "foo", + "B": 42, + "C": true, + "D": true, + "X": { + "c": 4.2 + } +} +{{< /code-tab >}} +{{< /code-tabs >}} + +## Related content + +- {{< linkto/related/tour "expressions/conditional" >}} +- {{< linkto/related/tour "expressions/listcomp" >}} +- {{< linkto/related/tour "expressions/fieldcomp" >}}