Revision as of 22:18, 22 September 2014

Template:mIRC Guide Regular expressions, from here on referred to as regex, can be used to perform complicated pattern matching operations. Users should already be familiar with, and comfortable using, Regular expressions at this point. The Regular Expressions page contains more detailed information for users who are new to regex.

General Information

mIRC uses the PCRE library to implement regex with the following options enabled:

• --enable-utf8
• --enable-unicode-properties
• --with-match-limit - around 1,000,000
• --with-match-limit-recursion - 999

mIRC also has two custom modifiers for regex:

• S - Strips control codes from the input before matching (not supported by $hfind).
• g - Performs global matches: after one match has been found, mIRC tries to match again from the current position.

Note: mIRC remembers up to 50 regex matches. However, after 50 matches have been filled, the first match is overwritten. It is very important to keep this 50 match limitation in mind when comparing large quantities of regex.

Regex Identifiers

The four main identifiers, $regex, $regsub, $regml, and $regsubex, can take an optional Name as a parameter. This name can be used to reference the regex comparison later. If a name is not specified, mIRC uses a default one.

$regex

$regex([name],<input>,<regex>)

The sample above performs a regular expression match, which returns the number of matches found. If any errors are detected, a negative value is returned (-8 if you reach the maximum number of matches allowed, or -21 if you read the maximum number of recursions allowed).

$regml

$regml([name],N)

mIRC remembers up to 32 entires of captured text; this is known as back-reference. $regml can be used in order to return the Nth back-reference. As with all other aspects of mIRC fetch identifiers, if 0 is specified as the Nth reference, then the total number of matching references is returned.

$regml also has a .pos property, which returns the position within the input where the capture occurred.

Below is an example of a regular expression, using name as the optional [Name] property, and then using $regml to reference the match(es):

//noop $regex(name,test,/[es]/g) | echo -a $regml(name,0) : $regml(name,1) -- $regml(name,2)

$regsub

$regsub([name],<input>,<regex>,<subtext>,<%varname>)

Performs a regular expression match, like $regex, and then performs a substitution using <subtext>.

The example below returns the total number of substitutions made, and assigns the result(s) to <%varname>:

//noop $regsub(name,test,/([es])/g,t) | echo -a $regml(name,0) : $regml(name,1) -- $regml(name,2)

$regsubex

$regsubex([name],<input>,<regex>,<subtext>)

$regsubex is a more modern version of $regsub, in that it performs the match, then the substitution, and finally returns the result of the substitution.

This time, <subtext> is evaluated during substitution. <subtext> can also be an identifier.

Special markers can be used within <subtext> as well. Below is the list of these markers:

• \0 - Returns the number of matches.
• \n - Returns the current match number.
• \t - Returns the current match text (same as $regml(\n)).
• \a - Returns all matching items.
• \A - Returns a non-spaced version of \a.
• \1 \2 \N ... - Returns the Nth back-reference for the current match.

Important Notes

The main steps when mIRC evaluates an identifier are:

• Process [ ], which evaluates any variables/identifiers inside of the brackets once, and [[ ]], which turns into [ ].
• Separates the identifier's parameters and evaluates each parameter. These evaluations take place in order from left to right.
• Passes the parameters to the identifier

$regsubex is a bit different, which has its own parsing routine. $regsubex does not need to evaluate the subtext parameter before making the regex match. The steps for $regsubex are shown below:

• Process [ ] and [[ ]].
• Seperate parameters, evaluate the 'input' and the 'regex' parameters.
• Perform the regex match.
• * Tokenize $1- according to the number of markers used in the 'subtext' parameters.
• Replaces any markers used in the subtext with their corresponding $N identifiers.
• Evaluate the subtext parameter (one or more times, if /g is used).
• Performs the substitutions and returns the result.

Note: mIRC internally uses $1- to store the values of the markers, this means that the previous tokenization of $1- in the subtext cannot be used.

The way mIRC does this is pretty ugly, it checks how many markers you have and creates a list of tokens ($1-). Each token is assigned a value and mIRC then replaces the marker with the corresponding $N value.

Let's have a look at an example subtext:

\t \t \1 \n

mIRC assigns $1 to $2 from the matched text above, the first back-reference in the pattern is assigned to $3, and finally the Nth iteration is assigned to $4.

If the form \N is used, where N is a positive number greater-than or equal to 1 (such as \1), and there is no such back-reference number in the pattern, mIRC will fill that value (internally, using $1-) with the value of $regml(\n + N - 1).

An example of this is shown below:

$regsubex(abcdefgij,/([a-z])/g,<\6>)

Here we have a break-down of the results of this regex:

• The \6 doesn't mean anything, as there are not 6 back-references made.
• When a is matched, \n is 1, and only one marker is used. Therefore, $1 is filled with $regml(1 + 6 -1) = $regml(6), which is f
• When b is matched, \n is 2, $1 is then filled with $regml(2 + 6 - 1) = $regml(7), which is g
• Until \n + N - 1 is greater than the number of back-references, the characters are replaced with $null.

Because of this, you cannot use the previous $N- value in the subtext.

Nested calls

Nested $regsubex calls are possible, but caution must be taken to remember the main steps:

• Processes [ ] and [[ ]]
• Seperates parameters, evaluate the 'input' and the 'regex' parameters
• Performs the regex match.
• * Tokenizes $1- according to the number of markers used in the 'subtext' parameters.
• Replaces any markers used in the subtext by their corresponding $N identifiers.
• Evaluates the 'subtext' parameter (one or more times, if /g is used).
• Performs the substitutions and returns the result.

When mIRC replaces the markers, it will do so on the whole subtext parameter:

$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper(\t)) : \t)

In the above example, the outer $regsubex will make the regex match, then it will replace \t everywhere in the subtext. The subtext of the outer $regsubex will be:

$regsubex(\t,/(.)/g,$upper(\t))

From the example above, all occurances of \t will receive the value of the matched text from the outer $regsubex, even the one inside $upper; this means that the evaluation won't work as expected. Instead, the \t inside the $upper needs to be the value of the matched text of the inner $regsubex, not the outer one.

The idea is to get mIRC to see something other than \t when looking at the markers inside $upper within the subtext of the outer $regsubex.

Assume the following example:

$regsubex(\t,/(.)/g,$upper( \ $+ t ))

This example would end up calling $upper(\t) with plain text \t, because the $+ is going to be evaluated at the same time $upper is evaluated. The expected result is for the interaction to take place after the outer $regsubex has finished replacing markers, but before $upper is called.

The solution to this issue is to use the [[ \ $+ t ]] construct:

$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper(<nowiki>[[ \ $+ t ]]</nowiki>)))

It is already known that $regsubex will not evaluate the subtext parameter, but the processing of [ ] a,d [[ ]] is done for the whole line. mIRC first changes this line into:

$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper( [ \ $+ t ] )))

The example above conveys how only the [[ ]] has changed. $+ was not evaluated because that subtext parameter is not evaluated since the [ ] processing happens before.

Now, the outer $regsubex gets its parameters (mIRC will fail to see \t there; instead it will see \ $+ t, which is the desired result), makes the regex match, and calls the subtext:

$regsubex(<value of \t in the outer $regsubex>,/(.)/g,$upper( [ \ $+ t ] ))

The expected result is that [ ] is processed first, then \ $+ t gives \t before the inner $regsubex starts to replace its own markers. This is finally the accomplished goal of the initial problem from above.

No Markers

You cannot use a marker, within the inner $regsubex subtext itself, in order to get the value of the marker from the outer $regsubex context:

$regsubex(abcdefcdab,/(cd)/g,@\t : $regsubex(\t,/(.)/g, <why is \ $+ t not cd : \t>) $+ @)

The reason the above example will not work is because mIRC uses the intermediate $1- value.

mIRC will replace markers of the outer regsubex if the following conditions are true:

• 4 markers used in the subtext of the outer $regsubex
• $1 = $2 = $3 = $4 = \t = the matchtex text

The example code from above will then become:

$regsubex($1,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)

mIRC adds the $+ if the markers have text surrounding them.

Although at this point the inner $regsubex has been evaluated, $1- is still what the outer $regsubex tokenization has produced. Before replacing the markers, the expression has been evaluated to:

$regsubex(<value of $1>,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)

The subtext is not evaluated the same as before. Since $1 in the subtext is not evaluated, the markers are then replaced:

• 0 marker used
• $1 = $null

Since $1 is $null, the $1 in the inner $regsubex subtext parameter is also $null.

/filter

/filter supports the -g switch, which uses a regular expression. It is important to note that the back-reference value cannot be obtained using $regml if a custom alias is used as the output (-k). In order to be able to use $regml, $regex would need to be called.

$hfind

$hfind can be used along with $regex. However, $hfind does not support the custom S modifier.

/write, $read, $fline, etc

These, and many more, are various places where Regular Expression can be used.