Mòideal:Escape/doc
This is the documentation page for Mòideal:Escape
(deasbaireachd⧼tpt-languages-separator⧽ ⧼tpt-languages-separator⧽eachdraidh⧼tpt-languages-separator⧽ceanglaichean⧼tpt-languages-separator⧽doc⧼tpt-languages-separator⧽bogsa-gainmhich⧼tpt-languages-separator⧽cùisean deuchainn)
This module is currently protected from editing. See the protection policy and protection log for more details. Please discuss any changes on the talk page; you may submit an edit request to ask an administrator to make an edit if it is uncontroversial or supported by consensus. You may also request that this page be unprotected. |
This module is subject to page protection. It is a highly visible module in use by a very large number of pages, or is substituted very frequently. Because vandalism or mistakes would affect many pages, and even trivial editing might cause substantial load on the servers, it is protected from editing. |
This module is rated as ready for general use. It has reached a mature form and is thought to be bug-free and ready for use wherever appropriate. It is ready to mention on help pages and other Wikipedia resources as an option for new users to learn. To reduce server load and bad output, it should be improved by sandbox testing rather than repeated trial-and-error editing. |
Ùsaid - 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.
or esc:char('%')
esc:kill{'{{example|\\}}}', '}'} == '{{example|}'
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() | Takes two arguments:
|
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:
|
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 (or (presuming you stored the table returned by this module in the local variable ).
When called without the second argument, char() will return a table containing the functions. This allows, for example, For the most part, there is very little reason to set Ath-ghoirid - ShortcutIf provided a second argument that is a table containing a {key = value} pair, such that the key is
|
Sanasan - 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
(which use the delete char). To set a different separator char, include the key-value pairmw.text.nowiki()
{safeChr = alternate character}
in the table that you pass to escape:char().
Luaths - Speed
The following are benchmarks...
when executing the following module function:
function p.test_kill500(frame)
local esc = require('Module:Escape')
for k = 1, 500 do
local v = esc:kill(p.test_string2(), 'test')
end
return os.clock(esc)
end
0.14814
when repeating the following line 500 times in a template:
{{#invoke:Escape|main|mode=kill|{{#invoke:Escape/testcases|test_string2}}|test}}
0.767
All times in seconds. The module time x500 was calculated when you loaded this doc page (normally between 0.02 and 0.07). The template time x500 was recorded on Jan 15, 2015.
Eisimpleirean - Examples
Teamplaid - Template
Mòideal - Module
Here's some sample output from the debug consol below the module editor:
local escape = require('Module:Escape') test3 = escape:char('\\'):text(test2) test4 = escape:char('{', {undo = test3}) test4 = escape:char('\\', {undo = test3}) test5 = escape:char('{', {undo = test4}) =escape:undo(test3)--doesn't work because char is still set to '{' in current session =escape:undo(test4) =escape:char('\\'):undo(test3) =escape:char('{', {undo = escape:char('\\'):undo(test3)}) =test == escape:char('{', {undo = escape:char('\\'):undo(test3)}) =test == escape:char('{', {undo = escape:char('\\'):undo(test3, '\\')}) local t = 'test { test {\\{ test, \\test, \\{,test\\ \\ \\ {\\' local e = require('Module:Escape') local tk0 = escape:kill(t, '{') |