doc: Effective CUE

[cueckoo]

Originally opened by @myitcv in https://github.com/cuelang/cue/issues/1013

Is your feature request related to a problem? Please describe.

The tutorials provide an excellent introduction to CUE, the language and its tooling.

The CUE spec, provides a reference manual for the language.

But there is a rather large gap in between these two extremes.

As has been discussed before, whilst we should aim for creating more tutorials, interactive guides and introductory material, it feels like there is a place for "Effective CUE", much like "Effective Go" to answer the following question:

How do I write clear, idiomatic CUE?

Describe the solution you'd like

To add "Effective CUE" as part of https://cuelang.org/, version along with the CUE language spec.

Describe alternatives you've considered

There is not really anything else that fills this gap at the moment. Or rather there are very scattered attempts in the form of answers to specific questions on GitHub Discussions, Slack etc. It feels like it will be more effective to pull this together in a central effort.

[Kinrany]

May be relevant: https://documentation.divio.com/

[myitcv]

Discussion on naming conventions: https://github.com/cue-lang/cue/discussions/972

[rudifa]

Almost 2 years later, there is still a rather large gap in between those two extremes.

IMO, How-to Guides (problem->solution) would be most welcome, both for creation and application of schemata, and for writing go code that uses the CUE API.

Is there anyone knowledgeable who would like to start a skeleton doc project?

[verdverm]

@rudifa have you seen https://cuetorials.com? We have Go API examples, you are welcome to contribute anything there.

The CUE Team is working on a new version of the docs with an updated language guide: https://alpha.cuelang.org/

[rudifa]

@verdverm Yes, I have seen cuetorials.com, and no, I have not worked through them yet, so it is too early (in my CUE discovery) for me to complain.

[rudifa]

@rudifa navigue à vue dans les Cuetorials

Working in Loading CUE with simple.go and hello.cue , I was surprised to see that changing from

        entrypoints := []string{"hello.cue"}`

	// Load Cue files into Cue build.Instances slice
	// the second arg is a configuration object, we'll see this later
	bis := load.Instances(entrypoints, nil)

to

       entrypoints := []string{}
...

makes no difference, the program still finds, reads and evaluates hello.cue.

But why? Cuemagic?

later

After a some of experimenting, reading the Instances docs and looking up its code it became clear that the call to Instances(..., nil) uses a default Config{}, which has Dir == "", and the doc says `If Dir is empty, the current directory is used.

However, it does not say that in that case Instances picks up the ./*cue files, probably depending on what package these files declare.

1. This tutorial page would be a good place to mention and explain such hidden effects.
2. It would also be a good place for an extended example, showing how to unify .cue with .json, .yaml, e.t.c. files, or a link to another, more elaborate example.
3. If I wanted to post an Issue on this subject, where would I post it?

@verdverm This example illustrates the existence of the gap that @cueckoo wrote about.

EDIT link to another, more elaborate example: I'd like to see an example showing how to parse a json string into a cue Value and then validate it against a Value built from a cue string.

Is there anywhere in the Cueverse such an example, or should I just read the code starting from the cue/cmd?

[verdverm]

If you'd like to see or add content to Cuetorials, you can do so at: https://github.com/hofstadter-io/cuetorials.com

There are links at the bottom of every page for convenience

[rudifa]

@verdverm Thank you for the pointers. If and when I come up with something (IMO) useful, I will post it for review.

Beyond the showing how to parse a json string into a cue Value and then validate it against a Value built from a cue string problem, I'd like also to find how to export only selected (matching explicitly defined) fields. Is this what the planned query project should do?

[verdverm]

@rudifa If you want to just spam thoughts into our issues on Cuetorials, feel free!

I'm sure I've had many of the same ones and just forgot to write them down 🤣

[rudifa]

@verdverm Thank you for the invitation.

[the-nurk]

what is the pattern for automatic re-writing exactly? how can one start with cuelang code, indicate fields at any static evaluation depth that need to have their names (left-hand-side of fields, definitions, hidden, hidden defs) changed and then output that exact same cuelang syntax code (in exact cue fmt form, ready to execute again) with all references changed to match the new lhs naming scheme? this would apply across an entire package or module depending on which names were changed?

lsp and other manually automated supports seem to be the only way. i.e. search and replace or architect all left hand sides to be templated, which likely ruins performance. as such, i'm assuming this is something that is best done via go and is basically an AST transformation of some kind. cue doesn't re-write its syntax out the box it seems, just other syntaxes and data types. i'm guessing this is related to bootstrapping cue, which i would love.

but maybe i just missed something crucial.

this would make coding so much faster in cuelang. if i could use cue to generate an exact copy of an entire module or package, but with fields (definitions and hidden definitions) changed, that would be a phenomenal starting spot for a new module that keeps most of the same stuff while not having to do manual boilerplate reduction and validation. just copy on write an entire logic graph/spec and make some path changes. query proposal will provide right hand side re-write changes at arbitrary depth easy.