Returning Values from Lua Functions

Return Values

Values are returned by functions using the return statement, optionally followed by a value or a comma-separated sequence of two or more values. Let's take a quick at how this works with the following function definition which returns two values: local two = function () return 1 , 2 end We can collect both return values by defining variables for each expected value: local a , b = two () print ( a ) -- 1 print ( b ) -- 2 Unlike some programming languages, it is not an error to collect a different number of values than the function returns. If we only assign one of the return values to a variable, the left-most return value is assigned, while the others are simply ignored: local a = two () print ( a ) -- 1 print ( b ) -- nil Likewise, if we assign more values to variables than are returned by the function, the extra variables are simply assigned a value of nil : local a , b , c = two () print ( a ) -- 1 print ( b ) -- 2 print ( c ) -- nil

Arguments

One of the key advantages of functions is that they allow a piece of code to be written then called repeatedly. This is accomplished by allowing arguments to be passed to functions, then have the function work with those arguments to produce the desired output. Most functions are defined to accept a fixed number of arguments . When values are passed to the function they are taken positionally and assigned to the variable name for the corresponding argument. When arguments are passed into a function, they become locally-scoped within the function, just like variables that are defined inside the function definition, which allows Lua to support nesting and recursive functions . Lua is quite forgiving regarding values passed to functions, when a function call contains fewer values than arguments it simply assigns nil to the unused variables. When too many values are passed, it simply ignore them extra values. For example, the following function definition expects 2 values to be passed into the function when it is called: local test = function ( a , b ) print ( a ) print ( b ) end Let's now call this function: print ( test ( 1 , 2 )) which produces the output: 1 2 Ok, as expected. Let's now try calling the function with a single argument: print ( test ( 1 )) which produces the output: 1 nil Whereas many languages will raise an error when a function is called with the incorrect number of arguments, Lua simply assigns nil to unused variables. Finally, let's try passing extra arguments to our function: print ( test ( 1 , 2 , 3 )) which produces the output: 1 2 Again, no error was raised, and the extra argument was simply ignored.

Function Definition

Like most programming languages, Lua supports the ability to add new functionality by implementing functions . At a high-level, functions are "callable units" of code that can optionally accept 1 or more parameters, perform some operations on them, then optionally return 0 or more results. Lua supports two different, but equivalent, styles for defining functions . The first style creates a variable then assigns a function to that variable: -- local name = function(args) local sum = function ( a , b ) -- function body return a + b end The second style is equivalent to the first, but the order of the function keyword and the variable name are reversed. -- local function name(args) local function diff ( a , b ) --function body return a - b end In both cases, the function's arguments are defined as a sequence of 0 or more comma-separated variable names in the function definition. Which style to use is generally a matter of personal coding style, but the second style allows functions to be stored in tables which allows them to operate as "methods" when implementing classes with Lua.

Lua

Lua is a lightweight, cross-platform, high-level programming language that has become increasingly-popular as an embedded scripting language. Lua is often praised as a clean, simple, easy to learn scripting language that is applicable to a wide range of tasks. Today Lua can be found in a wide range of applications ranging from wezterm to xplr and neovim . Let's get started.

Working with Lua Patterns

In the previous section we looked at format strings , which provide a convenient way to create consistent, well-formatted strings that can contain unique values. In this chapter we look at patterns , which are roughly the opposite: patterns allow us to extract values from well-formatted strings. A pattern defines a specification that describes the content of a strings . When a pattern is compared to a "target" string , if the pattern describes the string we say that the target "matches the pattern". Patterns are generally composed of a sequence of smaller patterns , called "atoms". These atoms are arranged in a specific sequence to create the specification. As a simple example, let's build a pattern that matches phone numbers, then we will describe the process in more detail in the coming sections. We will assume phone numbers matching the format: +1(234)567-8910 The first step is to break this string into a sequence of components: +[country code]([area code])[prefix]-[line number] Next, we need to specify each component in terms of regular expressions, then combine them into the pattern. One possible final pattern might be: +%d[(]%d%d%d[)]%d%d%d-%d%d%d%d which is made up of: A literal + The " character class " %d , which specifies that the characters in those locations must be digits, Literal ( and ) surrounding a sequence of 3 digits %d Sequences of 3 and 4 digits, separated by a literal - If we apply this pattern to our target phone number, the target string is returned (which is a truthy value indicating that a match occurred. For comparison, we include a few other target strings with slightly different format, which produce nil (i.e. falsy ) values indicating that a match did not occur. local pattern = "+%d[(]%d%d%d[)]%d%d%d[-]%d%d%d%d" print ( string.match ( "+1(234)567-8910" , pattern )) -- +1(234)567-8910 print ( string.match ( "+1(23)4567-8910" , pattern )) -- nil print ( string.match ( "(234)567-8910" , pattern )) -- nil With that quick introduction, let's learn how to create patterns.

Lua's Reserved Words

Lua defines a number of reserved words , which are words that have special meaning to Lua and therefore cannot be used as identifiers such as variable or function names. It is an error to use any of the following: and break do else elseif end false for function if in local nil not or repeat return then true until while

Lua's Repeat Loop

Like the While Loop , the Repeat Loop is a "condition-controlled" loop. Unlike the While Loop , the Repeat Loop guarantees that the loop body is executed at least one time, then stops when the controlling condition is true . Repeat loops follow the pattern: repeat -- loop body -- repeat as long as boolean expression is true until [ boolean expression ] As a simple example, let's sum up all numbers from 0 to 4 using a repeat loop : local x = 0 local result = 0 repeat result = result + x x = x + 1 until x >= 5 print ( result ) -- 10 The break statement can be used to terminate a repeat loop early, just like a while loop . The following is equivalent to the previous example. local x = 0 local result = 0 repeat result = result + x x = x + 1 if x >= 5 then break end until false print ( result ) -- 10 Note that in this case we set the boolean expression to false , so that it continues to execute until the break is encountered. As while the while loop , care must be taken to prevent infinite loops . Finally, let's implement the final example from the while loop section using a repeat loop , showing that the repeat loop also terminates when a return statement is encountered: local function sum () local x = 0 local result = 0 repeat result = result + x x = x + 1 if x >= 5 then return result end until false end print ( sum ()) -- 10

Lua String Length

Lua includes two methods of determining the length of a string ; the length operator # and the library function string.len . Whereas similar functions in most high-level languages return the length as the number of characters in the string , Lua returns the number of bytes of memory occupied by the string. In many common cases such as ASCII these yield the same result, but case should be taken to watch for unexpected results. Let's take a look at a few examples: local x = "abcd" local y = "ab cd" print ( # x ) -- 4 print ( # y ) -- 5 print ( string.len ( x )) -- 4 print ( y : len ()) -- 5 In this case, we defined two strings containing only ASCII characters, and demonstrated how to find the length using both the length operator and the string.len library function. Both examples are basically the same, although the second example include a space ( " " ) to show that these are counted, just like any other character. Now, let's take a look at a few unicode strings, which can each occupy multiple bytes: local x = "中文" local y = "zhōng wén" local z = "😊" -- careful! print ( # x ) -- 6 print ( # y ) -- 11 print ( # z ) -- 4 print ( string.len ( x )) -- 6 print ( y : len ()) -- 11 print ( z : len ()) -- 4 These are (probably) not the results that we would have expected. Our main point is to make you aware of how Lua treats string length , and how it might produce unexpected results.

Control Structures

Lua implements several of the basic control structures that might be expected in a programming language. Here is a quick summary of the available options, then we will get into the details in the coming sections: Control Type Structure Conditional If-Then Condition-controlled Loop While Condition-controlled Loop Repeat Count-controlled Loop Numeric For Collection-controlled Loop Generic For

Format Strings

unknown_document