concept: import cuelang.org/docs/usecases/

This change imports each of the 6 pages under
https://cuelang.org/docs/usecases/ as its own Concept Guide, as of
commit 4b2c488.

Whilst the words on most of the use case pages are valuable and worth
preserving (perhaps with the slight exception of the "Scripting" page!),
they're not really "Concept Guides". This is the closest category that
fits their content right now, but is a sign that their content should
probably be teased apart and made into more Diataxis-friendly pieces of
documentation, over time. For now, let's import them here.

Each file was only changed sufficiently to allow alpha's preprocessor
and hugo version to parse the source successfully. A diff of each can be
generated with these commands:

    git diff 4b2c488:content/en/docs/usecases/generate.md content/docs/concept/code-generation-and-extraction-use-case/en.md
    git diff 4b2c488:content/en/docs/usecases/configuration.md content/docs/concept/configuration-use-case/en.md
    git diff 4b2c488:content/en/docs/usecases/validation.md content/docs/concept/data-validation-use-case/en.md
    git diff 4b2c488:content/en/docs/usecases/query.md content/docs/concept/querying-use-case/en.md
    git diff 4b2c488:content/en/docs/usecases/datadef.md content/docs/concept/schema-definition-use-case/en.md
    git diff 4b2c488:content/en/docs/usecases/scripting.md content/docs/concept/scripting-use-case/en.md

During import, cue-lang/cue#2666 was opened to request the preprocessor
change how it formats multi-document YAML files.

Closes cue-lang/docs-and-content#23

Preview-Path: /docs/concept/code-generation-and-extraction-use-case/
Preview-Path: /docs/concept/configuration-use-case/
Preview-Path: /docs/concept/data-validation-use-case/
Preview-Path: /docs/concept/querying-use-case/
Preview-Path: /docs/concept/schema-definition-use-case/
Preview-Path: /docs/concept/scripting-use-case/
Signed-off-by: Jonathan Matthews <[email protected]>
Change-Id: Iabf035fa1eaed25c663811f9ab1a3208d3c2dac9
Dispatch-Trailer: {"type":"trybot","CL":1171276,"patchset":7,"ref":"refs/changes/76/1171276/7","targetBranch":"alpha"}

content/docs/concept/code-generation-and-extraction-use-case/en.md

@@ -0,0 +1,118 @@
+---
+title: "Code Generation and Extraction use case"
+description: "Converting CUE constraints to and from definitions in other languages"
+toc_hide: true
+---
+
+Code generation and extraction is a broad topic and, for instance, overlaps
+with the topics discussed in
+[Schema Definition]({{< relref "/docs/concept/schema-definition-use-case" >}}) and
+[Go](/docs/integrations/go).
+<!-- TODO: update link after integration pages are imported -->
+
+In this section we emphasize the role of CUE in a code-generation pipeline,
+that is using CUE as an interlingua for the extraction from and the
+generation to multiple sources.
+
+
+## Core issues addressed by CUE
+
+### Extract data definition from existing sources
+
+When one identifies the need to define interchangeable data schema
+one usually already has some code base to deal with.
+
+CUE can currently extract definitions from:
+
+<!-- TODO: update link after integration pages are imported -->
+- [Go code](/docs/integrations/go#extract-cue-from-go)
+- Protobuf definitions.
+
+Moreover, CUE can combine and reduce the constraints from various sources
+and report if there are any inconsistencies.
+
+
+### Enhance existing standards
+
+CUE also allows annotating existing sources with CUE expressions.
+This allows one to keep using existing sources or allow for a smoother
+transition into taking a CUE-centric approach.
+For instance, a project might be quite reliant on protobuf definitions
+as the source of truth of at least one aspect of schema definition.
+For this particular case, CUE allows annotating Protobuf field declarations
+with CUE expressions using field options.
+
+{{{with code "en" "proto-1"}}}
+-- in.proto --
+message Server {
+  int32 port = 1 [(cue.val) = ">5000 & <10_000"];
+}
+{{{end}}}
+
+A similar approach is supported for Go:
+
+{{{with code "en" "go"}}}
+-- in.go --
+type Sum struct {
+    A int `cue:"c-b" json:"a,omitempty"`
+    B int `cue:"c-a" json:"b,omitempty"`
+    C int `cue:"a+b" json:"c,omitempty"`
+}
+{{{end}}}
+
+In both cases, the constraints will be included the extraction to CUE.
+In the case of Go, the constraints specified in the field tags can also
+be used to validate Go structs directly.
+
+
+### Convert CUE to other standards
+
+Currently, CUE supports converting CUE to OpenAPI and Go, although it is
+certainly not limited to these cases.
+
+
+## Comparisons
+
+### CEL
+
+The [Common Expression Language](https://github.com/google/cel-spec),
+or CEL, defines a simple expression language that can be used as a
+standardization of constraints.
+It focuses on simplicity, speed, termination guarantees and
+being able run embedded in applications.
+
+Unification of basic typed-feature structures has pseudo-linear run
+time complexity.
+The addition of comprehensions make the operation polynomial.
+Not disallowing recursion would make CUE Turing complete.
+The addition of sum types in CUE make certain operations NP-complete.
+The NP-completeness manifests itself only when reasoning over incomplete types.
+Trying to optimize a CEL expression would generally suffer from the same issue.
+The same problem does not exist when applying CUE to concrete values.
+
+That said, CUE is currently not optimized for embedded running.
+Currently, generated Go stubs embed a CUE interpreter into the code.
+These stubs are compatible with a mode where CUE generates native code,
+which would give it similar characteristics.
+
+CEL allows embedded implementation to add arbitrary functions.
+CUE does not.
+CUE keeps tight control over the pureness or hermeticity of evaluation
+and to ensure the properties of the value lattice are not broken.
+It would be possible, however, to provide the ability to add custom functions
+for restricted to concrete values.
+
+
+### Protoc-gen-validate (PGV)
+
+PGV also allows annotating Protobuf fields with validation code,
+with implementations for Go and Java and an experimental versions for C++
+as of this writing.
+
+
+{{{with code "en" "proto-2"}}}
+-- in.proto --
+message Server {
+  int32 port = 1 [(validate.rules).int32 = { gte: 5000, lte: 10000 }];
+}
+{{{end}}}

content/docs/concept/code-generation-and-extraction-use-case/gen_cache.cue

@@ -0,0 +1,20 @@
+package site
+{
+	content: {
+		docs: {
+			concept: {
+				"code-generation-and-extraction-use-case": {
+					page: {
+						cache: {
+							code: {
+								"proto-1": "WJqxJBmZxawhD1zanSswGQOV/CRvJ/Q8MPj5XjlN0D8="
+								go:        "i710rUh7cCg46orXaxdFaeJgm2G32l6Mwj3a2GfQTrc="
+								"proto-2": "hftRHuNwzV8FyU3H4oto4/ealvn4RCAJHN7xdxPX0Po="
+							}
+						}
+					}
+				}
+			}
+		}
+	}
+}

content/docs/concept/code-generation-and-extraction-use-case/page.cue

@@ -0,0 +1,3 @@
+package site
+
+content: docs: concept: "code-generation-and-extraction-use-case": {}