Design doc

Features

Ability to match and expand complex variadics:

--- @generic T
--- @param ... Future<T>...
--- @return ... Future<[T...]>
function join(...) end

Ability to unpack multiple variadic packs simultaneously:

--- @generic L, R
--- @param l [L...]
--- @param r [R...]
--- @return [[L, R]...]
function zip2(...) end

Note: L and R must have the same length and shape for successful expansion.

Multidimensional variadics:

--- @generic T
--- @param ... Future<[T...]>...
--- @return ... Future<[[T...]...]>
function join(...) end

Note: there's not enough metaprogramming utilities to implement complex things
like transpose, but we're getting there.

Design decisions

Handling variadic packs of different length or shape

For now, I've decided that all variadic packs that participate in expansion
should have the same length and shape.

Consider zip2 from above. It will successfully expand if L = Multi<A1, B1, C1...>
and R = Multi<A2, B2, C2...>, but will not expand if L = Multi<A1, B1, C1...>
and R = Multi<A2, B2, C2> (notice absence of ... after C2).

We can revise this behavior later. Alternatives include picking longes or shortest
variadic pack. Also, we can add a utility alias that coerces variadic packs
to have the same shape.

Preserving exact shapes of variadic packs

There's a difference between Multi<T...> and T.... The former participates
in checks for variadic pack shapes, while the later doesn't. For this reason,
we can't arbitrarily expand one into another. All optimizations that relate
to collapsing them are now delayed until after generic instantiation.
This also affects empty variadic packs, which are not replaced with a single nil
until later.

Implicit vs explicit unwrapping

Consider the following two functions:

--- @generic T
--- @param ... T...
--- @return [T]
function packTuple1() end

--- @generic T
--- @param ... T...
--- @return [T...]
function packTuple2() end

The question is, what should packTuple1 return?

packTuple2 is obvious: it takes n arguments and puts them into a tuple of length n.

With packTuple1, there are two alternatives:

Require explicit unwrapping (current EmmyLua behavior).

T is a variadic pack. Unless T is explicitly unwrapped with ..., it always
evaluates to the first type in a pack. So, packTuple1 returns a single tuple
of length 1; first element of this tuple has type of the first function parameter.
Implicitly unwrap variadics at the end of type expressions.

T is a variadic pack. Since it appears at the end of a tuple, it is implicitly
unwrapped. So, [T] is equivalent to [T...], therefore packTuple1 is equivalent
to packTuple2.

This PR implements approach 1. I've decided that explicit is better than implicit
in this case, plus I don't want to introduce backward-incompatible changes.

One might argue that approach 2 is more consistent with how variadics work
in Lua's functions. That is, return f() will forward all results of f,
not just the first one. There is a number of issues here, though:

In Lua, return (f()) will only return the first value. Should [(T)] pick
the first argument from T then? If so, will the current grammar for doc types
allow for distinction between T and (T)?
What if T is empty? Should [T] expand to an empty tuple? Should [(T)]
expand to [nil]?

I argue that these questions, however we might answer them, make the system
less intuitive. They introduce hidden rules that the user should always remember.
With the first approach, there's only one rule: T always expands to a single type,
while T... can expand to zero or more types.

Further work

Handling variadic generics in aliases and classes could use some overhaul as well.

I want to make the system less error-prone and more explicit by making class
and alias generic signatures behave like function signatures. That is, last generic
in a class can be a variadic, and only variadic generics can contain type packs:

--- When working with `A`, `B` and `C` users can be sure that
--- `A` and `B` are never variadics.
---
--- @class F<A, B, C...>
---
--- Among other things, users can be sure that `get` returns a single value...
--- @field get fun(self): A
---
--- ...and `getMany` returns multiple (possibly zero) values.
--- @field getMany fun(self): C...

Also, I want to investigate returning variadics from aliases, and how it behaves.

--- Here, `UnpackPair` is an alias that expands to a variadic pack.
---
--- @alias UnpackPair<T> std.RawGet<T, 1>, std.RawGet<T, 2>

--- @generic T
--- @param pair T
--- @return UnpackPair<T>
function unpackPair(pair) end

Allow more complex variadic expansions #714

Description

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions