Scope Tutorial

wiki

Interactive interpreter note

The examples in this page will be written in the form of a script file instead of an interactive interpreter session, since local variables are really hard to work with in it. It will be explained why later.

Creating local variables

To create local variables, add the local keyword before the assignment:

local a = 5

print(a)

You don't need the local keyword any more when changing the variable:

local a = 5

a = 6 -- changes the local a, doesn't create a global

Local variables only exist in the block they were created in. Outside of the block, they do not exist any more.

local a = 5

print(a) --> 5



do

  local a = 6 -- create a new local inside the do block instead of changing the existing a

  print(a) --> 6

end



print(a) --> 5

The place where a variable is visible is called the "scope" of a variable.

Now let's use functions to show how this is really useful:

function bar()

  print(x) --> nil

  local x = 6

  print(x) --> 6

end



function foo()

  local x = 5

  print(x) --> 5

  bar()

  print(x) --> 5

end



foo()

As you can see, each variable is visible from the point where it's declared to the end of the block it's declared in. Even though bar's x exists at the same time as foo's x, they're not written in the same block, so they're independent. This is what's called lexical scoping.

local function syntax sugar

local function f() end



-- is equivalent to



local f

f = function() end



-- not



local f = function() end

the difference between the last two examples is important: the local variable still doesn't exist to the right of the = that gives it the initial value. So if the contents of the function used f to get a reference to itself, it will correctly get the local variable in the first and second versions, but the third version will get the global f (which will be nil, if not a completely unrelated value set by some other code).

Closures

Functions can use local variables created outside of them. These are called upvalues. A function that uses upvalues is called a closure:

local x = 5



local function f() -- we use the "local function" syntax here, but that's just for good practice, the example will work without it

  print(x)

end



f() --> 5

x = 6

f() --> 6

The function sees the change even if it's changed outside of the function. This means that the variable in the function is not a copy, it's shared with the outer scope.

Also, even if the outer scope has passed, the function will still hold on to the variable. If there were two functions created in the scope, they will still share the variable after the outer scope is gone.

local function f()

  local v = 0

  local function get()

    return v

  end

  local function set(new_v)

    v = new_v

  end

  return {get=get, set=set}

end



local t, u = f(), f()

print(t.get()) --> 0

print(u.get()) --> 0

t.set(5)

u.set(6)

print(t.get()) --> 5

print(u.get()) --> 6

Since the two values returned by the two calls to f are independent, we can see that every time a function is called, it creates a new scope with new variables.

Similarly, loops create a new scope on each iteration:

local t = {}



for i = 1, 10 do

  t[i] = function() print(i) end

end



t[1]() --> 1

t[8]() --> 8

Why are local variables difficult in the interactive interpreter

Because it runs each line in a new scope:

> local a=5; print(a)

5

> print(a) -- a is out of scope now, so global a is used

nil

One thing you can do is wrap the code in a do-end block, but it won't be interactive until you finish writing the whole block:

> do

>>  local a = 5

>>  print(a) -- works on a new line

>> end

5

Why not local by default?

You might be coming from another language that makes variables local by default, and are probably thinking "what is the point of all this extra complication? Why not make variables local by default?":

x = 3



-- more code, you might have even forgotten about variable x by now...



function ()

  -- ...

  x = 5 -- does this create a new local x, or does it change the outer one?

  -- ...

end



-- some more code...

The problem with changing the outer one is that you might have intended to make a new variable, and instead change the existing one that you might not even know about, introducing bugs.

The problem with creating a new one is what if you actually want to change the outer one?

With the local keyword, it's all explicit: without local, you change the existing variable, with it, you create a new one.

For more discussion about this, see LocalByDefault.

When to use local variables

The general rule is to always use local variables, unless it's necessary for every part of your program to be able to access the variable (which is very rare).

Since it's easy to forget a local, and since Lua doesn't warn you about it (instead silently creating a global), it can be a source of bugs. One solution is to use a script like strict.lua (shown below), that uses metatables (mentioned in a later tutorial) to trap global variable creation and raise an error. You can put the script in a file in your project, and do require("strict") to use it.

--

-- strict.lua

-- checks uses of undeclared global variables

-- All global variables must be 'declared' through a regular assignment

-- (even assigning nil will do) in a main chunk before being used

-- anywhere or assigned to inside a function.

--



local mt = getmetatable(_G)

if mt == nil then

  mt = {}

  setmetatable(_G, mt)

end



__STRICT = true

mt.__declared = {}



mt.__newindex = function (t, n, v)

  if __STRICT and not mt.__declared[n] then

    local w = debug.getinfo(2, "S").what

    if w ~= "main" and w ~= "C" then

      error("assign to undeclared variable '"..n.."'", 2)

    end

    mt.__declared[n] = true

  end

  rawset(t, n, v)

end

  

mt.__index = function (t, n)

  if not mt.__declared[n] and debug.getinfo(2, "S").what ~= "C" then

    error("variable '"..n.."' is not declared", 2)

  end

  return rawget(t, n)

end



function global(...)

   for _, v in ipairs{...} do mt.__declared[v] = true end

end

For more info about enforcing use of local variables, see DetectingUndefinedVariables.