Module:debug

From Wiktionary, the free dictionary
Jump to navigation Jump to search

This module is used to debug templates and other modules, and to help track down problems or incorrect usage.

dump

dump(value)

Converts any value (except for functions) into a string representation. The string is formatted as Lua syntax, so you should be able to take the output of this function and insert it back into a Lua module. Tables are processed recursively. Tabs are converted into spaces.

highlight_dump

highlight_dump(value)

Does the same as dump, except it adds Lua syntax highlighting, and tabs are preserved.

error

{{#invoke:debug|error|message}}

This function is invoked from templates, and simply triggers a script error with a message. This is useful if you want to trigger a script error but don't have the time or knowledge to convert a template to Lua.

track

track(key)

Convenience function which transcludes a tracking subtemplate. The key is a string or a list of strings: track("key") or track{ "key1", "key2", "key3", ... }.

Usually invocations of this functions should look like this: require('Module:debug/track')(key) or require('Module:debug').track(key). Loading this module on the spot instead of ahead of time may prevent unnecessary transclusion list overload.

highlight

This function creates the equivalent of a <source> or <syntaxhighlight> tag using the frame:extensionTag() function from Scribunto. Depending on the arguments, it behaves in two different ways:

highlight(content, options)
Highlight the given content (which should be a string) using the table of options.
require("Module:debug").highlight('<span class="Latn" lang="en">word</span>', { lang = "html" }) -- generate syntax-highlighted HTML code
highlight(options)
Returns a highlighting function that uses the given table of options. This is useful when a given set of options are used multiple times in a module. The highlighting function receives a string as argument.
local highlight_HTML = require("Module:debug").highlight{ lang = "html" } -- generate syntax-highlighting function for HTML
highlight_HTML('<span class="Latn" lang="en">word</span>') -- generates syntax-highlighted HTML code

The function recognizes two fields in the table of options:

lang
Language or file format. (See the full list.) Defaults to "lua".
inline
Display the code inline, rather than as a block.

local export = {}

local escape
do
	local escapes = {
		["\a"] = "a", ["\b"] = "b", ["\f"] = "f", ["\n"] = "n", ["\r"] = "r",
		["\t"] = "t", ["\v"] = "v", ["\\"] = "\\", ["\""] = '"', ["'"] = "'",
	}
	
	local function helper(char)
		return escapes[char] and "\\" .. escapes[char]
			or ("\\%03d"):format(char:byte())
	end
	
	-- Escape control characters, backslash, double quote, and bytes that aren't
	-- used in UTF-8.
	-- Escape stuff that can't be saved in a MediaWiki page, like invalid UTF-8
	-- and NFD character sequences? Hard.
	-- Similar to string.format("%q", str), which does not use C-like simple
	-- escapes and does not escape bytes that are not used in UTF-8.
	escape = function (str)
		return (str:gsub("[%c\\\"\192\193\245-\255]", helper))
	end
end

export.escape = escape

-- Convert a value to a string
function export.dump(value, prefix, tsort)
	local t = type(value)
	
	prefix = prefix or ""
	
	if t == "string" then
		return '"' .. escape(value) .. '"'
	elseif t == "table" then
		local str_table = {}
		
		table.insert(str_table, " {")
		
		for key, val in require("Module:table").sortedPairs(value, tsort) do
			table.insert(str_table, " " .. prefix .. "\t[" .. export.dump(key, prefix .. "\t") .. "] = " .. export.dump(val, prefix .. "\t"):gsub("^ ", "") .. ",")
		end
		
		table.insert(str_table, " " .. prefix .. "}")
		
		return table.concat(str_table, "\n")
	else
		return tostring(value)
	end
end


function export.highlight_dump(value, prefix, tsort, options)
	options = options or {}
	
	local func = options.modified and "modified_dump" or "dump"
	
	local dump = export[func](value, prefix, tsort)
	
	-- Remove spaces at beginnings of lines (which are simply to force a <pre></pre> tag).
	dump = dump:gsub("%f[^%z\n] ", "")
	
	return export.highlight(dump)
end


-- Returns true if table contains a table as one of its values
local function containsTable(t)
	for key, value in pairs(t) do
		if type(value) == "table" then
			return true
		end
	end
	return false
end


local function containsTablesWithSize(t, size)
	for key, value in pairs(t) do
		if type(value) == "table" and require("Module:table").size(value) ~= size then
			return false
		end
	end
	return true
end	


--[=[
	Convert a value to a string.
	Like dump below, but if a table has consecutive numbered keys and does not
	have a table as one of its values, it will be placed on a single line.
	Used by [[Module:User:Erutuon/script recognition]].
]=]
function export.modified_dump(value, prefix, tsort)
	local t = type(value)
	
	prefix = prefix or ""
	
	if t == "string" then
		return '"' .. value .. '"'
	elseif t == "table" then
		local str_table = {}
		
		local containsTable = containsTable(value)
		local consecutive = require("Module:table").isArray(value)
		if consecutive and not containsTable or containsTable and containsTablesWithSize(value, 3) then
			table.insert(str_table, "{")
			
			for key, val in require("Module:table").sortedPairs(value, tsort) do
				if containsTable then
					table.insert(str_table, "\n\t" .. prefix)
				else
					table.insert(str_table, " ")
				end
				
				if type(key) == "string" then
					table.insert(str_table, "[" .. export.modified_dump(key) .. "] = ")
				end
				
				table.insert(str_table, type(key) == "number" and type(val) == "number" and string.format("0x%05X", val) or export.modified_dump(val))
				
				if not (consecutive and #value == 3) or type(key) == "number" and value[key + 1] then
					table.insert(str_table, ",")
				end
			end
			
			if containsTable then
				table.insert(str_table, "\n" .. prefix)
			else
				table.insert(str_table, " ")
			end
			
			table.insert(str_table, "}")
			return table.concat(str_table)
		end
		
		table.insert(str_table, " {")
		
		for key, val in require("Module:table").sortedPairs(value, tsort) do
			table.insert(str_table, " " .. prefix .. "\t[" .. export.modified_dump(key, prefix .. "\t") .. "] = " .. export.modified_dump(val, prefix .. "\t"):gsub("^ ", "") .. ",")
		end
		
		table.insert(str_table, " " .. prefix .. "}")
		
		return table.concat(str_table, "\n")
	elseif t == "number" and value > 46 then
		return string.format("0x%05X", value)
	else
		return tostring(value)
	end
end
	

export.track = require("Module:debug/track")


-- Trigger a script error from a template
function export.error(frame)
	error(frame.args[1] or "(no message specified)")
end

--[[
	Convenience function for generating syntaxhighlight tags.
	Display defaults to block.
	Options is a table. To display inline text with HTML highlighting:
		{ inline = true, lang = "html" }
]]
function export.highlight(content, options)
	if type(content) == "table" then
		options = content
		options = {
			lang = options.lang or "lua",
			inline = options.inline and true
		}
		return function(content)
			return mw.getCurrentFrame():extensionTag("syntaxhighlight", content, options)
		end
	else
		return mw.getCurrentFrame():extensionTag("syntaxhighlight", content, {
			lang = options and options.lang or "lua",
			inline = options and options.inline and true or nil
		})
	end
end

function export.track_unrecognized_args(args, template_name)
	local function track(code)
		export.track(template_name .. "/" .. code)
	end
	
    track("unrecognized arg")
	
	local arg_list = {}
	for arg, value in pairs(args) do
		track("unrecognized arg/" .. arg)
		table.insert(arg_list, ("|%s=%s"):format(arg, value))
	end
	
	mw.log(
		("Unrecognized parameter%s in {{%s}}: %s."):format(
			arg_list[2] and "s" or "",
			template_name,
			table.concat(arg_list, ", ")))
end

do
	local placeholder = "_message_"
	
	function export._placeholder_error(frame)
		-- A dummy function that throws an error with a placeholder message.
		error(placeholder, (frame.args.level or 1) + 6)
	end
	
	-- Throw an error via callParserFunction, which generates a real error with traceback, automatic categorization in [[CAT:E]] etc., but the error message is returned as a string. Then, replace the placeholder error message with `message`, which is preprocessed. This is necessary when preprocessing needs to be applied (e.g. when using <pre> tags), since otherwise strip markers and other half-processed text gets displayed instead.
	function export.formatted_error(message, level)
		local frame = mw.getCurrentFrame()
		return (frame:callParserFunction("#invoke", {"debug", "_placeholder_error", level = level})
			:gsub(placeholder, frame:preprocess(message)))
	end
end

return export