Module:Escape/doc

Usage

This module is designed as an way to escape strings in a customized and efficient manner. It works by replacing characters that are preceded by your escape char (or phrase) There are two ways to call this module:

From another module:

local esc = require('Module:Escape')
esc:char(escape char (or sequence))
local to_escape = esc:text(string)
code that replaces or removes unescaped chars
local result = esc:undo(to_escape)

From a template:

{{#invoke:Escape|main|mode=function|char=escape char (or sequence)|text}}

In a template, the most useful function is kill.

This module is primarily intended to be used by other modules. However all functions can be called in template space using |mode=the function you want to call followed by arguments.

All module functions (i.e. any func. other than main()) should be called using a colon (:), e.g. esc:char('%') or esc:kill{'{{example|\\}}}', '}'} == '{{example|}'

escape:text() escape:text()	This function takes only one argument: A string. All characters in this string which are preceded by the sequence set by escape:char() will be replaced with placeholders that can be converted back into that char by escape:undo()
escape:undo() escape:undo()	Takes two arguments: The string that may contain placeholders set by escape:text() Optional, a char to be placed in front of any characters that have been de-escaped. (i.e. if you need to re-escape those string with a different char)
escape:kill() escape:kill()	This is basically equivalent to calling string.gsub() on the string returned by escape:text() and feeding that result into escape:undo() in a single step. Takes three arguments: A string A sequence of characters to be removed from that string. (May use a string.gsub() pattern) Optional, a char to be placed in front of any characters that have been de-escaped.
escape:char() escape:char()	This function's primary use is to initialize the patterns to scan a string for an escape/escaped sequence. It takes two arguments, the first being the escape character and the second being a table of arguments (optional). By default, this module will escape the \ char. To escape the { char instead, you can do require('Module:Escape'):char('{') (or esc:char('{') (presuming you stored the table returned by this module in the local variable esc). When called without the second argument, char() will return a table containing the functions. This allows, for example, escape:char('*'):kill('1*23', '%d') which would return '2'. For the most part, there is very little reason to set |mode= in template space since the patterns it stores are not shared with other invokations of this module. Templates should instead use the |char= if a new escape sequence is desired. Shortcut If provided a second argument that is a table containing a {key = value} pair, such that the key is text, undo, or kill and the value is a table containing the arguments that would have been passed to those functions. For example, escape:char('\\', {text = 'string'}) is equivalent to escape:char('\\'):text('string'). Note that if multiple key-value pairs are provided, only one may execute. kill is ignored if either text or undo are present. undo is ignored if text is present.

Caveats

• When using a multi-character escape sequence, this module only marks it using the byte value of the first character. Thus, escape:undo() will unescape, for example, all characters escaped with 'e' and 'esc' if both were used. In practice however this shouldn't be a problem as multiple escape sequences are pretty rare unless you're transitioning between multiple code languages. (Multiple multi-char escape sequences beginning with the same character are simply bad practice anyhow.)
• Since byte values are stored as numbers, it is not recommended for you to use a number as an escape sequence (though it may work just fine).
• Placeholder byte values separated with return ('\r') characters--chosen because they are seldom used at all, and virtually never used unpaired with '\n'; moreover, it is distinct from the markers generated by <nowiki>...</nowiki> or mw.text.nowiki() (which use the delete char). To set a different separator char, include the key-value pair {safeChr = alternate character} in the table that you pass to escape:char().

Examples

Module

Here's some sample output from the debug console below the module editor:

local escape = require('Module:Escape')
test = 'test, \\test, \\{,test\\\\ \\\\ \\\\\\\\'

test2 = escape:char('{'):text(test)
=test2

test, \test, \7b

044
7btest\\ \\ \\\\

test3 = escape:char('\\'):text(test2)
=test3

test, 5c

0116
5cest, 5c

055
5cb

044
7btest5c

092
5c 5c

092
5c 5c

092
5c5c

092
5c

test4 = escape:char('{', {undo = test3})
=test4

test, 5c

0116
5cest, 5c

055
5cb

044
7btest5c

092
5c 5c

092
5c 5c

092
5c5c

092
5c

test4 = escape:char('\\', {undo = test3})
=test4

test, test, 7b

044
7btest\ \ \\

test5 = escape:char('{', {undo = test4})
=test5 == test

true

=escape:undo(test3)--doesn't work because char is still set to '{' in current session

test, 5c

0116
5cest, 5c

055
5cb

044
7btest5c

092
5c 5c

092
5c 5c

092
5c5c

092
5c

=escape:undo(test4)

test, \test, \,test\\ \\ \\\\

=escape:char('\\'):undo(test3)

test, test, 7b

044
7btest\ \ \\

=escape:char('{', {undo = escape:char('\\'):undo(test3)})

test, test, {,test\ \ \\

=test == escape:char('{', {undo = escape:char('\\'):undo(test3)})

false

=test == escape:char('{', {undo = escape:char('\\'):undo(test3, '\\')})

true

local t = 'test { test {\\{ test, \\test, \\{,test\\ \\ \\ {\\'
=t

test { test {\{ test, \test, \{,test\ \ \ {\

local e = require('Module:Escape')
local t2 = escape:text(t)
local t3 = string.gsub(t2, '{', )
local t4 = escape:undo(t3)
=t4

test  test { test, test, {,test   \

local tk0 = escape:kill(t, '{')
=tk0 == t4

true