Module:UtilsError

A utility module for error-handling, mainly with respect to argument validation.

This module should be lazy-loaded using Module:UtilsPackage so that pages which do not have errors (most pages) do not get added to Special:WhatLinksHere/Module:UtilsError. (This does mean that UtilsPackage gets linked everywhere but it is already anyway.)

local utilsPackage = require("Module:UtilsPackage")

local _utilsError = utilsPackage.lazyLoad("Module:UtilsError")

...

_utilsError().warn("...")

This module exports the following functions.

warn

warn(msg, [options])

Parameters

• msg

  Warning message to log above the edit preview area

• [options]

  [traceBack=true]

  If true, prints a stack trace of all module frames. If the invoking frame is a template, the name of the template is appended to the stack trace.

  [omitFrames=0]

  Number of additional frames to omit from the top of the stack trace.

Returns

• Returns nil, but logs the above message, possibly with a stack trace. Preview this page for an example of output.

Examples

#	Input	Output	Result	Status
1	warn("I AM ERROR")	nil
2	warn("I AM ERROR", { omitFrames = 2 })	nil
3	warn("I AM ERROR", { traceBack = false })	nil

---

local p = {}

function p.warn(msg, options)
	local options = options or {}
	local omitFrames = options.omitFrames or 0
	local traceBack = options.traceBack
	
	omitFrames = omitFrames or 0
	local errorSource
	local invokeFrame = mw.getCurrentFrame():getParent():getTitle()
	if mw.title.new(invokeFrame).nsText == "Template" then
		local template ="[[" .. mw.getCurrentFrame():getParent():getTitle() .. "]]"
		msg = "Misuse of " .. template .. ": " .. msg
		traceBack = false
	end
	if traceBack ~= false then
		msg = msg .. "\n"
		local callStack = debug.traceback("", 2)
		msg = msg .. "\n"
		for line in string.gmatch(callStack, "\tModule:[^:]*:[^\n]*\n") do
			if omitFrames ~= 0 then
				omitFrames = omitFrames - 1
			else
				line = string.gsub(line, "\tModule:([^:]*):(.*)", '::<span class="hidden-link">[[Module:%1]]:%2</span>') 
				msg = msg .. line .. "\n"
			end
		end
	end
	mw.addWarning(msg)
end

p.Schemas = {
	warn = {
		msg = {
			type  = "string",
			required = true,
			desc = "Warning message to log above the edit preview area",
		},
		options = {
			type = "record",
			properties = {
				{
					name = "traceBack",
					type = "boolean",
					default = true,
					desc = "If true, prints a stack trace of all module frames. If the invoking frame is a template, the name of the template is appended to the stack trace.",
				},
				{
					name = "omitFrames",
					type = "number",
					default = 0,
					desc = "Number of additional frames to omit from the top of the stack trace."
				},
			}
		}
	}
}

p.Documentation = {
	warn = {
		params = {"msg", "options"},
		returns = "Returns nil, but logs the above message, possibly with a stack trace. Preview this page for an example of output.",
		cases = {
			{
				args = {"I AM ERROR"},
			},
			{
				args = {"I AM ERROR", { omitFrames = 2 }},
			},
			{
				args = {"I AM ERROR", { traceBack = false }},
			}
		},
	},
}

return p