Template:Regex/doc

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 search link that can also be used to share such discoveries. This template can also be used to learn the regular expression syntax of this version of Cirrus Search. You could use a bare 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 search directly with insource: "quotes-delimited arguments". These find wikitext without resorting to the regex searches this template does with insource: /slash-delimited arguments/, (which is a common syntax for regex searches). See &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 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 its own page in an ad hoc sandbox. Once your regexp pattern is honed, you add a search domain, by setting prefix.

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 &sect; Parameters hastemplate and insource. In those cases, 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.
 * 1) 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.
 * 2) Open the wikitext, and enter a pattern. Prefix will be added later.
 * 3) Show Preview.  See the pattern in the newly created search link.
 * 4) Click on the search link. Note the bold text in each match, the centered, complete query, and note the count off to the right.
 * 5) Go back in your browser. Modify the regexp.  Cycle. Or don't go back, you may need to majorly reset at the complete query.
 * 6) Enter a prefix. Start with a namespace.  At the complete query trim results via 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 purge that target. You don't have to ever purge if you just change pattern. Note that you can target any single page using prefix:.

For this template, it is necessary to enter the pipe character using \| to find a literal pipe character in the wikitext.

For this template, we need to replace the pipe character with ! 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 pagenames that start with a given letter(s).