Proposal: functions in CUE

[mpvl]

📋 Proposal Details:

• File: designs/language/4484-functions.md
• Status: Draft

---

Proposal: functions in CUE

This proposal adds first-class functions to CUE. Today, users often imitate functions with structs, for example (sum & {a: 1, b: 2}).out. That pattern is verbose. It has no positional calling and no arity checking, and it doesn't separate parameters and results from ordinary fields. When something goes wrong, error messages point at struct internals instead of at a call. CUE also already has functions in the standard library, but their signatures can't be written in CUE itself. So builtins can't be documented precisely, higher-order parameters can't be typed, and there is no way to check that a user-supplied function matches an expected interface.

The solution is a function literal: func, parameters in parentheses, an optional result constraint after ->, and a body after :. You can call a function by position, by label, or both, with positional arguments first:

@experiment(functions)

Sum: func(a: int, b: int) -> int: a + b
p: Sum(1, 2)        // 3
m: Sum(1, b: 2)     // 3
add: func(a: int, b: int = 10) -> int: a + b
d: add(1)           // 11

Parameters come in five forms, ranging from position-only to name-only:

• Anonymous (int): supplied by position only.
• Positional-only with an alias (_~x: int): supplied by position; the body calls it x, which can be renamed freely.
• Named (a: int): callable both ways.
• Required (a!: int): supplied by label only.
• Optional (a?: int): may be omitted; supplied by label only.

A default is declared explicitly with =. It applies only when the argument is omitted, so an argument that carries its own disjunction default reaches the body unchanged. This fixes a real flaw in an earlier design that reused CUE's * defaults: the caller's default and the parameter's default would cancel each other out.

A literal without a body is a function type. Unifying a function type with a function value tightens the value, and the type's constraints are checked on every call. A trailing ... makes a type open, so it accepts extra parameters. Because constraints are checked per call rather than when types are unified, you can bind an idealized signature like func(int) -> int to a stricter implementation, such as one limited to 64 bits. Function types can appear anywhere a value can, so higher-order functions need nothing extra. A call ending in ..., such as add(1, ...), is a partial application that returns a function over the remaining parameters. Recursion, direct or mutual, is reported as a structural cycle, so CUE stays non-Turing-complete. Nested and repeated calls are still fine. Function values are opaque: a function unifies with itself and with function types, and with nothing else.

Conceptually, each call builds a fresh struct of parameter values, unifies the arguments with their constraints, and returns the body unified with the result constraint. This lets users reason about functions with the lattice they already know. The experimental evaluator runs functions natively and memoizes results per call site, which keeps deeply nested calls linear in cost. The proposal also defines backwards compatibility for evolving signatures. A change is compatible if every call the old signature accepted still binds and type-checks (inputs may only widen) and every new result is still an instance of the old result type (results may only narrow). Names and positions are one-way commitments: you can add a way to call a parameter, for example making a name-only parameter positional, but taking one away breaks callers. That is the reverse of Python's situation. A table in the proposal classifies common changes, such as adding a defaulted parameter (compatible) or renaming a named parameter (breaking).

The feature is enabled per file with @experiment(functions). A file without it parses exactly as before: func stays an ordinary identifier there, and -> and labeled arguments are gated. Modules that use functions can therefore depend on older modules and be depended on by them. When the experiment graduates to a language version, cue fix can drop the attribute and, if func becomes fully reserved, quote existing fields named func. Several things are left out on purpose. Foreign function interfaces, purity, and side effects are a main motivation but go to a follow-up proposal. Variadic arguments are passed as lists, as builtins already do. References between parameters are reserved as an error so that dependent parameter types remain possible later. Overloading through disjunctions of functions is also deferred.

[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 GitHub discussion.

[infogulch]

Can you define constraints between parameters? Say, a func(a, b) where b has to be the name of a key in a's object.

[mpvl]

I think you are referring to "dependent types". This is deliberately out of scope for now, but is considered as a possible future extension.

[imax9000]

What's the story on error propagation from the function body?

The use cases for dependent types may be covered by explicit checks inside the body:

f: func(a: _, b: _) -> _ : {
  _fieldNames: [for _name, _val in a {_name}]
  _assert1: [
    if list.Contains(_fieldNames, b) {true},
    error("a does not have field named '\(b)'")
   ][0]
  out: _
}.out

[infogulch]

I'm delighted to see a proposal that addresses one of CUE's oldest feature requests!

• User-defined functions? #484
• Proposal: core builtin extensions #943
• Better syntax support for user-defined "functions" #1480
• language: function signatures #2007

I'd like to hear how you would describe the similarities and differences to ideas floated in previous discussions, and what changed that made this able to land now.

[mpvl]

The main objections to functions I had was that it can easily be used abusively, to the point that configurations become unmanageable. I've seen many instances of that.

The function signature idea was long standing, but was always put on the back burner as long as it only involved function signatures.

The idea was always that one should write functions in another language. This forces a natural bridge and clean separation. We tried to provide a WASM bridge in the past, but then found WASM to be too immature. The idea was that once such bridges existed, we could provide functions as it would arguably only be used for simple cases as a convenience, and it would also help ground the development of signatures.

And indeed around the time we worked on WASM, we picked it up again. We got stuck, though. We don't call it strictly out in the proposal (it was already getting large), but if you look closely, CUE takes a relatively unconventional stance with respect to Variance. Sticking to the theoretical sound and conventional approach resulted in very strange and unintuitive outcomes and we couldn't come up with something that worked. CUE being a constraint language had something to do with that. So it took us some convincing ourselves that taking a different approach is the right thing to do for such a language. We think it results in much more intuitive semantics for defining invariants, for function overloading, and "combining" functions ((f & g)(arg)). It does limit static analysis a bit for higher order functions, but for all practical purposes it turned out not to be a limitation at all. Anyway, it took us a couple of years to take this leap of faith to go against the grain and understand that unifying two signatures is something different from matching a signature against an implementation, for instance.

But there were other reasons. You can simulate functions with structs and this is now a common pattern. This is arguably strictly worse than using functions to do it. At this point we might was well provide functions. The functions in CUE are deliberately not TC, like struct unification. This guarantees we can only make things strictly better relatively to the struct pattern.

Another thing that changed is that we are actually close to providing a Go bridge, allowing users to write Go functions. This feature requires some more machinery and trickery and will be tightly integrated with the Central Registry. So we are actually close to alleviating the first objection to having functions after all in the end. :)

There is a lot more to it, but hopefully this gives some back story.

[imax9000]

I see no explicit provisions for private/intermediate values. Is the intended approach for that to use a struct?

f: func(a: int) -> int : {
  op1: a * 2
  out: op1 + 1
}.out