From WikiChip
Difference between revisions of "mirc/regex"
< mirc

($regsubex([name],,,))
Line 1: Line 1:
 
{{mIRC Guide}}
 
{{mIRC Guide}}
Regular expressions can be used to perform complicated pattern matching operations. You should already know how to use Regular expressions as this page won't teach them.
+
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|Regular Expressions]] page contains more detailed information for users who are new to regex.
  
== Informations ==
+
== General Information ==
 
+
mIRC uses the [[PCRE library]] to implement regex with the following options enabled:
mIRC uses the PCRE library to implement regex with the following options enabled:
 
  
 
* --enable-utf8
 
* --enable-utf8
Line 11: Line 10:
 
* --with-match-limit-recursion - 999
 
* --with-match-limit-recursion - 999
  
mIRC has two custom modifier:
+
mIRC also has two custom modifiers for regex:
* S - strips control code from the input before matching (not supported by $hfind).
+
* S - Strips control codes from the input before matching (not supported by $hfind).
* g - perform a 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 remembers up to 50 regex matches. After 50 matches, the first match is overwritten.
+
'''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, $regsub and $regsubex can take an optional name as a parameter, to reference that call later, if you do not specify a name, mIRC use a default.
+
== 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([name],<input>,<regex>) ==
+
=== $regex ===
 +
<source lang="mIRC">$regex([name],<input>,<regex>)</source>
  
Perform  a regular expression match, returns the number of matches found. Returns a negative value to indicate an error (-8 if you reach the maximum number of match allowed or -21 if you read the maximum number of recursion allowed)
+
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).
  
mIRC remembers up to 32 captured text (backreference), you can use $regml([name],N) to returns the Nth backreference, or the total number of backreferences with N = 0
+
=== $regml ===
 +
<source lang=mIRC>$regml([name],N)</source>
  
$regml() also has a .pos property, which returns the position in the input where this was captured.
+
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.
  
<source lang="mIRC">
+
$regml also has a ''.pos'' property, which returns the position within the input where the capture occurred.
//noop $regex(name,test,/[es]/g) | echo -a $regml(name,0) : $regml(name,1) -- $regml(name,2)
 
</source>
 
  
== $regsub([name],<input>,<regex>,<subtext>,<%varname>) ==
+
Below is an example of a regular expression, using ''name'' as the optional ''[Name]'' property, and then using $regml to reference the match(es):
Performs a regular expression match, like $regex(), and then performs a substitution using <subtext>.
+
<source lang="mIRC">//noop $regex(name,test,/[es]/g) | echo -a $regml(name,0) : $regml(name,1) -- $regml(name,2)</source>
  
Returns N, the number of substitutions made, and assigns the result to <%varname>.
+
=== $regsub ===
 +
<source lang="mIRC">$regsub([name],<input>,<regex>,<subtext>,<%varname>)</source>
 +
Performs a regular expression match, like $regex, and then performs a substitution using <subtext>.
  
<source lang="mIRC">
+
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)
+
<source lang="mIRC">//noop $regsub(name,test,/([es])/g,t) | echo -a $regml(name,0) : $regml(name,1) -- $regml(name,2)</source>
</source>
 
  
== $regsubex([name],<input>,<regex>,<subtext>) ==
+
=== $regsubex ===
 +
<source lang="mIRC">$regsubex([name],<input>,<regex>,<subtext>)</source>
 +
$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.
  
$regsubex is a more modern version of $regsub, it performs the match, and then the substitution, returns the result of the substitution
+
This time, <subtext> is evaluated during substitution. <subtext> can also be an identifier.
  
This time, <subtext> is evaluated during substitution and can be an identifier.
+
Special markers can be used within <subtext> as well. Below is the list of these markers:
  
<subtext> can also contain special markers:
+
* \0 - Returns the number of matches.
 
+
* \n - Returns the current match number.
* \0 - returns the number of matches
+
* \t - Returns the current match text (same as $regml(\n)).
* \n - returns the current match number
+
* \a - Returns all matching items.
* \t - returns the current match text (same as $regml(\n))
+
* \A - Returns a non-spaced version of \a.
* \a - returns all match items
+
* \1 \2 \N ... - Returns the Nth back-reference for the current match.
* \A - returns a non-spaced version of \a.
 
* \1 \2 \N ... - returns the Nth backreference for the current match
 
 
 
'''Notes''' on $regsubex:
 
  
 +
==== Important Notes ====
 
The main steps when mIRC evaluates an identifier are:
 
The main steps when mIRC evaluates an identifier are:
* Processes [ ] (evaluating any variables/identifiers inside them once) and [[ ]] (turning them into [ ])
+
* Process '''[ ]''', which evaluates any variables/identifiers inside of the brackets once, and '''[[ ]]''', which turns into '''[ ]'''.
* Separates the identifier's parameters and evaluates each parameter (in left-to-right order).
+
* 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
 
* Passes the parameters to the identifier
  
It's a bit different in $regsubex, it has its own parsing routine. Indeed it needs not to evaluate the 'subtext' parameter before making the regex match, the steps are:
+
'''$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 [[ ]].
* Processes [ ] and [[ ]]
+
* Seperate parameters, evaluate the 'input' and the 'regex' parameters.
* Seperates parameters, evaluate the 'input' and the 'regex' parameters
+
* Perform the regex match.
* Performs the regex match
+
* <nowiki>*</nowiki> Tokenize '''$1-''' according to the number of markers used in the 'subtext' parameters.
* <nowiki>*</nowiki> Tokenizes $1- according to the number of markers used in the 'subtext' parameters
+
* Replaces any markers used in the subtext with their corresponding '''$N''' identifiers.
* Replaces any markers used in the subtext by their corresponding $N identifiers
+
* Evaluate the '''subtext''' parameter (one or more times, if /g is used).
* Evaluates the 'subtext' parameter (one or more times, if /g is used)
 
 
* Performs the substitutions and returns the result.
 
* Performs the substitutions and returns the result.
  
<nowiki>*</nowiki> mIRC internally use $1- to store the values of the markers, this means you cannot use the previous tokenization of $1- in the subtext.
+
'''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 create a list of token ($1-).
+
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.
  
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:
 +
<source lang="mIRC">\t \t \1 \n</source>
 +
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''.
  
Let's say your subtext is "\t \t \1 \n", mIRC assignes the matched text to $1, to $2, the first backreferences in the pattern is assigned to $3 and the Nth iteration 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)'''.
  
If you use a form \N where N is a positive number greater or equal to 1 (like \1) and there is no such backreference 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:
 
<source lang="mIRC">$regsubex(abcdefgij,/([a-z])/g,<\6>)</source>
 
<source lang="mIRC">$regsubex(abcdefgij,/([a-z])/g,<\6>)</source>
\6 doesn't mean anything, there is no 6 backreferences made.
+
Here we have a break-down of the results of this regex:
* When 'a' is matched \n is 1, only one marker used so $1 is filled with $regml(1 + 6 -1) = $regml(6) which is 'f'
+
* The '''\6''' doesn't mean anything, as there are not 6 back-references made.
* When 'b' is matched, \n is 2, $1 is filled with $regml(2 + 6 - 1) = $regml(7) which is 'g'
+
* 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'''
* And so on until \n + N - 1 is greater than the number of backref, at this point the characters are replaced with $null
+
* When ''b'' is matched, '''\n''' is ''2'', '''$1''' is then filled with ''$regml(2 + 6 - 1) = $regml(7)'', which is '''g'''
Because of this, you cannot use the previous $N- value in the subtext.
+
* 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 $regsubex calls are possible but let's remember the main steps:
 
  
 +
==== Nested calls ====
 +
Nested '''$regsubex''' calls are possible, but caution must be taken to remember the main steps:
 
* Processes [ ] and [[ ]]
 
* Processes [ ] and [[ ]]
 
* Seperates parameters, evaluate the 'input' and the 'regex' parameters
 
* Seperates parameters, evaluate the 'input' and the 'regex' parameters
* Performs the regex match
+
* Performs the regex match.
* Tokenizes $1- according to the number of markers used in the 'subtext' parameters
+
* <nowiki>*</nowiki> 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
+
* Replaces any markers used in the subtext by their corresponding $N identifiers.
* Evaluates the 'subtext' parameter (one or more times, if /g is used)
+
* Evaluates the 'subtext' parameter (one or more times, if /g is used).
 
* Performs the substitutions and returns the result.
 
* Performs the substitutions and returns the result.
  
 
When mIRC replaces the markers, it will do so on the whole subtext parameter:
 
When mIRC replaces the markers, it will do so on the whole subtext parameter:
 +
<source lang="mIRC">$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper(\t)) : \t)</source>
  
$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:
 +
<source lang="mIRC">$regsubex(\t,/(.)/g,$upper(\t))</source>
  
The outer $regsubex will make the regex match, then it will replace \t everywhere in the subtext, the subtext of the outer $regsubex is:
+
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.
  
$regsubex(\t,/(.)/g,$upper(\t))
+
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'''.
  
Here all \t's gets the value of the matched text of the outer $regsubex, even the one inside $upper(), meaning that it won't work as expected. Indeed you want the \t inside the $upper to be the value of the matchted text of the inner $regsubex, not the outer one.
+
Assume the following example:
 +
<source lang="mIRC">$regsubex(\t,/(.)/g,$upper( \ $+ t ))</source>
 +
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.
  
What we want to do is to get mIRC to see something different than "\t" when looking at the markers inside $upper in the subtext of the outer $regsubex.
+
The solution to this issue is to use the '''<nowiki>[[ \ $+ t ]]</nowiki>''' construct:
 +
<source lang="mIRC">$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper(<nowiki>[[ \ $+ t ]]</nowiki>)))</source>
  
If we were to use $regsubex(\t,/(.)/g,$upper( \ $+ t )) well you would just end up with calling $upper(\t) with plain text \t, because that $+ is going to be evaluated when $upper is evaluated. We want to interact after the outer $regsubex finished replacing markers but before $upper() is called.
+
It is already known that '''$regsubex''' will not evaluate the subtext parameter, but the processing of '''<nowiki>[ ] a,d [[ ]]</nowiki>''' is done for the whole line. mIRC first changes this line into:
 +
<source lang="mIRC">$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper( [ \ $+ t ] )))</source>
  
The solution is to use the <nowiki>[[ \ $+ t ]]</nowiki> construct:
+
The example above conveys how only the '''[[ ]]''' has changed. '''$+''' was not evaluated because that subtext parameter is not evaluated since the '''[ ]''' processing happens before.
  
$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper(<nowiki>[[ \ $+ t ]]</nowiki>)))
+
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:
 +
<source lang="mIRC">$regsubex(<value of \t in the outer $regsubex>,/(.)/g,$upper( [ \ $+ t ] ))</source>
  
As we know $regsubex doesn't evaluate the subtext parameter but the processing of <nowiki>[ ] a,d [[ ]]</nowiki> is done for the whole line. So mIRC first change this line into:
+
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.
  
$regsubex(abcdefcdab,/(cd)/g,\t : $regsubex(\t,/(.)/g,$upper( [ \ $+ t ] )))
+
==== 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:
 +
<source lang="mIRC">$regsubex(abcdefcdab,/(cd)/g,@\t : $regsubex(\t,/(.)/g, <why is \ $+ t not cd : \t>) $+ @)</source>
  
Notice how only the [[ ]] changed, $+ was not evaluated because that subtext parameter is not evaluated, the [ ] processing happens before.
+
The reason the above example will not work is because mIRC uses the intermediate '''$1-''' value.
 
 
Now the outer $regsubex gets its parameters (mIRC will fail to see \t there, it will see \ $+ t, which is what we wanted), makes the regex match and call the subtext:
 
 
 
$regsubex(<value of \t in the outer $regsubex>,/(.)/g,$upper( [ \ $+ t ] ))
 
 
 
And as usual, [ ] is processed first and \ $+ t gives \t before this inner $regsubex start to replaces its own markers. bingo.
 
 
 
Note also that you cannot use a marker in the inner $regsubex subtext itself to get the value of that marker of the outer $regsubex context:
 
 
 
$regsubex(abcdefcdab,/(cd)/g,@\t : $regsubex(\t,/(.)/g, <why is \ $+ t not cd : \t>) $+ @)
 
 
 
This is because mIRC use the intermediate $1- value, when mirc replaces markers of the outer regsubex:
 
  
 +
mIRC will replace markers of the outer '''regsubex''' if the following conditions are true:
 
* 4 markers used in the subtext of the outer $regsubex
 
* 4 markers used in the subtext of the outer $regsubex
 
* $1 = $2 = $3 = $4 = \t = the matchtex text
 
* $1 = $2 = $3 = $4 = \t = the matchtex text
  
The code becomes:
+
The example code from above will then become:
 +
<source lang="mIRC">$regsubex($1,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)</source>
  
$regsubex($1,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)
+
mIRC adds the '''$+''' if the markers have text surrounding them.
  
mIRC adds the $+ if the marker has text surrounding it.
+
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:
 
+
<source lang="mIRC">$regsubex(<value of $1>,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)</source>
Now that inner $regsubex is evaluated, at this point, $1- is still what the outer $regsubex's tokenization produced, so before replacing the markers, you have:
 
 
 
$regsubex(<value of $1>,/(.)/g, <why is \ $+ t not cd : $1 $+ >) $+ @)
 
 
 
The subtext is not evaluated as we saw, remember? So that $1 in the subtext is not evaluated, then we have the replacements of markers:
 
  
 +
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
 
* 0 marker used
* $1 = $null  
+
* $1 = $null
  
And since $1 is $null, well so is $1 in that inner $regsubex's subtext parameter.
+
Since '''$1''' is '''$null''', the '''$1''' in the inner '''$regsubex''' subtext parameter is also '''$null'''.
  
 
== /filter ==
 
== /filter ==
 
+
{{mIRC|/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.
{{mIRC|/filter}} supports the -g switch to use a regular expression, you cannot get the backreference value using $regml() if you use a custom alias as the output (-k), you need to use a $regex call on that line.
 
  
 
== $hfind ==
 
== $hfind ==
 +
'''$hfind''' can be used along with '''$regex'''. However, '''$hfind''' does not support the custom '''S''' modifier.
  
$hfind can be used with regex, it doesn't support the custom S modifier
+
== /write, $read, $fline, etc ==
 
+
These, and many more, are various places where [[regular expression|Regular Expression]] can be used.
== /write, $read, $fline etc ==
 
 
 
They are various places in which regex can be used.
 

Revision as of 23: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.