Postfix Aliases

[mpvl]

📋 Proposal Details:

• File: designs/language/4014-aliases-v2.md
• Status: Draft

---

Proposal: Postfix Aliases

Postfix Aliases Proposal Summary

This proposal introduces a new syntax for aliases in CUE that addresses several issues with the current system. The main problem is that CUE currently uses the = symbol for aliases across seven different kinds in five syntactic positions, creating unnecessary complexity. This conflicts with how = is used for assignment in other languages (Dhall, Nickel, PKL, KCL) and even within CUE itself for let statements. Additionally, the current syntax encourages field aliases when value aliases would be more appropriate in most cases.

The proposed solution replaces all current alias forms with a single postfix notation using the ~ symbol. Instead of F=label: value, the new syntax would be label~X: value. To access different aspects of an alias, three new builtins are introduced: keyOf(X) for the field name, refOf(X) for the field reference (similar to current field aliases), and valueOf(X) for the field's value. Using X directly is shorthand for valueOf(X). The proposal also introduces a self keyword to refer to the current scope, addressing a previous limitation where the package root couldn't be referenced.

The benefits of this change are significant. The syntax becomes more regular and consistent, with aliases appearing in only one position instead of three. The ~ symbol avoids the confusion with assignment semantics and integrates better with potential future features like dot notation (a~A.b~B: {...}) and query syntax. This is particularly valuable for complex comprehensions where aliases can be bound within query paths, making the code more readable. For example: members.*~M.children.*~C.address~A clearly shows the path traversal with bound aliases at each level.

The transition strategy involves using cue fmt and cue fix to automatically rewrite existing code, with both syntaxes supported during a transition period. This allows the CUE team to introduce the new syntax before making final decisions about repurposing the freed = symbol for other features. The proposal carefully considers alternatives and edge cases, such as list element aliases, while maintaining backward compatibility through the module version system.

[Summary generated by Claude AI]

---

Full Proposal

The complete proposal with all technical details, examples, and implementation notes can be found in the proposal document.

How to Comment

Please provide feedback on this proposal:

• For general discussion: Comment in this GitHub discussion
• For detailed code review: Comment on the Gerrit CL (link will be added when available)

Last updated: 2025-08-05 15:30:40 UTC

[infogulch]

Overall this design seems simpler and more consistent.

This proposal provides a syntax for labeling keys, and eliminates labeling values altogether, with this functionality substituted by the valueOf function (which is the default result of using the label). This privileges structs over lists which have no explicit keys. The only issue I might be concerned about is that referencing values in nested lists would be a bit awkward. If I understand correctly it would look like this:

a~X: [[1, 2, [3, 4]], 5]
// want to reference the value 4
b: X.0.2.1

To be fair this scenario probably doesn't occur very often.

---

We also propose introducing the self keyword to refer to the current scope (the value to the right of the innermost colon :).

I like self. This description seems to exclude the package root though.

[infogulch]

[aliases are] only visible within the scope in which they are declared

I would have thought that the "scope" is the object where the key is a member, not the value.

I made a simple example to see if I understand:

{
  // X is not in scope
  foo~X: { 
    // X is in scope
    bar: 123
    baz: X.bar+1 // case 1: valid
  }
  // X is not in scope
  bop: X.bar+2 // case 2: invalid
}

boo: X.bar+3 // case 3: definitely invalid

Is this right?

IMO it wouldn't make sense for case 3 to be valid, but I feel like this feature would be way more useful if case 2 was valid. Maybe we should consider this to be a different feature ("anchors"), but I don't really get why there's a distinction. 🤷

Anyway I like the anchor syntax; but maybe we would want to stick with the postfix? (personally I'm still undecided):

a: [[1, 2, [3, 4~X]], 5]
b: X

Maybe we want to consider the design space of anchors while we're nailing down aliases. Or maybe we're getting sidetracked and we should continue the discussion of anchors elsewhere. 😄

[mpvl]

Just as with current aliases, case 2 would be valid, case 3 would, indeed, not be, as it stands.

[mpvl]

I think anchors are indeed related and thus discussing it here is appropriate. But it does seem like it could be a followup proposal. It depends a bit on whether people really need it.

Another avenue for lists, btw, would be to allow let declarations in lists as well.

a: [ let X = 4, X, X, X ]

Not quite the same, but might be sufficient.

[infogulch]

case 2 would be valid, case 3 would [be invalid]

Ah thank you for clarifying, I had misunderstood. This form of the proposal seems reasonable to me again. :)

And now I realize why my original example { a: [[1, 2, [3, ~X 4]], 5], b: X} actually requires some kind of anchors feature, because it's naming a value deep in a nested object and 'dereferencing' in an outer scope. Defining the object in one line obscured the fact that it is quite nested.

Allowing let declarations in lists seems like a good solution.

[seh]

Per #2194, I find myself writing let declarations in lists regularly, just as your example shows here, Marcel, assuming mistakenly that they're allowed. If I recall correctly, the specification did promise them at some point, but we were still waiting on an implementation to come.

[mpvl]

One suggestion that came up is that with the foo~(K,V): x form and having self, there is perhaps no need for the additional builtins. V would be refOf form. To get valueOf, one would use self

foo: {
    let X = self
    
    b: X + c.1
}

In practice, the difference between valueOf and refOf does not make much of a difference and emphasizing this distinction may cause more confusion than necessary.

[jpluscplusm]

How would this new syntax interact with interpolating values into the built-in function error()'s string argument?

The following (unpublished!) update to a cuelang.org guide is being held back from being published both because we consider it to be a bit confusing, but also because its aliasing seems to lead to a contradiction (tracked in #4038). How would it be represented using the new alias syntax?

! exec cue vet example.cue
cmp stderr out
-- example.cue --
// DO NOT use this as an example of idiomatic (or even correct) CUE!
#Even: X=(2 * div(X, 2)) | error("\(X) is not even")
#Odd:  X=(1 + 2*div(X, 2)) | error("\(X) is not odd")

even: [...#Even]
even: [42, 13, 0]

odd: [...#Odd]
odd: [42, 13, 0]
-- out --
even.1: 13 is not even:
    ./example.cue:2:28
odd.0: 42 is not odd:
    ./example.cue:3:30
odd.2: 0 is not odd:
    ./example.cue:3:30

[mpvl]

I would say this is an evaluator bug, and not so much an issue with aliases per se.

But nonetheless a good question. In the first iteration of the new alias proposal we suggested that X in foo~X: bar use valueOf, which would be the right thing to use. Now we say there is only refOf. With the latest iteration of the new proposal, you would have to use self.

The equalent of #Even above is then

#Even: {2 * div(self, 2)} | error("\(self) is not even")

The curly braces are needed here to scope self to the value itself.

[jpluscplusm]

Line 144 of the proposal uses Config~data on the RHS of a field. I can't see this form demonstrated elsewhere in the proposal, and I didn't spot that kind of use being specified - in my initial read through, at least. Is it intended, and what does it represent?

[mpvl]

That's a "typo". It should just be Config.

[myitcv]

I might well be missing something here, but do the proposed scope semantics of self not break the property that X == {X} for all X?

[myitcv]

For reference, this question arises from my inaccurate quoting of this part of the spec:

The result of { A } is A for any A (including definitions).

[mpvl]

That is an interesting question and observation. One could argue either way, but I think the lexical scoping of self can be seen orthogonally from that requirement. So I don't see this as a big issue.

Having said that, @cuematthew pointed out we should probably remove the {X} is A from the spec. I tend to agree. This rule was mostly intended as a guideline to understand closedness, and how closedness percolates up in structure. Also scalars, perhaps, but mostly that. With the new #A... semantics this is far less relevant, as there is no interaction anymore with the outer scopes in this case.

[myitcv]

FYI - the proposal contains an unfinished sentence "To bind with"

[mpvl]

Another modification: scoping rules refinement:

• self also gets scoped by [], not just {}
• implicit scopes count: so a: b: self.c refers to a.c, not c at the top level.

[mpvl]

In the latter case, we should probably have the formatter rewrite a: b: self.c to a: { b: self.c }