Regex Tutorial

Contributed by Trystan
Regular Expressions: a complex look into the world
Officially the mIRC help file does not contain much documentation on the $regex() identifier so I took some time to look through how mIRC would support it how to come up with a way to explain them in a simple terms that the new scripter or the maybe those who have never worked with regular expressions to get an idea of how this may be used best with your scripts. I will assume if you are reading this you have at least looked at the mIRC help file and are now wondering what good is this new identifier if there is not real documentation of how it works. So you have probably done onto the Internet and looked up Regular Expression and are now trying to figure out where you want wrong even looking them up, as it looks so complex. Yes Regular Expressions are complex but I hope this document will take some of the complexity out of them and help you better understand them. So now lets take a few to talk about how the Regular Expressions language itself deals with the determining whether your string is in the Expression. I have done my best to document all the switches and characters that I can locate. If there are others, and they work with mIRC I will be glad to hear about it. Also a word of warning do not assume from the first few examples that $regex() is a boolean operator, please read on

Terms used
First lets cover some of the terms that will be used in this tutorial so that there is no confusion.

The mIRC help file defines the usage for $regex() as 

$regex([name], text, re)
For this tutorial I am going to drop the usage of the [name], its usage is describe well enough in the mIRC help file. The text I will refer to as the string, the re will be referred to as the expression or substring. The expression is how $regex() evaluates the string to determine the matches. Some prefer the term substring when talking about the expression part of $regex() as it is substring of the primary string we are attempting to match.

Basic Operators
^ : matches the substring at the start of the string. The first character or characters must match the substring for it to return a value. 
$regex(abc,^a)
$regex(this is a string,^this)
Returns 1 : as the string ABC when compared to the substring of A the A appeared at the start of the string, if we were to change the string to bcd it would return 0. Do not think of this as a true, false state of $regex although it can be used in that state, the nature of $regex is not as a true, false identifier

$ : matches a string that ends with the substring of the expression. This time the last character or characters. 

$regex(abc,c$)  
$regex(this is a string,string$)
This will returns 1, as the substring appears at the end of the string, if we were to change the end of the string to something else it would return 0

^ and $ : matches the string for an exact match of the substring. 

$regex(abc,^abc$)
This will returns 1, was the string starts with substring and ends with the substring if any change to either the substring or the string is made the returned value would be 0

* : Zero or more : with this operator we are looking to find out if there is a character which can exist but does not have to. 

$regex(ab,ab*) 
$regex(a,ab*)  
$regex(abbbbb,ab*)
All of the above will return a 1, was what we are looking at is, the expression of there must be a least 1 'a' found in the string, followed maybe a 'b' and if there is a 'b' there can be any number of them. This operator is not good when looking for a an exact phrase to appear.

+ : One or More : similar to the * operator, this time we want to find a character in the string that matches the substring and it must occur it least once but can occur more then once. 

$regex(abbbb,ab+)
$regex(ab,ab+)
these would return 1 as they are true. The substring ab+ meaning, the character a followed by one or more of the character b

? : Zero or One : In the same family as the * and + operates. The ? is the Zero or more operator. It looks for substring which does not have to appear in the string but if if does it must appear at least once. 

$regex(ab,a?b)
$regex(cb,a?b)
$regex(abbbbb,ab?)
Again we are still dealing with the true, false expression of how this is returned. The substring is evaluated as the first character A is checked against the operator ? to see if it appears in the string. Then moves to the character b and checks to make sure it is in the string.

| : OR operator : like other languages this is used to to have a substring that can have one value or another. 

$regex(hello there,hi|hello)
it compares the first part of the substring against the string, if it is not found it tries to match the second part of the substring. Else it will return 0 if neither of of the substrings match the string.

. : Character operator : this stands for "one character", this is helpful when looking at a spring that you might want to find one character and another that might be joined together by a character that you do not have concern for 

$regex(abc,a.c) 
$regex(axe,.x.)
$regex(oxe,.x.)
All will return 1 as they match the pattern of the substring.
Grouping of items
Regular expressions allow you to group like parts of the substring into groups which makes it easier to write the expressions.

() : Grouped substrings. This allows you to evaluate a group of characters in a substring separate from the rest of the substring. 

$regex(abc,a(bc)*) : returns 1
$regex(ac,a(b|c))
In the above examples the characters inside the () are seprated from the substring and it then applies the given operator to those characters. So we look at a string and there must be an 'a' followed by the characters b or c in the pattern we have determined.

[ ] : blocked groups : this allows you to search for characters within a range which appears between the [ ] there are some rules to using these

a-z : mean lower case
A-Z : mean upper case
0-9 : are the valid range for a digit

now to provide an example of usage. 

$regex(abcdef,[ab])
this is much like the a|b from the or operator, as this will look at the string and attempt to find a match for 'a' or 'b' which could be said 'a' to 'b'

By adding the - you can now find a range of characters, this can save you from having to type abcdefgh etc.. If you want to search for the - as part of the range is must appear as the first character in the string. (yes there is another way but is more complex) 

$regex(the cat,[g-i])
$regex(the-cat,[-w-x])
this looks for a character that appears between the start point 'g' and the end point of 'i' which in the example would find the 'h' and return 1

If you were to use G-I you would get the returned value of 0 as there is no 'H' in the string that you are searching, so if you want to find 'h' or 'H' you need to combine the values between the [ ] like so [g-iG-I] this will now search for a letter that appears between both upper and lower case.

When searching for a number in the string you can search for numbers between 0 to 9, so you can find a number 

$regex(1%,[0-9]%)
so the number is between 0 to 9, it found 1 and had the character % after it. Which is an exact match. So how does one match numbers that are over 9? simple apply two [ ] searches [2-3][0-9] 
$regex(31,[2-3][0-9])
this will search for a range of numbers between 20 and 39

You can search for both Digits and characters in the same [ ] the order in which they appear does not matter so the [0-9a-z] and [a-z0-9] are both acceptable.

Finally the [ ] have a not ^ operator which can search for a string that is not between the [ ] 

$regex(the cat,[^w-z])
this will search for characters that are not between the given range.

[: :] : Characters Classes, these are groups of the character that fall into the same group like alphanumeric characters, the space bar and the return key. These are the types that work so far. 

$regex(123,[[:digit:]])
Special Characters
Since Regular Expressions use many of the characters that you might want search for, how do you search for those characters? with the \ operator to escape the run of the Expression. Here is a list of the escape characters 
   Characters        Escape Character Code
       ?                        \?
       *                        \*
       +                        \+
       .                        \.
       |                        \|
       {                        \{
       }                        \} 
       \                        \\
       [                        \[
       ]                        \]
       (                        \(
       )                        \)
there are a few \ that can help you find some of different types of character strings 
   \b  Matches between a word boundary :  $regex(rat,\brat\b)
   \B  The Match-within-word Operator  :  $regex(crate,c\Brat\Be)
   \s  Matches the space bar character :  $regex(test this\s)
   \S  Matches any non space character :  $regex(test,\S)
   \w  Match any word character.       :  $regex(test,\w)
   \W  Match any non-word character.   :  $regex(test this\W)
   \d  Match any digit.                :  $regex(test 20,\d)
   \D  Match any non-digit.            :  $regex(test,\D)
In all other cases, $regex() ignores '\' For example, '\n' matches 'n'.
Switches
Regular Expressions have a few switches which can be used to help the pattern matching. These normally start with the / and end with the /character

//x : Extend the Pattern to allow for white space
//g : Match all possibilities in the pattern
//s : Treat the string as a single line

Pattern Matching
Regular Expressions can be used to match something, whether it is a character or a phrase or how many times a character or phrase appear in the string we are searching

lets take a look at search a string for a character or phrase first before we get into finding the number of times something happens 

$regex(we want to match something,a)
This will return 1 as the character 'a' appears in the string this can be helpful if you are looking for a special character to be in the phrase. 
$regex(regular expressions tutorial by trystan,tutorial by)
we can also search to see if the phrase we are looking for has been used, this is helpful when dealing with bad language kickers, you search the string and have a 1 or a 0 value returns based on what was said

now lets look at how we can count the number of times a character or phrase. for this regular expressions require the //g switch an example 

$regex(test,/t/g)
this returns the number 2 as the letter 't' appears 2 times in the given string. you can search for a full word to appear in a string as long as text appears between the //g operators 
$regex(I ran a test of the test,/test/g)
this will return 2 as the phrase test appears 2 times in the given string.
{n,n} : length pattern matching
first a note of warning when using {n,n} with mIRC be aware that it see the ,n as a comma dividing the code into the next section. For this its recommend that you set a %variable and run the code 
$regex(abbbb,ab{2}) : returns 1
$regex(abbbb,ab{4}) : returns 1
now this looks at the string and says, is there at least 1 'a', and is it followed by b who is repeated 2 or more times. You can combine the it to check for the length to be within a given range with the {2,4} 
set %reg ab{2,4}
$regex(abbbb,%reg)
will return 1 as the string finds an a least 1 'a', followed by a B which appears between 2 to 4 times
Some Examples:
Matching correct format for a channel name : before you would have to run three looks at the string to determine if it was in the correct format. Now we can look at it once and determine it 
alias eval_chan_name {
  if($regex($1,^(#|\+|&))) { echo -a Validated }
  else { echo -a Invalid }
}
the expression ^(#|\+|&) means we want the first character to be a #, or + or &

Matching the validity of an email address : This allows you to ensure that the email address is in the format of letters and numbers, with a @ and . in it 

alias eval_email {
  var %reg ^[_\.0-9a-zA-Z]+@([0-9a-zA-Z][0-9a-zA-Z]+\.)+[a-zA-Z]{2,3}$
  echo -a $regex($1,%reg)
}
the expression ^[_\.0-9a-zA-Z]+@([0-9a-zA-Z][0-9a-zA-Z]+\.)+[a-zA-Z]{2,3}$ means that at the start of the string there must be a series of characters which can be _ . numbers from 0 to 9 and letters from a to z and A-Z and that this patter must be one or more characters. followed by a @, followed by a series of characters that forms the providers name. Again this pattern must be one or more characters. Finally we look at the .com part, and we say it must be between 2 to 3 characters and between the letters a-z which must end the string

Well that's it for my first tutorial, and this does not even scratch the surface of regular expressions, there are tons of more, so some recommended reading would be

http://www.perl.com/CPAN-local/doc/manual/html/pod/perlre.html
http://www.cs.utah.edu/dept/old/texinfo/regex/regex_toc.html

All content is copyright by mircscripts.org and cannot be used without permission. For more details, click here.