Functions

-- A function packages up some work so you can run it again and again.
-- The shape is:  function name(arguments) ... return value end
-- Put 'local' in front so the function stays scoped (your default!).
local function greet(name)
  return "Hello, " .. name .. "!"   -- '..' joins text together
end

-- Call it by writing its name followed by (arguments):
print(greet("Ada"))     -- prints: Hello, Ada!
print(greet("Lin"))     -- prints: Hello, Lin!

-- Without 'return' a function just DOES something and hands back nil:
local function shout(word)
  print(word .. "!!!")  -- this prints as a side effect
end
shout("go")             -- prints: go!!!
local result = shout("hi")  -- prints: hi!!!
print(result)           -- prints: nil   (shout returned nothing)

-- Leaving off 'local' makes a GLOBAL function — visible everywhere,
-- which is exactly the namespace pollution you want to avoid.

-- Lua functions can return MORE THAN ONE value. Just list them after return.
local function divide(a, b)
  return a // b, a % b      -- // is integer divide, % is remainder
end

-- Catch each returned value in its own variable, left to right:
local q, r = divide(17, 5)
print(q, r)                 -- prints: 3   2

-- A handy real example: split a full name into first and last.
local function splitName(full)
  return full:match("(%w+)%s+(%w+)")   -- pattern returns TWO captures
end
local first, last = splitName("Grace Hopper")
print(first, last)          -- prints: Grace   Hopper

-- ⚠️ A function call is TRUNCATED to one value unless it's LAST in a list.
local function pair() return 1, 2 end
print(pair(), 99)           -- prints: 1   99   (pair() cut to just 1)
print(99, pair())           -- prints: 99   1   2   (pair() is last -> all kept)

-- 🎯 YOUR TURN — replace each ___ then run the code.

-- Write a function that returns BOTH the min and the max of two numbers.
local function minMax(a, b)
  -- 1) If a is smaller, the order is a, b — otherwise b, a
  if a < b then
    return ___, ___      -- 👉 smaller first, then larger: a, b
  else
    return ___, ___      -- 👉 b, a
  end
end

-- 2) Catch BOTH returned values in two variables, left to right
local low, high = ___    -- 👉 minMax(8, 3)

print(low, high)

-- ✅ Expected output:
-- 3   8

-- '...' (three dots) means "any number of extra arguments".
-- It collects everything the caller passed into a vararg list.
local function sum(...)
  local total = 0
  for _, n in ipairs({...}) do   -- {...} packs the args into a table
    total = total + n
  end
  return total
end
print(sum(1, 2, 3))         -- prints: 6
print(sum(10, 20, 30, 40))  -- prints: 100

-- select("#", ...) counts how many varargs arrived.
-- select(i, ...)   returns everything from position i onward.
local function describe(...)
  print("got " .. select("#", ...) .. " arguments")
  print("first one is " .. select(1, ...))
end
describe("a", "b", "c")
-- prints: got 3 arguments
-- prints: first one is a

-- table.pack keeps a correct count even when some args are nil.
local packed = table.pack(1, nil, 3)
print(packed.n, packed[1], packed[3])   -- prints: 3   1   3

-- 🎯 YOUR TURN — build an average() that accepts any number of scores.

-- 1) Use ... so the caller can pass as many numbers as they like
local function average(...)
  local total = 0
  local nums = {___}            -- 👉 pack the varargs into a table: ...

  for _, n in ipairs(nums) do
    total = total + n
  end

  -- 2) How many numbers came in? Use the # length operator on the table
  local count = ___             -- 👉 #nums

  -- 3) Avoid divide-by-zero: if count is 0, the answer is 0
  if count == 0 then return 0 end
  return total / count
end

print(average(10, 20, 30))      -- 👉 call it with three numbers
print(average(4, 8))

-- ✅ Expected output:
-- 20.0
-- 6.0

-- Lua has no built-in default arguments, so use the 'or' idiom:
--   local x = x or fallback
-- 'or' returns its first TRUTHY value, so a missing (nil) arg falls back.
local function greet(name, greeting)
  name = name or "stranger"        -- if name is nil, use "stranger"
  greeting = greeting or "Hello"   -- if greeting is nil, use "Hello"
  return greeting .. ", " .. name .. "!"
end

print(greet())                 -- prints: Hello, stranger!
print(greet("Ada"))            -- prints: Hello, Ada!
print(greet("Ada", "Hi"))      -- prints: Hi, Ada!

-- ⚠️ Watch out: 'or' treats false and nil the same.
-- For boolean flags, compare to nil instead so 'false' survives:
local function setup(verbose)
  if verbose == nil then verbose = true end   -- only default when truly missing
  return verbose
end
print(setup())        -- prints: true    (defaulted)
print(setup(false))   -- prints: false   (kept!)

-- Functions are FIRST-CLASS VALUES: store them, pass them, return them.
local function square(x) return x * x end
local f = square              -- store a function in a variable
print(f(5))                   -- prints: 25

-- Pass a function as an argument (here, apply it to every item):
local function applyAll(fn, list)
  local out = {}
  for i, v in ipairs(list) do out[i] = fn(v) end
  return out
end
local doubled = applyAll(function(n) return n * 2 end, {1, 2, 3})
print(doubled[1], doubled[2], doubled[3])   -- prints: 2   4   6

-- A CLOSURE is a function that remembers variables from where it was made.
-- 'count' lives on between calls because the inner function captured it.
local function makeCounter()
  local count = 0
  return function()
    count = count + 1     -- updates the captured 'count'
    return count
  end
end
local next = makeCounter()
print(next(), next(), next())   -- prints: 1   2   3

-- Each closure gets its OWN private copy — they don't share state:
local a, b = makeCounter(), makeCounter()
print(a(), a(), b())            -- prints: 1   2   1

-- RECURSION: a function that calls itself, shrinking the problem each time.
-- Every recursion needs a BASE CASE so it eventually stops.
local function factorial(n)
  if n <= 1 then return 1 end        -- base case: stop here
  return n * factorial(n - 1)        -- recursive step: gets smaller
end
print(factorial(5))    -- prints: 120   (5*4*3*2*1)

-- Recursion shines on nested data, like counting files in a folder tree.
local function countdown(n)
  if n == 0 then
    print("liftoff!")
    return
  end
  print(n)
  countdown(n - 1)     -- call self with a smaller number
end
countdown(3)
-- prints: 3
-- prints: 2
-- prints: 1
-- prints: liftoff!