Lua — Complete Beginner Tutorial

-- local keyword makes variables safe and scoped
local name    = "Alice"      -- string
local age     = 25           -- number
local score   = 95.5         -- number (all numbers are floats)
local passing = true         -- boolean
local nothing = nil          -- nil means "no value"

-- print() shows values in the console
print(name)
print(age)
print(score)
print(passing)
print(nothing)

-- type() tells you the type of any value
print(type(name))
print(type(age))
print(type(passing))
print(type(nothing))

local firstName = "Alice"
local lastName  = 'Smith'      -- single quotes work too
local greeting  = "Hello"

-- Concatenation uses .. (two dots)
local fullName = firstName .. " " .. lastName
print(fullName)
print(greeting .. ", " .. firstName .. "!")

-- # gives string length
print("Length:", #fullName)

-- String methods (two ways to call them)
print(string.upper(firstName))
print(firstName:upper())         -- colon syntax (same thing)
print(firstName:lower())
print(firstName:len())
print(firstName:rep(3, "-"))     -- repeat 3 times with separator
print(("  hello  "):match("^%s*(.-)%s*$"))  -- trim whitespace

-- Number to string
local n = 42
print("The answer is: " .. tostring(n))
print(type(tostring(n)))

local a = 20
local b = 6

-- Basic arithmetic
print(a + b)    -- 26
print(a - b)    -- 14
print(a * b)    -- 120
print(a / b)    -- 3.3333... (always float division)
print(a // b)   -- 3  (integer/floor division)
print(a % b)    -- 2  (remainder)
print(a ^ 2)    -- 400 (power — uses ^ not **)

-- Math library
print(math.sqrt(144))   -- 12.0
print(math.floor(3.9))  -- 3
print(math.ceil(3.1))   -- 4
print(math.abs(-7))     -- 7
print(math.max(4,7,2,9,1))  -- 9
print(math.min(4,7,2,9,1))  -- 1
print(math.pi)              -- 3.1415926535898

-- Random numbers
math.randomseed(42)
print(math.random(1, 10))   -- random int between 1 and 10

local score = 73

if score >= 90 then
    print("Grade: A — Outstanding!")
elseif score >= 80 then
    print("Grade: B — Great work!")
elseif score >= 70 then
    print("Grade: C — Good effort")
elseif score >= 60 then
    print("Grade: D — Just passed")
else
    print("Grade: F — Try again")
end

-- Truthy/falsy: only false and nil are falsy
print("--- Truthy/Falsy ---")
if 0 then print("0 is truthy!") end           -- prints! (unlike C/Python)
if "" then print("Empty string is truthy!") end -- prints!
if nil then print("never") else print("nil is falsy") end
if false then print("never") else print("false is falsy") end

-- Combining conditions with and / or / not
local age = 20
local hasID = true

if age >= 18 and hasID then
    print("Welcome!")
else
    print("Sorry, cannot enter.")
end

-- Numeric for: for var = start, stop, step do
print("--- Counting up ---")
for i = 1, 5 do
    print("Count:", i)
end

print("--- Counting down ---")
for i = 10, 1, -3 do       -- step of -3
    print(i)
end

print("--- while loop ---")
local count = 1
while count <= 4 do
    print("While:", count)
    count = count + 1       -- Lua has no ++ or +=
end

print("--- repeat-until ---")
local n = 5
repeat
    print("Repeat:", n)
    n = n - 1
until n <= 0                -- runs while condition is FALSE

print("--- break ---")
for i = 1, 10 do
    if i == 5 then
        print("Stopped at", i)
        break
    end
    print(i)
end

-- Basic function
local function greet(name)
    print("Hello, " .. name .. "!")
end

greet("Alice")
greet("Bob")

-- Function with return value
local function square(n)
    return n * n
end

print("5 squared:", square(5))
print("12 squared:", square(12))

-- Default parameter workaround (Lua has no defaults)
local function greetWithTitle(name, title)
    title = title or "Friend"    -- "or" trick for defaults!
    return "Hello, " .. title .. " " .. name .. "!"
end

print(greetWithTitle("Alice", "Dr"))
print(greetWithTitle("Bob"))        -- uses default

-- Functions are values — store them in variables
local double = function(n) return n * 2 end
print("Double 7:", double(7))

-- Pass functions as arguments
local function applyTwice(fn, value)
    return fn(fn(value))
end

print("Apply double twice to 3:", applyTwice(double, 3))

-- Return multiple values with comma
local function divmod(a, b)
    return math.floor(a / b), a % b   -- quotient AND remainder
end

local q, r = divmod(17, 5)
print("17 / 5 = " .. q .. " remainder " .. r)

-- Swap two values (classic use of multiple returns)
local function swap(a, b)
    return b, a
end

local x, y = 10, 20
print("Before:", x, y)
x, y = swap(x, y)
print("After:", x, y)

-- Return status + value (error handling pattern)
local function safeDivide(a, b)
    if b == 0 then
        return nil, "Error: cannot divide by zero"
    end
    return a / b, nil
end

local result, err = safeDivide(10, 2)
if err then
    print("Failed:", err)
else
    print("Result:", result)
end

local result2, err2 = safeDivide(10, 0)
if err2 then
    print("Failed:", err2)
else
    print("Result:", result2)
end

-- Closure: inner function remembers outer variables
local function makeCounter(start)
    local count = start or 0
    return function()       -- returns a function!
        count = count + 1
        return count
    end
end

local counter1 = makeCounter(0)
local counter2 = makeCounter(10)

print(counter1())   -- 1
print(counter1())   -- 2
print(counter1())   -- 3
print(counter2())   -- 11 (independent counter!)
print(counter2())   -- 12

print("---")

-- Variadic function: ... accepts any number of args
local function sum(...)
    local args = {...}     -- pack ... into a table
    local total = 0
    for _, v in ipairs(args) do
        total = total + v
    end
    return total
end

print("Sum:", sum(1, 2, 3))
print("Sum:", sum(10, 20, 30, 40, 50))

-- select('#', ...) counts the arguments
local function countArgs(...)
    print("Got", select('#', ...), "arguments")
end

countArgs("a", "b", "c", "d")

-- Create a table as an array
local fruits = {"apple", "banana", "cherry", "mango"}

-- Access by index — STARTS AT 1, NOT 0!
print(fruits[1])   -- first element
print(fruits[2])   -- second
print(fruits[4])   -- fourth
print(#fruits)     -- length: 4

-- Iterate with ipairs (in order, stops at first nil)
for i, fruit in ipairs(fruits) do
    print(i, fruit)
end

print("---")

-- Add to the end
table.insert(fruits, "kiwi")
print("After insert:", #fruits, fruits[5])

-- Insert at specific position
table.insert(fruits, 2, "grape")
print("After insert at 2:", fruits[2])

-- Remove from end
local removed = table.remove(fruits)
print("Removed:", removed)

-- Remove from position
table.remove(fruits, 1)
print("First item now:", fruits[1])

-- table.concat: join into a string
local numbers = {10, 20, 30, 40, 50}
print(table.concat(numbers, ", "))

-- Table as dictionary (key-value pairs)
local student = {
    name    = "Alice",
    age     = 20,
    score   = 95,
    city    = "Cape Town",
    passing = true,
}

-- Access with dot notation
print(student.name)
print(student.age)

-- Access with bracket notation (same thing)
print(student["score"])
print(student["city"])

-- Add new key
student.email = "alice@example.com"
print(student.email)

-- Check if key exists (returns nil if not)
print(student.phone)    -- nil (does not exist)

-- Delete a key (set to nil)
student.passing = nil
print(student.passing)  -- nil (deleted)

-- Iterate with pairs (any order)
print("--- All fields ---")
for key, value in pairs(student) do
    print(key, "=", value)
end

-- Mixed table (array + dictionary parts)
local mixed = {
    "first", "second", "third",  -- array part: indices 1,2,3
    label = "my table",           -- dictionary part
    count = 3,
}
print(mixed[1])
print(mixed.label)

-- Nested tables
local school = {
    name = "CodeLearn Academy",
    students = {
        { name = "Alice", score = 95 },
        { name = "Bob",   score = 82 },
        { name = "Carol", score = 71 },
    },
}

print(school.name)
print(school.students[1].name)
print(school.students[2].score)

-- Loop through nested table
for i, student in ipairs(school.students) do
    print(i .. ". " .. student.name .. ": " .. student.score)
end

print("---")

-- Table as a namespace/module
local MathUtils = {}

MathUtils.PI = 3.14159

function MathUtils.circleArea(r)
    return MathUtils.PI * r * r
end

function MathUtils.factorial(n)
    if n <= 1 then return 1 end
    return n * MathUtils.factorial(n - 1)
end

print(string.format("Area: %.2f", MathUtils.circleArea(5)))
print("5! =", MathUtils.factorial(5))

-- A simple "class" using metatables
local Animal = {}
Animal.__index = Animal   -- look up missing keys in Animal

-- Constructor function
function Animal.new(name, sound)
    local self = setmetatable({}, Animal)  -- create instance
    self.name  = name
    self.sound = sound
    return self
end

-- Methods go on Animal
function Animal:speak()
    -- the colon (:) automatically passes self as first arg
    print(self.name .. " says " .. self.sound .. "!")
end

function Animal:describe()
    print("I am " .. self.name)
end

-- Create instances
local dog = Animal.new("Rex", "Woof")
local cat = Animal.new("Whiskers", "Meow")

dog:speak()
cat:speak()
dog:describe()

-- Access fields
print(dog.name)
print(cat.sound)

-- Base class
local Shape = {}
Shape.__index = Shape

function Shape.new(colour)
    local self = setmetatable({}, Shape)
    self.colour = colour or "white"
    return self
end

function Shape:getColour()
    return self.colour
end

function Shape:describe()
    print("Shape — colour: " .. self:getColour())
end

-- Derived class: Circle extends Shape
local Circle = setmetatable({}, { __index = Shape })
Circle.__index = Circle

function Circle.new(radius, colour)
    -- Call parent constructor, then add own fields
    local self = Shape.new(colour)
    setmetatable(self, Circle)
    self.radius = radius
    return self
end

function Circle:area()
    return math.pi * self.radius ^ 2
end

-- Override parent method
function Circle:describe()
    print(string.format(
        "Circle — r=%.1f, area=%.2f, colour=%s",
        self.radius, self:area(), self:getColour()
    ))
end

local s = Shape.new("blue")
local c = Circle.new(5, "red")

s:describe()
c:describe()
print(c:getColour())    -- inherited from Shape!
print(c:area())

-- Create a coroutine from a function
local function countdown(from)
    print("Starting countdown from " .. from)
    for i = from, 1, -1 do
        coroutine.yield(i)       -- pause and send i back
    end
    return "Blast off! 🚀"      -- final value on completion
end

local co = coroutine.create(countdown)

-- Resume the coroutine step by step
local ok, value = coroutine.resume(co, 5)  -- start with arg 5
print("Status:", ok, "Value:", value)

ok, value = coroutine.resume(co)
print("Status:", ok, "Value:", value)

ok, value = coroutine.resume(co)
print("Status:", ok, "Value:", value)

ok, value = coroutine.resume(co)
print("Status:", ok, "Value:", value)

ok, value = coroutine.resume(co)
print("Status:", ok, "Value:", value)

-- After the function returns:
ok, value = coroutine.resume(co)
print("Final:", ok, "Value:", value)

-- Dead coroutine — cannot resume again
ok, value = coroutine.resume(co)
print("Dead:", ok, "Message:", value)

-- Simulating a module (normally this would be a .lua file)
-- math_utils.lua would contain:
local MathUtils = {}

function MathUtils.clamp(value, min, max)
    if value < min then return min end
    if value > max then return max end
    return value
end

function MathUtils.lerp(a, b, t)
    return a + (b - a) * t
end

function MathUtils.round(n, decimals)
    local factor = 10 ^ (decimals or 0)
    return math.floor(n * factor + 0.5) / factor
end

function MathUtils.average(t)
    local sum = 0
    for _, v in ipairs(t) do sum = sum + v end
    return sum / #t
end

-- Use the module
print(MathUtils.clamp(150, 0, 100))    -- 100 (clamped)
print(MathUtils.clamp(-5,  0, 100))    -- 0   (clamped)
print(MathUtils.clamp(50,  0, 100))    -- 50  (unchanged)

print(MathUtils.lerp(0, 100, 0.25))    -- 25.0 (25% between)
print(MathUtils.lerp(0, 100, 0.75))    -- 75.0

print(MathUtils.round(3.14159, 2))     -- 3.14
print(MathUtils.round(3.14159, 4))     -- 3.1416

local scores = {75, 88, 92, 61, 95}
print("Average:", MathUtils.average(scores))