Kulemba Module:Ustring/doc

{{used in system}}
{{Module rating |release<!-- Values:  pre-alpha • alpha • beta • release • protected  --  If a rating not needed/relevant, delete this template call -->}}
<!-- Please place categories where indicated at the bottom of this page and interwikis at Wikidata (see [[Wikipedia:Wikidata]]) -->
This module directly imports all functions from the {{luaref|Ustring library|mw.ustring}} library. Documentation for each function can be found there.

The module takes an indefinite number of arguments. Arguments given as {{para|s1}}, {{para|s2}}, etc, are read first, and are used as strings. All remaining numerical arguments are coerced to number type if possible, and remain strings if not. If you wish for a numerical (i.e. unnamed or "{{para|1}}", "{{para|2}}") to remain a string, you can simply escape it by inserting <code>\</code> at the beginning of the string.

Note that MediaWiki will always trim whitespace from named arguments; to give arguments with surrounding whitespace you must use unnamed parameters starting with <code>\</code>.

{| class="wikitable"
|+ How to pass inconvenient strings
|-
! To pass this... !! Write this !! Explanation
|-
| <code>"  0123  "</code> || {{para||\  123  }} || To get surrounding whitespace must use unnamed, but must precede with <code>\</code> to indicate that it isn't a number.
|-
| <code>"0123"</code> || {{para|s1|0123}} || If you don't need to preserve whitespace use {{para|s1}} etc.
|-
| <code>"0123"</code> || {{para|1|\0123}} || If you don't need to preserve whitespace explicitly use {{para|1}} etc.
|-
| In another template, to pass its parameter <code>{{{1}}}</code>, preserving whitespace || {{para||\{{{1}}}}} || Must provide the <code>\</code> with unknown string input.
|-
| In another template, to pass its parameter <code>{{{1}}}</code>, stripping whitespace || {{para|s1|{{{1}}}}} || 
|-
| In another template, to pass its parameter <code>{{{1}}}</code>, stripping whitespace || {{para|1|<nowiki>\{{#if:1|{{{1}}}}}</nowiki>}} || 
|}

You can also wrap results in tags. All other unused arguments will be passed to {{luaref|frame:extensionTag}}

== Usage ==

<code><nowiki>{{</nowiki>#invoke:{{BASEPAGENAME}}|''function_name''|arg1|arg2|...}}</code> is equivalent to {{luaref|Ustring library|mw.ustring.''function_name''|args=arg1, arg2, ...}}

===Example using mw.ustring.sub===
<code><nowiki>{{#invoke:Ustring|sub|s1=abcde|2|4}}</nowiki></code>

produces:

{{#invoke:Ustring|sub|s1=abcde|2|4}}

===Example using mw.ustring.gsub===
<code><nowiki>{{#invoke:Ustring|gsub|s1=1234|23|}}</nowiki></code>

produces:

{{#invoke:Ustring|gsub|s1=1234|23|}}

===Example using mw.ustring.char===
<code><nowiki>&amp;amp;#{{#invoke:ustring|char|49|48|59}}</nowiki></code>

produces:

&amp;#{{#invoke:ustring|char|49|48|59}}

===Example using mw.ustring.match===
<code><nowiki>{{#invoke:Ustring|match|s1=abcde|s2=(c%w)}}</nowiki></code>

produces:

{{#invoke:Ustring|match|s1=abcde|s2=(c%w)}}

Note: Only the first match is returned. Additional returns are omitted because mw.ustring.gsub's second return value is generally undesirable.

===Example using tag arguments===
<pre>{{#invoke:Ustring|match
|s1={{Module:Ustring}}|%s%s%sif%snot%s[^%s]+%sthen.+%
<!--enter an actual newline character to match '\n'-->%s%s%send
|tag=syntaxhighlight|lang=lua}}</pre>
produces:
{{#invoke:Ustring|match
|s1={{Module:Ustring}}|%s%s%sif%snot%s[^%s]+%sthen.+%
<!--enter an actual newline character to match '\n'-->%s%s%send
|tag=syntaxhighlight|lang=lua}}

Note that:
{{#tag:pre|<nowiki><syntaxhighlight lang="lua">{{#invoke:Ustring|match
|s1={{Module:Ustring}}|%s%s%sif%snot%s[^%s]+%sthen.+%
<!--enter an actual newline character to match '\n'-->%s%s%send}}</syntaxhighlight></nowiki>}}
produces:
<syntaxhighlight lang="lua">{{#invoke:Ustring|match
|s1={{Module:Ustring}}|%s%s%sif%snot%s[^%s]+%sthen.+%
<!--enter an actual newline character to match '\n'-->%s%s%send}}</syntaxhighlight>

== Errors ==
Errors from accessing {{luaref|Ustring library|mw.ustring}} should be maintained, e.g.:

<code><nowiki>{{#invoke:Ustring|xyzzy}}</nowiki></code>

should produce:

{{script error|Script error: The function "xyzzy" does not exist.}}

and

<code><nowiki>{{#invoke:Ustring|maxPatternLength}}</nowiki></code>

should produce:

{{script error|Script error: "maxPatternLength" is not a function.}}

== See also ==
{{String handling templates}}
<includeonly>{{#ifeq:{{SUBPAGENAME}}|sandbox | |
<!-- Categories below this line, please; interwikis at Wikidata -->
[[Category:Modules that manipulate strings|*]]
}}</includeonly>