rfcs/docs/syntax-structure-matching.md

# Structure matching

## Summary

Agree on the generic syntax for *structure matching* - a prerequisite to implementing destructuring in any part of Luau.

This is intended as a spiritual successor to the older ["Key destructuring" RFC by Kampfkarren](https://github.com/luau-lang/rfcs/pull/24), which was very popular but requires more rigour and wider consensus to have confidence implementing the feature.

**This is not an implementation RFC.**

## Motivation

Simple indexes on tables are very common both in and outside of Luau. A common use case is large libraries. It is common in the web world to see something like:

```js
const { useState, useEffect } = require("react");
```

...which allows you to quickly use `useState` and `useEffect` without fully qualifying it in the form of `React.useState` and `React.useEffect`. In Luau, if you do not want to fully qualify common React functions, the top of your file will often look like:

```lua
local useEffect = React.useEffect
local useMemo = React.useMemo
local useState = React.useState
-- etc
```

...which creates a lot of redundant cruft.

It is also common to want to have short identifiers to React properties, which basically always map onto a variable of the same name. As an anecdote, a regex search of `^\s+local (\w+) = \w+\.\1$` comes up 103 times in the My Movie codebase, many in the form of indexing React properties:

```lua
local position = props.position
local style = props.style
-- etc...
```

...whereas in JavaScript this would look like:
```js
const { position, style } = props

// Supported in JavaScript, but not this proposal
function MyComponent({
	position,
	style,
})
```

React properties are themselves an example of a common idiom of passing around large tables as function arguments, such as with HTTP requests:

```js
// JavaScript
get("/users", ({
	users,
	nextPageCursor,
}) => { /* code */ })
```

## Design

This proposal does not specify any specific locations where this syntax should appear. Instead, the aim is to get consensus on the syntax we would be most comfortable with for all instances of destructuring we may choose to implement at a later date.

In particular, this proposal punts on implementation at sites of usage:

- Destructuring re-assignment (as opposed to destructuring `local` declarations)
- Defaults for destructured fields (unclear how this interacts with function default arguments)
- Unnamed function parameters (destructuring a parameter doesn't name the parameter)
- Type declarations on keys (for providing types when destructuring a function argument)

The purpose of this proposal is to instead find consensus on specific syntax for the matching itself.

This proposal puts forward a superset of syntax, able to match any table shape, with logical and simple desugaring, giving a rigorous foundation to the previously agreed-upon concise syntaxes.

### Structure matching

This proposal will use the term *structure matcher* to refer to syntax for retrieving values from table structures.

The most basic structure matcher is a set of empty braces. All matching syntax occurs between these braces.

```Lua
{ }
```

Empty structure matchers like these are not invalid (they still fit the pattern), but aren't very useful - linting for these makes sense.

#### Basic matching

This is the most verbose, but compatible way of matching values.

Keys are specified in square brackets, and are allowed to evaluate to any currently valid key (i.e. not `nil`, plus any other constraints in the current context).

To save the value at that key, an identifier is specified to the left of the key. An `=` is used to indicate assignment.

```Lua
{ foo = [1], bar = [#data] }
```

This desugars to:

```Lua
foo, bar = data[1], data[#data]
```

#### Dot keys with names

Keys that are valid Luau identifiers can be expressed as `.key` instead of `["key"]`.

```Lua
{ myFoo = .foo, myBar = .bar }
```

This desugars once to:

```Lua
{ myFoo = ["foo"], myBar = ["bar"] }
```

Then desugars again to:

```Lua
myFoo, myBar = data["foo"], data["bar"]
```

#### Dot keys without names

When using dot keys, the second identifier can be skipped if the destination uses the same identifier as the key.

```Lua
{ .foo, .bar }
```

This desugars once to:

```Lua
{ foo = .foo, bar = .bar }
```

Then desugars twice to:

```Lua
{ foo = ["foo"], bar = ["bar"] }
```

Then desugars again to:

```Lua
foo, bar = data["foo"], data["bar"]
```

#### Nested structure

Keys can be chained together to match values in nested tables.

```Lua
{ .foo.bar }
```

This desugars once to:

```Lua
{ bar = .foo.bar }
```

Then desugars twice to:

```Lua
{ bar = ["foo"]["bar"] }
```

Then desugars again to:

```Lua
bar = data["foo"]["bar"]
```

To avoid fully qualifying multiple paths, parentheses can be used to share a common prefix:

```Lua
{ .foo(.bar, myBaz = ["baz"]) }
```

This desugars once to:

```Lua
{ .foo.bar, myBaz = .foo["baz"] }
```

Then desugars twice to:

```Lua
{ foo = ["foo"]["bar"], myBaz = ["foo"]["baz"] }
```

Then desugars again to:

```Lua
local bar, myBaz = data["foo"]["bar"], data["foo"]["baz"]
```

## Alternatives

### Unpack syntax

Dedicated array/tuple unpacking syntax was considered, but rejected in favour of basic syntax.

For unpacking arrays, this proposal suggests:

```Lua
{ foo = [1], bar = [2] }
```

Or alternatively, using `table.unpack`:

```Lua
foo, bar = table.unpack(data)
```

For disambiguity with other languages, we would still not allow:

```Lua
{ foo, bar }
```

The original `unpack` syntax is listed below.

Instead of listing out consecutive numeric keys, `unpack` would be used at the start of a matcher to implicitly key all subsequent items.

```Lua
{ unpack foo, bar }
```

This would desugar once to:

```Lua
{ foo = [1], bar = [2] }
```

Then desugars again to:

```Lua
foo, bar = data[1], data[2]
```

`unpack` would have skipped dot keys and explicitly written keys. If an explicit key collided with an implicit key, this would be a type error.

```Lua
{ unpack foo, bar = [true], baz, .garb }
```

This would desugar once to:

```Lua
{ foo = [1], bar = [true], baz = [2], garb = ["garb"] }
```

Then desugars again to:

```Lua
foo, bar, baz, garb = data[1], data[true], data[2], data["garb"]
```

### Indexing assignment

A large amount of effort was poured into finding a way of moving the destructuring syntax into the middle of the assignment.

A `.=` and/or `[]=` assignment was considered for this, for maps and arrays respectively:

```Lua
local amelia, bethany, caroline .= nicknames
local three, five, eleven []= numbers
```

However, this was discarded as it does not align with the design of other compound assignment operations, which mutate the left-hand-side and take the right-hand-side of the assignment as the right-hand-side of the operation itself.

```Lua
local foo = {bar = "baz"}
foo .= "bar"
print(foo) --> baz
```

Many alternate syntaxes were considered, but discarded because it was unclear how to introduce a dinstinction between maps and arrays. They also didn't feel like they conformed to the "shape of Luau".

```Lua
local amelia, bethany, caroline [=] nicknames
local amelia, bethany, caroline ...= nicknames
local ...amelia, bethany, caroline = nicknames
```

### Type-aware destructuring

Another exploration revolved around deciding between array/map destructuring based on the type inferred for the right-hand-side.

However, this was discarded because it made the behaviour of the assignment behave on non-local information, and was not clearly telegraphed by the syntax. It would also not work without a properly inferred type, making it unusable in the absence of type checking.

### Multiple indexing

A syntax for indexing multiple locations in a table was considered, but rejected by the Luau team over concerns it could be confused for multi-dimensional array syntax.

```Lua
local numbers = {3, 5, 11}

local three, five, eleven = numbers[1, 2, 3]
```

### Don't do anything

This is always an option, given how much faff there has been trying to get a feature like this into Luau!

However, it's clear there is widespread and loud demand for something like this, given the response to the previous RFC, and the disappointment after it was discarded at the last minute over design concerns.

This proposal aims to tackle such design concerns in stages, agreeing on each step with open communication and space for appraising details.

## Drawbacks

### Structure matchers at line starts

This design precludes the use of a structure matcher at the start of a new line, among other places, because of ambiguity with function call syntax:

```Lua
local foo = bar

{ } -- bar { }?
```

Such call sites will need a starting token (perhaps a reserved or contextual keyword) to dispel the ambiguity.

We could mandate a reserved or contextual keyword before all structure matchers:

```Lua
match { myFoo = .foo }
in { myFoo = .foo }
```

But this proposal punts on the issue, as this is most relevant for only certain implementations of matching, and so is considered external to the main syntax. We are free to decide on this later, once we know what the syntax looks like inside of the braces, should we agree that braces are desirable in any case.