designed primarily for embedded use in applications.

designed as an extension language, to be embedded in a host C program

• scripting
• imperative (procedural, prototype-based, object-oriented)
• functional
• meta
• reflective
• cross-platform, since the interpreter of compiled bytecode is written in ANSI C
• dynamically typed language
• advanced:
  • first-class functions
  • garbage collection
  • closures
  • proper tail calls
  • coercion (automatic conversion between string and number values at run time)
  • coroutines (cooperative multitasking)
  • dynamic module loading.

It ignores spaces (including new lines) and comments between lexical elements (tokens), except as delimiters between names and keywords.

Lua programs are much more error prone, due to automatic coercion, accessing of unset variables without an exception, and having to check most functions for nil values, rather than just catching the exceptions.

Lua has out-of-the-box support for multiple threads and multiple interpreters in a single thread or process

Lua starts table indices at 1, which is strange for a language designed to interface with C where arrays start at 0. (Comment: Ad-hoc , there is no problem to use index 0 or even -1

chunk

The unit of compilation of Lua is called a chunk. Syntactically, a chunk is simply a block. Chunks do not nest (unlike blocks). A chunk is an outermost block which you feed to "load". Lua handles a chunk as the body of an anonymous function.

(no term)

::

• +: addition
• -: subtraction
• *: multiplication
• /: float division
• //: floor division
• %: modulo
• ^: exponentiation
• -: unary minus

• &: bitwise AND
• |: bitwise OR
• ~: bitwise exclusive OR
• >>: right shift
• <<: left shift
• ~: unary bitwise NOT

• ==: equality
• ~=: inequality
• <: less than
• >: greater than
• <=: less or equal
• >=: greater or equal

• 10 or 20 –> 10
• 10 or error() –> 10
• nil or "a" –> "a"
• nil and 10 –> nil
• false and error() –> false
• false and nil –> false
• false or nil –> nil
• 10 and 20 –> 20

from lower to higher:

1. or
2. and
3. < > <= >= ~= ==
4. |
5. ~
6. &
7. << >>
8. ..
9. -
10. / // %
11. unary operators (not # - ~)
12. ^

nil, boolean, number, string, function, userdata, thread, and table.

nil

singleton - absence of a useful value - (as false)

boolean

false and true

number

integer numbers and real (floating-point) numbers

integer

float

string

immutable sequences of bytes. 8-bit clean: strings can contain any 8-bit value. encoding-agnostic; it makes no assumptions about the contents of a string.

function

written in Lua and functions written in C

userdata

block of raw memory - arbitrary C data to be stored in Lua variables. assignment and identity test. created and modified only through the C API.

full userdata

an object with a block of memory

light userdata

a C pointer value

thread

used to implement coroutines. not related to operating-system threads

table

associative arrays - idexes of any type. can be heterogeneous - can contain values of all types (except nil)

• can be used to represent ordinary arrays, lists, symbol tables, sets, records, graphs, trees, etc.
• a.name as syntactic sugar for a["name"]

Tables, functions, threads, and (full) userdata values are objects: variables do not actually contain these values, only references to them.

converts between integer and float automatically as needed.

Standard Lua uses 64-bit integers and double-precision (64-bit) floats, but you can also compile Lua so that it uses 32-bit integers and/or single-precision (32-bit) floats.

valid integer constants are

3   345   0xff   0xBEBADA

Examples of valid float constants are

3.0     3.1416     314.16e-2     0.31416E1     34e1
0x0.1E  0xA23p-4   0X1.921FB54442D18P+1

kinds of variables in Lua:

• global variables
• local variables
• table fields.

always passed by reference

A key (index) can be any value except nil and NaN, including functions.

Every value in Lua can have a metatable - table, that defines the behavior of the original value under operations.

• consist of event "__add" key and metamethods - value

to retrieve the metamethod for event ev in object o, Lua does:

• rawget (table, index) - Gets the real value of table[index], index may be any value.
• getmetatable (object) - get nil, metatable or metatable.__metatable field.

rawget(getmetatable(o) or {}, "__ev")

setmetatable (table, metatable) - metatable is nil, removes the metatable of the given table. If the original metatable has a __metatable field, raises an error. This function returns table.

object-oriented programming can be emulated using functions and tables

if condition then
        --statement body
elseif condition then
        --statement body
else -- optional
        --optional default statement body
end

while condition do
  --statements
end

repeat
  --statements
until condition

for i = first, last, delta do  --delta may be negative, allowing the for loop to count down or up
  --statements
  --example: print(i)
end

for key, value in pairs(_G) do
  print(key, value)
end

local grid = {
  { 11, 12, 13 },
  { 21, 22, 23 },
  { 31, 32, 33 }
}

for y, row in pairs(grid) do
  for x, value in pairs(row) do
    print(x, y, value)
  end
end

as

for i,v in ipairs({3,3,2}) do
   print(i,v)
end

1	3
2	3
3	2

• components in a path are separated by semicolons ";"

?;?.lua;c:\windows\?;/usr/local/lua/?/?.lua

require"lili" will try to open the following files:

• lili
• lili.lua
• c:\windows\lili
• /usr/local/lua/lili/lili.lua

module("mymath", package.seeall)

function mymath.add(a,b)
   print(a+b)
end

function mymath.sub(a,b)
   print(a-b)
end

usage:

require "mymath.add"
mymath.add.test2()

alternative

-- file: finance/BankAccount.lua

local M = {}; M.__index = M

local function construct()
  local self = setmetatable({balance = 0}, M)
  return self
end
setmetatable(M, {__call = construct})

function M:add(value) self.balance = self.balance + value end

return M

usage:

local BankAccount = require "finance.BankAccount"
local account = BankAccount()

• assert (v [, message]) Calls error if v is false.
• collectgarbage ([opt [, arg]]) opt:"collect", "stop", "restart", "count", "step", "setpause", "setstepmul", "isrunning"
• dofile ([filename]) Opens the named file and executes its contents as a Lua chunk.
• error (message [, level]) levels = 1 (default) - position where error was called, 2 - function that call error
• _G variable of type table - holds the global environment
• getmetatable (object) not have = nil, the object's metatable __metatable field or metatable of the object
• ipairs (t) used in: for i,v in ipairs(t) do (1,t[1]), (2,t[2]), …,
• load (chunk [, chunkname [, mode [, env]]]) chunk is a string of function that return string.
• loadfile ([filename [, mode [, env]]]) gets the chunk from file filename
• next (table [, index]) returns the next index of the table and its associated value.
• pairs (t) for k,v in pairs(t) do body end - over all key–value pairs of table t. next
• pcall (f [, arg1, ···]) protected mode - error inside f is not propagated. ret: (true, return) or (false, message)
• print (···) any number of arguments, to stdout. tostring. for quick way only. use string.format and io.write.
• rawequal (v1, v2) bool, v1 is equal to v2, without invoking the __eq metamethod.
• rawget (table, index) table[index], without invoking the __index metamethod. index - any value.
• rawlen (v) v - string or table, without invoking the __len metamethod. integer
• rawset (table, index, value) table[index], without invoking the __newindex. returns table.
• select (index, ···) number - return next elemets … after number, '#' - count of … elements.
• setmetatable (table, metatable)
• tonumber (e [, base]) base - any integer between 2 and 36. return int or nil.
• tostring (v) call __tostring.
• type (v) return type coded as a string. "nil", "number", "string", "boolean", "table", "function", "thread", and "userdata".
• _VERSION string - the running Lua version.
• xpcall (f, msgh [, arg1, ···]) This function is similar to pcall, except that it sets a new message handler msgh.

other

• require (modname)

• coroutine.
• package.
• string.
• utf8.
• table.
• math.
• io.
• file:
• os:
• debug.

LuaDoc can parse some tags at each function or table documentation. Tags are indicated in the source code with a `@' character followed by the name of the tag:

@author <text>

An author of the module or file.

@copyright <text>

The copyright notice of the module or file. LuaDoc adds a © sign between the label (Copyright) and the given text (e.g. 2004-2007 Kepler Project).

@field

Describe a table field definition.

@param <word> <text>

Describe function parameters. It requires the name of the parameter and its description.

@release <text>

Free format string to describe the module or file release.

@return <text>

Describe a returning value of the function. Since Lua can return multiple values, this tag should appear more than once.

@see <text>

Refers to other descriptions of functions or tables.

@usage <text>

Describe the usage of the function or variable.

The following tags would be normally infered by LuaDoc, but they can be used to override the infered value.

@class <word>

If LuaDoc cannot infer the type of documentation (function, table or module definition), the programmer can specify it explicitly.

@description

The description of the function or table. This is usually infered automatically.

@name <word>

The name of the function or table definition. This is usually infered from the code analysis, and the programmer does not need to define it. If LuaDoc can infer the name of the function automatically it's even not recomended to define the name explicitly, to avoid redundancy.

1. @module A Lua module containing functions and tables, which may be inside sections
2. @classmod Like @module but describing a class
3. @submodule A file containing definitions that you wish to put into the named master module
4. @script A Lua program
5. @author (multiple), copyright, @license, @release only used for project-level tags like @module
6. @function, @lfunction. Functions inside a module
7. @param formal arguments of a function (multiple)
8. @return returned values of a function (multiple)
9. @raise unhandled error thrown by this function
10. @local explicitly marks a function as not being exported (unless –all)
11. @see reference other documented items
12. @usage give an example of a function’s use. (Has a somewhat different meaning when used with @module)
13. @table a Lua table
14. @field a named member of a table
15. @section starting a named section for grouping functions or tables together
16. @type a section which describes a class
17. @within puts the function or table into an implicit section
18. @fixme, @todo and @warning are annotations, which are doc comments that occur inside a function body.

http://lua-users.org/wiki/DocumentingLuaCode

Formatting

• Indentation - Indenting often uses two spaces.

Naming

• lenght - variable names with larger scope should be more descriptive than those with smaller scope.

variables

• lowercase - Variables holding values or objects are typically lowercase and short (e.g. color)
• Booleans - It can be helpful to prefix Boolean values or functions used as predicates with is, such as is_directory rather than directory (which might store a directory object itself).
• underscore "_" is commonly used as a placeholder when you want to ignore the variable
• i, k, v, t

for k,v in pairs(t) ... end
for i,v in ipairs(t) ... end
mt.__newindex = function(t, k, v) ... end

M is sometimes used as the "current module table"

• functions - print_table or getmetatable.
• constants - ALL_CAPS, with words optionally separated by underscores.
• module/package - nouns with names that are short and lowercase, with nothing between words.
• Class names - upper CamelCase

libraries - Avoid using the debug library unless necessary, especially if trusted code is being run.

Use local! Globals have larger scopes and lifetimes and therefore increase [coupling] and complexity

• limit the scope of local variables with do-blocks

Don't use semicolons ;. They are generally only useful to separate multiple statements on a single line, but you shouldn't be putting multiple statements on a single line anyway.

• http://lua-users.org/wiki/LuaStyleGuide
• https://roblox.github.io/lua-style-guide/
• https://github.com/luarocks/lua-style-guide

Indexing into a table in Lua gives you nil if the key isn't present.

local MyEnum = {
    A = "A",
    B = "B",
    C = "CC",
}

print(MyEnum.V) -- nil

setmetatable(MyEnum, {
    __index = function(self, key)
        error(string.format("%q is not a valid member of MyEnum",
            tostring(key)), 2)
    end,
})

print(MyEnum.C) -- CC
print(MyEnum.V) -- error

nil
CC