cheat-sheet-lua/README.md

# cheat-sheet-lua

Here is the IO-Project cheat sheet to quickly learn the "Lua" programming language.
I suggest you to consult the documentation of lua for more information on the language, it is available by following [this link](https://www.lua.org/manual/5.3/).

## Table of contents

Use this table of contents to travel more easily through this cheat sheet.

- [cheat-sheet-lua](#cheat-sheet-lua)
  - [Table of contents](#table-of-contents)
  - [Basics](#basics)
    - [Code comments](#code-comments)
    - [Variables and loop](#variables-and-loop)
    - [Functions](#functions)
  - [Advanced](#advanced)
    - [Tables, Array, dict..](#tables-array-dict)
      - [Metatables and metamethods](#metatables-and-metamethods)
      - [Class-like tables and inheritance.](#class-like-tables-and-inheritance)
    - [Coroutine](#coroutine)
    - [Error handling](#error-handling)
    - [Modules](#modules)

## Basics

> We'll now introduce the basics of lua, starting with comments, variables, loops and functions.

### Code comments

````lua
-- Two dashes start a one-line comment.

--[[
     by adding two "[" opening and two "]" closing,
     you define a multi-line commentary. ;-)
--]]
````

### Variables and loop

Introduction to variables, basic conditions, some loops ([examples available here](support/while.lua)) and the equivalent of the ternary operator.

````lua
num = 42  -- All numbers are doubles.
-- Don't freak out, 64-bit doubles have 52 bits for
-- storing exact int values; machine precision is
-- not a problem for ints that need < 52 bits.

s = 'walternate'  -- Immutable strings like in Python.
t = "double-quotes are also fine"
u = [[ Double brackets
       start and end
       multi-line strings]]
t = nil  -- Undefines t; Lua has garbage collection.

-- Blocks are denoted with keywords like do/end:
while num < 50 do
  num = num + 1  -- No ++ or += type operators.
end

-- If clauses:
if num > 40 then
  print('over 40')
elseif s ~= 'walternate' then  -- ~= is not equals.
  -- Equality check is ==; ok for strs.
  io.write('not over 40\n')  -- Defaults to stdout.
else
  -- Variables are global by default.
  thisIsGlobal = 5  -- Camel case is common.

  -- How to make a variable local:
  local line = io.read()  -- Reads next stdin line.

  -- String concatenation uses the .. operator:
  print('Winter is coming, ' .. line)
end

-- Undefined variables return nil.
-- This is not an error:
foo = anUnknownVariable  -- Now foo = nil.

aBoolValue = false

-- Only nil and false are false; 0 and '' are true.
if not aBoolValue then print('that was false') end

-- 'or' and 'and' are short-circuited.
-- This is similar to the a?b:c operator in C/js:
ans = aBoolValue and 'yes' or 'no'  --> 'no'

karlSum = 0
for i = 1, 100 do  -- The range includes both ends.
  karlSum = karlSum + i
end

-- Use "100, 1, -1" as the range to count down:
fredSum = 0
for j = 100, 1, -1 do fredSum = fredSum + j end

-- In general, the range is begin, end[, step].

-- Another loop construct:
repeat
  print('the way of the future')
  num = num - 1
until num == 0
````

### Functions

Introduction to function definition, recursion with lua and chain assignment followed by closure function.

````lua
-- The famous Fibonacci sequence.
function fib(n)
  if n < 2 then return 1 end
  return fib(n - 2) + fib(n - 1)
end

-- Closures and anonymous functions are ok:
function adder(x)
  -- The returned function is created when adder is
  -- called, and remembers the value of x:
  return function (y) return x + y end
end
a1 = adder(9)
a2 = adder(36)
print(a1(16))  --> 25
print(a2(64))  --> 100

-- Returns, func calls, and assignments all work
-- with lists that may be mismatched in length.
-- Unmatched receivers are nil;
-- unmatched senders are discarded.

x, y, z = 1, 2, 3, 4
-- Now x = 1, y = 2, z = 3, and 4 is thrown away.

function bar(a, b, c)
  print(a, b, c)
  return 4, 8, 15, 16, 23, 42
end

x, y = bar('zaphod')  --> prints "zaphod nil nil"
-- Now x = 4, y = 8, values 15..42 are discarded.

print(type(x))  --> number
-- 'type()' function allow to detemindthe  type of a variable.

-- '...' is an elipse parameter, retrievable in context by '...'.
function e(...) print(...) end
e(2, 4, 8, 6)  --> prints "2    4    8    6"

-- Functions are first-class, may be local/global.
-- (global) These are the same:
function f(x) return x * x end
f = function (x) return x * x end -- same of javascript definition

-- (local) And so are these:
local function g(x) return math.sin(x) end
local g; g = function (x) return math.sin(x) end
-- the 'local g' decl makes g-self-references ok.

-- Trig funcs work in radians, by the way.

-- Calls with one string param don't need parens:
print 'hello'  -- Works fine.
````

## Advanced

> Let's move on to more advanced notions. With the notion of table, class, module, coroutine, meta-programming and module.

### Tables, Array, dict..

Tables are the only compound data structure in Lua, they are associative arrays. Similar to php arrays or js objects, they are hash-lookup dicts that can also be used as lists.

````lua
-- Using tables as dictionaries / maps:

-- Dict literals have string keys by default:
t = {key1 = 'value1', key2 = false}

-- String keys can use js-like dot notation:
print(t.key1)  -- Prints 'value1'.
t.newKey = {}  -- Adds a new key/value pair.
t.key2 = nil   -- Removes key2 from the table.

-- Literal notation for any (non-nil) value as key:
u = {['@!#'] = 'qbert', [{}] = 1729, [6.28] = 'tau'}
print(u[6.28])  -- prints "tau"

-- Key matching is basically by value for numbers
-- and strings, but by identity for tables.
a = u['@!#']  -- Now a = 'qbert'.
b = u[{}]     -- We might expect 1729, but it's nil:
-- b = nil since the lookup fails. It fails
-- because the key we used is not the same object
-- as the one used to store the original value. So
-- strings & numbers are more portable keys.

-- A one-table-param function call needs no parens:
function h(x) print(x.key1) end
h{key1 = 'Sonmi~451'}  -- Prints 'Sonmi~451'.

for key, val in pairs(u) do  -- Table iteration.
  print(key, val)
end

-- _G is a special table of all globals.
print(_G['_G'] == _G)  -- Prints 'true'.

-- Using tables as lists / arrays:

-- List literals implicitly set up int keys:
v = {'value1', 'value2', 1.21, 'gigawatts'}
for i = 1, #v do  -- #v is the size of v for lists.
  print(v[i])  -- Indices start at 1 !! SO CRAZY !!
end
-- A 'list' is not a real type. v is just a table
-- with consecutive integer keys, treated as a list.
````

#### Metatables and metamethods

A table can have a metatable that gives the table operator-overloadish behavior. Later we'll see how metatables support js-prototypey behavior.

````lua
f1 = {a = 1, b = 2}  -- Represents the fraction a/b.
f2 = {a = 2, b = 3}

-- This would fail:
-- s = f1 + f2

metafraction = {}
function metafraction.__add(f1, f2)
  sum = {}
  sum.b = f1.b * f2.b
  sum.a = f1.a * f2.b + f2.a * f1.b
  return sum
end

setmetatable(f1, metafraction)
setmetatable(f2, metafraction)

s = f1 + f2  -- call __add(f1, f2) on f1's metatable

-- f1, f2 have no key for their metatable, unlike
-- prototypes in js, so you must retrieve it as in
-- getmetatable(f1). The metatable is a normal table
-- with keys that Lua knows about, like __add.

-- But the next line fails since s has no metatable:
-- t = s + s
-- Class-like patterns given in the section below would fix this.

-- An __index on a metatable overloads dot lookups:
defaultFavs = {animal = 'gru', food = 'donuts'}
myFavs = {food = 'pizza'}
setmetatable(myFavs, {__index = defaultFavs})
eatenBy = myFavs.animal  -- works! thanks, metatable
-- Direct table lookups that fail will retry using
-- the metatable's __index value, and this recurses.

-- An __index value can also be a function(tbl, key)
-- for more customized lookups.

-- Values of __index, add, .. are called metamethods.
-- Main list. Here is a table with the metamethods.

-- __add(a, b)                     for a + b
-- __sub(a, b)                     for a - b
-- __mul(a, b)                     for a * b
-- __div(a, b)                     for a / b
-- __mod(a, b)                     for a % b
-- __pow(a, b)                     for a ^ b
-- __unm(a)                        for -a
-- __concat(a, b)                  for a .. b
-- __len(a)                        for #a
-- __eq(a, b)                      for a == b
-- __lt(a, b)                      for a < b
-- __le(a, b)                      for a <= b
-- __index(a, b)  <fn or a table>  for a.b
-- __newindex(a, b, c)             for a.b = c
-- __call(a, ...)                  for a(...)
````

#### Class-like tables and inheritance.

Classes aren't built in, there are different ways to emulate them with tables and metatables.
The different ways to define a class in Lua are not easy to understand, so I suggest you to look at the [following document](support/class.lua) implementing 3 types of class definition. The last one being the one I chose (my preferred method).

````lua
-- Explanation for this example is below it.
Dog = {}                                   -- 1.

function Dog:new()                         -- 2.
  newObj = {sound = 'woof'}                -- 3.
  self.__index = self                      -- 4.
  return setmetatable(newObj, self)        -- 5.
end

function Dog:makeSound()                   -- 6.
  print('I say ' .. self.sound)
end

mrDog = Dog:new()                          -- 7.
mrDog:makeSound()  -- 'I say woof'         -- 8.

-- 1. Dog acts like a class; it's really a table.
-- 2. function tablename:fn(...) is the same as
--    function tablename.fn(self, ...)
--    The : just adds a first arg called self.
--    Read 7 & 8 below for how self gets its value.
-- 3. newObj will be an instance of class Dog.
-- 4. self = the class being instantiated. Often
--    self = Dog, but inheritance can change it.
--    newObj gets self's functions when we set both
--    newObj's metatable and self's __index to self.
-- 5. Reminder: setmetatable returns its first arg.
-- 6. The : works as in 2, but this time we expect
--    self to be an instance instead of a class.
-- 7. Same as Dog.new(Dog), so self = Dog in new().
-- 8. Same as mrDog.makeSound(mrDog); self = mrDog.

----------------------------------------------------

-- Inheritance example:
LoudDog = Dog:new()                         -- 1.

function LoudDog:makeSound()
  s = self.sound .. ' '                     -- 2.
  print(s .. s .. s)
end

seymour = LoudDog:new()                     -- 3.
seymour:makeSound()  -- 'woof woof woof'    -- 4.

-- 1. LoudDog gets Dog's methods and variables.
-- 2. self has a 'sound' key from new(), see 3.
-- 3. Same as LoudDog.new(LoudDog), and converted to
--    Dog.new(LoudDog) as LoudDog has no 'new' key,
--    but does have __index = Dog on its metatable.
--    Result: seymour's metatable is LoudDog, and
--    LoudDog.__index = LoudDog. So seymour.key will
--    = seymour.key, LoudDog.key, Dog.key, whichever
--    table is the first with the given key.
-- 4. The 'makeSound' key is found in LoudDog; this
--    is the same as LoudDog.makeSound(seymour).

-- If needed, a subclass's new() is like the base's:
function LoudDog:new()
  newObj = {}
  -- set up newObj
  self.__index = self
  return setmetatable(newObj, self)
end
````

### Coroutine

Let's turn now to coroutines. Coroutines are functions that can be suspended and resumed at a later time. They are used to implement iterators, generators and event loops and represent a line of execution with its own stack. In other words, they can be compared to threads.

````lua
-- Create a coroutine that prints 'Hello' and then stops.
coHi = coroutine.create(function () print('Hello') end)
print(coHi)  -- thread: 0x7f9c0c00a0c0

-- Coroutine status can be 'suspended', 'running' or 'dead'.
-- The coroutine is created in the 'suspended' state.

-- Resume the coroutine. It will print 'Hello' and stop.
coroutine.resume(coHi)  -- return 'true'
print(coroutine.status(coHi))  -- 'dead'

-- We can also pass arguments to the coroutine.
-- The arguments of the first resume are passed to the
-- function of the coroutine. The following arguments
-- are passed to the yield function.
routine = coroutine.create(function (a, b, c)
  print('first print: ', a, b, c)
  print('yield1: ', coroutine.yield())
  print('yield2: ', coroutine.yield('a variable'))
  return(a+b+c)
end)

-- will run the coroutine until the first yield.
coroutine.resume(routine, 1, 2, 3)
-- run the coroutine until the second yield passing
-- the arguments 4, 5 and 6 to the 1er yield and
-- retrieve the return value of the second yield.
print('out routine: ' , coroutine.resume(routine, 4, 5, 6))
-- this will run out the second yield and made the
-- adition of 'a+b+c'  and kill the coroutine.
print(coroutine.resume(routine, 7, 8, 9)) -- 1+2+3 = '6'

-- All these steps will print:
--[[
    first print:    1       2       3
    yield1:         4       5       6
    out routine:    true    a variable
    yield2:         7       8       9
    true    6
--]]
````

### Error handling

Lua provides several core functions for error handling: `assert`, `error`, `pcall` (protected call), and `xpcall` (extended protected call), each offering different levels of control.  
The examples below will explain and illustrate how each method is intended to be used.

#### assert

`assert` is used to check a condition. If the result is `false` or `nil`, it triggers an error with a custom message.  
It's especially useful when validating user input or enforcing preconditions.

```lua
local function isMajorUser(age)
	assert(age >= 18, "You are not allowed to buy this item, you need to be 18 years old")
end

isMajorUser(15)
-- Output : You are not allowed to buy this item, you need to be 18 years old !
```

#### error(message [, level])

The `error` function allows you to manually raise an error, similar to `throw` in other languages. It immediately stops the current execution flow.  
You can provide a custom error message, as well as a `level` parameter to control where the traceback starts in the call stack.

Possible values for `level`:

- **0**: No call stack information is shown.

```lua
error("Simple error without trace", 0)
-- Result: Simple error without trace
```

- **1** *(default)*: The error appears at the exact place where `error` is called.

```lua
local function triggerError()
    error("An error has occurred", 1)
end

triggerError()

-- Result
--[[
lua: script.lua:2: An error has occurred
stack traceback:
    script.lua:2: in function 'triggerError'
    script.lua:5: in main chunk
]]
```

- **2**: The error appears at the place where the function **calling `error`** was itself called.

```lua
local function triggerError()
    error("Error reported to caller", 2)
end

local function wrapper()
    triggerError()
end

wrapper()

-- Result
--[[
lua: script.lua:7: Error reported to caller
stack traceback:
    script.lua:7: in function 'wrapper'
    script.lua:10: in main chunk
]]
```

#### pcall (protected call)

As its name suggests, `pcall` allows you to execute a function in **protected mode**, catching any potential error that might occur.  
It acts similarly to a `try-catch` block found in other programming languages.

The result of calling `pcall` returns two values, typically stored in two variables like `success` and `result`, though you can name them as you wish.

- If the call succeeds:
  - `success` will be `true`,
  - `result` will contain the function’s returned value(s).

- If an error occurs:
  - `success` will be `false`,
  - `result` will contain the error message.

If the function does not return anything, `result` will be `nil`.

```lua
local function divideANumberByAnOther(a, b)
	return a / b -- it would be better to validate parameters, but this is for example purposes
end


-------------------------------
-- First scenario: error case
-------------------------------
local success, result = pcall(divideANumberByAnOther, 1, 0)

if not success then
	print("An error has occured :", result)
end

-- Output: An error has occured :


-------------------------------
-- Second scenario: valid case
-------------------------------

local success, result = pcall(divideANumberByAnOther, 10, 2)

if success then
	print("Result is :", result)
end

-- Output: Result is : 5



---------------------------------------------------------------------
-- Third scenario: combine pcall with assert for critical operations
---------------------------------------------------------------------

local function readFile(fileName)
	local fileToRead = assert(io.open(fileName, "r"), "Impossible to read the file")
	-- Continue processing if successfully opened
	fileToRead:close()
end

local success, result = pcall(readFile, "data.txt") -- providing a file name that doesn't exist

if not success then
	print("An error has occured :", result)
end

-- Output: An error has occured : Impossible to read the file

-- Here we use assert to robustly manage errors: if the file cannot be opened, 
-- assert triggers an error and immediately stops the program with the message.



-----------------------------------------------------------------------
-- Fourth scenario: pcall with a function that returns multiple values
-----------------------------------------------------------------------
local function sumAndProduct(a, b)
	return a + b, a * b
end

local success, sum, product = pcall(sumAndProduct, 3, 4)

if success then
	print("Sum :", sum) -- 7
	print("Product :", product) -- 12
else
	print("Error : ", sum) -- sum would contain the error message if one occurred
end

-- Reminder: pcall always returns two things:
-- 1. A boolean indicating if the call was successful.
-- 2. All values returned by the function if successful.
```

#### xpcall (extended protected call)

`xpcall` is the big brother of `pcall`. It works in the same way but with an extra feature:  
we can provide a **custom error handler function** that will be executed if an error occurs during the protected function call.

This is especially useful when we want to customize how errors are displayed or logged, for example by adding stack traces or additional context.

```lua
local function errorHandler(err)
    print("🔴 Error caught:", err)
    print(debug.traceback("Stack trace:", 2))
end

local function riskyFunction()
    print("🟢 In riskyFunction")
    error("Something went wrong!")
end

local function wrapper()
    print("🟡 Calling riskyFunction()")
    riskyFunction()
    print("🟡 After riskyFunction") -- never reached
end

print("1. Start")

local success, result = xpcall(wrapper, errorHandler)

print("2. Execution finished")
print("3. Success:", success)
print("4. Result:", result)

-- Output:
--[[
1. Start
🟡 Calling riskyFunction()
🟢 In riskyFunction
🔴 Error caught: Something went wrong!
Stack trace:
stack traceback:
    script.lua:6: in function 'riskyFunction'
    script.lua:11: in function 'wrapper'
    ...
2. Execution finished
3. Success: false
4. Result: nil
]]

--[[
===========================
debug.traceback Cheatsheet
===========================

debug.traceback([message], [level])

- message (string) → optional message shown before the stack trace
- level (number) → determines where the trace starts in the call stack:

    level = 0 → shows EVERYTHING, including debug.traceback itself
    level = 1 → (default) starts trace inside errorHandler() (not very useful)
    level = 2 → starts trace at the point where the error actually occurred (e.g., riskyFunction)

Recommended usage:
    debug.traceback("Optional message", 2)
]]
```

### Modules

Modules are a way to organize your code. They are a way to group functions and variables together in a single file. You can then use the module in other files by using the `require` function.

````lua
-- Suppose the file mod.lua looks like this:
local M = {}

local function sayMyName()
  print('Hrunkner')
end

function M.sayHello()
  print('Why hello there')
  sayMyName()
end

return M  -- Return the table M.

-- Another file can use mod.lua's functionality:
local mod = require('mod')  -- Run the file mod.lua.

-- require is the standard way to include modules.
-- require acts like:     (if not cached; see below)
local mod = (function ()
  <contents of mod.lua>
end)()
-- It's like mod.lua is a function body, so that
-- locals inside mod.lua are invisible outside it.

-- This works because mod here = M in mod.lua:
mod.sayHello()  -- Says hello to Hrunkner.

-- This is wrong, sayMyName only exists in mod.lua:
mod.sayMyName()  -- error

-- require's return values are cached so a file is
-- run at most once, even when require'd many times.

-- Suppose mod2.lua contains "print('Hi!')".
local a = require('mod2')  -- Prints Hi!
local b = require('mod2')  -- Doesn't print; a=b.

-- dofile is like require without caching:
dofile('mod2.lua')  --> Hi!
dofile('mod2.lua')  --> Hi! (runs it again)

-- loadfile loads a lua file but doesn't run it yet.
f = loadfile('mod2.lua')  -- Call f() to run it.

-- loadstring is loadfile for strings.
g = loadstring('print(343)')  -- Returns a function.
g()  -- Prints out '343', nothing printed before now.

````

### Credits

- EndMove - [contact@endmove.eu](mailto:contact@endmove.eu)
- Varmix - [contact@varmix.fr](mailto:contact@varmix.fr)