(→Markers, $1- and Nested $regsubex calls) |
|||
Line 11: | Line 11: | ||
* --with-match-limit-recursion - 999 | * --with-match-limit-recursion - 999 | ||
− | mIRC | + | mIRC has two custom modifiers for regex: |
* S - Strips control codes from the input before matching (not supported by $hfind). | * 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. | * g - Performs global matches: after one match has been found, mIRC tries to match again from the current position. | ||
+ | |||
+ | mIRC also supports 3 custom markers inside a pattern: | ||
+ | |||
+ | * \cc - will match $chr(3) (control code for the color sequence) | ||
+ | * \co - will match $chr(15) (control code for ending a color sequence) | ||
+ | * \cb - will match $chr(2) (control code for the bold sequence) | ||
'''Note:''' mIRC remembers up to 50 regex matches. After 50 matches, the first match is overwritten and the backreferences for that match are lost. | '''Note:''' mIRC remembers up to 50 regex matches. After 50 matches, the first match is overwritten and the backreferences for that match are lost. |
Revision as of 21:36, 18 December 2014
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.
Contents
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 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.
mIRC also supports 3 custom markers inside a pattern:
- \cc - will match $chr(3) (control code for the color sequence)
- \co - will match $chr(15) (control code for ending a color sequence)
- \cb - will match $chr(2) (control code for the bold sequence)
Note: mIRC remembers up to 50 regex matches. After 50 matches, the first match is overwritten and the backreferences for that match are lost.
Example:
/(This is) (a ) pattern/
This represent one regular expression (or one match) with 2 captured backreferences.
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 the /g modifier is used, that number can be greater than 1. You may see a negative value being returned if an error occured:
- -8 - you reached the maximum number of backtracks allowed
- -21 - you reached an internal recursion limit
$regml
$regml([name],N)
$regml can be used to return the Nth back-reference. It takes the optional [name] used in $regex/$regsub/$regsubex. As with all other aspects of mIRC identifier, if 0 is specified as the Nth reference, then the total number of backreferences 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@bc@ef,/([a-z])([a-z])/g,<\1><\n><\t><\a><\A><\2>)
Here you have two matches with two backreferences made per match:
First match is on 'bc':
- \1 is 'b'
- \2 is 'c'
- \n is 1 because it's the first match.
- \t is the current matchtext (same as $regml(\n)), which is 'b'
- \a is "b c" while \A is "bc"
Second match is on 'ef':
- \1 is 'e'
- \2 is 'f'
- \n is 2 because it's the second match.
- \t is the current matchtext (same as $regml(\n)), which is 'c' and not 'e' (\n is 2), it is important to note that when you have more than one backreference and more than one match, \t is a bit meaningless.
- \a is "e f" while \A is "ef"
The way mIRC evaluates those markers is special, it is important at this point to talk about the main steps happening 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 (it is restored after).
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, \1 is assigned to $3 and finally, \n is assigned to $4.
Then each marker is replaced with their corresponding values, the subtext becomes:
$1 $2 $3 $4
And now mIRC evaluates that for each match and use it as a replacement.
Note: If the form \N is used in the subtext, 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 in the pattern (only one backreference, the pattern will, however, be applied 6 times and more because of the /g modifier)
- When a is matched, \n is 1, and only one marker is used. Therefore, $1 (used to represent \6) 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, which at this point, $null is used.
Nested calls
Nested $regsubex calls are possible, but caution must be taken with markers.
First of all, if you use the /g modifier in the outer $regsubex and you need to use the different backreferences made inside the inner $regsubex, you must give a name to either the outer or inner $regsubex (ot both), otherwise, the call of the inner $regsubex will overwrite the backreferences of the outer $regsubex (if you don't use a name, mIRC use a default name, which would be the same here).
When mIRC replaces the markers, it will do so on the whole subtext parameter, consider:
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper(\t)))
In the above example, the outer $regsubex will make the regex match, then it will loop on the result and replace \t accordingly everywhere in the subtext. Notice the subtext of the outer $regsubex is:
$regsubex(\t,/(.)/g,$upper(\t))
All occurences of \t (can appear anywhere and it can be touching others characters) are changed with their corresponding $N value, even the one inside $upper; this means that the code won't work as expected. Typically we want this \t inside $upper() to be the corresponding value from the inner $regsubex, not the outer one.
The idea is to get mIRC to see something other than \t (inside that $upper()) when looking for markers 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 after the inner $regsubex made his own regex match & loop over its results, which is after both $regsubex looked for markers. Something need to be done before the markers of the inner $regsubex are replaced but after the outer $regsubex made his match: when the outer $regsubex is ready to loop over its result.
The solution is to use the [[ \ $+ t ]] construct:
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper( [[ \ $+ t ]] )))
Indeed, the processing of [ ] and [[ ]] is done for the whole line. mIRC first changes this line into:
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper( [ \ $+ t ] )))
The example above conveys how only the [[ ]] has changed. Remember $+ was not evaluated because the subtext parameter of $regsubex is not evaluated until the regex match is performed.
Now, the outer $regsubex is evaluated, [ \ $+ t ] produces \t right before the $regsubex gets its parameters, makes the regex match, and calls the subtext for each match:
$regsubex(<value of \t from the outer $regsubex>,/(.)/g,$upper( \t ))
The more nested $regsubex you have, the more you have to makes sure each subtext has the correct number of [[ ]]. You can make this cleaner by calling a custom alias as the subtext with the markers passed as parameters and doing the nested $regsubex call here.
No Marker
You cannot use a marker inside the subtext of the inner $regsubex to get the value of the marker of the outer $regsubex context, that's why our previous example fails:
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper(\t)))
You are tempted to think that \t inside $upper should always be "cd", because that's the only value that \t can have from the outer $regsubex and we just saw how the marker are replaced for the whole subtext, no matter where it appears. However, we also saw that mIRC does not blindly replace the markers with their real value, it uses the intermediate tokens identifiers ($1 etc), this is required otherwise element such as ) would be taken as closing parenthesis for identifier for example, or comma as argument seperator inside an identifier:
Two markers are used in the subtext of the outer $regsubex, so mIRC make the match, cd is found twice so a two iterations loop is made, each time replacing the match with the evaluation of the subtext parameter. Right before that loop, because two markers are used, mIRC fills $1 with \t as well as $2 with \t and then evaluate the subtext, which gives before evaluation:
$regsubex($1,/(.)/g,$upper( $+ $2 $+ )))
However remember that the subtext is not evaluated before the regex match is done, so only $1 gets evaluated here:
$regsubex(cd,/(.)/g,$upper( $+ $2 $+ )))
As you can see, mIRC adds the $+ if the markers have text surrounding them, that's why you don't need to space them out like identifiers. You might understand why it's failing at this point: $2 has no value in this example because no marker are used in this inner $regsubex's subtext parameter, so $2 is $null.
So how do you use the value of the marker of the outer $regsubex inside the subtext of the inner $regsubex?
The solution is to use [[ \t ]]:
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper( [[ \t ]] )))
As we saw, mIRC will first turn this line into
$regsubex(name,abcdefcdab,/(cd)/g,$regsubex(\t,/(.)/g,$upper( [ \t ] )))
Then the outer $regsubex will make the regex match and replaces markers so the subtext of the outer regsubex becomes:
$regsubex($1,/(.)/g,$upper( [ $+ $2 $+ ] )))
The difference is that you now have a pair of bracket, which are processed first, forcing the evaluation of $2, which has the correct value at this point.
Note: the more you are nesting, the more you need to get mIRC to see the correct things, 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.