Escopo

Em scripting, um bloco de código é o corpo de uma estrutura de controle ou função. O escopo de uma variável ou função é o bloco de código que pode acessá-la, e pode ser global ou local. Todos os blocos podem acessar variáveis e funções globais. Um bloco pode acessar variáveis e funções locais em seu bloco pai, mas não em nenhum de seus blocos filhos.

Variáveis e funções têm escopo global por padrão, mas é quase sempre melhor declará-las com escopo local porque Luau acessa variáveis e funções locais mais rapidamente do que as globais. Para dar a uma variável ou função escopo local, coloque a palavra-chave local antes de seu nome ao declará-la.

Scripts não podem acessar variáveis ou funções globais e locais em outros scripts. Se você quiser compartilhar valores e funções entre scripts, use ModuleScripts.

local helloWorld = 'Hello World!'
local function printHelloWorld()
	print(helloWorld)
end
printHelloWorld() -- Hello World!

• O bloco B pode acessar a variável local no bloco A.
• O bloco C pode acessar as variáveis e funções locais nos blocos A e B.
• O bloco A não pode acessar as variáveis e funções locais nos blocos B ou C.
• O bloco B não pode acessar a variável local no bloco C.

Escopo global

Depois de declarar uma variável ou função global, qualquer bloco de código no mesmo script pode acessá-la. Variáveis e funções têm escopo global, a menos que você as declare com a palavra-chave local.

No código a seguir, testVar tem escopo global dentro da função local testFunc(). Quando Luau chama a testFunc(), ele atribui a testVar o valor 64. A testVar tem escopo global, então a função print() fora de testFunc() pode acessá-la e imprimir 64.

local function testFunc()  -- escopo local
	testVar = 64  -- escopo global
end

testFunc()

print(testVar) -- 64

No código a seguir, a variável global x começa em 0, incrementa em 1 a cada iteração do for loop, e imprime novamente depois com um valor final de 4.

x = 0  -- Variável global "x"

for i = 1, 4 do
	x += 1
	print("Global 'x' = " .. x)
end

print("Global 'x' = " .. x)

--[[ Saída resultante:
Global 'x' = 1
Global 'x' = 2
Global 'x' = 3
Global 'x' = 4
Global 'x' = 4
]]

É mais fácil declarar variáveis e funções globais porque você não precisa digitar tanto, mas variáveis e funções globais têm as seguintes desvantagens em comparação com as locais:

• Luau acessa variáveis e funções globais com uma busca hash, então é caro em termos de desempenho. Usar uma variável global em um loop crítico de tempo pode torná-lo mais de 10% mais lento do que usar uma variável local no mesmo loop.
• Luau descarta variáveis locais após o término de seu escopo, reduzindo o uso de memória.
• Você pode acessar variáveis e funções globais dentro do mesmo script, mas não entre múltiplos scripts. Portanto, uma variável ou função global não oferece nenhum benefício em relação a um equivalente local em escopo, um upvalue, ou um shadow.

Escopo local

Luau só pode acessar uma variável ou função local no bloco de código onde você a declara. Criar uma variável com escopo local dá a você um controle mais rigoroso sobre quando e onde seu valor muda.

No código a seguir, a função testFunc() e a variável testVar têm escopo local. Apenas o código dentro de testFunc() pode acessar a variável testVar. A variável testVar não tem um valor fora de testFunc(), então chamar print(testVar) dentro de testFunc() imprime o valor de testVar, mas chamar print(testVar) fora de testFunc() imprime nil.

local function testFunc()  -- escopo local
	local testVar = 64  -- escopo local
	print(testVar) -- 64
end

testFunc()

print(testVar) -- nil

No código a seguir, a variável local x tem o valor 0 na linha 1. À medida que Luau itera pelo for loop, uma variável local diferente x tem o valor 1. Em seguida, Luau imprime a variável inicial x com um valor inalterado de 0.

local x = 0  -- Variável local "x"

for i = 1, 4 do
	local x = 1  -- Variável diferente "x", local a este "for" loop
	print("Loop 'x' = " .. x)
end

print("Inicial 'x' = " .. x)

--[[ Saída resultante:
Loop 'x' = 1
Loop 'x' = 1
Loop 'x' = 1
Loop 'x' = 1
Inicial 'x' = 0
]]

Variáveis e funções const seguem as mesmas regras de escopo que as local. Você pode declará-las em qualquer bloco, incluindo dentro de outra função. Para mais informações sobre const, veja Variáveis const.

Captura

Depois de declarar e atribuir uma variável local, você pode lê-la em seu nível de escopo e em funções cujo escopo está contido pelo mesmo escopo que contém a variável local. Essa técnica é conhecida como captura.

No código a seguir, a função f captura a variável local x. A variável x em f() é um upvalue.

local x = 5

local function f()
	print(x)
end

f() -- 5
print(x) -- 5

Sombra

Depois de declarar e atribuir uma variável local, você pode lê-la em seu nível de escopo e em níveis de escopo descendentes. Se você redeclarar e reatribuir a variável em um nível de escopo descendente, então você cria uma nova variável local com o mesmo nome, mas com um valor diferente da atribuição mais recente. A nova variável local não afeta a variável local da atribuição anterior. Essa técnica, conhecida como sombreamento, ajuda você a reutilizar o nome de uma variável sem reutilizar seu valor.

No código a seguir, Luau faz sombra da variável x. A variável x em f() é uma variável de sombra.

local x = 5

local function f()
	local x = 7
	print(x)
end

f() -- 7
print(x) -- 5

Você também pode redeclarar uma variável local sem atribuir um valor a ela para que você possa reatribuir a variável em seu nível de escopo e em níveis de escopo descendentes. Redeclarar uma variável local sem atribuir um valor a ela define seu valor como nil.

No código a seguir, Luau faz sombra da variável local fruitName na função getFruitByColor(). A função redeclara fruitName como uma nova variável de sombra e define seu valor como nil. A função tem um nível de escopo descendente, um for loop, que atribui um valor a fruitName. Após o loop for, a função retorna a variável de sombra fruitName. Ao longo de toda a função, fruitName é a mesma variável local que não sobrescreve a variável local inicial fruitName.

local fruitName = "Chocolate"
local fruitTable = {
	Lemon = "Amarelo",
	Apple = "Vermelho",
	Orange = "Laranja"
}

local function getFruitByColor(color)
	local fruitName
	for key, value in fruitTable do
		if value == color then
			fruitName = key
		end
	end
	return fruitName
end

local fruit = getFruitByColor("Amarelo")
print(fruit) -- Lemon
print(fruit .. ", não " .. fruitName) -- Lemon, não Chocolate