Difference between revisions of "Module:Protect/doc"

From blackwiki
Jump to navigation Jump to search
blackwiki>Petr Matas
m (7 revisions imported)
 
(5 intermediate revisions by 2 users not shown)
Line 1: Line 1:
 
{{Module rating|a}}
 
{{Module rating|a}}
 
+
{{used in system}}
 
This [[Help:Lua metamodules|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.
 
This [[Help:Lua metamodules|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.
  
Line 6: Line 6:
  
 
  local protect = require('Module:Protect')
 
  local protect = require('Module:Protect')
  local protectedFunc = '''protect(''func'', ''errFormat'', ''raw'')'''
+
  local protectedFunc = '''protect(''func'', ''errFormat'', ''options'')'''
  
 
=== Arguments ===
 
=== Arguments ===
Line 12: Line 12:
 
* ''{{code|func}}''
 
* ''{{code|func}}''
 
*: Function to be transformed.
 
*: Function to be transformed.
* ''{{code|errFormat}}'' (optional)
+
* ''{{code|errFormat}}'' (default: {{code|'Error: %s'}})
 
*: Custom error message.
 
*: Custom error message.
 
*: Use {{code|'%s'}} to include the message from a caught error.
 
*: Use {{code|'%s'}} to include the message from a caught error.
*: Default: {{code|'Error: %s'}}
+
* ''{{code|options}}'' – optional table with the following fields:
* ''{{code|raw}}'' (optional)
+
** {{code|raw}} (default: false)
*: If true, then ''{{code|errFormat}}'' will be used as is, otherwise it will be wrapped inside a tag <code><nowiki><strong class="error"></nowiki></code>.
+
**: If true, then ''{{code|errFormat}}'' will be used as is, otherwise it will be wrapped inside a tag <code><nowiki><strong class="error"></nowiki></code>.
*: Default: false
+
** {{code|removeLocation}} (default: true)
 +
**: If true, removes location information from caught error messages.
  
 
=== Return value ===
 
=== Return value ===
  
The resulting {{code|protectedFunc}} is a ''function'', which calls the original function ''{{code|func}}'', passing all arguments to it and returning all its return values. If ''{{code|func}}'' throws an error, the specified error message is returned instead.
+
The resulting {{code|protectedFunc}} is a ''function'', which calls the original function ''{{code|func}}'', passing all arguments to it, and returns all its return values. If ''{{code|func}}'' throws an error, the specified error message is returned instead.
  
 
== Example ==
 
== Example ==
Line 32: Line 33:
 
  function p.main(frame)
 
  function p.main(frame)
 
     if not frame.args[1] then
 
     if not frame.args[1] then
         error('missing argument', 0) ''-- The zero prevents including location information''
+
         error('missing argument')
 
     end
 
     end
 
     return frame.args[1]
 
     return frame.args[1]
Line 43: Line 44:
 
Invoking the main function without arguments will output: <strong class="error">Error: missing argument</strong>
 
Invoking the main function without arguments will output: <strong class="error">Error: missing argument</strong>
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
 +
[[Category:Error-handling modules]]
 
[[Category:Lua metamodules]]
 
[[Category:Lua metamodules]]
 
}}</includeonly>
 
}}</includeonly>

Latest revision as of 08:27, 27 September 2020

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)

Arguments

  • func
    Function to be transformed.
  • errFormat (default: 'Error: %s')
    Custom error message.
    Use '%s' to include the message from a caught error.
  • options – optional table with the following fields:
    • raw (default: false)
      If true, then errFormat will be used as is, otherwise it will be wrapped inside a tag <strong class="error">.
    • removeLocation (default: true)
      If true, removes location information from caught error messages.

Return value

The resulting protectedFunc is a function, which calls the original function func, passing all arguments to it, and returns all its return values. If func throws an error, the specified error message is returned instead.

Example

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

Invoking the main function without arguments will output: Error: missing argument