Module:FrameTools

See Global Lua Modules/FrameTools

Subpages

{{#dpl: | namespace = Module | titlematch = FrameTools/% | skipthispage = false }}

---

-- <nowiki>
--------------------------------------------------------------------------------
-- This module contains helper functions for dealing with frame objects.
--
-- @script frameTools
-- @alias p
-- @author [[User:DarthKitty]]
-- @author [[User:Dessamator]]
--------------------------------------------------------------------------------
local p = {}
local util = require "libraryUtil"

--------------------------------------------------------------------------------
-- Frame methods are protected by a `checkSelf` function, which makes them more
-- difficult to copy.
--
-- @param {Frame|PseudoFrame} frame
--        The frame of pseudo-frame to copy.
-- @return {PseudoFrame}
--------------------------------------------------------------------------------
function p.copy(frame)
    util.checkType("frameTools.copy", 1, frame, "table")

    local copy = mw.clone(frame)

    -- Point methods on `copy` to their `frame` counterparts
    for methodName, method in pairs(frame) do
        if type(method) == "function" and methodName ~= "getParent" then
            copy[methodName] = function (copy, ...)
                return method(frame, ...)
            end
        end
    end

    -- This method needs special treatment
    function copy:getParent()
        local parent = frame:getParent()

        if parent then
            return p.copy(parent)
        end
    end

    return copy
end

--------------------------------------------------------------------------------
-- Creates a pseudo frame with some useful functions available in
-- [[mw:Extension:Scribunto]], e.g. `newChild`.
--
-- @param[opt] {Frame} frame
--             The frame that provides implementatinos for the `preprocess` method.
-- @param[opt] {table} parentArgs
--             The parameters available on `pseudoFrame:getParent().args`
-- @param[opt] {table} childArgs
--             The parameters available on `pseudoFrame.args`
-- @return {PseudoFrame}
--         The new pseudo-Frame
--------------------------------------------------------------------------------
function p.makePseudoFrame(frame, parentArgs, childArgs)
    util.checkType("frameTools.makePseudoFrame", 1, frame, "table", true)
    util.checkType("frameTools.makePseudoFrame", 2, parentArgs, "table", true)
    util.checkType("frameTools.makePseudoFrame", 3, childArgs, "table", true)

    local pseudoFrame = {parent = {}}
    local checkSelf = util.makeCheckSelfFunction("pseudoFrame", "frame", pseudoFrame, "PseudoFrame object")
    local parentFrame = pseudoFrame.parent
    local checkSelfParent = util.makeCheckSelfFunction("pseudoFrame", "frame", parentFrame, "parent PseudoFrame object")
    local pArgs = {}
    local pTitle
    local args = {}

    if frame then
        args = frame.args

        for name in pairs(frame) do
            pseudoFrame[name] = function (pseudoFrame, ...)
                return frame[name](frame, ...)
            end

            parentFrame[name] = function (parent, ...)
                return pseudoFrame[name](frame, ...)
            end
        end

        if type(frame.getParent) == "function" and frame:getParent() then
            pArgs = frame:getParent().args
            pTitle = frame:getParent():getTitle()
        end
    end

    parentFrame.args = mw.clone(parentArgs or pArgs)
    pseudoFrame.args = mw.clone(childArgs or args)
    pseudoFrame.title = mw.title.getCurrentTitle().text
    parentFrame.title = pTitle or ""

    function pseudoFrame:getTitle()
        checkSelf(self, "getTitle")

        return self.title
    end

    function parentFrame:getTitle()
        checkSelfParent(self, "getTitle")

        return self.title
    end

    function pseudoFrame:getParent()
        checkSelf(self, "getParent")

        return self.parent
    end

    function parentFrame:getParent()
        checkSelfParent(self, "getParent")

        return self.parent
    end

    -- Creates a new Frame object that is a child of the current frame, optional
    -- arguments and title.
    -- Syntax: frame:newChild{title = title, args = table}
    function pseudoFrame:newChild(attributes)
        checkSelf(self, "newChild")

        local tmpTable = p.makePseudoFrame(frame, self.args, attributes.args)

        tmpTable.parent.title = self.title
        tmpTable.title = attributes.title

        return tmpTable
    end

    function pseudoFrame:showargs()
        checkSelf(self, "showargs")

        local childParams = "Child parameters:\nKey \t Value"
        local parentParams = "Parent parameters:\nKey \t Value"

        if self.args then
            for k, v in pairs(self.args) do
                childParams = childParams .. "\n" .. k .. "\t" .. v
            end
        end

        if self.parent.args then
            for k, v in pairs(self.parent.args) do
                parentParams = parentParams .. "\n" .. k .. "\t" .. v
            end
        end

        return childParams .. "\n\n" .. parentParams
    end

    function pseudoFrame:setArgs(childArgs, parentArgs)
        checkSelf(self, "setArgs")

        if childArgs then
            self.args = childArgs or {}
        end

        if parentArgs then
           self.parent.args = parentArgs
        end
    end

    local function preprocessMock(parent) return function(self, opt)
        if parent then
            checkSelfParent(self, "expandTemplate")
        else
            checkSelf(self, "expandTemplate")
        end

        local text
        if type(opt) == "table" then
            text = opt.text
        else
            text = opt
        end
        text = tostring(text)

        return text
    end end
    if not pseudoFrame.preprocess then
        pseudoFrame.preprocess = preprocessMock()
    end
    if not pseudoFrame.parent.preprocess then
        pseudoFrame.parent.preprocess = preprocessMock("parent")
    end

    local function expandTemplateMock(parent) return function(self, opt)
        if parent then
            checkSelfParent(self, "expandTemplate")
        else
            checkSelf(self, "expandTemplate")
        end

        if type(opt) ~= "table" then
            error("frame:expandTemplate: the first parameter must be a table")
        end

        local title
        if opt.title == nil then
            error("frame:expandTemplate: a title is required")
        else
            title = tostring(opt.title)
        end

        local args
        if opt.args == nil then
            args = {}
        elseif type(opt.args) == "table" then
            args = opt.args
        else
            error("frame:expandTitle: args must be a table")
        end

        local keys = {}
        for k in pairs(args) do
            table.insert(keys, k)
        end
        table.sort(keys)

        local text = {}
        table.insert(text, "{{" .. title)
        local anonymous_index = 0
        for _, k in ipairs(keys) do
            table.insert(text, "|" .. (tonumber(k) == (anonymous_index + 1) and "" or (" " .. k .. " = ")) .. args[k])
            if tonumber(k) == (anonymous_index + 1) then anonymous_index = anonymous_index + 1 end
        end
        table.insert(text, "}}")
        text = table.concat(text, '\n')

        return text
    end end

    if not pseudoFrame.expandTemplate then
        pseudoFrame.expandTemplate = expandTemplateMock()
    end
    if not parentFrame.expandTemplate then
        parentFrame.expandTemplate = expandTemplateMock("parent")
    end

    if mw.getCurrentFrame() == nil then
        _G.mw.getCurrentFrame = function() return pseudoFrame end
    end

    return pseudoFrame
end

--------------------------------------------------------------------------------
-- Returns a frame-like object with the given arguments removed.
--
-- @param {Frame|PseudoFrame} frame
--        The Frame to copy
-- @param[opt] ...
--             The arguments to omit from the new `Frame`'s `args` property
-- @return {PseudoFrame}
--------------------------------------------------------------------------------
function p.removeArgs(frame, ...)
    util.checkType("frameTools.removeArgs", 1, frame, "table")

    local pseudoFrame = p.copy(frame)
    local args = pseudoFrame.args
    local metatable = getmetatable(args)

    -- disable arg caching
    metatable.__index = nil
    metatable.__pairs = nil

    -- remove args
    for _, arg in ipairs{...} do
        args[arg] = nil
    end

    return pseudoFrame
end

--------------------------------------------------------------------------------
-- A frame-like object that provides mock implementations for the most common
-- @{Frame|mw.frame} instance methods and properties
--
-- @type {Frame} PseudoFrame
--------------------------------------------------------------------------------

return p

-- </nowiki>
-- (Add categories here.)