[WIP] 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.

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.

This is WIP because I can't get the preprocessor to stop trying to
execute a `cue export` whilst checking
content/docs/concept/data-validation-use-case/en.md, instead of obeying
the txtar commented command; which fails because the real command is
marked as failing where the (seemingly) implicit `export` isn't.

**Any insight into the following behaviour and error is much appreciated!**

    $ _scripts/runPreprocessor.bash execute
    cuelang.org/content/docs/concept/data-validation-use-case/en.md:31:8: failed to run /home/jonathan/bin/docker run --rm -i -e USER_UID=1000 -e USER_GID=1000 preprocessor:6737cccc9f796ca2aee8f8d2bb769c3cc3d28646cede57309f24310407b51610
    -- cue export --out=yaml yaml: -: exit status 1
    	max: conflicting values 5 and 10:
    	    -:2:7
    	    -:5:7
    	min: conflicting values 10 and 5:
    	    -:1:7
    	    -:4:7

    cuelang.org/content/docs/concept/data-validation-use-case/en.md:31:8: failed to format files: in error
    terminating because of errors

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

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

@@ -0,0 +1,115 @@
+---
+title: "Code Generation and Extraction use case"
+description: "Converting CUE constraints to and from definitions in other languages"
+---
+
+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 other docs 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:
+
+- [Go code](/docs/integrations/go#extract-cue-from-go) <!-- TODO: update link after other docs are imported -->
+- 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": {}