howto: commented CUE for functions in the standard library

[jpluscplusm]

Let's add a commented CUE how-to guide for any functions in the standard library that would benefit from a clear example of the function.

For each standard library <package>.<function> that would benefit:

• add a commented CUE under /docs/howto/use-the-standard-<package>-<function>-function-to-<task>
• choose the <task> which demonstrates the most common use case of the function

For each <package>:

• add a glossary entry for the package
• test out including links to the function-level how-to guides in the package's glossary entry's mini-index

Add a tag for these pages. builtin? stdlib?

[jpluscplusm]

Audit of which functions have examples on their godoc page: https://alpha.cuelang.org/play/?id=44iZ2XN1Bxd#w=function&i=cue&f=eval&o=cue

inline copy of data, in case the backend service loses it

```CUE // go docs contain an inline CUE example of function use? // "go" == there's an example, but it's in Go, not CUE. #Function: bool | #Go #Go: "go" #Package: { [string]: #Function } packages: [goDocURL=string]: #Package packages: { // crypto "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/ed25519": { Valid: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/hmac": { Sign: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/md5": { Sum: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/sha1": { Sum: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/sha256": { Sum224: false Sum256: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/crypto/sha512": { Sum384: false Sum512: false Sum512_224: false Sum512_256: false } // encoding "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/encoding/base64": { Decode: false DecodedLen: false Encode: false EncodedLen: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/encoding/csv": { Decode: false Encode: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/encoding/hex": { Decode: false DecodedLen: false Dump: false Encode: false EncodedLen: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/encoding/json": { Compact: false HTMLEscape: false Indent: false Marshal: false MarshalStream: false Unmarshal: false UnmarshalStream: false Valid: false Validate: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/encoding/yaml": { Marshal: false MarshalStream: false Unmarshal: false UnmarshalStream: false Validate: false ValidatePartial: false } // html "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/html": { Escape: false Unescape: false } // list "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/list": { Avg: false Concat: true Contains: false Drop: true FlattenN: true IsSorted: false IsSortedStrings: false Max: false MaxItems: false Min: false MinItems: false Product: false Range: true Repeat: true Slice: true Sort: true SortStable: false SortStrings: false Sum: false Take: true UniqueItems: false } // mathS "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/math": { Abs: false Acos: false Acosh: false Asin: false Asinh: false Atan: false Atan2: false Atanh: false Cbrt: false Ceil: false Copysign: false Cos: false Cosh: false Dim: false Erf: false Erfc: false Erfcinv: false Erfinv: false Exp: false Exp2: false Expm1: false Floor: false Gamma: false Hypot: false Ilogb: false J0: false J1: false Jacobi: false Jn: false Ldexp: false Log: false Log10: false Log1p: false Log2: false Logb: false Mod: false MultipleOf: false Pow: false Pow10: false Remainder: false Round: false RoundToEven: false Signbit: false Sin: false Sinh: false Sqrt: false Tan: false Tanh: false Trunc: false Y0: false Y1: false Yn: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/math/bits": { And: false At: false Clear: false Len: false Lsh: false OnesCount: false Or: false Rsh: false Set: false Xor: false } // net "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/net": { FQDN: false GlobalUnicastIP: false IP: false IPCIDR: false IPString: false IPv4: false InterfaceLocalMulticastIP: false JoinHostPort: false LinkLocalMulticastIP: false LinkLocalUnicastIP: false LoopbackIP: false MulticastIP: false ParseIP: false PathEscape: false PathUnescape: false QueryEscape: false QueryUnescape: false SplitHostPort: false ToIP16: false ToIP4: false UnspecifiedIP: false } // path "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/path": { Base: #Go Clean: false Dir: #Go Ext: #Go FromSlash: false IsAbs: #Go Join: #Go Match: #Go Rel: #Go Resolve: false Split: #Go SplitList: #Go ToSlash: false VolumeName: false } // regexp "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/regexp": { Find: false FindAll: false FindAllNamedSubmatch: false FindAllSubmatch: false FindNamedSubmatch: true FindSubmatch: false Match: false QuoteMeta: false ReplaceAll: false ReplaceAllLiteral: false Valid: false } // strconv "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/strconv": { Atoi: false FormatBool: false FormatFloat: false FormatInt: false FormatUint: false IsGraphic: false IsPrint: false ParseBool: false ParseComplex: false ParseFloat: false ParseInt: false ParseUint: false Quote: false QuoteRune: false QuoteRuneToASCII: false QuoteRuneToGraphic: false QuoteToASCII: false QuoteToGraphic: false Unquote: false } // strings "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/strings": { ByteAt: false ByteSlice: false Compare: false Contains: false ContainsAny: false Count: false Fields: false HasPrefix: false HasSuffix: false Index: false IndexAny: false Join: false LastIndex: false LastIndexAny: false MaxRunes: false MinRunes: false Repeat: false Replace: false Runes: false SliceRunes: false Split: false SplitAfter: false SplitAfterN: false SplitN: false ToCamel: false ToLower: false ToTitle: false ToUpper: false Trim: false TrimLeft: false TrimPrefix: false TrimRight: false TrimSpace: false TrimSuffix: false } // struct "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/struct": { MaxFields: false MinFields: false } // text "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/text/tabwriter": { Write: false } "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/text/template": { Execute: false HTMLEscape: false JSEscape: false } // time "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/time": { Duration: false Format: false FormatDuration: false FormatString: false Parse: false ParseDuration: false Time: false Unix: false "Parts.Split": false } // uuid "https://pkg.go.dev/cuelang.org/go@v0.7.0/pkg/uuid": { FromInt: true MD5: false Parse: false SHA1: false ToInt: false ToString: false URN: false Valid: false Variant: false Version: false } } ```

[jpluscplusm]

My suggestions for which functions we could include in the initial round of alpha docs, created in line with:

• how often I feel I've seen the function come up in Slack answers to user questions
• how often I've personally gone hunting for in the docs for examples, and not found one that suits my purpose
• how non-trivial the function's signature or common use case is
  • i.e. I've /generally/ avoided things like strings.To* and strings.Trim*, where I feel the potential for user confusion is pretty low

I've included list.* as IMHO the majority of its functions disproportionately deserve a good example given list's unique place as a non-primitive type that doesn't have the advantages of structs' (easy!) mergeability. There are probably individual list functions I'll discover that don't merit a stand alone example right now - I'll pass lightly over those without trying to craft the perfect guide.

• encoding/
  • base64.Decode+base64.Encode: https://cuelang.org/cl/1174178
  • csv.Decode+csv.Encode: https://cuelang.org/cl/1174183
  • json.Compact+json.Indent: https://cuelang.org/cl/1175999
  • json.Marshal+yaml.Marshal: I'm stuck for ideas on what scenario to use to demonstrate these, as displaying any output variable that might contain their responses might as well be performed with cue export --out json/yaml.
  • In other words, I currently can't figure out the "task" at the end of the page title that starts "How to use the built-in function encoding/json.Marshal to ...", without the answer being "just use cue export --out json", instead of "use json.Marshal".
  • json.Validate+yaml.Validate+yaml.ValidatePartial: https://cuelang.org/cl/1176034
• list/
  • Avg+Max+Min+Sum: https://cuelang.org/cl/1174381
  • Contains: https://cuelang.org/cl/1174384
  • MaxItems+MinItems: https://cuelang.org/cl/1174389
  • SortStrings+IsSortedStrings+Sort+IsSorted: https://cuelang.org/cl/1174391
  • FlattenN: https://cuelang.org/cl/1174439
  • UniqueItems: https://cuelang.org/cl/1174648
  • Concat: https://cuelang.org/cl/1174726
  • Take+Drop+Slice: Unsure if it's worth including these, given their similarity to the core language foo[x:y] syntax. No-one's disagreed in Slack yet, either.
  • Range: The authoritative stdlib docs seem sufficient.
  • Repeat: The authoritative stdlib docs seem sufficient.
• net/
  • IP+IPv4+IPCIDR: https://cuelang.org/cl/1174202
  • ParseIP+IPString: https://cuelang.org/cl/1174210
  • FQDN: not documenting this for now, given that #2431 causes it to accept (pretty much) any FQDN - even invalid ones.
• path/
  • Base+Dir+Ext: https://cuelang.org/cl/1174212
  • FromSlash+ToSlash: not including these for now, as their "simple" behaviours as text modifiers is pretty easy to understand and the stdlib docs are self-explanatory. However, one of their (main?) use cases is inside cue cmd tooling, where system variable injection allows a definitive path to be kept in the CUE file and then adapted, on the fly, for whichever OS the command finds itself running on. Demonstrating /this/ needs some thought; parking this pair of functions for now.
  • Join: https://cuelang.org/cl/1174728
• regexp/
  • ReplaceAll+ReplaceAllLiteral: https://cuelang.org/cl/1174750
  • Match: Pausing on this, as closer inspection suggests that this function is close match to the core language syntax of foo: =~"^a reg[ex]$", but with the disadvantage of not working as a field validator.
• strconv/
  • Atoi: https://cuelang.org/cl/1174211
• strings/
  • Contains+HasPrefix+HasSuffix: https://cuelang.org/cl/1174729
  • Join: Pausing as per Split, below.
  • Replace: https://cuelang.org/cl/1174748
  • Split: Pausing on this to consider if it should be demonstrated alongside Join, or alongside all the Split* variants, or both.
• text/
  • template.Execute: https://cuelang.org/cl/1174775

[jpluscplusm]

Closed as of https://github.com/cue-lang/cuelang.org/commit/0d7f4b28d07cc8617be2209c7c6d767cae8cb9bb.

We'll see how folks get on with the currently documented function examples, and address any gaps on an ongoing basis.