# vs _# and capitalization

[extemporalgenome]

Reading through the tutorial and the spec, I see both # and _# offered as possible prefixes for definitions but no definitive guidance on when to use one as opposed to the other. When should we use _# rather than just #.

Furthermore, it appears that definitions and aliases can all be spelled starting with either uppercase or lowercase letters. Under which circumstances should one letter-casing be preferred over another?

I'm happy to submit a docs PR with whatever I learn here.

[mpvl]

This is a relatively new thing and the documentation needs to be updates. For details see https://cuelang.org/docs/references/spec/#definitions-and-hidden-fields

But in short, exported definitions (those starting with #) are visible outside your package, whereas hidden ones are not. If you don't intend to share a package, then it doesn't matter much.

There is one case where this is important though. Consider

import "acme.com/foo"

a: foo.#Def & {
    #foo: {...}
   a: #foo
   b: #foo
}

Adding a definition to a struct is currently allowed in CUE, even if foo.#Def doesn't define it. This will be disallowed in v0.4.0. See #543 for more details and discussion. The solution then is to write:

import "acme.com/foo"

a: foo.#Def & {
    _#foo: {...}
   a: _#foo
   b: _#foo
}

Hidden fields, including definitions, always live in a different namespace per package (much like Go unexpected fields) and thus are safe to add.

[extemporalgenome]

I see, thanks! Couldn't the v0.4.0 solution be to write:

import "acme.com/foo"

a: foo.#Def & {
   _foo: {...}
   a: _foo
   b: _foo
}

If this is effectively equivalent, since hidden non-definition fields are excluded from output, then there might not be any reason to allow the specification of even hidden definitions within a struct.

[mpvl]

It depends on whether you want _foo to be "closed" or not. So it may still be necessary to use a hidden definition there.

[mpvl]

Also, hidden definitions have the same properties as regular hidden fields in that their namespace is local to a package. So there would also be no benefit to disallowing them here.

[mpvl]

As for casing, the original CUE spec used casing for determine whether to export something or not, similar to Go.

However, although this works well with Go, it doesn't work well for CUE as it may be used in conjunction with data with arbitrary casing. The convention is to use camel case for JSON, but in reality it is all over the place. So we introduced the use of # instead. Note that the # is part of the identifier, so you get a similar level of clarity and a similar feel as the casing approach in Go. It just takes some getting used to.

As for a recommendation, normally I would say using # + upper case, but it really depends in which context you use CUE.

[cueckoo]

This discussion has been migrated to cue-lang/cue#686.

For more details about CUE's migration to a new home, please see cue-lang/cue#1078.