Module:Protect/doc

This is a documentation subpage for Module:Protect.
It may contain usage information, categories and other content that is not part of the original module page.

This Lua module is used in system messages, and on approximately 116,000 pages.
Changes to it can cause immediate changes to the Wikipedia user interface.
To avoid major disruption and server load, any changes should be tested in the module's /sandbox or /testcases subpages, or in your own module sandbox. The tested changes can be added to this page in a single edit. Please discuss changes on the talk page before implementing them.

This metamodule simplifies error handling in other modules. It transforms a function, which may throw an error, into a function, which returns a specified error message in that case.

Usage

local protect = require('Module:Protect')
local protectedFunc = protect(func, errFormat, options)

</syntaxhighlight>

Arguments

<syntaxhighlight lang="text" class="" style="" inline="1">func</syntaxhighlight>
Function to be transformed.
<syntaxhighlight lang="text" class="" style="" inline="1">errFormat</syntaxhighlight> (default: <syntaxhighlight lang="text" class="" style="" inline="1">'Error: %s'</syntaxhighlight>)
Custom error message.

Use <syntaxhighlight lang="text" class="" style="" inline="1">'%s'</syntaxhighlight> to include the message from a caught error.
<syntaxhighlight lang="text" class="" style="" inline="1">options</syntaxhighlight> – optional table with the following fields:
- <syntaxhighlight lang="text" class="" style="" inline="1">raw</syntaxhighlight> (default: false)
  If true, then <syntaxhighlight lang="text" class="" style="" inline="1">errFormat</syntaxhighlight> will be used as is, otherwise it will be wrapped inside a tag <strong class="error">.
- <syntaxhighlight lang="text" class="" style="" inline="1">removeLocation</syntaxhighlight> (default: true)
  If true, removes location information from caught error messages.

Return value

The resulting <syntaxhighlight lang="text" class="" style="" inline="1">protectedFunc</syntaxhighlight> is a function, which calls the original function <syntaxhighlight lang="text" class="" style="" inline="1">func</syntaxhighlight>, passing all arguments to it, and returns all its return values. If <syntaxhighlight lang="text" class="" style="" inline="1">func</syntaxhighlight> throws an error, the specified error message is returned instead.

Example

<syntaxhighlight lang="lua"> local protect = require('Module:Protect')

local p = {}

function p.main(frame)

   if not frame.args[1] then
       error('missing argument')
   end
   return frame.args[1]

end

p.main = protect(p.main)

return p </syntaxhighlight> Invoking the main function without arguments will output: Error: missing argument