Revision as of 18:10, 23 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. After 50 matches, the first match is overwritten and the backreferences for that match are lost.

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 get the backreference captured by the regex match. If a name is not specified, mIRC uses a default one.

$regex

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

The sample above performs a regular expression match and returns the number of matches found. If any error occurs, a negative value is returned (for example -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 entries of captured backreferences. $regml can be used in order to return the Nth back-reference. It takes the optional [name] used in $regex/$regsub/$regsubex. 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>. Returns the number of substitution made and fills <%varname> with the resulting text

//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 so you can use %variables and $identifiers there, they will be evaluated

Markers, $1- and Nested $regsubex calls

Special markers can be used inside the <subtext> parameter of $regsubex:

• \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 made for a given match

$regsubex(a@b,/([a-z])([a-z])/g,@<\1><\t><\n><\a><\A><\2>)

Here you have two backreferences made, you can use \1 and \2 in the subtext to refer to those values.

The way mIRC evaluates those markers is special, it is important at this point to talk about the main steps when evaluating $identifiers:

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

$regsubex is a bit different, it has its own parsing routine. By design, $regsubex must not evaluate the subtext parameter before doing 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's values.
• Evaluate the subtext parameter (one or more times, if /g is used).
• Performs the substitutions and returns the result.

mIRC internally uses $1- to store the values of the markers, it means the previous tokenization of $1- cannot be used in the subtext parameter.

The way mIRC does this is quite special, it checks how many markers you have and creates a list of tokens (so, with $1-). Each token is assigned a value and mIRC then replaces the markers with the corresponding $N value before evaluating that result.

Let's have a look at an example, consider the following subtext:

\t \t \1 \n

mIRC assigns the value of \t to $1 & $2, 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 use 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
• And so on until \n + N - 1 is greater than the number of back-references, the characters are replaced with $null.

Nested calls

Nested $regsubex calls are possible, but caution must be taken with markers:

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

$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 is:

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

All occurences of \t there are changed with corresponding $N value, even the one inside $upper; this means that the code won't work as expected. Instead, the \t inside $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 this marker inside $upper, from the outer $regsubex context.

A simple $+ cannot be used:

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

Having this as the subtext of the $regsubex would end up calling $upper(\t) with plain text "\t", because the $+ is going to be evaluated at the same time $upper is evaluated, which is after $regsubex looked for markers. Something need to be done before the markers are replaced.

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

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

Indeed, the processing of [ ] and [[ ]] 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.

Now, the outer $regsubex is evaluated, it 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 ] ))

[ ] are again processed first to produce "\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,$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.

As we know, mIRC replaces markers of the outer regsubex:

• there are 2 markers used in the subtext of the outer $regsubex (\t and \t)
• $1 and $2 get filled with the value of \t

Then the subtext parameter of the outer $regsubex is evaluated, mIRC actually evaluates at this point:

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

As you can see, mIRC adds the $+ if the markers have text surrounding them.

When this inner $regsubex evaluates, $1 gets evaluated correctly while $2 is not, again, because the subtext parameter of $regsubex doesn't get evaluated before making the regex match. This inner $regsubex will then replaces its own markers, refilling $1- with $null since its subtext doesn't have any markers, which is why $2 will be evaluated to nothing

Note: It's possible to get $2 (or such) to be different from $null if you have markers in the inner $regsubex, but it wouldn't be the expected value, of course.

The solution is to use \t , in our example this would make $2 being evaluated while the list of token $1- still is the content from the outer $regsubex.

Note: the more you are nesting, the more you need to get mIRC to see the correct stuff, which easily gets ugly, calling an alias in the subtext to do the replacement is recommended.

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