Lua/Lua_Quick_Guide.ipynb

{
 "cells": [
  {
   "cell_type": "markdown",
   "id": "801429af",
   "metadata": {},
   "source": [
    "Get the pdf version of this document [here](https://github.com/medwatt/Notes/blob/main/Lua/Lua_Quick_Guide.pdf)."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8dc7bf28",
   "metadata": {},
   "source": [
    "# Basics"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b2956b49",
   "metadata": {},
   "source": [
    "## Comments"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d915da8e",
   "metadata": {},
   "outputs": [],
   "source": [
    "-- This is a single line comment.\n",
    "\n",
    "--[[\n",
    "     This is a multi-line comment.\n",
    "--]]"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "8802d11b",
   "metadata": {},
   "source": [
    "## Variable Scope\n",
    "\n",
    "All variables are considered **`global`** unless explicitly declared as **`local`**. The scope of local variables is limited in the [**chunk**](https://www.lua.org/pil/1.1.html) in which they appear in. Lua usually interprets each line that we type in _interactive mode_ as a complete chunk or expression. This implies that a variable declared `local` in one line is out of scope in the next line. We can create local chunks by using the **`do`** and **`end`** keywords. This works because if the interpreter detects that the line is not complete, it waits for more input, until it has a complete chunk."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "59559e6d",
   "metadata": {},
   "outputs": [],
   "source": [
    "var = 10 -- global\n",
    "print( \"Global var:\", var ) --> 10\n",
    "\n",
    "do\n",
    "    local var = 20 -- local\n",
    "    print( \"Local var:\", var ) --> 20\n",
    "end\n",
    "\n",
    "print( \"Global var:\", var ) --> 10"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47c65664",
   "metadata": {},
   "source": [
    "## Variable Assignment\n",
    "\n",
    "- Lua does not offer syntactic sugar for **augmented assignments**. That is, we must explicitly write `a = a + 1` instead `a += 1`.\n",
    "\n",
    "- Lua does not offer syntactic sugar for **chained assignments**. That is, instead of `a = b = 0`, each variable assignment must be written separately.\n",
    "\n",
    "- Lua supports **parallel assignment**. For example, `a, b, c = 0, 0, 0`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f29d66a4",
   "metadata": {},
   "source": [
    "## Variable Types\n",
    "\n",
    "There are eight basic types in Lua: _nil_, _boolean_, _number_, _string_, _userdata_, _function_, _thread_, and _table_.\n",
    "\n",
    "- A _nil_ value represents the absence of data. If you try to access a variable that has not been created yet, its value will be _nil_. If you are done using a variable, you can assign it to _nil_ to delete it.\n",
    "- Until version 5.2, Lua represented all numbers using double-precision floating-point format. Starting with version 5.3, Lua uses two alternative representations for numbers: 64-bit integer numbers (called _integer_), and double-precision floating-point numbers (called _float_).\n",
    "\n",
    "**NOTE**: Any arithmetic operation applied to a _string_ will attempt to convert this _string_ to a _number_. Conversely, whenever a _string_ is expected and a _number_ is used instead, the _number_ will be converted to a _string_. This can also be done manually using the `tostring` and `tonumber` functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6ee73ad4",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( type(\"Hello\")   )  --> string\n",
    "print( type(10.4*3)    )  --> number\n",
    "print( type({1, 2, 3}) )  --> table\n",
    "print( type(print)     )  --> function\n",
    "print( type(true)      )  --> boolean\n",
    "print( type(nil)       )  --> nil"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "47d51dbb",
   "metadata": {},
   "source": [
    "## Math Operators\n",
    "\n",
    "The division operator `/` performs regular floating-point division. Lua 5.3 introduced the `//` operator that performs integer (floor) division."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "ebd949a9",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b = 0x14, 4\n",
    "\n",
    "print( a + b ) --> 24\n",
    "print( a - b ) --> 16\n",
    "print( a * b ) --> 80\n",
    "print( a ^ b ) --> 160000.0\n",
    "print( a / b ) --> 5.0\n",
    "print( a % b ) --> 0\n",
    "print(  -a   ) --> -20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2cac5253",
   "metadata": {},
   "source": [
    "## Relational Operators"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "91dad2f7",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b = 20, 4\n",
    "\n",
    "print( a == b ) --> false\n",
    "print( a ~= b ) --> true\n",
    "print( a > b  ) --> true\n",
    "print( a < b  ) --> false\n",
    "print( a >= b ) --> true\n",
    "print( a <= b ) --> false"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "15555569",
   "metadata": {},
   "source": [
    "## Logical Operators\n",
    "\n",
    "- Only **`false`** and **`nil`** are considered `false`; every other value is `true`.\n",
    "\n",
    "- The operator **`and`** returns its first argument if it is `false`; otherwise, it returns its second argument.\n",
    "\n",
    "- The operator **`or`** returns its first argument if it is not `false`; otherwise, it returns its second argument."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f32629b2",
   "metadata": {},
   "outputs": [],
   "source": [
    "print(true and 10)        --> 10\n",
    "print(10 and true)        --> true\n",
    "print(false and 10)       --> false\n",
    "print(false or 10)        --> 10\n",
    "print(nil and 10)         --> nil\n",
    "print(nil or 10)          --> 10\n",
    "print(false and nil)      --> false\n",
    "print(false and not(nil)) --> false"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cc7c67a2",
   "metadata": {},
   "source": [
    "# Strings"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bf664a79",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a = 'there is a \"quote\" inside this string'\n",
    "local b = [[This is a\n",
    "       multi-line string]]\n",
    "local c = \"this is a string with \\t escape characters \\\\\""
   ]
  },
  {
   "cell_type": "markdown",
   "id": "30fef4e9",
   "metadata": {},
   "source": [
    "## Common String Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1cc75611",
   "metadata": {},
   "source": [
    "- Convert string to uppercase"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a45c32ae",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.upper( \"The\" ) ) --> THE"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee4264c9",
   "metadata": {},
   "source": [
    "- Convert string to lower case"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84b02df9",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.lower(\"ADT\") ) --> adt"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f60bdeaa",
   "metadata": {},
   "source": [
    "- Return the length of the string. We can also use **`#string`** to return the length of a string. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "55ce24ac",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.len(\"a b c\") ) --> 5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c30f68e6",
   "metadata": {},
   "source": [
    "- Return the start index and end index of the _find string_ in the _main string_. This function takes optional start and end indices to indicate which section of the _main string_ to search."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a0f4fd70",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.find(\"This is\", \"is\") ) --> 3  4"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "2475b2bf",
   "metadata": {},
   "source": [
    "- Return a substring of the string given by the start index and end index"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1a9f8185",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.sub(\"abcd\", 2, 3) ) --> bc"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d703663a",
   "metadata": {},
   "source": [
    "- Return a string by replacing occurrences of the _find string_ with the _replace string_"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "78945c6b",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.gsub(\"pen\", \"e\", \"i\") ) --> pin"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "6a7de99d",
   "metadata": {},
   "source": [
    "- Return a string by repeating the same string n number of times"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e7c76b1a",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.rep(\"ab\", 2) ) --> abab"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "bcad5113",
   "metadata": {},
   "source": [
    "- Concatenate two strings with the `..` operator"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "dc1553e9",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( \"a\" .. \": \" .. \"b\" ) --> a: b"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f486f69d",
   "metadata": {},
   "source": [
    "- Return a string by reversing the characters of the passed string"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "4b002197",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.reverse(\"abcd\") ) --> dcba"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "97517d0f",
   "metadata": {},
   "source": [
    "- Return the character represented by the ASCII code"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b540afa9",
   "metadata": {},
   "outputs": [],
   "source": [
    "print( string.char(98) ) --> b"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f337c2e4",
   "metadata": {},
   "source": [
    "- Return the ASCII code of a character given by index (default is 1)"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "e4e7d578",
   "metadata": {},
   "outputs": [],
   "source": [
    "print ( string.byte(\"abc\", 2) ) --> 98"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "91f17b5e",
   "metadata": {},
   "source": [
    "## String formatting\n",
    "\n",
    "String formatting in Lua follows the same patterns as `printf` in C with the exception that the options/modifiers `* l L n p h` are not supported.\n",
    "\n",
    "A format specifier follows this prototype:\n",
    "\n",
    "`%[flags][width][.precision][length]specifier`\n",
    "\n",
    "Some common specifiers are given below:\n",
    "\n",
    "| Specifier | Meaning          |\n",
    "| --        | --               |\n",
    "| `s`       | string           |\n",
    "| `q`       | quoted string    |\n",
    "| `c`       | character        |\n",
    "| `d`       | signed integer   |\n",
    "| `u`       | unsigned integer |\n",
    "| `x`       | hexadecimal      |\n",
    "| `o`       | octal            |\n",
    "| `e`       | exponent         |\n",
    "| `f`       | float            |\n",
    "\n",
    "The flags that can be used are:\n",
    "\n",
    "- `-`: Left-justify within the given field width; right justification is the default.\n",
    "\n",
    "- `+`: Forces to preceed the result with a plus or minus sign (+ or -) even for positive numbers. By default, only negative numbers are preceded with a - sign.\n",
    "\n",
    "- `#`: When used with `o` or `x` specifiers, the value is preceeded with `0` or `0x` respectively for values different than zero.\n",
    "\n",
    "- `0`: Left-pads the number with zeroes (0) instead of spaces when padding is specified.\n"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "02061447",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b, c = \"string\", 1000, 2.718\n",
    "\n",
    "print( string.format(\"String: %s\", a)                  )\n",
    "print( string.format(\"Preceding with blanks: %10s\", a) )\n",
    "print( string.format(\"Signed Integer: %d\", b)          )\n",
    "print( string.format(\"Preceding with zeros: %010d\", b) )\n",
    "print( string.format(\"Float: %.2f\", c)                 )\n",
    "print( string.format(\"Scientific Notation: %.0e\", b)   )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fc903cce",
   "metadata": {},
   "source": [
    "## Pattern Matching\n",
    "\n",
    "Lua's **string library** doesn't support regular expressions (regex), but it supports something similar, albeit more limited in functionality.\n",
    "\n",
    "Lua recognizes the following character classes:\n",
    "\n",
    "| Class | Matching section                        |\n",
    "| --    | --                                      |\n",
    "| %a    | letters (A-Z, a-z)                      |\n",
    "| %c    | control characters (\\n, \\t, \\r, ...)    |\n",
    "| %d    | digits (0-9)                            |\n",
    "| %l    | lower-case letter (a-z)                 |\n",
    "| %p    | punctuation characters (!, ?, &, ...)   |\n",
    "| %s    | space characters                        |\n",
    "| %u    | upper-case letters                      |\n",
    "| %w    | alphanumeric characters (A-Z, a-z, 0-9) |\n",
    "| %x    | hexadecimal digits (\\3, \\4, ...)        |\n",
    "| %z    | the character with representation 0     |\n",
    "\n",
    "An upper case version of any of those classes represents the **complement of the class**. For instance, `%A` represents all non-letter characters.\n",
    "\n",
    "The  characters `( ) . % + - * ? [ ^ $`, known as _magic characters_, have special meanings when used in a pattern.\n",
    "\n",
    "- `.` matches any character.\n",
    "\n",
    "- `%` works as an escape character for the magic characters. That is, to match a plus sign (`+`), we have to include it as `%+` in the pattern string.\n",
    "\n",
    "- Square brackets can be used to define custom character classes. For example, `[%w%d]` matches both letters and digits. Appending `^` to the start of a character class negates the class. For example, `[^%d]` matches any non-digit character and is equivalent to `%D`.\n",
    "\n",
    "- `+ - * ?`, known as _modifier characters_, can be appended to a character (or class) to indicate whether the character (or class) can repeat or is optional.\n",
    "    + `*` - match the previous character (or class) zero or more times, as many times as possible (greedy)\n",
    "    + `+` - match the previous character (or class) one or more times\n",
    "    + `-` - match the previous character (or class) zero or more times, as few times as possible (lazy)\n",
    "    + `?` - make the previous character (or class) optional\n",
    "\n",
    "- Round brackets can be used to capture and return sections of the matched string instead of the full string.\n",
    "\n",
    "**Caveats**\n",
    "\n",
    "- With regular expressions, `(foo)+` can be used to match the string `foo` one or more times. In Lua, only a character (or class) can be repeated.\n",
    "\n",
    "- Lua also doesn't support choosing between one or more strings as in `(foo|bar)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "28087827",
   "metadata": {},
   "outputs": [],
   "source": [
    "local str = 'email me at moon@lua.com for more info'\n",
    "local pat = '[%w%d%-_]+@[%w%d%-_]+%.[%w%d%-_]+'\n",
    "\n",
    "print( string.match(str, pat) ) --> moon@lua.com"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "34770316",
   "metadata": {},
   "outputs": [],
   "source": [
    "local str = 'color:#@(fg)'\n",
    "local pat = '@%(([^()]+)%)'\n",
    "local repl = 'FF00FF'\n",
    "\n",
    "print( string.gsub(str, pat, repl) ) --> color:#FF00FF"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c7b07e50",
   "metadata": {},
   "source": [
    "# Control Structures"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "62a602a8",
   "metadata": {},
   "source": [
    "## Conditional Statements"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "66e93817",
   "metadata": {},
   "outputs": [],
   "source": [
    "local num = math.random(1, 100)\n",
    "\n",
    "if (num < 25) then\n",
    "    print( string.format(\"%d < 25\", num) )\n",
    "elseif (num < 50) then\n",
    "    print( string.format(\"%d < 50\", num) )\n",
    "else\n",
    "    print( string.format(\"%d >= 50\", num) )\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "1eb76487",
   "metadata": {},
   "source": [
    "## Loops"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b507103d",
   "metadata": {},
   "source": [
    "- loop `while` condition is `true`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "0e410d6c",
   "metadata": {},
   "outputs": [],
   "source": [
    "local i = 1\n",
    "\n",
    "while i <= 5 do\n",
    "    io.write(i, \" \") --> 1  2  3  4  5\n",
    "    i = i + 1\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "95f8daf4",
   "metadata": {},
   "source": [
    "- `repeat` until the condition is `false`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "bb398f44",
   "metadata": {},
   "outputs": [],
   "source": [
    "local i = 1\n",
    "\n",
    "repeat\n",
    "    io.write(i, \" \") --> 1  2  3  4  5\n",
    "    i = i + 1\n",
    "until i > 5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "65d008be",
   "metadata": {},
   "source": [
    "- `for` loop"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c6b5af85",
   "metadata": {},
   "outputs": [],
   "source": [
    "for i = 1, 5, 1 do -- we can omit the step size since default is 1\n",
    "    io.write(i, \" \") --> 1  2  3  4  5\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "92439e5d",
   "metadata": {},
   "source": [
    "## Break"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "294150f3",
   "metadata": {},
   "outputs": [],
   "source": [
    "local min, max = 1, 100\n",
    "local secret = math.random(min, max)\n",
    "\n",
    "while true do\n",
    "    io.write(string.format(\"Guess a number from %d to %d: \", min, max))\n",
    "    local guess = io.read(\"*n\") -- \"*n\" means read a number\n",
    "    if guess == secret then\n",
    "        print(\"Correct!\")\n",
    "        break\n",
    "    else\n",
    "        if guess > secret then\n",
    "            print(\"The guess is too high!\")\n",
    "        else\n",
    "            print (\"The guess is too low!\")\n",
    "        end\n",
    "    end\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "01246f7c",
   "metadata": {},
   "source": [
    "## Continue\n",
    "\n",
    "- Lua doesn't have a `continue` statement. One workaround is to use a `goto` statement."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1bfb2c88",
   "metadata": {},
   "outputs": [],
   "source": [
    "for i=1, 10 do\n",
    "    if (i % 2 == 0) then goto continue end\n",
    "    io.write(i, \" \")\n",
    "    ::continue::\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "322599ed",
   "metadata": {},
   "source": [
    "- Lua 5.1 and earlier doesn't have `goto`. The above code would have to be rewritten as shown below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "8576bca1",
   "metadata": {},
   "outputs": [],
   "source": [
    "for i=1, 10 do\n",
    "    if (i % 2 ~= 0) then\n",
    "        io.write(i, \" \")\n",
    "    end\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "27595fbd",
   "metadata": {},
   "source": [
    "# Tables\n",
    "\n",
    "Tables are the only \"container\" type in Lua. They are **associative arrays**, which means they store a set of key/value pairs. In a key/value pair, you can store a value under a key and then later retrieve the value using that key.\n",
    "\n",
    "The `#` operator can be used to retrieve the length of a string or the number of elements in a table. However, when used with tables, it doesn't count all the items in the table. Instead it finds the last **integer key**. Because of how it's implemented, its results are undefined if all the integer keys in the table aren't consecutive, which is why it shouldn't be used for tables used as sparse arrays."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "232fff99",
   "metadata": {},
   "source": [
    "## Indexing\n",
    "\n",
    "Indexing in Lua starts at 1. Since tables in Lua are associative, declaring `vec = {\"a\", \"b\", \"c\"}` is the same as writing `vec = {[1]=\"a\", [2]=\"b\", [3]=\"c\"}`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "c9572c41",
   "metadata": {},
   "outputs": [],
   "source": [
    "local T =  {\n",
    "    4, 8, \"x\",         -- indexed with T[1], T[2], T[3]\n",
    "    [\"title\"] = \"Lua\", -- indexed with T[\"title\"] or T.title\n",
    "    x = 3,             -- indexed with T[\"x\"] or T.x\n",
    "    [\"the page\"] = 5,  -- indexed with T[\"the page\"]\n",
    "    [123] = 456,       -- indexed with T[123]\n",
    "    {4, 5, 6}          -- indexed with T[4][1], T[4][2], T[4][3]\n",
    "}\n",
    "-- # returns only the last consecutive integer key !!\n",
    "print( #T ) --> 4"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "c209a343",
   "metadata": {},
   "source": [
    "## Basic Table Operations\n",
    "\n",
    "Lua provides `ipairs` and `pairs` as iterator functions that provide successive elements from a table. Both of these functions return two variables: key/index and value. Generally, `ipairs` should be used to iterate over arrays since the `ipairs` iterator will stop at the first non-initialized index (the index at which the value is `nil`)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "cca061ab",
   "metadata": {},
   "outputs": [],
   "source": [
    "local T = {\"b\", \"c\", \"d\"} --> {[1]=\"b\", [2]=\"c\", [3]=\"d\"}\n",
    "\n",
    "-- update an entry\n",
    "T[1] = \"a\" --> {[1]=\"a\", [2]=\"c\", [3]=\"d\"}\n",
    "\n",
    "-- add a new item at a specific unoccupied index\n",
    "T[10] = \"j\" --> {[1]=\"a\", [2]=\"c\", [3]=\"d\", [10]=\"j\"}\n",
    "\n",
    "-- add a new item to the end of the last consecutive integer key\n",
    "table.insert(T, \"e\") --> {[1]=\"a\", [2]=\"c\", [3]=\"d\", [4],\"e\", [10]=\"j\"}\n",
    "\n",
    "-- insert a new item at a specific occupied index\n",
    "table.insert(T, 2, \"b\") --> {[1]=\"a\", [2]=\"b\", [3]=\"c\", [4]=\"d\", [5],\"e\", [10]=\"j\"}\n",
    "\n",
    "-- T[6] = nil, so the loop stops at T[5]\n",
    "for index, value in ipairs(T) do\n",
    "    print(index, value)\n",
    "end\n",
    "\n",
    "-- delete a key/value pair by setting the key to nil\n",
    "T[3] = nil --> {[1]=\"a\", [2]=\"b\", [3]=nil, [4]=\"d\", [5],\"e\", [10]=\"j\"}\n",
    "\n",
    "-- remove item from a specific location\n",
    "table.remove(T, 3) --> {[1]=\"a\", [2]=\"b\", [4]=\"d\", [5],\"e\", [10]=\"j\"}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d3e972b8",
   "metadata": {},
   "source": [
    "## Other Table Methods"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "691109c9",
   "metadata": {},
   "source": [
    "- Concatenate the elements of a table to form a string: `table.concat(table[, separator[, start_index[, end_index])`"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "51df039d",
   "metadata": {},
   "outputs": [],
   "source": [
    "local T = {[1]=\"a\", [2]=\"b\", [3]=\"c\", [10]=\"j\"}\n",
    "\n",
    "print( table.concat(T, \", \", 2, 3) ) --> b, c"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "7c944d2e",
   "metadata": {},
   "source": [
    "- Move the elements in table `T` from index `f` until `e` (both inclusive) to position `t`. This function was introduced in Lua 5.3."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "3d095f96",
   "metadata": {},
   "outputs": [],
   "source": [
    "local T = {2, 3, 4, 5}\n",
    "\n",
    "table.move(T, 1, #a, 2) --> T = {2, 2, 3, 4, 5}\n",
    "T[1] = 1 --> T = {1, 2, 3, 4, 5}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "40183a5b",
   "metadata": {},
   "source": [
    "- Sort list elements in a given order, _in-place_. If `comp` is given, then it must be a function that receives two list elements and returns `true` when the first element must come before the second in the final order. If `comp` is not given, then the standard Lua operator `<` is used instead. "
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "f9eae1ca",
   "metadata": {},
   "outputs": [],
   "source": [
    "local T = {\"John\", \"Mary\", \"Thomas\"}\n",
    "\n",
    "-- create a comparison function to sort according to the second letter\n",
    "local function comp(s1, s2)\n",
    "    return string.sub(s1,2,2) > string.sub(s2,2,2)\n",
    "end\n",
    "\n",
    "-- sort the table according to this function\n",
    "table.sort(T, comp) --> T = {John, Thomas, Mary}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "fbca07e3",
   "metadata": {},
   "source": [
    "# Functions"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5e029773",
   "metadata": {},
   "source": [
    "## Basic Expression\n",
    "\n",
    "Lua supports first class functions, which means that functions can be stored in variables (both global and local) and in tables, can be passed as arguments, and can be returned by other functions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "197576f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "local function add (a, b)\n",
    "    return a + b\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "de092906",
   "metadata": {},
   "source": [
    "Since Lua supports first class functions, the above function can also be written as shown below:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6697d866",
   "metadata": {},
   "outputs": [],
   "source": [
    "local add\n",
    "add = function (a, b)\n",
    "    return a + b\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "ee0f29b7",
   "metadata": {},
   "source": [
    "When performing a function call, if the function has one single argument and this argument is either a **literal string** or a **table** constructor, then the **parentheses are optional**; so, both `print(\"Hello\")` and `print \"Hello\"` are valid."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "db31ccb2",
   "metadata": {},
   "source": [
    "## Function Parameters\n",
    "\n",
    "This is how Lua handles function parameters:\n",
    "\n",
    "| CALL           | PARAMETERS                  |\n",
    "| --             | --                          |\n",
    "| `add(3, 4)`    | a=3, b=4                    |\n",
    "| `add(3, 4, 5)` | a=3, b=4   (5 is discarded) |\n",
    "| `add(3)`       | a=3, b=nil                  |"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "19da12af",
   "metadata": {},
   "source": [
    "## Default Arguments\n",
    "\n",
    "A typical way to assign a default value to a variable in Lua is to use the construct `var = var or default_value`. The `or` operator will return the left value if it is not `nil` or `false`, otherwise it will return the right value."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "18fbfeb2",
   "metadata": {},
   "outputs": [],
   "source": [
    "function add (a, b)\n",
    "    b = b or 10 -- if b is nil, set it to 10\n",
    "    return a + b\n",
    "end\n",
    "\n",
    "print( add(3) ) --> 13"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "32674284",
   "metadata": {},
   "source": [
    "## Returning Multiple Values\n",
    "\n",
    "When returning multiple values, we can either return them with:\n",
    "\n",
    "1. `return var1, var2, var3`. **Note**: Do not group the results with a pair of parenthesis since a pair of parenthesis around the returned values only returns the first result!\n",
    "2. `return {var1, var2, var2}` (return them in a table)\n",
    "\n",
    "For case 1, Lua always adjusts the number of results from a function to match the number of variables. This is explained below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "6a01f04e",
   "metadata": {},
   "outputs": [],
   "source": [
    "function arith(a, b)\n",
    "    r1 = a + b\n",
    "    r2 = a - b\n",
    "    r3 = a * b\n",
    "    return r1, r2, r3\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5a1eb692",
   "metadata": {},
   "source": [
    "- function has no result for the fourth variable"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d39f92f7",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b, c, d = arith(5,4)\n",
    "print( a, b, c, d ) --> a=9, b=1, c=20, d=nil"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "429be31c",
   "metadata": {},
   "source": [
    "- extra return values are discarded"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "db93f694",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b = arith(5,4)\n",
    "print( a, b ) --> a=9, b=1"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "10af4d88",
   "metadata": {},
   "source": [
    "- a function call that is not the last element in the list returns only the first result!"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "17393e1e",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b, c, d = arith(5,4), 10\n",
    "print( a, b, c, d ) --> a=9, b=10, c=nil, d=nil"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b092b41b",
   "metadata": {},
   "source": [
    "- the correct way is to place the function call at the end"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "05f20f8a",
   "metadata": {},
   "outputs": [],
   "source": [
    "local a, b, c, d = 10, arith(5,4)\n",
    "print( a, b, c, d ) --> a=10, b=9, c=1, d=20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "48b12658",
   "metadata": {},
   "source": [
    "If we return the results in a table and we want to assign them to variables, we will need to **unpack** the results first. We can use the global `unpack` function for Lua versions below 5.3 and `table.unpack` for later versions."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "723e6050",
   "metadata": {},
   "outputs": [],
   "source": [
    "local function arith(a, b)\n",
    "    r1 = a + b\n",
    "    r2 = a - b\n",
    "    r3 = a * b\n",
    "    return {r1, r2, r3}\n",
    "end\n",
    "\n",
    "-- unpacking the results\n",
    "local k, l, m = table.unpack(arith(5,4))\n",
    "print( k, l, m ) --> k=9, l=1, m=20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "e2ba707c",
   "metadata": {},
   "source": [
    "## Variable Number of Arguements\n",
    "\n",
    "Three dots `...` in a parameter list indicate that the function has a variable number of arguments. We can pass the list of variable arguments that we receive to another function using the same `...` operator."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "24459c2b",
   "metadata": {},
   "outputs": [],
   "source": [
    "local function average(...)\n",
    "    local sum = 0\n",
    "    local arg = {...} -- capture arguments in a table\n",
    "    \n",
    "    -- `_` is a placeholder for a variable whose value we don't care about\n",
    "    for _, value in ipairs(arg) do\n",
    "        sum = sum + value\n",
    "    end\n",
    "    \n",
    "    return (sum / #arg)\n",
    "end\n",
    "\n",
    "print( string.format(\"The average is %.f.\", average(10,5,3,4,5,6)) )"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "251ba5f4",
   "metadata": {},
   "source": [
    "## Non-Global Functions\n",
    "\n",
    "Lua supports first class functions, which means that functions can be stored in tables. Most Lua libraries store functions in table fields. For example, `math.sin`. Such definitions are particularly useful for packages as Lua does not provide any explicit mechanism for packages."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1bc9b540",
   "metadata": {},
   "outputs": [],
   "source": [
    "local M = {} -- create an empty table\n",
    "\n",
    "-- define functions that can be accessed with M.function_name\n",
    "function M.gcd(a, b)\n",
    "    if b ~= 0 then\n",
    "        return M.gcd(b, a % b)\n",
    "    else\n",
    "        return math.abs(a)\n",
    "    end\n",
    "end\n",
    "\n",
    "print( M.gcd(8, 12) ) --> 4"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "35b99810",
   "metadata": {},
   "source": [
    "## Closures\n",
    "\n",
    "We have a *closure* when:\n",
    "\n",
    "- a nested function references a value (called an _upvalue_ in Lua lingo) of its enclosing function, and then\n",
    "- the enclosing function returns the nested function"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "80492ea1",
   "metadata": {},
   "source": [
    "### Simple Class\n",
    "\n",
    "Closures can be used to mimic a simple class (in object-oriented languages) with instance variables and methods."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "a858885e",
   "metadata": {},
   "outputs": [],
   "source": [
    "local function f()\n",
    "    -- this variable will be captured by the closure\n",
    "    -- it acts like an instance variable\n",
    "    local v = 0\n",
    "    -- nested function\n",
    "    -- it acts like an instance method\n",
    "    local function get()\n",
    "        return v\n",
    "    end\n",
    "    -- another nested function\n",
    "    local function set(new_v)\n",
    "        v = new_v\n",
    "    end\n",
    "    -- enclosing function returns nested functions\n",
    "    return {get=get, set=set}\n",
    "end\n",
    "\n",
    "local t = f() -- create an instance of the closure\n",
    "print(t.get()) --> 0\n",
    "t.set(5)\n",
    "print(t.get()) --> 5"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "528f232f",
   "metadata": {},
   "source": [
    "### Iterator Functions\n",
    "\n",
    "Another common use of closures is to create custom iterator functions. In the example below, we build a custom iterator that returns the next number of a power series of a given length."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "21b4cd24",
   "metadata": {},
   "outputs": [],
   "source": [
    "function power_iter(exp, len) -- exp = exponent, len = length of the series\n",
    "    local iter = 1 -- variable to keep track of where we are in the series\n",
    "    \n",
    "    return function ()\n",
    "        -- the closure captures variables: exp, len, iter\n",
    "        if iter <= len then     \n",
    "            local res = math.pow(iter, exp)\n",
    "            iter = iter + 1\n",
    "            return res\n",
    "        else\n",
    "            return nil\n",
    "        end\n",
    "    end\n",
    "    \n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "88cf725d",
   "metadata": {},
   "source": [
    "We can use the iterator in two ways:"
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1e7e3c7c",
   "metadata": {},
   "outputs": [],
   "source": [
    "local square = power_iter(2, 5) -- square series of length 5\n",
    "\n",
    "while true do\n",
    "    local num = square() -- call iterator to return the next value\n",
    "    if num == nil then break end\n",
    "    io.write(num, \" \") --> 1  4  9  16  25\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "34cfd39d",
   "metadata": {},
   "source": [
    "A downside to using the iterator as we did above is that once that iterator reaches the end, it becomes exhausted and can no longer be used.\n",
    "\n",
    "The second way to use the iterator is given below."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d0735410",
   "metadata": {},
   "outputs": [],
   "source": [
    "for num in power_iter(3, 4) do\n",
    "    io.write(num, \" \") --> 1  8  27  64\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "531fc063",
   "metadata": {},
   "source": [
    "# Metatables"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "5d98d1de",
   "metadata": {},
   "source": [
    "## Tables as Unordered Sets\n",
    "\n",
    "A set is a data structure in which all the items are unique. An easy way to implement sets in Lua is to store items in the keys of a table and setting the values to a dummy value (like `true`). Doing this will help you use a table like an unordered set with fast insertion and removal since there is no need to shift the items in the table when an item is added or removed. Also, when checking whether an item is in the set, instead of searching the table for a given element, you just index the table and test whether the returned value is `nil` or not."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "1ff0e3ea",
   "metadata": {},
   "outputs": [],
   "source": [
    "-- a function that makes a table behave like a set\n",
    "local function Set (list)\n",
    "    local set = {}\n",
    "    for _, v in ipairs(list) do\n",
    "        set[v] = true\n",
    "    end\n",
    "    return set\n",
    "end\n",
    "\n",
    "local s1 = Set {1, 2, 3, 2, 4} --> s1 = {1, 2, 3, 4}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "946ab033",
   "metadata": {},
   "source": [
    "Now that we've found a way to use tables to represent sets, how can we use operators such as `+` and `-` to find the union and difference of two sets? This is where [**metatables**](https://www.lua.org/pil/13.html) and **metamethods** come to the rescue.\n",
    "\n",
    "Suppose we want the addition operator (`+`) to compute the union of two sets. Clearly, Lua does not know the mathematical definition of the union of two sets. We can tell it by creating a function that implements the union operation and then associate this function with the `+` operator.\n",
    "\n",
    "Let us call the union function associated with the `+` operator a **metamethod**. This is nothing new. This is known as operator overloading in other programming languages. What is new is that we need to inform all `Set` objects of the existence of this metamethod so that the expression `s1 + s2` calls our union function on the two sets.\n",
    "\n",
    "The way this is done is to define all our functions in a separate table, called a **metatable**, and then inform our objects to inherit from this table using the `setmetatable` function.\n",
    "\n",
    "When you create a new table, Lua does not give it a metatable. That is, by default a table will have a `nil` value for its metatable. The steps required to assign a metatable to our `Set` object are listed below:\n",
    "\n",
    "- Create a regular table that we will use as the metatable for our sets. For example, `Set.mt = {}`\n",
    "- To use the `+` operator, we redefine the reserved function `__add` of the metatable `Set.mt` to implement the union operation\n",
    "- Finally, we associate each of our `Set` objects (which are tables) with the metatable\n",
    "\n",
    "Complementary to the `setmetatable` method, you can retrieve the metatable of a table using the `getmetatable` method."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d4b3fdd7",
   "metadata": {},
   "outputs": [],
   "source": [
    "Set = {}\n",
    "\n",
    "-- create a metatable for Set\n",
    "Set.mt = {}\n",
    "\n",
    "-- method to make a table behave like a set object\n",
    "function Set.new (list)\n",
    "    local set = {}\n",
    "    setmetatable(set, Set.mt) -- associate each set object with the metatable\n",
    "    for _, v in ipairs(list) do set[v] = true end\n",
    "    return set\n",
    "end\n",
    "\n",
    "-- metamethod that allows us to use + to compute the union of two sets\n",
    "function Set.mt.__add (a, b)\n",
    "    local res = Set.new {}\n",
    "    for k in pairs(a) do res[k] = true end\n",
    "    for k in pairs(b) do res[k] = true end\n",
    "    return res\n",
    "end\n",
    "\n",
    "-- metamethod that allows us to use tostring(obj)\n",
    "function Set.mt.__tostring (set)\n",
    "    local s = \"{\"\n",
    "    local sep = \"\"\n",
    "    for e in pairs(set) do\n",
    "        s = s .. sep .. e\n",
    "        sep = \", \"\n",
    "    end\n",
    "    return s .. \"}\"\n",
    "end\n",
    "\n",
    "local s1 = Set.new {1, 2, 3}\n",
    "local s2 = Set.new {3, 4, 5}\n",
    "local s3 = s1 + s2\n",
    "\n",
    "print( s1 + s2 ) --> {1, 2, 3, 4, 5}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "81a1f970",
   "metadata": {},
   "source": [
    "For each arithmetic operator there is a corresponding field name in a metatable. Besides `__add`, there are:\n",
    "\n",
    "- `__sub` (for subtraction)\n",
    "- `__mul` (for multiplication)\n",
    "- `__div` (for division)\n",
    "- `__unm` (for negation)\n",
    "- `__pow` (for exponentiation)\n",
    "- `__mod` (for modulo)\n",
    "- `__concat` (for the concatenation operator `..`).\n",
    "\n",
    "For relational operators, there are:\n",
    "\n",
    "- `__eq` (_equality_)\n",
    "- `__lt` (_less than_)\n",
    "- `__le` (_less or equal_)\n",
    "\n",
    "There are no separate metamethods for the other three relational operators, as Lua translates `a ~= b` to `not (a == b)`, `a > b` to `b < a`, and `a >= b` to `b <= a`.\n",
    "\n",
    "Other useful metamethods include:\n",
    "\n",
    "- `__tostring`, which is used for string representation.\n",
    "- `__call`, which makes the object callable.\n",
    "- `__index`, which specifies how we retrieve values from missing keys in a table.\n",
    "- `__newindex`, which specifies how we assign values to missing keys.\n",
    "\n",
    "\n",
    "We make use of the simple example below to demonstrate how `__index` and `__newindex` work."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "93962cf4",
   "metadata": {},
   "outputs": [],
   "source": [
    "local P = { x=10 } -- P has only one field\n",
    "\n",
    "-- let's put some default values in the metatable\n",
    "local meta = { x=0, y=0 }\n",
    "\n",
    "-- let's add the __index metamethod to the metatable\n",
    "meta.__index = function(table, key)\n",
    "    return meta[key]\n",
    "end\n",
    "\n",
    "-- let's add the __newindex metamethod to the metatable\n",
    "meta.__newindex = function(table, key, value)\n",
    "    meta[key] = value\n",
    "end\n",
    "\n",
    "-- Now, let's associate P with the metatable\n",
    "setmetatable(P, meta)\n",
    "\n",
    "print( P.x, P.y, P.z ) --> 10  0  nil\n",
    "\n",
    "P.z = 20\n",
    "\n",
    "print( P.x, P.y, P.z ) --> 10  0  20"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "77c608db",
   "metadata": {},
   "source": [
    "In the above snippet, when we call `P.x`, since `P` has a `x` field, the value of `x` is returned. When we call `P.y`, Lua sees that `P` does not have a `y` field, but is associated a metatable that has an `__index` metamethod. Lua then calls the `__index` method with `P` and `y`. In the example here, the metamethod indexes itself. This is because the metatable is `meta` and we are searching for `y` inside `meta`. In cases where the `__index` metamethod is just indexing the metatable, we can replace the entire function with just `meta.__index = meta`. If `y` is found inside the metatable, the value of `y` is returned, otherwise `nil` is returned.\n",
    "\n",
    "Finally, when we execute `P.z = 20`, Lua sees that `P` does not have a `z` field but has a metatable with a `__newindex` metamethod. Lua then calls the `__newindex` metamethod and assigns a new key/value pair to `meta`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "cbb1e910",
   "metadata": {},
   "source": [
    "## Object Oriented Programming\n",
    "\n",
    "In many OO languages, **classes** can be thought of as the templates from which **objects** can be created. The class definition typically specifies **instance variables**, also known as data members or data attributes, that the object contains, as well as the **methods**, also known as member functions, that the object can execute.\n",
    "\n",
    "Lua does not have the concept of a class. However, we can use tables to emulate its functionality. We already know enough to build a simple class. The steps are outlined below:\n",
    "\n",
    "- We create a namespace for the class. For example, `MyClass = {}`.\n",
    "- We then create a class prototype table that contains the data attributes and methods that all object will share.\n",
    "- Next, we create a class metatable in which we can define our metamethods and also use to index the prototype table so that objects can inherit from the prototype.\n",
    "- Finally, we create a constructor function where we set the metatable of all newly created objects to that of the class metatable."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "84013b5b",
   "metadata": {},
   "outputs": [],
   "source": [
    "local Vector = {} -- our class\n",
    "\n",
    "-- class data members and methods go in the prototype\n",
    "Vector.prototype = { x=0, y=0, z=0 }\n",
    "\n",
    "-- metamethods go in the metatable\n",
    "-- metatable also indexes the prototype table\n",
    "Vector.mt = { __index = Vector.prototype }\n",
    "\n",
    "-- constructor\n",
    "function Vector.new (obj)\n",
    "    obj = obj or {}   -- create object if user does not provide one\n",
    "    setmetatable(obj, Vector.mt)\n",
    "    return obj\n",
    "end\n",
    "\n",
    "-- metamethod\n",
    "Vector.mt.__add = function(v1, v2)\n",
    "    local vec = Vector.new()\n",
    "    vec.x = v1.x + v2.x\n",
    "    vec.y = v1.y + v2.y\n",
    "    vec.z = v1.z + v2.z\n",
    "    return vec\n",
    "end\n",
    "\n",
    "-- prototype method\n",
    "Vector.prototype.translate = function (vec, dy, dx, dz)\n",
    "    vec.x = vec.x + dx\n",
    "    vec.y = vec.y + dy\n",
    "    vec.z = vec.z + dz\n",
    "end\n",
    "\n",
    "local v1 = Vector.new {x=10,y=10,z=10}\n",
    "local v2 = Vector.new {x=15, y=15}\n",
    "local v3 = Vector.new()\n",
    "\n",
    "v3 = v1 + v2\n",
    "v1.translate(v1, 10, 10, 10)\n",
    "\n",
    "print( v1.x, v1.y, v1.z ) --> 20  20  20\n",
    "print( v2.x, v2.y, v2.z ) --> 15  15  0\n",
    "print( v3.x, v3.y, v3.z ) --> 25  25  10"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "b54da8b7",
   "metadata": {},
   "source": [
    "The above code works as expected but it's a little bit verbose:\n",
    "\n",
    "- we have to explicitly create a metatable\n",
    "- the notation used to apply the `translate` method on the object is a little bit inconvenient\n",
    "\n",
    "Fortunately, there is a solution to these two issues:\n",
    "\n",
    "For the first issue, we arrange for all new objects to inherit their operations directly from `Vector`. We can reference `Vector` with the `self` keyword. All we then need to do is set the metatable of new objects to `self` and set the `__index` metamethod of `self` to point to `self`.\n",
    "\n",
    "As for the second issue, we can also use the `self` keyword to point to the object that called the method. So, `Vector.translate (vec, dy, dx, dz)` becomes `Vector.translate (self, dy, dx, dz)`. While this doesn't seem to have solved the issue of the inconvenient notation, Lua offers the `:` operator to allow us to hide `self` from the parameter list (even though it is there) and get instead `Vector:translate (dy, dx, dz)`."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "2883c9bc",
   "metadata": {},
   "outputs": [],
   "source": [
    "Vector = {  x=0, y=0, z=0 } -- our class\n",
    "\n",
    "-- constructor\n",
    "function Vector:new (obj)\n",
    "    obj = obj or {}   -- create object if user does not provide one\n",
    "    setmetatable(obj, self)\n",
    "    self.__index = self\n",
    "    return obj\n",
    "end\n",
    "\n",
    "-- metamethod\n",
    "Vector.__add = function(v1, v2)\n",
    "    local vec = Vector:new()\n",
    "    vec.x = v1.x + v2.x\n",
    "    vec.y = v1.y + v2.y\n",
    "    vec.z = v1.z + v2.z\n",
    "    return vec\n",
    "end\n",
    "\n",
    "-- prototype method\n",
    "function Vector:translate (dy, dx, dz)\n",
    "    self.x = self.x + dx\n",
    "    self.y = self.y + dy\n",
    "    self.z = self.z + dz\n",
    "end\n",
    "\n",
    "local v1 = Vector:new {x=10,y=10,z=10}\n",
    "local v2 = Vector:new {x=15, y=15}\n",
    "local v3 = Vector:new()\n",
    "\n",
    "v3 = v1 + v2\n",
    "v1:translate(10, 10, 10)\n",
    "\n",
    "print( v1.x, v1.y, v1.z ) --> 20  20  20\n",
    "print( v2.x, v2.y, v2.z ) --> 15  15  0\n",
    "print( v3.x, v3.y, v3.z ) --> 25  25  10"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "0a5c1a0b",
   "metadata": {},
   "source": [
    "# Packages\n",
    "\n",
    "Lua does not provide any explicit mechanism for organizing code in packages. However, we can implement them easily by a table, as the basic libraries do.\n",
    "\n",
    "All the functions defined inside the package can be called from outside the package. If we do not want a function to be accessible from outside the package, we can declare it `local`.\n",
    "\n",
    "When using tables for packages, we must explicitly put the package name in every function definition and a function that calls another function inside the same package must prefix the function name with the package name. We can ameliorate these problems by using a fixed local name for the package (`M`, for instance)."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "b2cce3f5",
   "metadata": {},
   "outputs": [],
   "source": [
    "local M = {} -- all definitions go inside this table\n",
    "\n",
    "local function fib_r (n)\n",
    "    if n <= 1 then return n else return fib1(n-1) + fib1(n-2) end\n",
    "end\n",
    "\n",
    "function M.fib_m (n)\n",
    "    local memo = {1, 1}\n",
    "    local function inner (n)\n",
    "        if memo[n] == nil then\n",
    "            memo[n] = inner(n - 1) + inner(n - 2)\n",
    "        end\n",
    "        return memo[n]\n",
    "    end\n",
    "    return inner(n)\n",
    "end\n",
    "\n",
    "function M.fib_t (n)\n",
    "    local T = {}\n",
    "    T[1], T[2] = 0, 1\n",
    "    for i=1,n-1 do\n",
    "        T[i+1] = T[i+1] + T[i]\n",
    "        T[i+2] = T[i]\n",
    "    end\n",
    "    T[#T] = T[#T] + T[#T-1]\n",
    "    return T[#T]\n",
    "end\n",
    "\n",
    "return M"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "d5fe71ec",
   "metadata": {},
   "source": [
    "A drawback of this approach is its verbosity when accessing other public entities inside the same package, as every access still needs the prefix `M`. A bigger problem is that we have to change the calls whenever we change the status of a function from private to public (or from public to private). \n",
    "\n",
    "A solution to this problem is to declare all functions in our package as `local` and later put them in the final table to be exported."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "9327d590",
   "metadata": {},
   "outputs": [],
   "source": [
    "local function fib_r (n)\n",
    "    if n <= 1 then return n else return fib1(n-1) + fib1(n-2) end\n",
    "end\n",
    "\n",
    "local function fib_m (n)\n",
    "    local memo = {1, 1}\n",
    "    local function inner (n)\n",
    "        if memo[n] == nil then\n",
    "            memo[n] = inner(n - 1) + inner(n - 2)\n",
    "        end\n",
    "        return memo[n]\n",
    "    end\n",
    "    return inner(n)\n",
    "end\n",
    "\n",
    "local function fib_t (n)\n",
    "    local T = {}\n",
    "    T[1], T[2] = 0, 1\n",
    "    for i=1,n-1 do\n",
    "        T[i+1] = T[i+1] + T[i]\n",
    "        T[i+2] = T[i]\n",
    "    end\n",
    "    T[#T] = T[#T] + T[#T-1]\n",
    "    return T[#T]\n",
    "end\n",
    "\n",
    "-- MyPackage is global, so no need for `return MyPackage`\n",
    "MyPackage = {\n",
    "    fib_r = fib_r,\n",
    "    fib_t = fib_t\n",
    "}"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "115e1d7e",
   "metadata": {},
   "source": [
    "Finally, to make the functions in the package accessible in another file, we simply do:\n",
    "\n",
    "`local some_name = require \"MyPackage\"`\n",
    "\n",
    "To call a function from the package, we use `some_name.func_name`."
   ]
  },
  {
   "cell_type": "markdown",
   "id": "f709aaff",
   "metadata": {},
   "source": [
    "# The Environment\n",
    "\n",
    "Lua keeps all its global variables in a regular table, called the _environment_, and the the environment itself in a global variable `_G`.\n",
    "\n",
    "Because the environment is a regular table, you can simply index it with the desired key (the variable name): `value = _G[varname]`. This makes it possible to retrieve the value of a global variable when a local variable of the same name exists."
   ]
  },
  {
   "cell_type": "code",
   "execution_count": null,
   "id": "d20f64e4",
   "metadata": {},
   "outputs": [],
   "source": [
    "x = 10 -- global\n",
    "do\n",
    "    local x = 20\n",
    "    print(_G[\"x\"], x) --> 10  20\n",
    "end"
   ]
  },
  {
   "cell_type": "markdown",
   "id": "a43a622f",
   "metadata": {},
   "source": [
    "In a similar way, you can assign to a global variable whose name is computed dynamically, writing `_G[varname] = value`."
   ]
  }
 ],
 "metadata": {
  "kernelspec": {
   "display_name": "Lua",
   "language": "lua",
   "name": "lua"
  },
  "language_info": {
   "file_extension": ".lua",
   "mimetype": "text/x-lua",
   "name": "lua",
   "version": "5.4"
  },
  "toc-autonumbering": true,
  "toc-showtags": true
 },
 "nbformat": 4,
 "nbformat_minor": 5
}