This page gives you a quick rundown of how Lua is like if you already know Perl. I found myself particularly enjoying Lua when wearing my Perl hat, thus this page was born. Though Lua's role is very different from Perl, to me Lua is an elegant subset of the great features in the very Perl core plus means to code the rest. A kind of minimalist embedded, alternative Perl if you will. The official quote about it is: Lua gives you the power; you build the mechanisms.
Where as Perl shines in text processing and libraries, Lua is mostly used as an embedded language in C apps, such as games (World of Warcraft and Monkey Island) and screenreaders (Supernova and System Access to Go) to mention a few app areas. Lua library support depends an awful lot on what kind of application you're using the language in. Since the interpreter is only 200 KB in size, however, you can also use Lua's standard library for writing portable scripts that do basic file or text processing tasks based on ANSI C:ish underpinnings.
Rather than generally showing much sample code in detail, I'll run through several important features of Lua compared against Perl, as that's the quickest way to grasping the differences and similarities. For in depth information there's the Lua reference manual and for learning the language properly, the first edition of Programming in Lua for version 5.0 is freely available on-line. Be sure to grab a copy of Lua at lua org for experimentation.
Since the aim was to also clarify concepts new to me as a perler, I'm spending a lot of time and sample code in iterators, coroutines and various fancy ways of doing object orientation in Lua. While I do make heavy referencing to Perl to make things shorter and snappier, you may still be able to understand most of this tutorial coming from Ruby, Python or another object oriented dynamically typed language, just skip the Perl code. Finally, the rundown of the standard library can also serve as a quick reference to what's out there if you're new to Lua. This tutorial was written for Lua 5.1 and assumes familiarity with Perl 5.8.
AccessKey r Returns to the Top
To the Start of the Actual Text
Both languages have the concept of global and local variables in addition to a fairly Spartan set of data types. The major difference is that Lua uses hashes even more than Perl does, which I consider a good thing, as well as not using sigils at all. All lua datatypes are first class, they can be stored in variables and passed to functions quite easily.
Where as Perl variables know that they hold an array, hash or a scalar, Lua variables don't, they merely hold values. In Perl you introduce new local variables with:
my($scalar, @array, %hash);
You do in Lua.
local scalar, array, hash
There are no parens around lists, the my equivalent is local, and no sigils, either. On the down side you cannot have $var and @var but that's small potatoes. Note that Lua statements are separated by line breaks, not semicolons. You can use semicolons to separate multiple statements, say on a single line, if you want to, however.
Variable declarations default to global in both languages. In Perl:
$answer = 42;
in Lua:
answer = 42
Both Perl and Lua use doubles internally to represent numerical data. Perl tries to optimize by using ints as needed while Lua stays firmly in the double domain. This can actually be an advantage. As of Perl 5.10 according to comp.lang.perl.misc the Windows port doesn't have 64-bit long long ints, and so Perl has to continuously convert between int and double to workaround support for large ints. By using doubles for positive and negative integers both very small and very large as well as real numbers, Lua neatly sidesteps the issue while staying minimalist: just a single number type is sufficient. Double arithmetic is quite fast in modern Cpus, too, Lua is often one of the fastest scripting languages around according to bench marks.
Lua's answer to the Perl special scalar value undef is the value nil which is a separate datatype. It signals the lack of a proper value. Unassigned array elements, global variables etc... start out as nil. Assigning nil to anything wipes out the previous value including keys in hashes, thus Lua makes no defined, exists distinction of hash values as Perl does.
To avoid having to use values such as nil and 1 for storing truth, Lua has a Boolean datatype, too, with the useful property that the value true is true and the value false is false. The only other value that is false in the language is nil, and thus storing true can be used as a workaround to storing undef in Perl. Just think of true and false as nice constants for storing truth, rather than a really separate datatype with special operations, and you'll do fine.
Perl's approach to references is that they are typed, they know whether they point to a scalar, array, function or something else. In stead of a single reference datatype, Lua has separate minimalist types for the kinds of references. Their operations are Spartan mostly equality comparisons and operations on the underlying data.
The type userdata is an opaque cookie for C libraries your script doesn't need to care about. The type thread is the handle you use to manipulate Lua's version of Perl's interpreter threads and like user data is just mostly passed to libraries or tucked away in some data structure.
The data type, function, is very much like code refs in Perl. You dereference it by calling it, and that's about it. syntactically it is very much like Perl apart from the sigil:
code ref(arg1, arg2)
Like those of Perl, Lua strings hold a chunk of text and don't allow access to individual characters without library functions. They also support a minimalist subset of regular expressions, with a slightly different syntax, that is quick to master and relatively powerful. Lua is not primarily a text processing language, though.
Lua strings are always passed by reference behind the scenes, where as Perl scalars are copied in function calls if you assign them to my variables. Another major difference is that you can never modify Lua strings in place, in stead the result is a new string. strings are immutable which makes passing them to functions and hashing with strings a whole lot easier. This doesn't mean they would be hard to use, Just assign the new resultant string to a variable as not to lose it.
The only operator in the whole language that is mostly string specific is concatenation which is two dots in stead of one. Thus the Perl code:
$a = $b . $c;
Becomes:
a = b .. c
You should only use concatenation for small strings since previous values are garbage collected resulting in a lot of overhead, as in Java. There are library functions such as join, that have much better performance. all string functions in Lua reside in a global hash called string and will be dealt with later.
For doubles and integers based on them, both Lua and Perl share much the same syntax. You can, for example, use the unary minus or the e notation in both. Both single and double quoted strings of Lua work like double quoted strings of Perl, however. If you don't wish to use C:ish escape sequences you'll have to backslash them. The only reason why single quoted strings are part of Lua is that it makes it easier to put double quotes into strings without backslashing. Do note that you cannot interpolate variables in lua strings, just do a string concatenation in stead. Rather than saying:
print("x is x");
Type in stead:
print("x is " .. x)
Perl's # single line comment is two dashes in Lua:
# this is a comment
becomes:
-- this is a comment.
For constructs spanning multiple lines and supporting nesting Lua has a generic concept called a long bracket. A long bracket is two opening brackets, with 0 to n equals signs in between telling the level of nested long brackets. The closing long bracket is the same but uses closing brackets. Multiline comments are comments starting with a single line comment and a long bracket immediately after it.
--[=[ commented multiline code of long bracket level 1 ]=]
Lua also has heredocs, that are just long bracketed text without the initial comment, i.e.:
print [[ this is a here doc ]]
As in Perl, you do have to unindent here docs or make a modified copy of the string, if you don't want spaces or tabs after the newlines.
Perl has a firm distinction between an ordered list with a length we call an array and an unordered datastructure rapidly mapping strings to scalars called a hash. Yet even Perl uses hashes for a great many things: sparse arrays and long linked lists, sets, trees, maps, named parameters, symbol tables and object orientation, the list goes on and on.
Lua's hash type is called a table and the good news is that you can use it for the very same things Perl hashes are used for. Like Lisp only has a linked list data type, the designers of Lua chose to go with only a hash type they call a table. As a performance optimization, however, hashing with contiguous integer keys is as fast as looking up stuff in a real Perl array would be. Hashing doesn't stringify either: numbers, functions, tables etc... do not lose their identity becoming strings, which makes using them easier. It also makes hashing with ints faster, I reckon.
Unlike the conceptual mess that hashes are in PHP, Lua's hashes, however, are never ordered, just like a hash should be. When you use a hash as an array, you simply happen to be looking up stuff by contiguous integer keys so the data comes out ordered, if you will. Integer indexed contiguous tables we call arrays do have a length, too, which can be retrieved in logarithmic time, I think.
Though it would be tempting to use Lua's table as an array hash monster, both as an array and as a record datatype at the same time for a single variable, do avoid the temptation. a good rule of thumb is to be clear of whether what you are dealing with is an array or a hash, and only keep keys of one type in the table.
Just like Perl has reference constructors for hashes and arrays, Lua has a constructor for tables. A pair of braces is used for that purpose alone.
Inside the braces you can put either key value pairs, lists of values or both. The two languages have a lot in common in terms of syntactic sugar for table literals and indexing. The Perl fat arrow quoting its right side as a string:
my $person = {name = "John", age = 20 }
Has the Lua equivalent:
local person = {name = "John", age = 20 }
But only in table constructors, though. Similarly, an array like:
my @vars = ("foo", "bar", "baz", 42)
Can be written:
local vars = {"foo", "bar", "baz", 42}
Contiguous integer indices are inserted automagically to support array like usage in this second example.
Array indexing in Lua starts from 1, not from $[ as in Perl. Before you scream in horror, let me confess that after having gotten used to it, I'm rather fond of the 1-based counting. It is more natural to think addressing a collection from 1, especially a matrix or the characters of a string i.e. the third character is at index 3. Perl's notion of 0-based indexing harks back to C's pointer arithmetic where array indexing is really an element offset from the start of the array, not an ordinal number denoting the rank of an array element as in 1-based indexing.
The final syntactic shortcut I'm going to cover is a function call as the last, or maybe even the only, element of a table constructor. In such a case all the return values are gathered into an array automatically:
local retvalAsTable = { myFunction() }
No matter which datatype you use to index a hash, syntactically it looks like array indexing in Perl without the sigil:
$person{"name"}
becomes:
person["name"]
Similarly:, the Perl statement:
$position[0]
is expressed in Lua as:
position[1]
Negative integer indexing of an array hashes with negative integer keys. It does not count from the end of the array, like it does in Perl arrays. Negative indexing of positions can be used in string functions, however.
Since symbol tables, record datatypes and many other things do index a hash with a string, Perl offers the syntactic sugar of braces quoting their contents like it was an identifier-like string
:
$person{name}
Lua has the same sugar but rather than brackets you use a period followed by the unquoted string:
person.name
which is sugar for:
person("string")
When it comes to array and hash idioms that Lua does not have, here are some. You cannot slice arrays as such, you'll have to repeat the array name in a list assignment in stead. If this bothers you, it is relatively easy to whip up a wrapper function for particular kinds of slicing.
Also, indexing with nonexistent elements doesn't autovivify arrays or hashes, you just get the value nil back in stead and an error about indexing nil. An explicit assignment is needed to put a table inside a table,
Tables in Lua always produce a single element even in a list assignment, which is a reference to the said table. This makes it very easy to efficiently process tables by reference, without having to use a special syntax for it. All dereferencing for a table is implicit and assignments always affect the reference. You can also override equality, comparisons and many other operators for user objects that are based on tables. To copy the top level of a table to another, an explicit one-liner for-loop is needed, though you could again do a wrapper.
It is also possible to explode tables indexed with integer keys into a list of values, losing their identity, which is the way arrays work in Perl. To do that, you use the unpack function with a table. It can also take extra arguments specifying the start and end indices of a table slice to be exploded. As a simple example:
foo(@args );
Would be written in Lua:
foo(unpack(args))
It should go without saying that the magic of assigning a list of key value pairs to a hash does not work in Lua. You are free to write a hash creator function that goes through consecutive pairs of array elements inserting them in a hash, however. The same goes for qw lists based on string literals.
Regarding the functions available for tables, apart from builtins such as next, pairs and ipairs, they live in a global table called table, no surprise there. and again I'll go through these functions later on.
The basic idea in list assignments is much the same in Lua and Perl. Both have lists on the left and right side of an equals sign, such that the right side is evaluated first and then all the assignments are made. Lua does not need parens around the lists, though. The Perl code:
$i, $j) = ($j, $i)
Is cleaned down to:
i, j = j, i
Further in common is the handling of missing or extra list elements. If there are more elements on the right, the extras are thrown away. IF there's more stuff on the left, the rest get nil in Lua, and undef in Perl.
The only major difference is in handling of lists, in Perl speak. Where as Perl functions with multiple return values insert all the return values in the list, in Lua only the first return value is inserted. In fact this is also how the code looks like, a single value on the right being assigned to a single value on the left. Exceptionally if a function with multiple return values is the last, or only, element on the right hand side, then all of its values are added on the list that is assigned. Returning a table from a function, or assigning to a table is always dealt with as assigning a single element, since, as I said, tables are handled as "scalar" references to the data.
Lua supports neither list slicing nor list context detectable in a function, in the general case. You can, however, use a function call as a statement, in void context, throwing away all the return values. similarly, if you put a function call in parens, only the first item of its return list is returned, even if it was the last element of a list assignment. That's sort of reminiscent of scalar context. Though context here is what the caller does with the return values, not something the callee can even detect and take action on as in Perl. At any rate, the Perl code:
$x = (myFunction())[0];
Is roughly equivalent to the Lua code:
x = ( myFunction() )
The same fast and hard rules for assignment I've covered here apply in a couple of other situations, too. In the return statement for a function, the arguments of a function call and the list after the in part of a for in expression. While that list is normally just a single function call producing the iterator function, it can be a list of expressions, too.
Where as Perl relies on punctuation to separate statements and uses braces for blocks, Lua relies more on white space and English reserved words. To me, this is an advantage, since I program Lua using synthetic speech legally blind.
Perl uses braces around blocks and parens around conditions as in:
while(condition) { statements }
Lua needs nothing around conditions and uses the words do and end for many block structures:
while condition do statements end
In Perl the do until structure is actually a special form of a function call as statement modifier:
do { codeblock } until condition
Lua, on the other hand, has a true control structure for the same thing:
repeat statements until condition
Perl does have a rich array of loop control keywords: next, last and redo as well as goto, all of which support labels. The only such keyword in lua is break, which is equivalent to last. This is arguably the most important of this lot, too.
On a side note, Lua has no until loop whose condition is tested at the top nor unless. Use the not operator for the reverse test in if or while.
If, else if and else structures work similarly in both languages. The only major difference is in the keywords Lua uses to start the blocks, then, and to end it, end. Thus the Lua equivalents of the Perl expressions_:
if(condition) { statements }
elsif(condition) { more statements }
if ...
elsif ...
else
{
statements
}
Are as follows:
if condition then statements end if condition then statements elseif condition then statements end if condition then ... elseif condition then ... else statements end
Lua's syntax is reasonably straightforward here, as long as you remember to follow if and elseif with then, and to end the final branch with an end. also Lua spells elseif with two letters e, not just one-.
For ranges, Perl has a separate operator .., that builds up lists between its endpoints.
for( 1 .. 10 )
It has been optimized not to burn memory when part of a for loop. Lua, though, has a lazy control structure for the job, in stead of an operator:
for variable = initialValue, finalValue, stepSize
All three expressions are evaluated only once, only the current element is stored and the optional step size argument let's you easily sweep up and down in sizes other than its default 1, too.
Perl's for builds up the list to be iterated all at once, and allows only a single iterator variable as part of the loop. Again, Lua's mechanism is lazy, more generic in that it is easy to build generic iterators working with the for, and supports multiple iterator variables. Where as you say in Perl:
for my $variable (@list) { statements }
The Lua equivalent for iterating an array is:
for index, variable in ipairs(list ) do statements end
Where ipairs is a built-in manufacturing a suitable callback function for numerical indices. The callback returns both the numerical index and its value one at a time. Note that you can just as well use a single iterator variable for only the numerical indices of an array as in:
for i in ipairs(array) -- and so on
For iterating a hash one of the Perl idioms is:
while(my($key, $value) = each %hash)
Since hashes are just tables, Lua employs the same for in iterator structure as above. You should use the generic table iterator called pairs, for iterating all types of keys and their values, not just the contiguous numerical indices:
for key, value in pairs(hash)
Because of how iterators in Lua work, returning copies of elements they go through, iterated hash values aren't aliases the same way they are in Perl's for. the only exception here are tables inside tables, which are assigned by reference anyway. To modify values whose kind is not table in a for in loop, index the iterated table with a key you get from the iterator, and assign to the value you get as a result of indexing. For example, doubling all the table values in Perl:
my @numbers = qw|1 2 4 8|; $_ = 2 * $_ for @numbers; print "@numbers";
Would be carried out as follows in Lua:
local numbers = {1, 2, 4, 8}
for i, number in ipairs(numbers) do numbers[i] = 2 * number end
for i, number in ipairs(numbers) do io.write(number .. " ") end
It is also worthy of note that the very same idiom of modifying the values works equally well for hashes. the only difference is the iterator, pairs, in stead of ipairs. Of course, pairs works for arrays, too, it just goes through the integer keys of the hash in an apparently random order which would not matter in many element by element processing tasks. However, it does in printing.
io.write here is a function that writes to the default file handle unformatted, where as print inserts tabs between its arguments and a newline at the end. Print always prints to stdout, too, but the default file handle for the io operations can easily be changed. The stringified representation of tables is not pretty in print, but you can override that for any table based objects of your own.
Perl's scalar types and their operators have a string number duality pervasive across the whole language. String and number conversions are implicit based on whether you use string or number operators to work on the operands. Relational operators and concatenation have this duality where as arithmetic does not unless you view .. as addition and x as multiplication.
In Lua there's only one set of operators for both strings and numbers. While it does make working with strings and numbers slightly more cumbersome, it is more advantageous to have a single set of operators for user types. Though Perl's duality works great for scalars, it is challenging to come up with both obvious string and number overloads for most user types. having only one set of operators in Lua sidesteps the issue at the cost of some convenience.
As a nod to the Perl string number dualism, however, arithmetic operators in Lua do numerify their operands, and string concatenation does stringify. additionally, the naming of table fields that control operator overloading of relational operators, such as __le, and __gt, is directly analogous with the names of string relational operators in Perl.
But this is all the automagic out there. String string and number number comparisons and equality are defined, of course, but comparing items of different types is viewed as a runtime error. To make sure this doesn't happen you can use the type function to determine the type of operands if not knowing it, which returns strings such as function, nil, number and table. Plus you can use the built-ins tonumber and tostring before doing the comparisons to force the operands to be of the same type. Tonumber will return nil if the object cannot be turned into a number.
Lua's arithmetic operators are very much like those of Perl and quite traditional, too. Addition (+), unary and binary minus (-), multiplication (*), division (/) and modulo (%) are all defined as usual. The caret ^ is used for exponentiation. There are no bitwise operators in Lua, but they can be implemented in C, if and when needed in a particular application area.
Arithmetic operators are only defined for number types and can be overridden for user types that are based on tables. However, they have no meaning for ordinary Lua tables, strings, Booleans, functions and the rest of the lot.
We covered assignment already but Perl does have augmented assignment for binary operators, as well as pre and post increment and decrement. Lua has none of that, since these augmented forms only add programmer convenience, and having fewer operators makes the language quicker to learn, and easier to memorize well. Thus Perl statements such as:
++$i; $i *= $j;
Are expressed in Lua as:
i = i + 1 i = i * j
The set of relational operators works for strings, numbers and user types. They are quite conventional, too. <, <=, ==, >= and > are supported with their usual meanings. Inequality is ~=, that is like the binding operator in Perl but the tilde being on the other side. These operators are only defined for operands whose types are the same.
Lua has logical not, or and the logical and, which again borrow from their Perl counterparts. For:
my $i = $i or $j;
The lua equivalent is:
local i = i or j
Returning its final value and being short-circuited much as in Perl, too. The one major difference is that you can only use the logical operators for flow control in conditions and as an r-value of assignments, not as an l-value or statement. Thus the Lua equivalent of Perl's:
exp1 or exp2;
Would be written:
if not exp1 then exp2 end
Which scales better for more elaborate error handling yet is almost as brief as or die, for the simple case. For merely dying with an error message, you can also do.
assert(not exp, value,)
As an equivalent of Perl's:
length($string); my $length = @array;
Lua takes advantage of a dedicated length operator #. The expressions become:
# string lenth = # table
Length can also be defined for user types but is not very well defined with tables for non-integer keys or holes, however. As mentioned earlier, strings use two dots for concatenation but this cannot be used for other built-in Lua datatypes.
Lua has a fairly simple syntax for functions with conventional named parameters, unlike Perl. While it doesn't have Perlish prototypes and list context, like Perl it has the means of creating hierh order and anonymous functions, lexical closure, supporting variable numbers of arguments, and even includes extras such as optimized tail recursion, coroutines and a language-wide contract for iterators.
To demonstrate basic uses of functions, let's write a function to return the maximum value and its index given a table with homogenous data in it. The Perl version is:
sub max {
return unless @_;
my($max, $index) = (shift, $[);
for my $i ($[ .. $#_) {
($max, $index) = ($_[$i], $i) if $_[$i] > $max;
} # for
return ($max, $index);
} # sub
Using Lua you can write much the same thing as:
function max(table) if not # table then return end local max, index = table[1], 1 for i, element in ipairs(table) do if element > max then max, index = element, i end end return max, index end
Apart from the keyword differences of sub Vs function, the basic idea is much the same. Lua's arguments are always named local variables in the function with no need for an explicit assignment to my variables as in Perl. Note that the rules of list assignments in Lua also govern the expressions in the list of items to be returned from a function.
Without an explicit return Perl returns the value of the last statement executed, while Lua simply returns nil. If you call the Perl function without arguments, then there are no arguments in the @_ array. In Lua the named parameters that were not assigned a value positionally receive the value nil, much as in the Perl idiom of assigning @_ to a bunch of my variables. Similarly, when calling a function, only the last expression in the function's argument list may put multiple values in the list of arguments the function is called with. In brief the rules of calling a function, receiving the function parameters, and returning values from a function, are exactly the same as for list assignments. And that's all you need to know. Lua functions have no Perlish prototypes or in fact any other kinds of exceptions in terms of calling them, either.
Not an exception, really, but there's a bit of syntactic sugar for calling functions that's invisible in the function itself but makes it nicer to write Lua code. These rules also make it more straight forward to use eval:ed Lua code as a data description or configuration language. The rules boil down to this. Only, and only if, the sole parameter of a function is a string literal or a table constructor, the parens around the function argument may be omitted. Thus you can write:
print "Hello, World!"
As well as
myFunc {table = t, index = 13, foo = bar }
to emulate passing named arguments rather than relying on their position.
Finally, if you do wish to emulate Perl's @_ construct for variable number of arguments, such as print, Lua is up to that, too, with a quirky syntax. In the last parameter of the function prototype, and in expressions within the function, you can use three periods, ..., as a place holder for all the variable arguments being inserted as a list of values in there much like what you get with unpack(table). The reason why the arguments don't come in a table is efficiency. If you merely wish to pass on the very same arguments to another function, you don't have to copy the variable argument list in a table at all. And if you do wish to put the list in a table, you can use this idiom.
local args = { ... }
Taking advantage of the fact that the table constructor with a list of values inserts them in integer indices automatically.
Since functions are first class values in Lua , it is easy to emulate the functional side of Perl. The Lua standard library doesn't have grep but it is easy to write one. Here we go:
function grep(list, willDo)
local passed = { }
for i, element in ipairs(list) do
if willDo(element) then table.insert(passed, element) end
end
return passed
end
The implementation is straight forward relying on the callback returning truth values as well as using the ipairs iterator. It assumes the second argument passed to the function is either a code ref that is a function, or a user type that can be called like a function. table.insert is a library function that given an array and an element, pushes the element at the end of the array analogously to Perl's push with only two arguments.
To use grep in a Perlish way requires that we use a short anonymous function, in stead of writing a separate named one, too. In Lua the syntax for anonymous functions is almost exactly like that of ordinary functions. The only difference is that you leave out the name of the function, but not its prototype.
This does mean that anonymous functions are a bit more wordy than in Perl. It also means that even a single statement anonymous function will have to use the return keyword, and for any arguments passed, will have to give them names as function parameters. While these rules do make it quite wordy to do very simple functional programming, the requirement tends to make anonymous functions more readable and self-documenting. A sorting function, for instance, can use any names of two arguments you give to your callback, as opposed to the Perl package globals $a and $b, for example.
To demonstrate using grep, the following code builds a list, filters only the even numbers, and prints them tab separated using unpack to explode a table :
local list = {1, 2, 7, 24, 57, 89, 93, 141, 244 }
local filtered = grep(list, function( i ) return (i % 2) == 0 end )
print(unpack(filtered) )
Also note the equality comparison after the modulo. That is needed as modulo 2 for an even number is 0, which is true as far as Lua is concerned.
Both Perl and Lua allow you to define anonymous functions inside of other functions. If the inner functions thus defined refer to local variables of the outer function, copies of the values in these variables become a permanent part of the inner function's state persisting across function calls. This happens every time a new anonymous function is created. The canonical, though useless, example is a counter counting say from 0 to n as defined by the outer function. The lua code for it is something like this:
function makeCounter(n) local count = 0 return function () if count > n then error "maximum count reached" end local value = count count = count + 1 return value end end
As for real examples of where closures get used, they are great when you need to manufacture functions that are parameterized in some way and can carry state. Perl's memoize module is based on them, for example. Closures can also be used as one model for object orientation, for true privacy in objects, and as simple means of keeping state in iterators, where full blown classes would be overkill.
As a special application of functions, Lua supports co-operative multi-tasking in Windows 3.1 style, where the program is in control of which thread of execution runs and how long. The design is based on coroutines, often referred to as threads in Lua, whose closest Perl analog are interpreter threads. I'm using the terms coroutine and thread interchangeably here.
The function coroutine.create given a function f, creates a coroutine object c for that function:
local c = coroutine.create(f)
Next, calling coroutine.resume for c with extra arguments a:
coroutine.resume(c, a)
Calls function f normally behind the scenes. But to make coroutines worthwhile, the magic happens in function f. In stead of returning, which makes the coroutine die, you use the blocking coroutine.yield function that's highly magical in f:
function f(a) .... coroutine.yield(r) .... end
coroutine.yield is like return in that the execution of f stops, control returns to whoever called f, and any return values such as r are also returned from resume. However, the function call f is only suspended.
When whoever called f calls resume for f again as in:
coroutine.resume(c, b)
coroutine.yield in f returns b, and the function f continues its execution as if nothing happened other than yield returning the arguments passed to resume.
I like to think of coroutines as follows. create is their constructor. The initial resume is just a funny way to call a function. after the initial call yield is like a return escaping to its caller, and subsequent resumes are like subsequent function calls, that rather than starting at the top, come back to where yield left off. The state of Lua threads could be viewed as the yielding functions local variables, call stack and program counter. Global variables can easily be modified from all Lua threads, though, so you probably should rather use yield and resume to exchange data.
If coming from Ruby, which I also like almost as much as Perl, forget what you know about yield. Lua's meaning for it is quite different due to the return to the caller. Where as yield and code blocks of Ruby 1.8, at least, are just syntactically fancy ways of writing callback functions and implementing callback based subroutines.
As a rather artificial example here are coroutines printing hi ho and foo bar, such that they interrupt each other, as though you were threading. The main program is in control and the coroutine allowed to run is determined pseudo-randomly, just for the fun of it: Normally you do wish to orchestrate exactly which coroutine runs and when, of course, which is advantageous in not having to worry about synchronization issues. The decision to add a bit of randomness to the resume calls was made due to wishing to emulate how more conventional threading looks like:
function printer(first, second) coroutine.yield() while true do print(first) coroutine.yield(first) print(second) coroutine.yield(second) end end local c1 = coroutine.create(printer) local c2 = coroutine.create(printer) coroutine.resume(c1, "hi", "ho") coroutine.resume(c2, "foo", "bar") math.randomseed( os.time() ) for i = 1, 30 do if math.random(2) == 1 then coroutine.resume(c1) else coroutine.resume(c2) end end
Note that the initial yield is there to prevent the coroutine doing much work when it is initialized with the resume called the first time. The real work happens only after the first resume, yield pair. At a more general level, whether you yield once before doing real work depends on whether the first and the rest of your calls to the coroutine are similar in arguments.
As in threading programs in Java, for example, the coroutines themselves run in an infinite loop and are garbage collected by the coroutine objects getting out of scope. Also the math functions here, are used for random number generation from 1 to n and seeding the generator with the current time in epoch seconds, think of rand and srand in Perl, or C even.
The syntax of Lua's generic for loop is:
for variableList in expressionList do block end
An iterator, then, is a callback function whose job is to produce the next element in a sequence to be iterated, every time the function is called. The function is called until it returns nil, and it may also return more than one value at a time, which get list assigned to the variables on the left side of the for itself before the block is run.
Obviously, an iterator function needs to carry some state to be able to produce a different element in the sequence each time. To help with this, Lua's for in iterator contract carries the state in the arguments passed to the callback function.
The function is always called with two arguments. The first is the state variable, that's meaningless to Lua in iteration, but using which the function may keep any extra state it needs such as a table being traversed. The second argument is the first value from the previous time the function returned, which should help in yielding the next element in the sequence.
Lua also does some other magic before and between the calls to the iterator function. Using the expression list on the right of the for in, it assumes that its first value is the callback function, the second value the value of the state variable and the third and final value is what the second argument to the callback is set, when it is called the first time. Thus the expression list initializes the callback, state and previous value before iteration. Lastly, between calls to the callback, its return values are list assigned, the block gets run as long as the first value is not nil and the function is called again with the state and the first value of its previous return. That's almost all there is to iterators on the surface.
As a common idiom in Lua, the expression list on the right is typically just a single function call you pass some arguments about the iteration, such as a table, and which then happens to return the callback, initial state and initial previous value. This is easier for the user who need not know about initializing the state and previous value at all.
To demonstrate iterators, let's write a lazy version of Perl's map working with Lua's for loop,. Rather than flattening multiple return values in the mapped list, they are assigned to the variables on the left of the for in loop, additionally, let's make the first variable of the for in the ordinal number of the element being mapped followed by anything the callback of map should return. The Lua code for our map would be as follows:
function mapper(state, previous)
local i = previous + 1
local input = state.table[i]
if input == nil then return end
return i, state.callback( input )
end
function map(table, callback)
return mapper, {table = table, callback = callback }, 0
end
The mapper function is just a constructor for an iterator. Its first return value is the actual iterator function called mapper. The second value, the state, is a table we cram the map callback function and table being mapped into. Thirdly and finally the initial value for the iterator is returned which is 0, one less the index of the first element we're going through.
The mapper function itself is more subtle. The second argument of mapper, and its first return value is what keeps the loop going. That is increasing the index we're going through by one and getting back the increased index on the next call. We know iteration should end when our integer index yields a nil table element, at which point we've run off the end of the array and merely do a plain return, returning nil and stopping the iteration. Pay attention to how we use the Lua idiom of hashing to a table with strings to get at the actual callback with a clean syntax, and the table we're traversing.
To demonstrate actual usage of the map, here's code to go through tripled integers and to separate the integer and fractional portions of doubles by using the math.mods function in map:
local int = {1, 2, 4, 7, 14, 35, 84}
local float = {1.1, 2.2, 3.14, 6,1, 7, 8.2, -9.1}
for i, squared in map(int, function (e) return e * e end ) do
print(i, int[i], squared)
end
for i, whole, fractional in map(float, function (e) return math.modf(e) end ) do
print(i, whole, fractional)
end
It isn't really necessary to create a separate constructor function if you make the user put in the state and previous value. Secondly, you can simply return an anonymous iterator function not bothering to invent a name for it.
As an example of an iterator lacking a constructor, consider the next built-in. Given a table t and a key k it returns nil if k is the last key, the first key-value pair if k is nil, and the key-value pair succeeding k otherwise. Essentially it is an iterator function assuming its state holding a table and the previous value being the previous key. Thus you can use next to go through the keys of any table without a separate constructor:
for k, v in next, table do ...
The initial state is the table, and the previous value gets nil then, yielding the first key which yields the next, which yields the next until the iterator is exhausted.
As you may have guessed based on the previous main chapter, you don't necessarily need any of the arguments passed to your iterator function, if your function keeps the state itself. This can easily be done using closures and coroutines, both of which will be shown in this chapter.
Here's a version of map implemented with closures:
function map(table, callback) local i = 0 return function () i = i + 1 local input = table[i] if input == nil then return end return i, callback(input) end end
Apart from the anonymous function and slightly different variable names, the core logic in the map function itself is much the same. All the state is kept in external local variables referred to by the inner function, namely i, table and callback. i is declared explicitly while the rest are parameters of map, that work exactly like local variables, however. If you were to write this in Perl, you would have to assign the arguments of map from @_ to my variables to get the same effect. Lua is cleaner in that this assignment is not needed. this second version of the iterator is less wordy, too, as the actual iterator function returned is both unnamed and argumentless. additionally, you don't need to look up the state in the state table, either. About the only down side is that this version is harder to understand for folks who aren't familiar with closures. the version with the explicit for contract is clear to anyone who knows how callback functions work and what the terms of the contract are.
Perhaps the most natural representation of the map iterator is expressing it with coroutines. Not to do multitasking as such, but for the ability to pause the execution of a function and return to it later on, maintaining its state. The code to make this happen looks like this.
function mapper(table, callback) for i, input in ipairs(table) do coroutine.yield(i, callback(input)) end end function map( ... ) local routine = coroutine.wrap(mapper) routine( ... ) return routine end
The new function coroutine.wrap is central to understanding what's going on. It is a convenience function returning a closure based callback that auto-resumes the created coroutine whenever it is called. This makes it trivial to do callback functions that are coroutines transparently to the user.
This time a constructor function is needed. However, since the iterator is called with the exact same arguments as the constructor, I've chosen to use a variable argument list in stead, merely passing on the list to the coroutine. In the constructor itself a coroutine based callback is instanciated,called once to pass it the arguments of the constructor, namely the table and the callback,andfinally returned as the iterator function to the for in loop.
There's no need to keep any state at all within the coroutine based callback itself. After all, the table and the callback are in the arguments that are local variables. Similarly, going through the table we're mapping is handled by the ipairs iterator and all that's left to do is to yield the mapped arguments back to our caller in the loop itself. The coroutine version is by far the simplest and the most natural way to express the map iterator. However, it might be difficult to understand initially, since coroutines are rarer than closures in dynamically typed languages. It also might not be the fastest option out there.
The key advantage of coroutines is the freedom from state management. That is, you don't need to refer to external local variables or cram the state in a table. Rather, just pause the function in the middle and carry on later as necessary. Because of this it is also easy to exploit other iterator functions without having to emulate the for in loop in Lua by hand, as you'd need to do if using for in or closures.
If you do wish to get rid of the constructor function, that's possible, too, using the same technique as in the closure version. This is probably the briefest implementation so far:
function map(table, callback) local routine = coroutine.wrap(function () for i, input in ipairs(table) do coroutine.yield(i, callback(input)) end end ) return routine end
Lua and Perl are rather similar languages when it comes to implementing modules, objects and operator overloading. Lua, however, manages to merely use tables with some extra functions and syntactic sugar when Perl requires separate magic for type globs, the ISA array, Overload, tied hashes, autoload and blessing among other things. Lua also makes it much easier to create new classes based on prototype objects as demonstrated later in this chapter.
Consider an expression such as:
math.modf(x)
Keeping in mind the syntactic sugar for tables, you may be wondering whether math is actually a global table, indexed with the string "modf". That's exactly how things stand:
math["modf"]
Because of the parens at the end, you may also be wondering whether the value in math["modf"] is just a code ref being called. Again, that's right.
Where as Perl requires you to go through the %:: hash to access packages and to master obscure reference assignments to do aliasing, Lua is quite straightforward. To alias the function as mod, all that's needed is:
mod = math.modf
Declaring a global named mod and assigning the code ref in question to it.
The conclusion we can draw here is that Lua packages, called modules, are just global tables that happen to contain strings mapping stuff to code references, or static data needed by the module. Syntactic sugar makes it easy to call and alias functions, or go through the whole table, even replacing data via assignment. the same is true of built-ins, they are just globals holding code refs e.g.:
print(ipairs) -- prints function: 003754C0
And to override it:
ipairs = function(array) ... end -- some fancy stuff.
To create a simple module, just put code in a dot lua file in the same folder as your code, declare a global table named after the module, and assign functions to string keys of that table. In the assignment, in stead of having to say.
mylib.func1 = function (param1, param2 ) ... end
There's syntactic sugar for that. The following is exactly equivalent with the above:
function mylib.func(param1, param2) ... end
Note that you do have to create the global table before adding functions to it, it does not autovivify.
To make use of the module use the require function. Like Perl's require it takes a string argument and happens at runtime. There's no import list you can pass to modules, though, and like Perl's require the function does not needlessly reload a module, either. Require returns the table implementing the module itself:
require "mylib"
If you do wish to access global variables, Lua's equivalent of Perl's %:: hash is a table called _G. Like that of Perl, the table contains a reference to itself since _G is a global name, too. This makes reflection trivial. How about listing all the global tables that might have modules in them, that's easy:
for name, value in pairs(_G) do if type(value) == "table" then print(name) end end
When you assign to a variable without the local qualifier, what you are actually doing is indexing to _G with the variable name string and assigning to it. fetching values of global variables are accesses to _G, as well.
When you declare a function, it is not really a declaration. rather it is a runtime assignment in the table _G. This:
function f() ... end
Really means this:
_G.f = function () ... end
That's why you'll always have to define functions before calling them in the code.
Lua's closest equivalent of tainted variables may be sandboxed environments. If you have an untrusted piece of code, you wouldn't want it accessing everything in _G, such as file functions, would you. Using functions called setfenv and getfenv, with an f, you can set the equivalent of _G for a function, where the so called global variables are looked up in the table you specify. If you only wish to give access to ipairs and print, with none of the other built-ins or tables available for a function, you can do something like this:
setfenv(untrusted, {ipairs = ipairs, print = print })
Now untrusted cannot use string functions at all, for example. Neither can it use getfenv to get its own environment or setfenv to set it to something else. Since _G is not part of its environment, untrusted cannot dabble with global variables, either. You may also give setfenv a number denoting a stack level of a function whose environment is set where 1 is the function calling setfenv. Of course, nothing stops you from building elaborate environment tables programmatically, say based on naming conventions, before using setfenv.
Lua has no main function at all, rather all Lua code is run from C code conceptually. Lua code is dealt with in chunks which may be strings or files (modules) loaded with functions such as loadfile and loadstring. Loadstring can be used to eval code and loadfile is probably used by Lua's require function.
A chunk, such as a file, is from Lua's point of view an anonymous function with a variable number of arguments, meaning you can return from it, receive arguments and declare locals too. Thus locals at the top level of a file are much like Perl's top-level my variables, rather than our variables.
When you call lua code from the Lua shell the variable arguments ... contain the command line arguments. In a module loaded by require the only argument passed to the module is the basename of its file.
Setfenv is sometimes handy in modules, too. Calling
setfenv(1, mylib)At the top level of a module, makes the anonymous function that's the chunk of code in the module, to make all global accesses in its own table. This prevents you from polluting the global namespace by accident, and makes it easy to keep static data in the module table. However, it also prevents you from accessing any other globals. The simplest work-around is to assign the global table to a local first:
local _g = _g
Before using setfenv, that is.
There are other advantages in setting the environment. When you declare a function inside a function, the environment is inherited, too, meaning all the functions in a module inherit the top level environment, i.e. they don't use globals. And what's more, you don't have to repeat the module name in function definitions, either, since any so called global functions go automatically to the module table after the above setfenv.
For the simple case of setting the module to be its own environment and creating a global table after the module name there's a built-in called module doing the work for you. Its sole argument is the module name determining the name of the table being created in _G. module does other neat things, too, such as setting up fields that make require also return the module table itself to the caller.
If you pass the variable arguments handed to your chunk by require to the module function, Lua creates the module table named after the module filename. The name of the module is easily changed by changing the file name, then, and the name of the global module table need not be hardcoded within the module itself. Module can also take a second argument which is a callback function. If you do wish the module to be able to access globals but assign to the module table rather than _G, you can give the code ref package.seeall as the second argument of module. In that case your module is looked into first but if a field is not found there, the global namespace is tried as well. Finally, the module function sets up new fields to your module table _M to refer to the module itself, _NAME to store the name of the module, which you cannot get from a table reference and _PACKAGEE to store all but the last dot separated component of the module name. These are conventions in Lua 5.1 modules, as is updating package.loaded[modname] with a reference to the module table.
To show how easy it is to create basic modules, let us emulate Perl's push, pop, shift an unshift for Lua arrays in a module. Here we go:
module(..., package.seeall)
ins, del = table.insert, table.remove
function pop(ar) return del(ar) end
function shift(ar) return del(ar, 1) end
function push(ar, ...)
for i, v in ipairs { ... } do ins(ar, v) end
return # ar
end
function unshift(ar, ...)
local new = { ... }
for i = # new, 1, -1 do table.insert(ar, 1, new[i]) end
return # ar
end
Do note the idiom of not hardcoding the module table name anywhere. And as module set up the environment for the code, all defined functions go to the said table.
as for the library functions used, all table functions take a table as the first argument. With two arguments insert puts the second at the end like push, with three arguments, the second is the index, the third the value, and the array is expanded as needed. similarly remove removes the last value as pop does with only one argument, and with two arguments the second is the index. The array is contracted if needed.
Lua uses tables to model objects analogously to how Perl uses hashes. Unlike Perl, though, Lua uses the same mechanism for operator overloading and object orientation (blessing). It is a pair of builtins called setmetatable and getmetatable, which allow you to control how operations on a particular table are to be performed. The table controlling these operations mapping strings to callbacks is known as a met table in Lua speak, but I tend to think of it as an operation table. At any rate, get gets the current met table for a table and set sets a new one. The format of the table reminds me of the format of the import list of Perl's overload.pm, with string keys for names of operations and callback functions as their values. All Keynames start with two underscores and there are names like add, concat, length, gt, call, index and newindex to mention a few. All of these callbacks are better and more concisely documented in the reference manual, and so won't be covered here. the once I do go through are index and newindex, since they are needed in object oriented programming. The built-ins rawget, rawset and rawequal can be used to perform table indexing, assignment and reference equality comparisons without triggering any so called meta methods, that is overloaded operations.
Let's recap what we know about Lua modules so far. Packages are just tables mapping strings to callbacks and tables can also be used to Perlishly model objects. Three pieces of the puzzle, equivalent to ->, bless and ISA, however, are missing.
To demonstrate let's attempt to create a person object with getters and setters for a name.
module(..., package.seeall)
function new() return {name = "John Doe" } end
function getName(self) return self.name end
function setName(self, new) self.name = new end
You can use it, but the syntax is not pretty. That is:
local p = modname.new()
To construct:
modname.getName(p)To get the name and so on. It would be nice to be able to omit the module name, and use the name of the object in stead.
Just like Perl has the arrow operator for blessed references for implementing method calls, Lua has the colon operator for passing an implicit first argument to methods, which is the object. While the arrow operator for Perl objects requires blessed references to know which package, or module,, to look into, Lua's method call syntax is just syntactic sugar. It knows nothing about any package. This:
t:f(arg)
is exactly equivalent to this:
t.f(t, arg)
Which means:
t["f"](t, arg)
In other words, the colon operator with the object o, function name f and arguments a, means take f to be a string, look up its value in o, call the result as a function, and pass o and a as ARGUMENTS. Obviously O must be a table for the table indexing to succeed.
But trying out the method syntax on the constructed person object fails miserably:
p:setName("Jane")
It complaining that the table key of our object, setName, is nil. which is true. Rather, we'd like to call getName in the module who created p in the first place. In Perl, you use bless to tell a blessed reference in which package it should look up its method calls. In Lua, you overload the particular table's indexing operator to look up stuff in the module if it cannot find it in the table, object, itself:
The two overridable table operations, akin to tied hashes, are index, for accessing a table field that doesn't exist, and newindex for assigning to such a field. overloading index in such a manner that it looks up the getname field that it didn't find in the object, in the class in stead, is carried out by modifying the constructor.
function new(self)
local data = {name = "John Doe" }
setmetatable(data, {__index = self })
return data
end
The constructor is then called:
local p = modname:new()
Where modname is whatever filename you used for the module. Which really means:
local p = modname.new(modname)
And after that you can call methods as expected:/p>
p:setName "Jane"
Comparing our constructor with that of a Perl object. In both cases we create a table to hold the object data and return it. Before returning we use bless in Perl to associate the object with the class and the setmetatable function in Lua, for the very same thing, implemented differently.
Where as class methods in Perl get the name of the class as self, what Lua methods get is what the global standing for the class name stands for. Namely the class table, which can then be set as the table to look into on not finding a field in the object. What the expression:
setmetatable(data, {__index = self })
Does is set a table to the __index field of the met table controlling the operator overloading of our object. assigning a table means if you didn't find the key, most likely the name of a string pointing to a code ref, in data, try to find it in self, our class table. This association is what bless is all about, too. Another way to think of setmetatable is as giving a common identity. Though each object has a separate met table, they all look the same, and so objects sharing the same operations are viewed as essentially belonging to the same class. Any differences are manifested in the object table itself, which holds the object's data.
Single Inheritance is also based on chained operator overloading. That is, set the super class to be the meta table of the sub class. This instructs Lua as follows: if you didn't find the field in the object, or it was not defined in our sub class, have a look in the super class, too. This has the same effect as assigning a single class name in Perl's' the ISA array, but again the implementation differs.
For multiple inheritance you need to decide which super class to look into first. If you assign the metatable's __index field a function rather than a table, then that function is called with the object and key as arguments. You can then arrange the desired kind of inheritance scheme in the callback function. This is more flexible than the ISA array with multiple classes in it. The __index field can also be used to emulate autoload for anything missing in the class by writing a suitable dispatch function and putting it in __index.
The __newindex field works very much like index but controls assignment to new fields. You can easily use it to, say, disallow assigning new data to a class or take any other action, such as running a setter behind the scenes.
Although it is recommended to use the module function in Lua, you can of course create your own global table and hardcode its name in each and every method. There's a syntactic shortcut for this case, If your definition looks like it is defining a method with the colon:
table:function(arg)
It is equivalent to:
table.function(self, arg)
I rather like the Perlish way of the explicit self parameter, however, and it plays nicer with the module function.
To illustrate the concepts rather than the implementation, let's create a person class with getters and setters for a name, and an overloaded == operator. Plus a subclass that adds a setter for the age and updates the equality operation accordingly.
The prototype based method is probably the most straightforward OOP technique in Lua. Yet even in this design there are surprisingly many design decisions. The person class is as follows:
module(..., package.seeall)
__index = _M
function getName(self) return self.name end
function setName(self, new) self.name = new end
function __eq(self, another) return self:getName() == another:getName() end
function new(self)
local data = {name = "John" }
setmetatable(data, self)
return data
end
Firstly, the class name is not hardcoded anywhere, it is based on the file name which is the sole argument in the var arg list ... We also use the module function to create our module table which happens to populate module fields such as _M for the module itself and _NAME for the module table name. module also sets up the __index field of the module table's met table such that it looks into _G. Thus we already have a form of inheritance, if there's not something in the module table, look it up in the global table. But that is not true of assignments since __newindex is not set, that is assigning to any non-locals assigns to fields of our module table, as that's the environment of our chunk, as set by module. So any functions we don't explicitly put in a table, that would be global, go in our module in stead, which is very handy.
We are going to use the module itself to define its overloaded operations, so module is its own met table. That's why we populate the __index field of module to point to the module itself.
The getname and setName methods are straight forward, and use an explicit self parameter to do their job as usual. Next comes the __eq meta method, which just looks like a method with two arguments to be compared, the first being self and the left operand of ==, another being the second argument, which is the right operand.
The only missing piece of the puzzle is the constructor. The argument is the class table. Just like in Perl, we create a local to hold our data, associate the data with the class and return the class. The association is done by setting the met table of our table holding the object data to self, our module table. Self is the module table, not a class name, and rather than bless magic, we merely use overloaded table indexing for looking up stuff in the class.
In terms of inheritance indexing an object goes like this. Look in the object which is our table. If the thing, usually string, you seek is not there, look in our module table, in stead. If it is not there, either, look in the global environment.
The subclass for a person with an age parameter and overloaded equality comparison looks as follows:
require "person" -- our super class file name.
module(..., package.seeall)
__index = _M
setmetatable(_M, {__index = person:new() } )
function setAge(self, age) self.age = age end
function __eq(self, another)
local prototype = getmetatable(_M).__index
return prototype.__eq(self, another) and self.age == another.age
end
function new(self)
local data = { age = 18 }
setmetatable(data, self)
return data
end
Many things have stayed the same. The constructor works much the same, although it only creates a table with a single age field and setting self to be its met table. Similarly, __index in the module points to the module itself. The majordifference is what the met table of our module is. It is set once at the top level of the class such that __index points to an instance of our super class, person. Once our object is constructed its inheritance works as follows:
If the thing you seek is not in our object holding only the age field added by our subclass, look in the subclass table itself. if it is not there, look in a person object shared by the whole class, which holds the name field initially shared by all subclass instances. If not there, which is the case if we are looking up a super class method, look in the super class itself. Finally on failure, look in the global environment _G.
So, in stead of associating a subclass with a super class table, we associate it with a super class instance, which is associated to a super class table because of how super class instances are constructed. This results in data fields of super class instances being inherited, too, rather than just the super class methods via a table lookup. This scheme also has the advantage that no super class constructor needs to be called explicitly in the subclass.
So, a data field d of an object o initially resides in our super class object which is shared by all subclass instances. If we call a setter method for d, the method gets looked up in the super class table, with self being our object o from the subclass, thus the changed name field is added there. As in Perl, self can be a subclass due to inheritance, which is what happens in such an assignment.
Finally, there's the equality comparison in which we invoke the super class equality comparison and add to that by comparing subclass specific fields. If we fetch what the index field of the met table of our module _M points to. we get at our prototype object or super class instance. calling the __eq function in that table then does go through to our super class table as desired. Note that __eq is called as a function in the super class object's table, but its self parameter is the self of our subclass, which is what inheritance is all about.
There are many different ways the design of the previous subchapter could be changed while still being a valid way to do OOP. In stead of using self as its own met table in both classes, we could have used an anonymous per-object table in stead, putting code refs pointing to the class in there. That way the equals method could easily be called equals, in the class itself. In that per object met table we also could have set the index field to self, avoiding the assignment at the top of the file as it would happen in the constructor.
Another way to change the design would be to replace the subclass module table with the instance of the prototype object directly. This would make the subclass methods and shared data live in the same table avoiding one extra table lookup on the way to the super class.
Thirdly and finally, A Perlish design with no real prototype object in it, where the super class adds its own data and associates an object with the sub class directly, is also a feasible but less Luaish way of coding OOP. In that design only the subclass needs to be modified as follows. At the top of the file:
local superclass = require "person" -- our super class file name.
module(..., package.seeall)
local setmetatable = setmetatable -- Next statement loses access to it.
__index = _M
setmetatable(_M, { __index = superclass } )
require returns the class table so this is a good way to expose the superclass to the rest of the module via lexical closure. Afther the package.seeall has done its job, the __index field of _M points to _G and the table _M itself is where non-local variables are looked up. If we were to say:
__index = _M
So that _M can be its own met table, looking objects in the class, followed by:
setmetatable(_M, { __index = superclass } )
So that anything not in _M is looked in the super class, we would be in trouble. After the first statement _M is its own met table. So when we are to look up:
setmetatable ...
To set the subclass, superclass relationship, setmetatable is not found in _M, and since the met table of _M is _M, not _G, we can no longer get to _G. The workaround is to say:
local setmetatable = setmetatable
So we can then call:
setmetatable(_M, { __index = superclass } )
Restoring the subclass access to the super class, which has access to _G again.
Within the constructor, we call our superclass constructor with the subclass self as parameter. This puts all the super class specific object data to our object, yet the object is associated with our subclass, which knows how to get to the superclass. That's all that's needed to do things in a more Perlish way.
For more complex Perl designs, it is customary to define a generic constructor with an init method call in it, so init can be overridden in subclasses. Modifying onwards from the previous example, the necessary changes are, for the person constructor:
function new(self)
local data = { }
setmetatable(data, self)
data:init()
return data
end
The only difference is the method call to init after the met table has been set to self. Naturally the class needs an init method, too, which becomes.
function init(self) self.name = "John" end
On the subclass side the init is:
function init(self) superclass:init(self) self.age = 18 end
Here superclass is our chunk-scoped local variable referring to what require "person" returned. Without the call to the super class's init, we would only get the subclass data fields in our object. As the subclass already sets _the __index field of _M to point to the superclass at the top of the file, a bit like pushing to Perl's ISA, we can call the superclass constructor with the subclass object. On doing that Lua does not find the new method in the subclass, and calls the superclass version with the subclass self as argument. That in turn causes the init method, which is done after the met table of data is set to the subclass self, to be looked up in the sub class constructing the object properly.
In stead of using the met table mechanism to dispatch methods to classes and subclasses, we can use closures in stead. That is a table of functions holding references to external local variables for the object data. this is fairly obscure and doesn't let you overload operators without metatables, but to show it can be done, what follows is a closure based implementation of the person classes with and without age.
Lua's attitude to privacy is the same as in Perl. Privacy by documentation convention, if you play with the internals, you can blame yourself if things blow up. Since lexical variables aren't globals nor fields in a table, they provide true privacy, unless you go and play with the debug module. It is also rather quick to code simple objects using closures.
Here's the closure based person class:
module(..., package.seeall)
function new()
local myName = "John"
return {
getName = function() return myName end ,
setName = function(n) myName = n end,
equals = function(another) return myName == another.getName() end,
}
end
The module lives in a table just as usual but the only function in the table is the constructor. It sets up some external local variables responsible for the object's state and then merely returns a table mapping strings to anonymous functions that refer to these variables. The anonymous functions are compiled only once when the chunk is, only the local external variables are object specific.
From a syntax point of view, you call closure based objects with the period syntax. the reason being that all of the objects have references to their functions. There's no self parameter, either, as you refer to the object's state directly. The logic in the functions is much the same as previously.
And next in order is the subclass:
require "person" module(..., package.seeall) function new() local myAge = 18 local p = person.new() local superEquals = p.equals p.setAge = function(a) myAge = a end p._getAge = function() return myAge end p.equals = function(another) return superEquals(another) and myAge == another._getAge() end return p end
The design is sort of prototype based in that an object of the super class is created, and new functions are then added to that instance. The new local variable age is responsible for keeping the new state in the subclass. It could be argued the objects don't have a class to begin with, only a table the object constructor lives in.
The interesting thing in the subclass is how the equals method has been implemented. To be able to refer to the superclass version of equals, the code ref is copied to a local variable superEquals before redefinition. That old version, together with a new comparison, is then used in the implementation itself.
But there's a slight problem. To save typing, for the most part, I decided to only create a setter for age, yet a getter is needed, too, and must be added as part of the class. Even the class itself cannot get at the external local variables of the object being compared, named another. That's why a separate _getAge method is added, too. If this method were to be private, you would simply leave it undocumented and perhaps include the underscore to signify privacy by convention.
The name of the Perl idiom inside-out objects comes from the fact that the object's data lives in the class table, sort of. The object does have metatables and a unique identity, i.e. a memory address for an empty table, but the rest of the responsibilities lay in the class table. Inside-out objects turn the responsibilities of classes and objects inside out.
Let's recreate our person class using inside out objects. To further demonstrate the advantages of inside out objects and the usage of weak references, let's add a method to print all alive objects, too. Here we go:
module(..., package.seeall)
__index = _M
local objects = { }
setmetatable(objects, { __mode = "k" })
function new(self)
local data = { }
local lastObject = { name = "John" }
objects[data] = lastObject
setmetatable(data, self)
return data
end
function getName(self) return objects[self].name end
function setName(self, name) objects[self].name = name end
function __eq(self, another)
self, another = objects[self], objects[another]
return self.name == another.name
end
function printObjects(self)
for object in pairs(objects) do
print(object:getName())
end
end
The first strange thing in the class is a top-level table in a local variable called objects. This is where all the objectss' data lives. It is not part of the class table but a local variable in the same chunk as the class. Think of Perl's file-scoped my variables.
In the constructor, a local variable lastObject holds all the data fields and an empty table data, is created with its meta table's index field set to the class. Then, the objects table is indexed with the address of the data table, which is unique, and the lastObject is assigned there. What we have is a table indexed by table references which maps them to the actual data belonging to the object. All that the table reference to the object does is give us a means of refer to the object via the objects table in the class. Additionally, it can dispatch methods to the class table because of a met table we set up. As we see in the getters and setters, whenever the object's data needs to be looked up, we do a lookup in the objects table using a method's self parameter as a key.
What is interesting about inside out objects is how the caller views them. All the caller sees are the methods in the class table and the self parameter, which is just a totally empty table. The data fields are not in self, so they cannot be modified. Actually, the object's fields aren't in the class table, either, but in the local chunk-scoped variable that the caller cannot access without the debug library, that is. So these objects do have true privacy.
As cover so far there's one major weakness (pun intended) in the objects table implementation, the lack of weak references. Consider what happens when an object o that the caller created goes out of scope. Before it goes out of scope, there are two references to the table t we use to look up objects with, one in o, and the other the key in objects[t]. When o goes out of scope, there's still the reference to o in t, and since the reference count is non-zero, our objects are never garbage collected. They've managed to gain eternal life, even if the variables the module user uses to manipulate objects go out of scope.
What we need to use in the table to remedy the problem are references that are ignored in reference counting, called weak references. No matter how many weak references point to an object, as long as there are no hard references left, the object is garbage collected anyway.
Lua's implementation of weak references only allows them to be keys or values in a table, called a weak table. So when an object with weak references is garbage collected, those references are removed from the table, be them keys or values in the table. If you set the __mode field of a met table for a table to k, v or kv, the table is made weak. When an object without non-weak references is garbage collected, both the key and the value are removed from a weak table. The mode determines whether objects referred to by the weak table's keys, values or either keys or values are to be considered, when determining whether there are weak references for a given object.
So, when we say:
setmetatable(objects, { __mode = "k" })
We make the references to the objects that are keys in the objects table weak. Using t to refer to the address of our object table, when Lua determines that objects[t] is the only reference to t left, and that reference is weak, both the value in objets[t], the object data, and the table in address t, the table key, get collected.
To further illustrate the point consider weak values, in stead:
setmetatable(objects, { __mode = "v" })
Now the object data, the value of objects[t], is considered. The only reference to that value is in the objects table. Meaning, that each time Lua gets to our objects table in its incremental garbage collection cycle, all the objects currently in the table die horribly.
One particular Ruby idiom I'm fond of is that of mixin classes. Consider an iterator function that allows you to go through everything in a collection object. Given such a function it is easy to do list processing functions such as map, grep, reduce and the rest of the lot, by using a callback function. This facility is so generic that a Java:ish implementation would probably include an iterator interface. Plus a set of utility methods taking anything implementing that iterator as an argument.
But wouldn't it be nicer, syntactically speaking, to call map, grep etc... directly on the object itself, without even having to know all the methods that utility class includes. This would also be more in line with The Lua and Perlish thinking of methods being polymorphic by name, rather than polymorphic via inheritance. Well, with mixin classes, you can.
The idea is simple. Just write generic methods that assume self to have particular methods to be present by name. Rather than having the user pass in the object implementing these methods, have him or her pass the class to be added to, and mixin the code ref to your method in the class itself. Essentially, mixins are a way of adding methods with particular assumptions about objects to the class of those objects.
Let's demonstrate mixins with an iterator function similar to pairs but that's required to be an object method. Given a class implementing it, let's mix in our coroutine based map function modified to be object oriented an make use of a next method working like pairs. The mixin class follows:
module(..., package.seeall) function map(self, callback) local routine = coroutine.wrap(function () for key, value in self:next() do coroutine.yield( callback(key, value) ) end end ) return routine end function mixin(class) class.map = map end
Apart from using a pairs-like method rather than ipairs, the map iterator should be familiar. All that's left to do is to have a class method you can call to mixin new methods. Since classes are just tables, the actual code to mixin a method could not frankly be much simpler. Given a table, add a mapping from a string to a code ref in there. To use our mixin in the inside out-based person class requires the following lines at the top:
require "map" map.mixin(_M)
The mixed in map should really be called as a class method for clarity. Since our objects already live in a table the iterator method named next is as short as:
function next(self) return pairs(objects) end
Finally using map to go through object's names, remember that object tables come as keys here, would look like:
for name in person:map(function (o) return o:getName() end ) do print(name) end
Again I'm amazed how simple Lua made implementing mixins. Manipulating a class like this in Perl is much harder.
Personally, I've found it quicker for someone to explain to me broadly how a library works compared to reading through all of its reference documentation. With this in mind, here's a cursory glance at the standard libraries Lua offers. string, table, coroutine and os are covered completely, most of io and math is run through, almost all core functions are mentioned apart from low level loading and garbage collection, and the debug library is excluded. Again, the reference manual is your friend.
The key to remember is that when you use Lua stand-alone in the Lua shell, all of the standard libraries have already been included and need not be required separately. Unless otherwise mentioned all of the functions introduced live in the tables indicated by their heading. String functions are in a table named string, table functions are in a table named table and so on. All table names are lowercase.
These functions are built-in in Lua, where as the standard library can easily be excluded when compiling. They live in _G.
For generating errors, assert calls its error with the second argument if its first is false. Given an argument error dies with the argument which is typically a string but other types can be used for richer exception information. The second argument is the level the error is reported in 1 being error's caller, 2 the caller's caller and so on. 0 means no information. The fact that you can blame your caller for errors avoids needing a separate carp module in Lua.
To catch errors analogously to an eval block use pcall, for a protected call. Given a code ref and variable arguments, it calls code ref with the arguments and in case of error returns false followed by the value from error, which are nicely feedable to assert, among other things. With no errors, true and any return values from the code ref are returned. xpcall, perhaps short for extended protected call, is much like call but using another code ref the error handler for its second argument. Rather than being returned directly, errors in the code being run are passed onto the error handler and its return values determine what is returned after false.
Lua's error handling is bare bones but is quite sufficient, since it is used as an embedded language, mostly from C code. If you want to, you are free to pass around elaborate error objets, not just strings, or even throw errors inside a coroutine to mimic exceptions.
getmetatable gets the met table, or operation table, controlling overloaded operations on the table. setmetatable with the table as a second argument sets a new one. Similarly, getfenv gets the environment of a function and setfenv sets a new one. The function may also be a number for referring to the stack 1 for the environment for the function who called setfenv. To avoid triggering operations in metatables given a table rawget index gets the index and rawset index, value sets a new one while rawequal compares two table references.
There are three built-ins for iterating tables. pairs and ipairs manufacture iterators for a table returning a subsequent key and value on each iteration. ipairs sweeps contiguous integer indices from 1 onwards where as pairs goes through all keys in an apparently random order dictated by hashing. next is a low-level function you can use as the iterator callback when building an iterator. With a table t and key k, it returns the first pair k, t[k] for a nil k, nil if k is the last key and the pair following k otherwise.
type returns the type of its argument as a string one of: function, nil, number, table, thread (that is a coroutine) or userdata. tonumber and tostring convert their arguments to strings or numbers. tostring calls the met table field __tostring if its argument has one. tonumber returns nil on failure and takes a base 2 to 36 for interpreting the number, defaulting to 10. Finally print prints its variable arguments tab separated and followed by a new line to stdout, no matter what handles io happens to be using. Call string.format for printf_like formatting or io.write for output to the default file handle without extra tabs or newlines .
For processing lists unpack and select come in handy. unpack explodes or flattens a table, returning a list assignment of all values in a table with integer keys, much like ... in a vararg function. Optional indices i and j determine the integer range being operated on. Select with m and var args, throws away n first arguments returning the rest. If n is a string "#" it returns the number of variable arguments it got.
When it comes to common needs to eval Lua code, dofile runs a Lua chunk from the specified filename or stdin, returning any arguments returned by the chunk i.e. a top-level return. It dies on error so use pcall or xpcall to catch them if you want to. Similarly, loadstring evals a string as Lua code returning the result as a function, or nil followed by an error on failure.
All table functions take the table to be operated on, omitted from the description, as their first argument and operate on tables with contiguous integer keys, that is arrays.
Insert with position and element inserts element in the specified numerical position resizing the table as necessary. If element is nil, assumes position to be an element to be added at the end like push. Remove with an index removes and returns the element at index, resizing the table.
concat given a separator works like Perl's join returning a string you get by joining the table elements stringified with separator between elements. With Optional indices i and j, only the range they specify is operated on. Finally, the legacy function maxn duplicates the length operator.
The last table function out there is sort taking an optional comparison function called with two arguments. The function is to return true if the second comes after the first and defaults to the < operator. The table is treated like an its values are reassigned to new keys such that sweeping through integer indices goes through the values in a sorted order. The sort is unstable and in-place.
This library is modelled very much on C's math.h and works on radians, not degrees:
abs returns the absolute value and modf the integer and fractional parts, while ceil and floor round down and up to the next integer.
As to powers, exp is e to the power of x and pow works like the exponentiation operator while sqrt is the square root. On the logarithm side, there's log10 and the natural logarithm log.
The var arg functions min and max return their largest and smallest arguments. randomseed seeds the random number generator with the specified value, which determines the sequence random(m, n) returns as follows. A double 0 to 1 if both are nil, int from 1 to m if n is nil, or an int from m to n otherwise.
The trigonometric functions atan, atan2, cos, cosh, sin, sinh, tan, tanh work as in most languages. The constants pi is defined, and the rad, deg pair can be used to convert between radians and degrees.
All of these take a coroutine as their first argument unless otherwise mentioned. I'm also assuming you've read the earlier coroutine chapter.
create and wrap take only a code ref and are a way to start using coroutines. Create returns the coroutine object while wrap returns a function f encapsulating the coroutine, that resumes on calling the function an returns back values on a yield. f also propagates errors, if error was called in a coroutine, and throws away the first argument of resume.
resume is the way to both initially call the function based on which the coroutine is created, and also re-enter the function thus returning from a blocking yield. The first return value is a Boolean error code followed by an error message if false. Else the rest of the arguments are return values from return or yield. yield is the way to escape back to the caller passing any arguments as return values from resume, and to block until resumed again, returning any values passed to resume.
running with no arguments returns the currently running coroutine or nil. Finally status given a coroutine gives a stringified status, one of: running, suspended, normal or dead.
The package functions help in creating and loading modules. require and module live in _G rather than the table package. The description here is very high level:
require given a name n looks for a lua file based on it, runs it as a module passing that file (chunk) n as an argument and usually returns the table on which the module is based, that is package.loaded[n]. It makes sure not to reload already loaded modules and dies on error e.g. not finding the module or failing its compilation.
module with a name n creates a module, a global table for it and sets the table it created as the module's global environment, meaning no access to print or global tables, at all. This means a totally self-contained module. For exposing globals for indexing but not assigning to, which is what you'd like to do in 90 % of all cases, pass package.seeall, a code ref doing this magic, as the second argument. most often you just say:
module(..., package.seeall)
For creating a module table after the file name, making global assignments go to that table automagically, and exposing the real globals in _G for reading.
note that module also creates fields in the module table itself _NAME for the table name, _M for the table itself, and _PACKAGE for name minus last dotted component. IT sets package.loaded[n] to hold a reference to the module so as to not have it reloaded.
The rest of the package library resides in package and is a lot about gory module details that aren't needed in very basic use. I'll refer you to the reference manual in stead. Example fields in the package table include: cpath and path for paths for finding C and Lua modules as well as loaders and loaded for doing the actual work and keeping track of already loaded modules.
These are operating system specifics modelled after C.
execute runs the string as a shell command returning the return value, while exit does a C-style return from main with a return code. getenv is the way to access the specified environment variable. setlocale sets a particular local with special values "C" for the ANSI C and the empty string for a native locale. Lua already honours locales by default. The second argument defines a category defaulting to all, one of: all, collate, ctype, monetary, numeric, or time. Calling with no arguments returns the current locale.
For files, remove deletes a file, rename renames old to new and tmpname comes up with an unused temp filename. Most of these return nil and an error on failure.
For handling time, time returns the number of epoch seconds i.e. the current time, clock the number of seconds of CPU time used and difftime computes a time difference between two times. Time may also be given a table based on which to return an epoch time with string fields:
sec, min, hour, day, month, year, isdst
Unlike in Perl days and months are 1-nased, years full 4-digits and Sunday is 1. Finally, date with a format string and epoch time returns a stringified representation of time. With no arguments it returns a reasonable representation of current time, with one argument it string formats the current time and only with two arguments is the second argument the time being formatted. With the format string "*t" a table you can feed to time is returned in stead of the string. The format specifiers in the string are those of the C function strftime apart from an initial ! signifying GMT rather than local time for formatting or conversions to table.
The string table is the met table for Lua's string type, so these functions may also be called as methods of strings. alternatively, just say string.func(string, args), in stead. The first argument, not described, is always the string being acted on and the self parameter in method-based usage. Positions in strings are 1-based and Perlish negative positions from the end of the string are allowed, too. Lua's strings you start and end positions rather than start and length. All modifications return a modified string, since strings are immutable anyway.
Regexp, or Patterns in Lua speak, are just strings that certain library functions treat specially. Understanding how to use these functions requires then that you understand the patterns. Syntactically Lua regexpe could be considered a cross section of what Perl regexp features most people tend to use with the extra requirement that their implementation in C should not be very sizable. The syntax also differs somewhat using percent signs for backslashes ad much less escaping. Many fancy features that are comparatively rare, such as alteration, look around and noncapturing parens, have been left out Still, the resultant subset is easy to master entirely, cleaner syntactically and requires much less code than a full regexp engine. In the following description I assume you know the Perl 5 regular expressions.
The primary simplification is that a quantifier may only follow a character class, you cannot quantify a parenthesize subexpression or a capturing group. *, question ? and + work exactly like their greedy counter parts in regexp. The only other quantifier is minus - which is like the lazy star, *?
Character classes are locale sensitive in Lua and Perl. Syntactically, in stead of backslashing symbols, you use the percent sign for the same thing. %a, %u and %l for alphabetic, caps and lowwercase letters, %d and %x for ordinary and hex digits, %c, %p and %z for control, punctuation and null characters. Uppercased versions of these classes are the complements, much as in Perl. Additionally, %% is a percent sign and the dot %. is any character, including new lines, unlike in regexp by default.
Bracketed sets of characters including character ranges and classes as part of them can be used much as in regexp. Exception: you cannot augment a character class with a range. You can, however, invert a range with a leading caret [^...].
Finally, lua patterns may also contain %b followed by two characters. The construct will match an expression with the counts of these characters being balanced, e.g. %b() for matching nested parens. Again, a balanced expression may not be quantified but may be captured.
Parens in Lua patterns neither group nor change precedence, they only surround bits of patterns to be captured. captured are numbered from 1 onwards and referred to in the same pattern as %1, %2 and so on. %0 in a replacement is the whole matched string. An empty pair of parens exceptionally captures the 1-based match position in stead.
The only anchors in Lua patterns are the caret ^and dollar $, which always only anchor at the beginning and end of the whole pattern, new lines in matched text don't affect their meaning.
find returns the indices of the first match of a pattern, followed by captures if any, or nil without a match. Optional third argument is the start position and the fourth one a Boolean determining whether to do a plain substring search in stead, like Perl's index as opposed to scalar m//g. match is like the 3-arg version of find but returns the captures rather than the matched indices.
gmatch, with a g for global, creates an iterator returning the captures or the whole matched string, doing a subsequent match on each loop iteration, a bit like m//g would do in a loop in scalar context. ^and $ are taken literally for this function.
match is the Lua version of s///g taking a pattern to match, replacement and an optional n for only replacing the first n matches. The replacement string is literal apart from %% standing for a percent sign and %1 onwards marking captures in the match. With a replacement table, the replacing literal strings are results of looking up items in the table with the first capture or the whole match without captures. With a replacement callback function, the function returns the literal replacement receiving captures or the whole match as arguments.
sub i, j returns the substring from i to j, both of which may be negativ. j defaults to -1. The equivalent of index is find with the string to find, start position and true for doing a plain string search, not a pattern match. The redundant len is like the # operator for strings. rep with a count repeats the string count times, like Perl's x while reverse returns a reversed copy.
upper and lower return case changed copies of their argument like uc and lc. The ord and chr analogs of Lua are byte and char going from characters to integer code points, and back. With optional arguments i and j byte returns a list of values one for each character in the range. Similarly, char is a var arg function whose return string has one character per each argument given to it.
format is very much like sprintf in Perl taking a format string and variable arguments to be formatted and following C's printf formatting conventions apart from the unsupported: *, l, L, n, p, and h. It also supports q returning an escaped double quoted Lua string of the argument, nice for serialization or evaluation. The final string function for serialization is dump, returning the bytecode representation of a code ref without lexical variables. For compiling bytecode in general, use luac in stead, Lua can transparently load precompiled bytecode files, too, which actually work much more reliably than in Perl. For general serialization, just create printable versions of Lua data structures that can be eval:ed using loadstring or loadfile, much like you would in Data::Dump.
Most of this library is based on method calls on file objects. You can call most io functions either as functions, which operate on default file handles, or as methods for a particular file handle, in which case the first argument is already the object on the left side of the colon.
Rather than having to create a file object you can work with one input and one output file handle directly, though, which goes through ordinary function calls in the table io, with no object needed. This is by far the easiest option, if you are happy with a single input and output file at a time. Most functions return nil, a generic error and an OS error on failure.
The io table has quite some convenience for simple needs. To change input or output files the io.input and io.output functions are used. They can accept a file handle or the name of a file which is opened for reading or writing in text mode. A call without arguments returns the current file. This function directly dies, raises an error, on failure. io.close closes the specified file, defaulting to the default output.
Even more directly io.lines with a name opens the file and returns an iterator reading lines one by one from it, and closing the file when done. Without a name it reads the default file and does not close it at the end. io.read and io.write are even fancier. Read reads a line, stripping the new line, if no format is given. Of the formats "*n" reads a number, "*a" the hole file, "*l" the current line with nil on EOF. The var arg function write writes its arguments, strings or numbers, to the file directly.
In the io table stdin, stdout and stderr are the initial file handle objects your Lua program was called with. To create new file handle objects you call io.open with a file name and mode string to construct a file object, and then use its methods. The most common modes are r for read, w for write, a for appending and r+ for updating, with an optional b for binary for any of them. io.tmpfile also creates an updatable temporary file for you which is automagically deleted when the program ends.
io.type determines the type of a file returning one of: file, closed file or nil. For less portable needs popen with a string and mode runs string as a program, piping stuff to it or reading from a pipe. The mode r reads from the processes pipe (stdout), w writes to it (stdin).
Of the methods especially specific to file objects, I'll mention seek. With a mode string and int byte offset is does random file access altering the file position. The modes are set as an offset from the start, cur relative to current position and end from the end of file. The new byte offset is returned. Without arguments, the offset is returned unchanged.
Perl for programming in the Small
If you have any questions, comments or suggestions, Drop Me a Line here