rfcs/docs/syntax-if-while-local-initializers.md

if local and while local statements

This RFC is an update and continuation to if statement initializers, featuring improved semantics as discussed and agreed-upon in that RFC's thread and in ROSS.

Summary

if local statements: Allow local identifiers to be bound in if statements to improve the ergonomics of extremely common control flow idioms, improve code clarity, reduce scope pollution, and improve the developer experience.

while local statements: Allow local identifiers to be bound in while statements to improve code clarity, improve sentinel value handling semantics, reduce scope pollution, and provide parity with if local statements.

Motivation

In Luau, an extremely common idiom is for fallible functions to return an optional value: an intended result if the operation succeeds or nil if it fails. Users are expected to nilcheck this result to handle success and failure/empty cases, and this constitutes a major aspect of control flow. An extremely common example of such is Roblox's Instance:FindFirstChild, which returns an Instance if one was found or nil otherwise:

local model = workspace:FindFirstChild("MyModel")
if model then
    -- model is bound and not nil
end
-- model is still bound here

With if local statements, this code may be rewritten as:

if local model = workspace:FindFirstChild("MyModel") then
    -- model is bound and is not nil
end
-- model is not bound here

In many cases, developers use an expression in an if statement's condition and then immediately use it again in its body:

if folders[folder][file_name].last_updated < now - TWO_DAYS then
    last_updated = folders[folder][file_name].last_updated
end

In this case, an if local statement with an in clause can reduce repetition and greatly improve readability:

if local update_time = folders[folder][file_name].last_updated 
in update_time < now - TWO_DAYS then
    last_updated = update_time
end

The primary motivation for if local statements isn't in small examples like those above, however, it's how it fits into whole codebases. if locals drastically improve code shape, readability, and the general conciseness and expressiveness of the Luau language.

while local statements allow you to set a value that persists throughout the execution of the loop as well as an in condition that re-evaluates every iteration of the loop.

In this case, current_path persists throughout all iterations, and without an in clause, the while local defaults to while true do behavior:

local init_luau_path = ""
while local current_path = provided_path do
    if local init_luau = fs.find(path.join(current_path, "init.luau")).file then
        init_luau_path = init_luau
        break
    elseif local parent = path.parent(current_path) then
        current_path = parent
    else
        error("ran out of parents")
    end
end

In another case, this while local loop allows for easy request retries:

local result
local retries = 0

while local response = http.get("https://my.unreliable.dev/api/") 
in 
    response.status_code ~= 200
    and retries < 3 
do
    if response.status_code == 429 then
        task.wait(response.headers["Retry-After"] or 3)
    elseif response.status_code == 404 then
        break
    end
    
    local new_response = http.get("https://my.unreliable.dev/api/")
    if new_response.status_code == 200 then
        result = new_response.body
    else
        retries += 1
        response = new_response
    end
end

Design

This proposal introduces if local and while local statements, or more precisely, allows local bindings to be initialized within if and while statement declarations.

if local statements

An if local statement is any if statement with one or more local bindings. local bindings may be declared after the if or elseif keywords of an if statement, may be followed by one in clause expression, and must be followed by the then keyword:

if local identifier = expression() then
end
-- or
if local identifier = expression() in condition() then
end

If local bindings are provided, then one optional in clause may be provided per branch to partially determine the evaluation condition of the if/elseif branch.

• If an in clause is not provided, then the evaluation condition of the branch is that the leftmost binding must evaluate not-nil. This is roughly similar to the current behavior of putting a multiret function call in an if statement condition; the conditional branch will evaluate if the first return of the multiret is truthy.

• If an in clause is provided, then the clause must be satisfied and the leftmost binding must evaluate not-nil. The in clause will not be evaluated if the leftmost binding is nil.

Although this behavior somewhat differs from the previous RFC, this is because the purpose of an if local initializer is to check if values exist, and if they do, to bind them. By expecting the leftmost binding to always exist, we can better support the primary usecase (only one binding) and allow users to omit the character and check in the following in clause:

if local character = player.Character 
in character:FindFirstChildOfClass("Humanoid").Health > 20 then
-- since character is the leftmost binding, it's guaranteed to exist
end

Initializations without assignments (if local x then end) are not permitted and cause a syntax error. Initializations of the leftmost binding to nil, including but not limited to the following:

• if local x = nil then end
• if local x, y = nil, 3 in x == nil or y then end

will always evaluate to false and will never execute a conditional branch.

Multiple bindings are allowed and must be separated by commas:

if local success, result = pcall(foo) then
-- note that success can be false here and still bound; false is falsey but not nil!
    if success then
        dothing(result)
    else
        print(result)
    end
end

Consider: can/should we allow locals split by semicolons/whitespace like in:

if
    local x, y = foo()
    local entry = fs.find("idk.txt")
    local file = entry.file
in
    entry:exists()
    and file ~= nil
    and file:read():match(`{x}{y}`) 
then
    print("yes")
end

This could make if locals with multiple bindings a lot more readable, the issue is just if it's even possible. if locals are possible by special casing if statements without needing generalized bindings-in-expressions, but what about these? I assume it'd work if we disallowed locals from referring to each other.

Variables bound in an if local initializer remain in scope within their in clause condition and then body, and subsequently go out of scope before the next conditional branch or end. In other words, if local bindings have no fallthrough.

For example,

if local cats = getCats() :: { Cat } in #cats > 0 then
    -- cats is bound here
elseif local dogs = getDogs() :: { Dog } in #dogs > 0 then
    -- dogs is bound here, but cats isn't
else
    -- neither cats nor dogs is bound here
end
-- neither cats nor dogs is bound here

Fallthrough was included in and was a major motivator for a previous version of this RFC. It was decided against since in other languages, it often leads to unexpected behavior, possible footguns, and is mostly useful for error catching. Additionally, as proposed in the previous RFC, if local fallthrough could easily result in hard-to-understand control flow in Luau that could increase the cognitive complexity of code in the language for little benefit.

As an edge case, locals may be reassigned within the in condition. In this case, the conditional branch executes because x is initially not nil, allowing the in condition to evaluate, reassign x to nil, and return true:

if local x = 3 in (function() x = nil; return true end)() then
    print(x) -- nil
end

while local loops

while local statements are defined as while loops with one or more local bindings. Similarly to if locals, local bindings may be declared after the while keyword, may contain one in conditional clause, and must follow with the do keyword.

while local identifier = expr() do
end
-- or
while local identifier = expr() in cond() do
end

Local bindings are evaluated once, before the first iteration, and in conditions are evaluated once every iteration. If an in clause is not specified, the while local treats the condition as a while true loop and will continue iterating indefinitely or until broken with break. Unlike bindings in if local statements, bindings in while local loops may be initialized to nil before their first iteration. Although this seems counterintuitive, it makes sense because the usecase for if locals (nilchecking) differs from while locals. Additionally, while loops don't often encounter nil sentinel values unlike if local statements, which mostly operate on nilchecking.

Drawbacks

Why should we not do this?

-- TODO

Alternatives

What other designs have been considered? What is the impact of not doing this?

-- TODO

if local expressions are not formally included in this RFC due to implementation difficulty, however are included as a future proposal and would follow extremely similar syntax to if local statements:

local humanoid: Humanoid? = if local character = player.Character
    then character:FindFirstChildOfClass("Humanoid")
    else nil

For if local expressions to be possible, Luau would need bindings-in-expressions support, which would require a compiler rewrite.