Editing Module:Escape/doc (section)

== 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:
 {{codett|2=lua|1=local esc = require('Module:Escape')}}
 esc:char({{green|''escape char (or sequence)''}})
 {{codett|2=lua|1=local to_escape = esc:text}}({{green|''string''}})
 {{green|''code that replaces or removes unescaped chars''}}
 {{codett|2=lua|1=local result = esc:undo(to_escape)}}

From a template:
 {{mlx|Escape|main|mode{{=}}{{green|''function''}}|char{{=}}{{green|''escape char (or sequence)''}}|{{green|''text''}}}}

In a template, the most useful function is {{code|kill}}. 

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

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

{|class="wikitable" style="background:#fff"
|-
!style="vertical-align:top;width:7em;font-family:monospace;"|{{TOC tab|escape:text()}}
|This function takes only one argument: A string. All characters in this string which are preceded by the sequence set by {{code|escape:char()}} will be replaced with placeholders that can be converted back into that char by escape:undo()
|-
!style="vertical-align:top;width:5em;font-family:monospace;"|{{TOC tab|escape:undo()}}
|Takes two arguments:
# The string that may contain placeholders set by {{code|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)
|-
!style="vertical-align:top;width:5em;font-family:monospace;"|{{TOC tab|escape:kill()}}
|This is basically equivalent to calling {{code|string.gsub()}} on the string returned by {{code|escape:text()}} and feeding that result into {{code|escape:undo()}} in a single step. Takes three arguments:
# A string
# A sequence of characters to be removed from that string. (May use a {{code|string.gsub()}} pattern)
# Optional, a char to be placed in front of any characters that have been de-escaped.
|- 
!style="vertical-align:top;font-family:monospace;"|{{TOC tab|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 {{code|\}} char. To escape the {{code|{}} char instead, you can do {{code|require('Module:Escape'):char('{')|lua}} (or {{code|esc:char('{')|lua}} (presuming you stored the table returned by this module in the local variable {{code|esc}}).

When called without the second argument, char() will return a table containing the functions. This allows, for example, {{code|escape:char('*'):kill('1*23', '%d')|lua}} which would return '{{samp|2}}'.

For the most part, there is very little reason to set {{para|mode}} in template space since the patterns it stores are not shared with other invokations of this module. Templates should instead use the {{para|char}} if a new escape sequence is desired.

====Shortcut====
If provided a second argument that is a table containing a <code>{key = value}</code> pair, such that the key is {{code|text}}, {{code|undo}}, or {{code|kill}} and the value is a table containing the arguments that would have been passed to those functions. For example, {{code|escape:char('\\', {text {{=}} 'string'})|lua}} is equivalent to {{code|escape:char('\\'):text('string')|lua}}.

Note that if multiple key-value pairs are provided, only one may execute. {{code|kill}} is ignored if either {{code|text}} or {{code|undo}} are present. {{code|undo}} is ignored if {{code|text}} is present.
|}
<span id='functions doc'></span>

===Caveats===
* When using a multi-character escape sequence, this module only marks it using the byte value of the first character. Thus, {{code|2=lua|escape:undo()}} will unescape, for example, all characters escaped with {{code|'e'}} and {{code|'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 ({{code|'\r'}}) characters--chosen because they are seldom used at all, and virtually never used unpaired with {{code|'\n'}}; moreover, it is distinct from the markers generated by {{tag|nowiki}} or {{code|mw.text.nowiki()}} (which use the delete char). To set a different separator char, include the key-value pair <code>{safeChr = {{green|alternate character}}}</code> in the table that you pass to escape:char().