Reba inkomoko ya Inyandikorugero:Regex/doc

{{Documentation subpage}}
{{tsh|slre}}


== Purpose ==

This template helps field the details in the wikitext of any page on the wiki.  Normally searches ignore non-alphanumeric characters, but regular expressions (regex) accept all characters, plus metacharacters.

This template acts as a doorway by helping to develop a database query before running it on the wiki, and it does this by way of a [[Template:Internal search templates common doc|search link]] that can also be used to share such discoveries. This template can also be used to learn the regular expression syntax of [[Special:Version#Installed software|this version]] of [[mw:Help:CirrusSearch|Cirrus Search]].  You could use a bare {{tlf|search link}} to do all this, but this template saves a lot of typing (see below), so you only need to focus on entering a regexp.

An important alternative to using this template is performing a [[H:S|search]] directly with ''insource:''<kbd>"quotes-delimited arguments"</kbd>. These find wikitext without resorting to the [[regex]] searches this template does with ''insource:''<kbd>/slash-delimited arguments/</kbd>, (which is a common syntax for regex searches). See [[#About CirrusSearch|&sect; About CirrusSearch]] below for a better understanding of when this template is not needed.  See below for other search tools.

[[Regular expressions]] are little computer programs, so it is characteristic of regex searches that they must always be tested to achieve their potential precision and thoroughness. But only a few of these intensive searches are technically able to run at a time against the database.  This template minimizes your footprint, and guarantees that you will never run an untested regexp on every namespace in the wiki, even if [[H:S#User preferences|your default search]] would let you do that.  Use of this template enables the smallest possible footprint by using filters to limit the search domain. The first domain it targets is its own page in an {{lang|la|ad hoc}} sandbox. Once your regexp pattern is honed, you add a search domain, by setting {{para|prefix}}.

== Parameters ==
{{more|Help:Parameters}}

{| class="wikitable"
|-
|{{para|pattern}} or {{param|1}}|| a regexp search pattern. Pattern is also the first positional parameter.
|-
|{{para|prefix}} or {{param|2}}|| search domain. Prefix accepts a [[WP:namespace|namespace]] number, or <code>n</code> for the current namespace, or <code>:</code> for mainspace, plus it has [[H:S#Parameters|the usual ''prefix:'' meaning]]. Defaults to its current page ([[wp:fullpagename|fullpagename]]) if a pattern is given alone.
|-
|{{para|label}} or {{param|3}}|| search link label.  Label is also a positional parameter.
|}

== Procedure ==

Decide whether you really need a thoroughly precise regexp search, or whether you can find the general wikitext of interest with a plain ''insource:'' filter. Examples of the plain ''insource:'' search are in [[#Parameters hastemplate and insource|&sect; Parameters hastemplate and insource]]. In those cases, {{tl|search link}} is sufficient, and sandboxing is not being suggested.

''Namespace plus pagename equals fullpagename.''

The procedure here is an iterative, read-evaluate-modify cycle.  
# Find an existing fullpagename with the wikitext instances you are interested in targeting. Or create one yourself, and save it to the database so the query will find it.  
# Open the wikitext, and enter a {{para|pattern}}. Prefix will be added later. 
# Show Preview.  See the pattern in the newly created search link.
# Click on the search link. Note the bold text in each match, the centered, complete query, and note the count off to the right.
# Go back in your browser. Modify the regexp.  Cycle. Or don't go back, you may need to majorly reset at the complete query.
# Enter a {{para|prefix}}. Start with a namespace.  At the complete query trim results via [[H:S#Parameters|the first letter(s) of]] pagenames tacked onto the namespace's automatically-given colon.

Step '''6''' is the core provision of this template.  ''Caveat emptor'': if you change the ''target'', you'll have to re-save it to the database. If you target it again immediately, you'll want to [[WP:Purge|purge]] that target.  You don't have to ever purge ''if you just change {{para|pattern}}''.  Note that you can target any single page using ''prefix:''.
{{Help:Searching/Regex/Sandboxing}}<!--
-->
{{Help:Searching/Features}}<!--
-->{{#section:Help:Searching/Regex|Regular expressions}}<!--
-->{{#section:Help:Searching/Regex|Metacharacters}}
For this template, it is necessary to enter the pipe character using <nowiki>\{{!}}</nowiki> to find a literal pipe character in the wikitext.
{{#section:|Help:Searching/Regex|Character classes}}<!--
-->{{#section:Help:Searching/Regex|Alternation}}
For this template, we need to replace the pipe character with {{tl|!}} so that the "pipe" for the regexp won't confuse this template (or any other template).  We need the parentheses  at times because an alternation finds the ''longest'' pattern, and so the parentheses define that boundary, but it's a boundary you don't have to make if an alternation is the entire regexp patter.

Regexp searches are restricted on the server, so this template reduces the
regex search footprint by using the ''prefix:'' filter every time,  restricting
the search domain to a namespace ''at most''. The ''prefix:'' parameter can
further filter a namespace by specifying [[wp:pagename|pagename]]s that start
with a given letter(s).<!--


-->

== [[Template:Internal_search_templates_common_doc|Templates for searching Wikipedia ]] ==
{{Template:Internal_search_templates_common_doc|seealso=|level=2}}
* {{tl|template usage}}
* {{tl|search link}}
* {{tl|for loop}}

== Notes ==
{{reflist}}

<includeonly>{{Sandbox other||
<!-- Categories below this line, please; interwikis at Wikidata. -->
[[Category:Search templates]]

}}</includeonly>