User Tools

Site Tools



Scripts are easier to manage when a group of statements is collected into a function that can be run at any time. A function can be called with a list of parameters and will produce a list of values when it returns.

-- Define the function
function divmod(num,den)
    return math.floor(num/den), num%den

-- Call the function
q,r = divmod(5,3)
print(q .. ' with a remainder of ' .. r)

Calling a function results in a list of values. If there is no return statement in the function, then the list is empty. When you type return nil, a list with one nil value is created. This is not the same as an empty list.

The return statement has the same restriction as break that it must be the last statement in a block. That block does not have to be the function body; it may be an if-then-else or loop block. There is an optimization when the expression used in a return statement is another function call. Instead of calling the function first, then returning from this function after the call has returned, the new function will replace the current function. When that function returns, it goes directly to where the original function call happened. This is referred to as a “tail-call”, and is very fast. Whenever you see the opportunity to write return tail_call(x), you should take advantage of it.

A function is called with a list of parameters enclosed in parenthesis. There may be spaces between the name of the function and the opening parenthesis, but in contrast to the usual rule, there may not be a line break. Otherwise, the interpreter can’t tell whether you want to call the function or use it as a value. After the opening parenthesis, of course, there is no ambiguity so the rest of the parameter list may be formatted in any way.

The names in a parameter list of a function definition are local variables in the scope of the function block. The parameter variables can be modified by the function. If the variable is an object that is passed by reference, then changes to the object value will be seen outside of the function. Otherwise, changing a parameter variable or assigning a new value will only be visible in the function block.

The last (or only) parameter in a function definition can be ... to make the function accept any number of parameters. When the function is called, any parameters that aren’t assigned to named variables are collected in a list that can be accessed by typing ... as an expression. The dots will expand to a list with the same rules as values returned from a function. You get the number of values in the list with the select function.

When you call a function with a single parameter, and that parameter is a literal string, then you can omit the parenthesis. Essentially, the opening quote or long bracket assumes the same role as the opening parenthesis of a parameter list. The end of the string also ends the parameters for the function call. The rule regarding space before the parameter list also applies between the function name and the start of the string.

print "Print this string."

A function is a value. When you define a function, you are merely assigning the function block to a variable. The definition can be explicitly written to demonstrate this.

divmod = function(num,den) return math.floor(num/den),num%den end
local double = function(i) return i*2 end
-- Same thing
local function double(i)
    return i * 2

Using the local keyword assigns the function to a variable in the local scope. The same scope rules apply to the function name; after all it is nothing more than a variable with the value of a function. A function block can be written wherever a function value is expected. A function can be used as the parameter to another function. You can even create an anonymous function and call it right away.

print( -- Print the results of calling this function
(function(s)  -- The function block is enclosed in parenthesis to make it an expression.
    t = {}
    for w in string.gmatch(s, "%a+") do
        -- Capitalize the first letter in w
        w = string.upper(string.sub(w,1,1)) .. string.sub(w,2)
        table.insert(t,w) -- add it to the table
    return table.unpack(t) -- returns the values in the table
end)("alpha beta gamma delta") -- Call the expression formed by the function block.
) -- End the print parameter list
lgscript/lua_functions.txt · Last modified: 2011/05/15 21:44 by telliamed