minetest-menu/templates.lua

--[[ MARK: - Template Engine
    
Builds a formspec from the contents of a game-provided main menu file.

=================================================================================
                            Menu File Documentation
=================================================================================

Menu files are essentially just formspecs, but with special semantics and extended syntax.

First, menu files are made up of a number of dialog definitions. A dialog definition is
basically an HTML tag, where the tag name is the name of the dialog. For example this:
```
<main>
  label[2,2;A label]
</main>
<other>
  button[1,1;4,1;button;This is a button]
</other>
```
will define a dialog named 'main', with a label in it, and a dialog named 'other',
with a button in it. Every menu file must have a dialog named 'main', which serves
as the entry point of the game's menu.

Note that to prevent dialog definitions from conflicting with the contents of
hypertext[] elements, they must not have leading whitespace before the opening
delimiter.

Being able to define these other dialogs would be pretty pointless if they couldn't
be used for anything. Accordingly, you can use standard formspec actions, e.g. buttons,
to segue to a different dialog. To do this, set the action name to
'.show_dialog_<name>', where <name> is the name of the dialog you want to open.
You can also use '.overlay_dialog_<name>' to draw the target dialog on top of the
current dialog, and '.unoverlay_dialog' to hide it again.

There are several other action patterns that invoke special behavior:
  - 
  - '.play': Start the game.
  - '.play_with_world_named_<name>': Start the game on the specified world. If the
    world in question does not exist, it will be created.

It is also possible to define metadata for the main menu. To do this, create a dialog
section named 'meta'. The contents of this section will then be parsed in the same way
as minetest.conf instead of being treated as a dialog.

Available metadata options are:
  - 'enable_clouds': true/false (defaults to false)


Now, all this is good when we know exactly what content we want on the main menu.
But what if we want to render e.g. a list of worlds, or even a list of game modes?
This can be done using the @foreach construct. @foreach takes in a list of values,
the name of a JSON file, or a reference to a menu-exposed list.

The major advantage of a foreach loop, however, is interpolation. Inside a foreach
loop, the pattern '${<expression>}' will be replaces with the result of <expression>.

Inside an expression, you can reference variables as '@<name>'. Which variables are
available depends on the iterated list. In the case of a list literal, the current
item is exposed as a variable named @item, while for a JSON file, each key in the
file's top-level object will correspond to a variable. (Note that variable names may
only contain letters or numbers, even if mapped from a JSON file.)

The menu-provided lists are:
  - @WORLDS: The list of worlds for this game. Exposes @name (the world name),
    @path (the world's full absolute path), @gameid (the ID of the current game),
    and @selected (whether the world is currently selected).
  - @MODS: The list of installed mods that are not incompatible with this game.
    Exposes @name, @title, @description, @author, @path, @depends, and @optional_depends.
  - @WORLDMODS: The list of mods installed on the current world. No-op if no world
    is selected.

Expressions also support rudimentary mathematical operations, namely addition (+),
'subtraction' (+-), multiplication (*), division (/), and exponentiation (^). Trying
to perform math on a non-tonumber()-able variable will treat the variable as 0.

As an example, this:
```
label[1,1;Worlds:]
@foreach:$WORLDS:name
  label[1,${@i + 1};World named ${@name}]
@endforeach:name

@foreach:[one,two,three]:name2
  label[4,${@i + 1};Item ${@i} is named: ${@item}]
@endforeach:name2
```
will:
  - Create a "Worlds" label at 1,1;
  - Create a label for every world with that world's name and a Y coordinate that
    corresponds to the world's position in the list, plus 1 so these labels start
    below the existing label.
  - Create labels for "one", "two", and "three" that display the item's value and
    its position in the list, with similarly increasing Y-coordinates.

Besides foreach loops, menu files also support conditionals. Conditionals are
written as '@if:<condition>:<name> ... @else:<name> ... @endif:<name>', where
<condition> is any expression. The conditional will be replaced with the contents
of its first block if the condition evaluates to non-zero, and the contents of
its second block otherwise. Note that the second block may not be omitted due to
how the parser works.

Example:
```
@if: @name = test :<name>
  <formspec 1>
@else:<name>
  <formspec 2>
@endif:<name>
```
    
Notes:
  - The only uniqueness requirements for the name of a block is that it not be
  the name of a statment of the same type contained in the body of that block.
  This is so that the parser knows which `end` belongs to which block without
  having to manage state.

Note: Because of the way the main menu works, image paths must be specified in full.
To make this non-painful, when referencing images use '$ASSET_PATH/<image name>'
instead of just the image name. $ASSET_PATH will be replaced with the actual path
to the game's menu/ directory, so images used by the main menu should be stored
there. You can use $ASSET_PATH in any context. Additionally, $DEFAULT_ASSET_PATH is
the path to the builtin assets folder, and $NO_IMAGE is the path to blank.png, in
case you need to stylistically unset a background image defined by a global style.
--]]

local fe = minetest.formspec_escape
local hte = minetest.hypertext_escape

local function build_template_dialog(fs, depth)
    if fs:trim() == "" then return end
    local dialog = {}
    local i = 0
    -- "(.-\n?)%s-@foreach:([^:]+):(%l*)\n(.-)\n%s-@endforeach:%3(\n?.*)"
    -- Extract foreach loops
    local prev = 0
    while i < 1000 do
        local fe_start, fe_end, fe_pattern, fe_name, fe_content = fs:find("@foreach:([^:]+):(%w-)\n(.-)\n%s-@endforeach:%2", prev)
        local if_start, if_end, if_expr, if_name, if_content, else_content = fs:find("@if:([^:]+):(%w-)\n(.-)\n%s-@else:%2\n(.-)\n%s-@endif:%2", prev)
--        print(string.rep("-", 20)..(depth or 0))
        if not fe_start and not if_start then break end
        if fe_start and fe_start < (if_start or math.huge) then
--            print("for each "..pattern.." ("..name..")\n"..content.."\nend for each ("..name..")")
            dialog[#dialog +1] = build_template_dialog(fs:sub(prev +1, fe_start -1), (depth or 0) +1)
            dialog[#dialog +1] = {
                foreach = fe_pattern:trim(),
                name = fe_name,
                content = build_template_dialog(fe_content:trim(), (depth or 0) +1)
            }
            prev = fe_end
            i = i +1
        end
        
        if if_start and if_start < (fe_start or math.huge) then
--            print("if "..expr.." ("..name..")\n"..content.."\nend if ("..name..")")
            dialog[#dialog +1] = build_template_dialog(fs:sub(prev +1, if_start -1), (depth or 0) +1)
            dialog[#dialog +1] = {
                condition = if_expr:trim(),
                name = if_name,
                content = build_template_dialog(if_content:trim(), (depth or 0) +1),
                else_content = build_template_dialog(else_content:trim(), (depth or 0) +1)
            }
            prev = if_end
            i = i +1
        end
    end

    if prev > 1 then
        dialog[#dialog +1] = build_template_dialog(fs:sub(prev +1))
    end
    
    if #dialog == 1 then dialog = dialog[1] end
    if i == 0 then dialog = fs end
--    minetest.log(dump(dialog, "  "))
    return dialog
end

function build_game_menu(input)
    -- MARK: Environment variables
    input = "\n"..input
        :gsub("%$ASSET_PATH", fe(state.current_game.path.."/menu"))
        :gsub("%$DEFAULT_ASSET_PATH", fe(assets:sub(1, #assets -1)))
        :gsub("%$NO_IMAGE", fe(default_textures.."blank.png"))
        :gsub("/%*.-%*/", "")
    local menu = {}
    for name, fs in input:gmatch("%f[^\n]<(%l+)>(.-)%f[^\n]</%1>") do
        if name == "meta" then
            menu[name] = parse_conf_text(fs)
        else
            menu[name] = build_template_dialog(fs)
        end
    end
--    print(dump(menu, "  "))
    return menu
end


-- Split a template expression into a binary-tree node.
local function split_template_expression(expr)
    
    -- These are basically the operator definitions, listed from lowest
    -- (evaluated last) to highest (evaluated first) precedence.
    
    local a, b, op
    -- Or
    if not a then
        a, b, op = expr:find("(|)")
    end
    -- And
    if not a then
        a, b, op = expr:find("(&)")
    end
    -- Greater than
    if not a then
        a, b, op = expr:find("(>)")
    end
    -- Greater than or equal to
    if not a then
        a, b, op = expr:find("(>=)")
    end
    -- Less than
    if not a then
        a, b, op = expr:find("(<)")
    end
    -- Less than or equal to
    if not a then
        a, b, op = expr:find("(<=)")
    end
    -- Equal to
    if not a then
        a, b, op = expr:find("(==)")
    end
    if not a then
        a, b, op = expr:find("(=)")
    end
    
    -- Addition
    if not a then
        a, b, op = expr:find("(+)")
    end
    -- Multiplication
    if not a then
        a, b, op = expr:find("(*)")
    end
    -- Division
    if not a then
        a, b, op = expr:find("(/)")
    end
    -- Modulo
    if not a then
        a, b, op = expr:find("(%%)")
    end
    -- Exponent
    if not a then
        a, b, op = expr:find("(%^)")
    end
    
    if not a then
        return {value = expr}
    end
    
    return {
        op = op,
        lhs = split_template_expression(expr:sub(1, a -1)),
        rhs = split_template_expression(expr:sub(b +1))
    }
end

-- Reduce a template expression from a binary-tree node into a single value.
local function reduce_template_expression(tree)
    if tree.op == "|" then
        return (reduce_template_expression(tree.lhs) ~= "0" or reduce_template_expression(tree.rhs) ~= "0") and "1" or "0"
    elseif tree.op == "&" then
        return (reduce_template_expression(tree.lhs) ~= "0" and reduce_template_expression(tree.rhs) ~= "0") and "1" or "0"
    elseif tree.op == ">" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) > (tonumber(reduce_template_expression(tree.rhs)) or 0) and "1" or "0"
    elseif tree.op == ">=" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) >= (tonumber(reduce_template_expression(tree.rhs)) or 0) and "1" or "0"
    elseif tree.op == "<" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) < (tonumber(reduce_template_expression(tree.rhs)) or 0) and "1" or "0"
    elseif tree.op == "<=" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) <= (tonumber(reduce_template_expression(tree.rhs)) or 0) and "1" or "0"
    elseif tree.op == "=" or tree.op == "==" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) == (tonumber(reduce_template_expression(tree.rhs)) or 0) and "1" or "0"
    elseif tree.op == "+" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) + (tonumber(reduce_template_expression(tree.rhs)) or 0)
    elseif tree.op == "*" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) * (tonumber(reduce_template_expression(tree.rhs)) or 0)
    elseif tree.op == "/" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) / (tonumber(reduce_template_expression(tree.rhs)) or 0)
    elseif tree.op == "%" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) % (tonumber(reduce_template_expression(tree.rhs)) or 0)
    elseif tree.op == "^" then
        return (tonumber(reduce_template_expression(tree.lhs)) or 0) ^ (tonumber(reduce_template_expression(tree.rhs)) or 0)
    else
        return tree.value
    end
end

-- Evaluate an interpolation expression, with an optional table of variables.
local function evaluate_template_expression(expr, vars, depth)
    if expr == "" then return "0" end
    if not depth then depth = 0 end
    -- This handles the case where vars is omitted, because then it ends up
    -- just setting vars to an empty table.
    if type(vars) ~= "table" then
        vars = {item = vars}
    end
    
    -- Check for operators early, because variables may contain punctuation when expanded.
    -- A class is used instead of %p because %p matches @, which is used for variables.
    local has_operators = expr:find("[|&><=+*/%%^]")
    
    -- Expand all variables so we can deal with a constexpr.
    local offset = 1
    while offset < 100000 do
        local a, b, name = expr:find("@([%a_]+)", offset)
        if not a then break end
        -- If referencing an undefined variable, default to 0 because it's safest that way.
        local result = minetest.formspec_escape(tostring(vars[name] or "0"))
        expr = expr:sub(1, a -1)..result..expr:sub(b +1)
        offset = a +#result
    end

    -- If there are no operators, this is a constant expression and we can just return.
    if not has_operators then return expr end
    
    -- Condense sub-expressions.
    local offset = 1
    while offset < 100000 do
        local a, b, se = expr:find("(%b())", offset)
        if not a then break end
        se = se:gsub("^%((.*)%)$", "%1")
        local result = evaluate_template_expression(se, vars, depth +1)
        expr = expr:sub(1, a -1)..result..expr:sub(b +1)
        offset = a +#result
    end
    
    -- Expression parsing
    local tree = split_template_expression(expr)
    return tostring(reduce_template_expression(tree))
end

-- Do variable interpolation for the given formspec using the provided variable table.
local function evaluate_template_block(fs, vars)
    local offset = 0
    while offset < 100000 do
        local s_start, s_end, s_name, s_expr = fs:find("@set:@?([%w_]+):([^\n]+)", offset)
        local i_start, i_end, i_expr = fs:find("%${([^}]-)}", offset)
        if not s_start and not i_start then break end
        if s_start and s_start < (i_start or math.huge) then
        -- Assignment statements
            vars[s_name] = evaluate_template_expression(s_expr, vars)
            fs = fs:sub(1, s_start -1)..fs:sub(s_end +1)
            offset = s_start
        elseif i_start then
        -- Interpolations
            local result = evaluate_template_expression(i_expr, vars)
            fs = fs:sub(1, i_start -1)..result..fs:sub(i_end +1)
            offset = i_start +#result
        end
    end
    return fs
end

-- Interpret the list expression of a foreach loop, then iterate.
local function evaluate_template_foreach(loop, vars)
    local out = ""
    local list = {}
    if loop.foreach:sub(1,1) == "[" then
        list = loop.foreach:gsub("^%[(.*)%]$", "%1"):split(",")
    elseif loop.foreach:sub(1, 1) == "@" then
        local var = loop.foreach:sub(2)
        -- Builtin variables take precedence.
        if var == "WORLDS" then
            list = get_worlds_for_game(state.current_game.id)
        elseif var == "MODS" then
            list = get_mods_for_game(state.current_game.id)
        elseif var == "WORLDMODS" then
            list = state.menu_vars.selected_world and get_mods_for_world(state.menu_vars.selected_world) or {}
        else
            list = vars[var]
        end
    end
    for i, x in ipairs(list) do
        local vars2 = {}
        if type(x) ~= "table" then
            vars2.item = x
        else
            for k, v in pairs(x) do
                vars2[k] = v
            end
        end
        vars.i = i
        out = out..evaluate_game_dialog(loop.content, setmetatable(vars2, {__index = vars, __newindex = vars})).."\n"
    end
    return out
end

-- Determine which branch of an if statement should be evaluated.
local function evaluate_template_conditional(cond, vars)
    local out = ""
    local list = {}
    local condition = evaluate_template_expression(cond.condition, vars)
    if condition ~= "0" then
        out = out..evaluate_game_dialog(cond.content, vars).."\n"
    else
        out = out..evaluate_game_dialog(cond.else_content, vars).."\n"
    end
--    print("Evaluated condition `"..cond.condition.."` as "..out)
    return out
end

-- Process the syntax tree for a game dialog and output the resulting string.
function evaluate_game_dialog(dialog, vars)
    local out = ""
    if not dialog then return out end
    if type(dialog) == "string" then
        return evaluate_template_block(dialog, vars)
    elseif dialog.condition then
        out = out..evaluate_template_conditional(dialog, vars)
    elseif dialog.foreach then
        out = out..evaluate_template_foreach(dialog, vars)
    else
        for _, c in ipairs(dialog) do
            out = out..evaluate_game_dialog(c, vars)
        end
    end
    return out
end

















template = {}

function template.build_expr(expr)
    return {type = "expr", value = expr}
end

function template.build(menu)
    -- First pass: Collect all tokens into a flat list
    local block = {}
    local item
    local offset = 1
    local pos = 1
    while true do
        local matched = false
        local stmt_start, stmt_end, stmt = menu:find("{%%%s*(.-)%s*%%}", pos)
        local expr_start, expr_end, expr = menu:find("{{(.-)}}", pos)
        local comment_start, comment_end, comment = menu:find("{#(.-)#}", pos)
        
        -- Statements
        if stmt_start and stmt_start < (expr_start or math.huge) and stmt_start < (comment_start or math.huge) then
            block[#block +1] = menu:sub(offset, stmt_start -1)
            
            local verb = stmt:match "^(%a+)"
            if verb == "if" then
                item = {
                    type = "if",
                    parent = block,
                    conditions = {{condition = template.build_expr(stmt:match "if%s*(.*)"), body = {}}}
                }
                block[#block +1] = item
                block = item.conditions[1].body
            elseif verb == "elseif" then
                local x = {
                    condition = template.build_expr(stmt:match "if%s*(.*)"),
                    body = {}
                }
                item.conditions[#item.conditions +1] = x
                block = x.body
            elseif verb == "else" then
                local x = {
                    condition = template.build_expr("true"),
                    body = {}
                }
                item.conditions[#item.conditions +1] = x
                block = x.body
            elseif verb == "endif" then
                block = item.parent
            elseif verb == "for" then
                
            elseif verb == "endfor" then
                
            elseif verb == "macro" then
                
            elseif verb == "endmacro" then
                
            elseif verb == "set" then
                
            elseif verb == "endset" then
                
            elseif verb == "include" then
                
            end
            print(verb)
            
            offset = stmt_end +1
            pos = stmt_end
            matched = true
        end
        
        -- Interpolations
        if expr_start and expr_start < (stmt_start or math.huge) and expr_start < (comment_start or math.huge) then
            block[#block +1] = menu:sub(offset, expr_start -1)
            
            block[#block +1] = template.build_expr(expr)
            
            offset = expr_end +1
            pos = expr_end
            matched = true
        end

        -- Comments
        if comment_start and comment_start < (stmt_start or math.huge) and comment_start < (expr_start or math.huge) then
            offset = expr_end
            pos = expr_end
            matched = true
        end
        
        if not matched then
            break
        end
    end
    
    return block
end

function template.evaluate_expr(expr)
    if expr.type == "" then
        
    else
        return false
    end
end

function template.evaluate(dialog, vars)
    local out = ""
    for _, item in ipairs(dialog) do
        if type(item) == "string" then
            out = out..item
        else
            if item.type == "if" then
                for _, cond in ipairs(item.conditions) do
                    if template.evaluate_expr(cond.condition) then
                        out = out..template.evaluate(cond.body)
                        break
                    end
                end
            elseif item.type == "for" then
                
            end
        end
    end
    return out
end

print(template.evaluate(template.build [[
    This is a {{blah}}.
    
    {% if foo %}
    Foo
    {% elseif bar %}
    Bar
    {% else %}
    Baz
    {% endif %}
    
    {% for x in [a,b,c] %}
        The item is {{ x }}!
        Uppercase: {{ x:upper() }}
    {% endfor %}
]], {
    foo = false
}))