Module:Sandbox/Grufo

-- Example module to demonstrate how it can detect how it is loaded and why such can be useful
require[[strict]]
local currentFrame = mw.getCurrentFrame()
local parentFrame = currentFrame:getParent()
local pkgTitle = ... or currentFrame:getTitle()
local pkgAPI = {}
function pkgAPI.invoke(emu, modname, fnname, modargs)
	local baseFrame = parentFrame or currentFrame -- No need to pass a frame with no parent
	if not emu then
		-- Copy "modargs" so we don't suddenly change them for the caller
		local parserfnargs = {}
		for k, v in pairs(modargs) do
			parserfnargs[k] = v
		end
		table.insert(parserfnargs, 1, fnname)
		table.insert(parserfnargs, 1, modname)
		return baseFrame:callParserFunction('#invoke', parserfnargs)
	end
	--[=[
	Emulate a "#invoke" call with "require", a frameSpoof and a monkey patched "getCurrentFrame"
	providing a spoofed "args", "getParent" and "getTitle"
	falling back to creating an on demand "newChild" frame for other fields
	]=]
	--[=[ TODO: Input validation:
	Scribunto does a good job of its own input validation and throws errors when we pass these on
	but we spoof "modargs" to the target *raw*, so do some validation so the target gets as few
	surprises as possible.
	]=]
	--XXX: mw.title.new(828, modname).prefixedText
	--XXX: mw.site.namespaces.Module.canonicalName .. ':' .. modname
	local modtitle = 'Module:' .. modname

	--[=[ Spoof a "#invoke" frame for the target:
	Scribunto frame objects are just regular Lua tables with method functions, however, those
	functions are also closures that depends on their upvalues and require one to pass in the
	correct frame reference, so we cannot copy those function references into our "spoofFrame"
 	but we can build redirector stub functions that punt calls to those, so long as we ensure
 	we always call them with the right frame reference. We want the target module to never use
 	these stubs as creating a frame via "newFrame" is expensive, so we go one further and
 	instead create delay stub functions that only do that on demand when the target module
 	tries to access any fields we do not end up directly spoofing. The delay stubs also have to
 	punt to newly created frame but only after it has created it. Creating the new frame should
 	only happen once so even though we create many delay stubs, only one will actually create
 	it. To ensure that only one winning delay stub is ever called, each delay stub updates all
 	fields of the "spoofFrame" to always punting stubs instead, thereby effectively caching
 	the frame creation. So we start by filling all frame fields of "spoofFrame" with delay stubs
 	that: first create a new frame, then cache it by update all frame fields with always punting
 	stubs, and finally punt themselves. Of course the "args" fields is not a function so it we
 	must handle it different but we at first ignore that and later ensure to overwrite it in
 	both cases: when writing always punting stubs we just write the actual frame "args" value and
 	when writing delay stubs we just write in our local "args" spoofer. Of course, we overwrite
 	the delay stubs with a few more local spoofs that are easy to create and commonly accessed
 	by the target: "getParent" and "getTitle". We might be able to improve performance by
 	spoofing more fields but many call back into the PHP parser so they would be hard to emulate
 	adequately without creating an actual parser frame and the ones we do spoof cover those
 	most frequently accessed by any target module: the "args" and the parent "args".
	]=]
	local frameSpoof = {}
	-- Punt to "newChild" frame on demand for all function fields; Spoofed fields are overwritten later
	for name in pairs(baseFrame) do
		frameSpoof[name] = function(self, ...)
			local frameDelayed = baseFrame:newChild{title = modtitle, args = modargs}
			-- Overwrite all fields on demand effectively caching this so it will only happen once
			for name in pairs(frameDelayed) do
				frameSpoof[name] = function(self, ...)
					if self == frameSpoof then
						self = frameDelayed -- Only redirect correct value and let error propagate
					end
					-- All future accesses will punt since we made an actual frame we lose nothing
					return frameDelayed[name](self, ...)
				end
			end
			-- Overwrite "args" again because it is not a function
			frameSpoof.args = frameDelayed.args
			if self == frameSpoof then
				self = frameDelayed -- Only redirect correct value and let error propagate
			end
			-- First punt after updating all fields to punt in the future
			return frameDelayed[name](self, ...)
		end
	end
	-- Spoof "getParent"
	function frameSpoof:getParent(...)
		if self ~= frameSpoof then
			return baseFrame.getParent(self, ...) -- Let a real frame throw the error
		end
		return baseFrame
	end
	-- Spoof "getTitle"
	function frameSpoof:getTitle(...)
		if self ~= frameSpoof then
			return baseFrame.getTitle(self, ...) -- Let a real frame throw the error
		end
		return modtitle
	end
	-- Spoof "args" including recreating a metatable
	local args_mt = {}
	args_mt.__index = modargs
	function args_mt:__pairs()
		return pairs(modargs)
	end
	function args_mt:__ipairs()
		return ipairs(modargs)
	end
	frameSpoof.args = setmetatable({}, args_mt)

	-- Emulate the "#invoke" call with "require" and our "frameSpoof"
	local mpkey = 'getCurrentFrame'
	local getCurrentFrame = rawget(mw, mpkey)
	-- Monkey patch "getCurrentFrame" to return our "frameSpoof"
	rawset(mw, mpkey, function() return frameSpoof end)
	local oldmod = rawget(package.loaded, modtitle)
	-- "require" here so the target initialization block sees our monkey patched "getCurrentFrame"
	local fn = require(modtitle)[fnname]
	rawset(package.loaded, modtitle, oldmod) -- Pretend "require" was never called here
	local ret
	if type(fn) == 'function' then --XXX: We don't support callable tables; neither does "#invoke"?
		ret = {fn(frameSpoof)}
	end
	rawset(mw, mpkey, getCurrentFrame) -- Revert earlier monkey patch
	--TODO: if "ret" is "nil", some nice error about "'fnname' is not a function in 'modname'"
	return table.concat(ret)
end
function pkgAPI.main(args, key)
	local numparamsn, numparams = 0, {}
	local strparamsn, strparams = 0, {}
	for param in pairs(args) do
		local paramtype = type(param)
		if 'number' == paramtype then
			numparamsn = 1 + numparamsn
			numparams[numparamsn] = param
		elseif 'string' == paramtype then
			strparamsn = 1 + strparamsn
			strparams[strparamsn] = param
		end
	end
	table.sort(numparams)
	table.sort(strparams)
	local ret = pkgTitle .. ' {{key|' .. key .. '}} {{nums'
	for i, numparam in ipairs(numparams) do
		ret = ret .. '|' .. numparam .. '=' .. args[numparam]
	end
	ret = ret .. '}} {{strs'
	for i, strparam in ipairs(strparams) do
		ret = ret .. '|' .. strparam .. '=' .. args[strparam]
	end
	ret = ret .. '}}'
	return ret
end

if ... then
	-- 'require()' and 'mw.loadData()'
	if not parentFrame then
		--[=[ 'mw.loadData()'
		This is where data that is static during a page rendering should be made available to modules
		]=]
		return {pkgTitle, 'loadData'}
	end
	--[=[ 'require()'
	This is where "main" functionality should be made available to modules
	]=]
	return pkgAPI
else
	-- '#invoke' and console
	if not parentFrame then
		--[=[ console
		This is where debug functionality should be made available to the console as 'p'
		]=]
		return pkgAPI
	end
	--[=[ '#invoke'
	This is where "wrapper" functionality should be made available to wikitext templates, etc.
	]=]
	local mt = {}
	function mt:__index(key)
		return function(frame) --[=[
			This is the function from '{{#invoke:key|...}}', where 'key' is any valid string argument
			'#invoke' parses this first "function" argument differently (e.g., "=" is valid, etc.)
			and sending the rest to the frame parser
			Notice: '{{#invoke:main|...}}' is valid despite
			"main" being an API function accessible from require()
			]=]
			assert(frame == currentFrame)
			return pkgAPI.main(currentFrame.args, key)
		end
	end
	return setmetatable({}, mt)
end