--------------------------------------------------------------------------------
-- Module:Example
-- Demonstration of a Lua Module for Wikipedia
--
-- This module serves as an example and guide for creating Lua modules on
-- Wikipedia. It defines several functions that can be invoked via the
-- {{#invoke:}} mechanism. Note that this module is for demonstration purposes
-- only and is not intended for actual production use.
--------------------------------------------------------------------------------

local p = {}  -- Table to hold the module's externally accessible functions.

--------------------------------------------------------------------------------
-- Function: p.hello
-- Description: Returns a simple, fixed greeting "Hello World!".
-- Usage: {{#invoke:Example|hello}}
--------------------------------------------------------------------------------
p.hello = function(frame)
    local greeting = "Hello World!"  -- Define the greeting message as a local variable.
    return greeting                  -- Return the greeting to Wikipedia.
end

--------------------------------------------------------------------------------
-- Function: p.hello_to
-- Description: Returns a personalized greeting using the first unnamed parameter.
-- Usage: {{#invoke:Example|hello_to|YourName}}
--------------------------------------------------------------------------------
function p.hello_to(frame)
    local name = frame.args[1]       -- Retrieve the first unnamed parameter.
    return "Hello, " .. name .. "!"   -- Concatenate and return the personalized greeting.
end

--------------------------------------------------------------------------------
-- Function: p.count_fruit
-- Description: Constructs and returns a sentence indicating the count of bananas
--              and apples, using proper singular/plural forms.
-- Usage: {{#invoke:Example|count_fruit|bananas=5|apples=6}}
--------------------------------------------------------------------------------
function p.count_fruit(frame)
    -- Convert the named parameters to numbers; default to 0 if conversion fails.
    local num_bananas = tonumber(frame.args.bananas) or 0
    local num_apples  = tonumber(frame.args.apples) or 0

    -- Determine the correct word for singular or plural form.
    local banana_label = (num_bananas == 1) and "banana" or "bananas"
    local apple_label  = (num_apples == 1) and "apple" or "apples"

    -- Construct and return the complete sentence.
    return "I have " .. num_bananas .. " " .. banana_label ..
           " and " .. num_apples .. " " .. apple_label .. "."
end

--------------------------------------------------------------------------------
-- Local Helper Function: lucky
-- Description: Returns a message stating that the given number is "lucky" if the
--              second parameter is the string "yeah"; otherwise, it simply returns
--              the number.
--------------------------------------------------------------------------------
local function lucky(a, b)
    if b == "yeah" then
        return a .. " is my lucky number."
    else
        return a
    end
end

--------------------------------------------------------------------------------
-- Function: p.Name2
-- Description: Demonstrates the use of both unnamed and named parameters from the
--              frame object. It accesses parameters from the current frame as well as
--              from the parent frame, and returns a message based on the provided values.
-- Usage: Can be invoked with parameters directly or via a parent template.
--------------------------------------------------------------------------------
function p.Name2(frame)
    -- Retrieve parameters from both the parent frame and the current frame.
    -- The parent frame allows template parameters to be used in this code easily.
    local parentArgs = frame:getParent().args
    local args = frame.args

    -- Use the first and second unnamed parameters, with a fallback to parent arguments.
    local M = args[1] or parentArgs[1]
    local m = args[2] or parentArgs[2]

    -- Retrieve the named parameter 'lucky' (if provided).
    local luckyParam = args.lucky or parentArgs.lucky

    -- Determine the output based on the provided parameters.
    if m == nil then
        return "Lonely"  -- If the second parameter is missing, return "Lonely".
    elseif M > m then
        -- If M is greater than m, calculate the difference and use the lucky helper.
        return lucky(M - m, luckyParam)
    else
        return "Be positive!"
    end
end

--------------------------------------------------------------------------------
-- Return the module table to make the functions accessible via {{#invoke:}}.
--------------------------------------------------------------------------------
return positive