Difference between revisions of "Module:Escape/doc"

From blackwiki
Jump to navigation Jump to search
blackwiki>Codehydro
m (11 revisions imported)
 
(8 intermediate revisions by 5 users not shown)
Line 2: Line 2:
 
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
 
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
 
== Usage ==
 
== Usage ==
This module is designed as an way to escape strings in a customized manner. There are two ways to call this module:
+
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:
 
From another module:
  local escape = require('Module:Escape')
+
  local esc = require('Module:Escape')
 +
esc:char({{green|''escape char (or sequence)''}})
 +
local to_escape = esc:text({{green|''string''}})
 +
{{green|''code that replaces or removes unescaped chars''}}
 +
local result = esc:undo(to_escape)
  
From a template:<pre>
+
From a template:
{{invoke:Escape|main|mode=|char=}}
+
<nowiki>{{invoke:Escape|main|mode=</nowiki>{{green|''function''}}|char={{green|''escape char (or sequence)''}}|{{green|''text''}}}}
</pre>
 
By default, this module will escape the {{code|\}} char. To escape the {{code|{}} char instead, you can do {{code|require('Module:Escape'):char('{')}} (or {{code|esc:char('{')}} if you've stored table returned by this module in the local variable {{code|esc}}). When used in a template, set {{para|char}} equal to the char code.
 
  
===Template Example===
+
In a template, the most useful function is {{code|kill}}.
While other modes are available, only <code>|mode=kill</code> is probably the one most useful outside of Module space. The first parameter is your text with escaped chars. The second parameter is a char or string or pattern you wish to remove.
+
 
<pre>
+
 
{{#invoke:Escape|main
+
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.
|mode=kill
+
 
|test { test {\{ test, \test, \{,test\ \\ \ {\ ,
+
All module functions (i.e. any func. other than main()) should be called using a colon (:), e.g. {{code|esc:char('%')}} or <code><nowiki>esc:kill{'{{example|\\}}}', '}'} == '{{example|}'</nowiki></code>
|{
+
 
}}
+
 
</pre>
+
{|class='wikitable' style='background:#fff'
{{#invoke:Escape|main
+
|-
|mode=kill
+
!style='vertical-align:top;width:7em'|{{TOC tab|escape:text()}}
|test { test {\{ test, \test, \{,test\ \\ \ {\ ,
+
|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()
|{
+
|-
}}
+
!style='vertical-align:top;width:5em'|{{TOC tab|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)
 +
|-
 +
!style='vertical-align:top;width:5em'|{{TOC tab|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.
 +
|-
 +
!style='vertical-align:top'|{{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('{')}} (or {{code|esc:char('{')}} (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')</code> which would return '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 {key = value} 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 escape:undo(), will cause the escaescape:text() and escape:kill()
 +
 
 +
 
 +
|}
 +
<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, 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 {{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().
 +
 
 +
==Speed==
 +
The following are benchmarks...
 +
 
 +
when executing the following module function:
 +
<syntaxhighlight lang="lua">
 +
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
 +
</syntaxhighlight>
 +
'''{{#invoke:Escape/testcases|test_kill500}}'''
 +
 
 +
 
 +
when repeating the following line 500 times in a template:
 +
 
 +
{{code|<nowiki>{{#invoke:Escape|main|mode=kill|{{#invoke:Escape/testcases|test_string2}}|test}}</nowiki>}}
 +
 
 +
'''0.767'''<!--
 +
NewPP limit report
 +
Parsed by mw1144
 +
CPU time usage: 1.082 seconds
 +
Real time usage: 1.109 seconds
 +
Preprocessor visited node count: 4001/1000000
 +
Preprocessor generated node count: 0/1500000
 +
Post‐expand include size: 33000/2097152 bytes
 +
Template argument size: 0/2097152 bytes
 +
Highest expansion depth: 3/40
 +
Expensive parser function count: 0/500
 +
Lua time usage: 0.767/10.000 seconds
 +
Lua memory usage: 1.5 MB/50 MB
 +
-->
 +
 
 +
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.
  
===Module Example===
+
==Examples==
 +
===Template===
 +
{{Module talk:Escape/testcases}}
 +
===Module===
 
Here's some sample output from the debug consol below the module editor:
 
Here's some sample output from the debug consol below the module editor:
 
{|- class='wikitable'
 
{|- class='wikitable'
Line 38: Line 108:
 
}}
 
}}
  
{{blue|'''test3 {{=}} escape:char('\\'):text(test2)<br><br>{{=}}test3'''}}<br>
+
{{blue|'''test3 {{=}} escape:char('\\'):text(test2)<br>{{=}}test3'''}}<br>
 
{{#invoke:Escape|main
 
{{#invoke:Escape|main
 
|mode=text
 
|mode=text
Line 48: Line 118:
 
}}
 
}}
  
{{blue|'''test4 {{=}} escape:char('{', {undo {{=}} test3})<br><br>{{=}}test4'''}}<br>
+
{{blue|'''test4 {{=}} escape:char('{', {undo {{=}} test3})<br>{{=}}test4'''}}<br>
 
{{#invoke:Escape|main|mode=undo
 
{{#invoke:Escape|main|mode=undo
 
|char={
 
|char={
Line 59: Line 129:
 
}}
 
}}
  
{{blue|'''test4 {{=}} escape:char('\\', {undo {{=}} test3})<br><br>{{=}}test4'''}}<br>
+
{{blue|'''test4 {{=}} escape:char('\\', {undo {{=}} test3})<br>{{=}}test4'''}}<br>
 
{{#invoke:Escape|main
 
{{#invoke:Escape|main
 
|mode=undo
 
|mode=undo
Line 71: Line 141:
 
}}
 
}}
  
{{blue|'''test5 {{=}} escape:char('{', {undo {{=}} test4})<br><br>{{=}}test5 {{=}}{{=}} test'''}}<br>
+
{{blue|'''test5 {{=}} escape:char('{', {undo {{=}} test4})<br>{{=}}test5 {{=}}{{=}} test'''}}<br>
 
{{#ifeq:
 
{{#ifeq:
 
  {{#invoke:Escape|main
 
  {{#invoke:Escape|main
Line 100: Line 170:
 
}}
 
}}
  
'''{{blue|{{=}}escape:undo(test4)}}<br>
+
'''{{blue|{{=}}escape:undo(test4)}}'''<br>
 
{{#invoke:Escape|main|mode=undo
 
{{#invoke:Escape|main|mode=undo
 
|char={
 
|char={
Line 113: Line 183:
 
}}
 
}}
  
'''{{blue|{{=}}escape:char('\\'):undo(test3)}}<br>
+
'''{{blue|{{=}}escape:char('\\'):undo(test3)}}'''<br>
 
{{#invoke:Escape|main
 
{{#invoke:Escape|main
 
|mode=undo
 
|mode=undo
Line 119: Line 189:
 
}}
 
}}
  
'''{{blue|{{=}}escape:char('{', {undo {{=}} escape:char('\\'):undo(test3)})}}<br>
+
'''{{blue|{{=}}escape:char('{', {undo {{=}} escape:char('\\'):undo(test3)})}}'''<br>
 
{{#invoke:Escape|main|mode=undo|char={
 
{{#invoke:Escape|main|mode=undo|char={
 
|{{#invoke:Escape|main|mode=undo|{{#invoke:Escape|main|mode=text|{{#invoke:Escape|main|mode=text|char={|{{#invoke:Escape/testcases|test_string}}}}}}}}
 
|{{#invoke:Escape|main|mode=undo|{{#invoke:Escape|main|mode=text|{{#invoke:Escape|main|mode=text|char={|{{#invoke:Escape/testcases|test_string}}}}}}}}
Line 125: Line 195:
 
}}
 
}}
  
'''{{blue|{{=}}test {{=}}{{=}} escape:char('{', {undo {{=}} escape:char('\\'):undo(test3)})}}<br>
+
'''{{blue|{{=}}test {{=}}{{=}} escape:char('{', {undo {{=}} escape:char('\\'):undo(test3)})}}'''<br>
 
false
 
false
  
'''{{blue|{{=}}test {{=}}{{=}} escape:char('{', {undo {{=}} escape:char('\\'):undo(test3, '\\')})}}<br>
+
'''{{blue|{{=}}test {{=}}{{=}} escape:char('{', {undo {{=}} escape:char('\\'):undo(test3, '\\')})}}'''<br>
true
+
{{#ifeq:
 
+
{{#invoke:Escape|main
'''{{blue|local t {{=}} 'test { test {\\{ test, \\test, \\{,test\\ \\ \\ {\\'<br>{{=}}t}}<br>'''
+
|mode=char
test { test {\{ test, \test, \{,test\ \ \ {\
+
|char={
 +
|undo={{#invoke:Escape|main
 +
|mode=char
 +
|char=\
 +
|undo={{#invoke:Escape|main|mode=text|{{#invoke:Escape|main|mode=text|char={|{{#invoke:Escape/testcases|test_string}}}}}}
 +
}}
 +
}}
 +
|{{#invoke:Escape/testcases|test_string}}
 +
|true
 +
|false
 +
}}
  
{{#invoke:Escape/testcases|test_string_module|2}}
+
'''{{blue|local t {{=}} '{{#invoke:Escape/testcases|test_string_module|2}}'<br>{{=}}t}}<br>'''
 +
{{#invoke:Escape/testcases|test_string2}}
  
'''{{blue|local e {{=}} require('Module:Escape')<br>local t2 {{=}} escape:text(t)<br>local t3 {{=}} string.gsub(t2, '{', '')<br>local t4 {{=}} escape:undo(t3)<br>{{=}}t4}}<br>'''
+
'''{{blue|local e {{=}} require('Module:Escape')<br>local t2 {{=}} escape:text(t)<br>local t3 {{=}} string.gsub(t2, '{', '')<br>local t4 {{=}} escape:undo(t3)<br>{{=}}t4''}}<br>'''
 
test  test { test, test, {,test  \
 
test  test { test, test, {,test  \
  
 
'''{{blue|local tk0 {{=}} escape:kill(t, '{')<br>{{=}}tk0 {{=}}{{=}} t4}}<br>'''
 
'''{{blue|local tk0 {{=}} escape:kill(t, '{')<br>{{=}}tk0 {{=}}{{=}} t4}}<br>'''
 
true
 
true
 
  
 
|}
 
|}
 
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
 
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
 
<!-- Categories below this line, please; interwikis at Wikidata -->
 
<!-- Categories below this line, please; interwikis at Wikidata -->
  
 
}}</includeonly>
 
}}</includeonly>

Latest revision as of 16:30, 26 September 2020

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|}'


Template:TOC tab 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()
Template:TOC tab Takes two arguments:
  1. The string that may contain placeholders set by escape:text()
  2. 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)
Template:TOC tab 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:
  1. A string
  2. A sequence of characters to be removed from that string. (May use a string.gsub pattern)
  3. Optional, a char to be placed in front of any characters that have been de-escaped.
Template:TOC tab 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 escape:undo(), will cause the escaescape:text() and escape:kill()


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().

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.07248


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.

Examples

Template

Module talk:Escape/testcases

Module

Here's some sample output from the debug consol 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