Add prior proposals as RFCs

rfcs/TEMPLATE.md

@@ -8,7 +8,7 @@ One paragraph explanation of the feature.
 
 Why are we doing this? What use cases does it support? What is the expected outcome?
 
-## Detailed design
+## Design
 
 This is the bulk of the proposal. Explain the design in enough detail for somebody familiar with the language to understand, and include examples of how the feature is used.
 
@@ -19,7 +19,3 @@ Why should we *not* do this?
 ## Alternatives
 
 What other designs have been considered? What is the impact of not doing this?
-
-## Unresolved questions
-
-What parts of the design are still undecided?

rfcs/change-global-version.md

@@ -0,0 +1,19 @@
+# Change \_VERSION global to "Luau"
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Change \_VERSION global to "Luau" to differentiate Luau from Lua
+
+## Motivation
+
+Provide an official way to distinguish Luau from Lua implementation.
+
+## Design
+
+We inherit the global string \_VERSION from Lua (this is distinct from Roblox `version()` function that returns a full version number such as 0.432.43589).
+
+The string is set to "Lua 5.1" for us (and "Lua 5.2" etc for newer versions of Lua.
+
+Since our implementation is sufficiently divergent from upstream, this proposal suggests setting \_VERSION to "Luau".

rfcs/function-string-pack-unpack.md

@@ -0,0 +1,69 @@
+# string.pack/unpack/packsize from Lua 5.3
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Add string pack/unpack from Lua 5.3 for binary interop, with small tweaks to format specification to make format strings portable.
+
+## Motivation
+
+While the dominant usecase for Luau is a game programming language, for backend work it's sometimes the case that developers need to work with formats defined outside of Roblox. When these are structured as JSON, it's easy, but if they are binary, it's not. Additionally for the game programming, often developers end up optimizing their data transmission using custom binary codecs where they know the range of the data (e.g. it's much more efficient to send a number using 1 byte if you know the number is between 0 and 1 and 8 bits is enough, but RemoteEvent/etc won't do it for you because it guarantees lossless roundtrip). For both working with external data and optimizing data transfer, it would be nice to have a way to work with binary data.
+
+This is doable in Luau using `string.byte`/`string.char`/`bit32` library/etc. but tends to be a bit cumbersome. Lua 5.3 provides functions `string.pack`/`string.unpack`/`string.packsize` that, while not solving 100% of the problems, often make working with binary much easier and much faster. This proposal suggests adding them to Luau - this will both further our goal to be reasonably compatible with latest Lua versions, and make it easier for developers to write some types of code.
+
+## Design
+
+Concretely, this proposal suggests adding the following functions:
+
+```
+string.pack (fmt, v1, v2, ···)
+```
+
+Returns a binary string containing the values v1, v2, etc. packed (that is, serialized in binary form) according to the format string fmt.
+
+```
+string.packsize (fmt)
+```
+
+Returns the size of a string resulting from string.pack with the given format. The format string cannot have the variable-length options 's' or 'z'.
+
+```
+string.unpack (fmt, s [, pos])
+```
+
+Returns the values packed in string s (see string.pack) according to the format string fmt. An optional pos marks where to start reading in s (default is 1). After the read values, this function also returns the index of the first unread byte in s.
+
+The format string is a sequence of characters that define the data layout that is described here in full: https://www.lua.org/manual/5.3/manual.html#6.4.2. We will adopt this wholesale, but we will guarantee that the resulting code is cross-platform by:
+
+a) Ensuring native endian is little endian (de-facto true for all our platforms)
+b) Fixing sizes of native formats to 2b short, 4b int, 8b long
+c) Treating `size_t` in context of `T` and `s` formats as a 32-bit integer
+
+Of course, the functions are memory-safe; if the input string is too short to provide all relevant data they will fail with "data string is too short" error.
+
+This may seem slightly unconventional but it's very powerful and expressive, in much the same way format strings and regular expressions are :) Here's a basic example of how you might transmit a 3-component vector with this:
+
+```
+-- returns a 24-byte string with 64-bit double encoded three times, similar to how we'd replicate 3 raw numbers
+string.pack("ddd", x, y, z)
+
+-- returns a 12-byte string with 32-bit float encoded three times, similar to how we'd replicate Vector3
+string.pack("fff", x, y, z)
+
+-- returns a 3-byte string with each value stored in 8 bits
+-- assumes -1..1 range; this code doesn't round the right way because I'm too lazy
+string.pack("bbb", x * 127, y * 127, z * 127)
+```
+
+The unpacking of the data is symmetrical - using the same format string and `string.unpack` you get the encoded data back.
+
+## Drawbacks
+
+The format specification is somewhat arbitrary and is likely to be unfamiliar to people who come with prior experience in other languages (having said that, this feature closely follows equivalent functionality from Ruby).
+
+The implementation of string pack/unpack requires yet another format string matcher, which increases complexity of the builtin libraries and static analysis (since we need to provide linting for another format string syntax).
+
+## Alternatives
+
+We could force developers to rely on existing functionality for string packing; it is possible to replicate this proposal in a library, although at a much reduced performance.

rfcs/syntax-array-like-table-types.md

@@ -0,0 +1,63 @@
+# Array-like table types
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Add special syntax for array-like table types, `{ T }`
+
+## Motivation
+
+Luau supports annotating table types. Tables are quite complex beasts, acting as essentially an associative container mapping any value to any other value, and to make it possible to reason about them at type level we have a more constrained definition of what a table is:
+
+- A table can contain a set of string keys with a specific type for each key
+- A table can additionally have an "indexer" for a given key/value type, meaning that it acts as an associative container mapping keys of type K to values of type V
+
+The syntax for this right now looks like this:
+
+```
+{ key1: Type1, key2: Type2, [KeyType]: ValueType }
+```
+
+This is an example of a hybrid table that has both an indexer and a list of specific key/value pairs.
+
+While Luau technically doesn't support arrays, canonically tables with integer keys are called arrays, or, more precisely, array-like tables. Luau way to specify these is to use an indexer with a number key:
+
+```
+{ [number]: ValueType }
+```
+
+(note that this permits use of non-integer keys, so it's technically richer than an array).
+
+As the use of arrays is very common - for example, many library functions such as `table.insert`, `table.find`, `ipairs`, work on array-like tables - Luau users who want to type-annotate their code have to use array-like table annotations a lot.
+
+`{ [number]: Type }` is verbose, and the only alternative is to provide a slightly shorter generic syntax:
+
+```
+type Array<T> = { [number]: T }
+```
+
+... but this is necessary to specify in every single script, as we don't support preludes.
+
+## Design
+
+This proposal suggests adding syntactic sugar to make this less cumbersome:
+
+```
+{T}
+```
+
+This will be exactly equivalent to `{ [number]: T }`. `T` must be a type definition immediately followed by `}` (ignoring whitespace characters of course)
+
+Conveniently, `{T}` syntax matches the syntax for arrays in Typed Lua (a research project from 2014) and Teal (a recent initiative for a TypeScript-like Lua extension language from 2020).
+
+## Drawbacks
+
+This introduces a potential ambiguity wrt a tuple-like table syntax; to represent a table with two values, number and a string, it's natural to use syntax `{ number, string }`; however, how would you represent a table with just one value of type number? This may seem concerning but can be resolved by requiring a trailing comma for one-tuple table type in the future, so `{ number, }` would mean "a table with one number", vs `{ number }` which means "an array-like table of numbers".
+
+## Alternatives
+
+A different syntax along the lines of `[T]` or `T[]` was considered and rejected in favor of the current syntax:
+
+a) This allows us to, in the future - if we find a good workaround for b - introduce "real" arrays with a distinct runtime representation, maybe even starting at 0! (whether we do this or not is uncertain and outside of scope of this proposal)
+b) Square brackets don't nest nicely due to Lua lexing rules, where [[foo]] is a string literal "foo", so with either syntax with square brackets array-of-arrays is not easy to specify

rfcs/syntax-continue-statement.md

@@ -0,0 +1,96 @@
+# continue statement
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Add `continue` statement to `for`, `while` and `repeat` loops using a context-sensitive keyword to preserve compatibility.
+
+## Motivation
+
+`continue` statement is a feature present in basically all modern programming languages. It's great for ergonomics - often you want the loop to only process items of a specific kind, so you can say `if item.kind ~= "blah" then continue end` in the beginning of the loop.
+
+`continue` never makes code that was previously impossible to write possible, but it makes some code easier to write.
+
+We'd like to add this to Luau but we need to keep backwards compatibility - all existing scripts that parse correctly must parse as they do now. The rest of the proposal outlines the exact syntax and semantics that makes it possible.
+
+## Design
+
+`continue` statement shall be the statement that *starts* with "continue" identifier (*NOT* keyword - effectively it will be a context-sensitive keyword), and such that the *next* token is none of (`.`, `[`, `:`, `{`, `(`, `=`, string literal or ',').
+
+These rules effectively say that continue statement is the statement that *does not* parse as a function call or the beginning of an assignment statement.
+
+This is a continue statement:
+
+```
+do
+continue
+end
+```
+
+This is not a continue statement:
+
+```
+do
+continue = 5
+end
+```
+
+This is not a continue statement:
+
+```
+do
+continue(5)
+end
+```
+
+This is not a continue statement either, why do you ask?
+
+```
+do
+continue, foo = table.unpack(...)
+end
+```
+
+These rules are simple to implement. In any Lua parser there is already a point where you have to disambiguate an identifier that starts an assignment statement (`foo = 5`) from an identifier that starts a function call (`foo(5)`). It's one of the few, if not the only, place in the Lua grammar where single token lookahead is not sufficient to parse Lua, because you could have `foo.bar(5)` or `foo.bar=5` or `foo.bar(5)[6] = 7`.
+
+Because of this, we need to parse the entire left hand side of an assignment statement (primaryexpr in Lua's BNF) and then check if it was a function call; if not, we'd expect it to be an assignment statement.
+
+Alternatively in this specific case we could parse "continue", parse the next token, and if it's one of the exclusion list above, roll the parser state back and re-parse the non-continue statement. Our lexer currently doesn't support rollbacks but it's also an easy strategy that other implementations might employ for `continue` specifically.
+
+The rules make it so that the only time we interpret `continue` as a continuation statement is when in the old Lua the program would not have compiled correctly - because this is not valid Lua 5.x:
+
+```
+do
+continue
+end
+```
+
+There is one case where this can create new confusion in the newly written code - code like this:
+
+```
+do
+continue
+(foo())(5)
+end
+```
+
+could be interpreted both as a function call to `continue` (which it is!) and as a continuation statement followed by a function call (which it is not!). Programmers writing this code might expect the second treatment which is wrong.
+
+We have an existing linter rule to prevent this, however *for now* we will solve this in a stronger way:
+
+Once we parse `continue`, we will treat this as a block terminator - similarly to `break`/`return`, we will expect the block to end and the next statement will have to be `end`. This will make sure there's no ambiguity. We may relax this later and rely on the linter to tell people when the code is wrong.
+
+Semantically, continue will work as you would expect - it would skip the rest of the loop body, evaluate the condition for loop continuation (e.g. check the counter value for numeric loops, call the loop iterator for generic loops, evaluate while/repeat condition for while/repeat loops) and proceed accordingly. Locals declared in the loop body would be closed as well.
+
+One special case is the `until` expression: since it has access to the entire scope of `repeat` statement, using `continue` is invalid when it would result in `until` expression accessing local variables that are declared after `continue`.
+
+## Drawbacks
+
+Adding `continue` requires a context-sensitive keyword; this makes editor integration such as syntax highlighting more challenging, as you can't simply assume any occurrence of the word `continue` is referring to the statement - this is different from `break`.
+
+Implementing `continue` requires special care for `until` statement as highlighted in the design, which may make compiler slower and more complicated.
+
+## Alternatives
+
+In later versions of Lua, instead of `continue` you can use `goto`. However, that changes control flow to be unstructured and requires more complex implementation and syntactic changes.

rfcs/syntax-type-ascription.md

@@ -0,0 +1,66 @@
+# Type ascriptions
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Implement syntax for type ascriptions using `::`
+
+## Motivation
+
+Luau would like to provide a mechanism for requiring a value to be of a specific type:
+
+```
+-- Asserts that the result of a + b is a number.
+-- Emits a type error if it isn't.
+local foo = (a + b) as number
+```
+
+This syntax was proposed in the original Luau syntax proposal. Unfortunately, we discovered that there is a syntactical ambiguity with `as`:
+
+```
+-- Two function calls or a type assertion?
+foo() as (bar)
+```
+
+## Design
+
+To provide this functionality without introducing syntactical confusion, we want to change this syntax to use the `::` symbol instead of `as`:
+
+```
+local foo = (a + b) :: number
+```
+
+This syntax is borrowed from Haskell, where it performs the same function.
+
+The `::` operator will bind very tightly, like `as`:
+
+```
+-- type assertion applies to c, not (b + c).
+local a = b + c :: number
+```
+
+Note that `::` can only cast a *single* value to a type - not a type pack (multiple values). This means that in the following context, `::` changes runtime behavior:
+
+```
+foo(1, bar()) -- passes all values returned by bar() to foo()
+foo(1, bar() :: any) -- passes just the first value returned by bar() to foo()
+```
+
+## Drawbacks
+
+It's somewhat unusual for Lua to use symbols as operators, with the exception of arithmetics (and `..`). Also a lot of Luau users may be familiar with TypeScript, where the equivalent concept uses `as`.
+
+`::` may make it more difficult for us to use Turbofish (`::<>`) in the future.
+
+## Alternatives
+
+We considered requiring `as` to be wrapped in parentheses, and then relaxing this restriction where there's no chance of syntactical ambiguity:
+
+```
+local foo: SomeType = (fn() as SomeType)
+-- Parentheses not needed: unambiguous!
+bar(foo as number)
+```
+
+We decided to not go with this due to concerns about the complexity of the grammar - it requires users to internalize knowledge of our parser to know when they need to surround an `as` expression with parentheses. The rules for when you can leave the parentheses out are somewhat nonintuitive.

rfcs/syntax-typed-variadics.md

@@ -0,0 +1,43 @@
+# Typed variadics
+
+> Note: this RFC was adapted from an internal proposal that predates RFC process
+
+## Summary
+
+Add syntax for ascribing a type to variadic pack (`...`).
+
+## Motivation
+
+Luau's type checker internally can represent a typed variadic: any number of values of the same type. Developers should be able to describe this construct in their own code, for cases where they have a function that accepts an arbitrary number of `string`s, for example.
+
+## Design
+
+We think that the postfix `...: T` syntax is the best balance of readability and simplicity. In function type annotations, we will use `...T`:
+
+```
+function math.max(...: number): number
+end
+
+type fn = (...string) -> string
+
+type fn2 = () -> ...string
+```
+
+This doesn't introduce syntactical ambiguity and should cover all cases where we need to represent this construct. Like `...` itself, this syntax is only legal as the last parameter to a function.
+
+Like all type annotations, the `...: T` syntax has no effect on runtime behavior versus an unannotated `...`.
+
+There are currently no plans to introduce named variadics, but this proposal leaves room to adopt them with the form `...name: Type` in function declarations in the future.
+
+## Drawbacks
+
+The mismatch between the type of `...` in function declaration (`number`) and type declaration (`...number`) is a bit awkward. This also gets more complicated when we introduce generic variadic packs.
+
+## Alternatives
+
+We considered several other syntaxes for this construct:
+
+* `...T`: leaves no room to introduce named variadics
+* `...: T...`: redundant `...`
+* `... : ...T`: feels redundant, same as above
+* `...: T*`: potentially confusing for users with C knowledge, where `T*` is a pointer type