2.11.1Class Regex

Regular expression binding encapsulation.

Class Regex( pattern, [options] )

pattern	The regular expression pattern to be compiled.
options	Pattern compilation options.
Raise	RegexError if the pattern is invalid.

The class constructor creates a Regex instance that can be then used to match, find, extract and substitute strings. Compilation of regular expressions can be an heavy step, so it's better to do it once and for all. In a program using repeatedly a set of well defined patterns, an option worth being considered is that of creating object instances that will have the VM to compile the pattern in the link step:

   load regex

   object bigPattern from Regex( "A pattern (.*) to be compiled" )
      // we may eventually consider also a study step in init
      init
         self.study()
      end
   end

   //...
   if bigPattern.match( "a string" )
      ...
   end

In case of regular expression pattern error, a RegexError instance will be raised. The option parameter can be provided to pass pattern compilation options to the constructor. It generally follows the PERL regular expression parameter specification, so that:

   PERL: /a pattern/i
   Falcon: Regex( "a pattern", "i" )

The recognized options are (case sensitive):

• a: anchored pattern. Usually, if only part of a pattern matches, a new search is attempted in the rest of the string. When this option is set, the pattern must either match completely or be rejected as the first match begins. So, the pattern "abc" will usually match "abdabc" starting from character 3, but if anchored option is set it won't match, as "abc" will start to match at the beginning of string, but then will fail when "d" is met.
• i: ignore case while matching. Case ignoring is currently supported only for Unicode characters below 128; this means that accented latin case ignoring is not supported. For example, "è" and "È" won't match even if "i" option is set.
• m: multiline match. Usually, the special characters "^" and "$" matches respectively the begin and the end of the string, so that "^pattern$" will match only "pattern", and not "this is a pattern". With "m" option, "^" and "$" matches the begin and the end of a line, being lines separated by Falcon newline characters ("n").

- s: dot match all. Usually, the line separator "n" is not captured in wide parenthesized expressions as (.*), and the generic "any character" wildcard (the dot ".") doesn't matches it. With "s" option, "n" is considered as a normal character and included in matches (although this doesn't alter the behavior of "^" and "$" which are controlled by the "m" option).

• f: first line. Match must start before or at the first "n", or else it will fail.
• g: ungreedy match. Repetition patterns behave normally in a way that is defined "greedy", unless followed by a question mark. Greedy matching will force quantifiers to match as many characters as possible in the target string. For example, normally 'field:s*(.*);', if applied to a string with two ";" after "field" will return the longest possible match. If applied to "field: a; b; c; and the rest" would return "a; b; c" as first submatch. Using a question mark would force to match the shortest alternative: 'field:s*(.*?);' would return only "a" as first submatch. The "g" option inverts this behavior, so that repetition quantifiers are ungreedy by default, and "?" will make them greedy.
• S: study the pattern. Tells Regex constructor to perform also a study step after compilation. According to PCRE documentation, this has currently little utility except for some very complex pattern involving recursive searches.

In case of error in compilation of the pattern (or eventually in the study step, if required), the constructor will raise an error of class RegexError.

Methods
captured	Return one of the captured (parenthesized) expressions.
capturedCount	Return the count of captured (parenthesized) expressions.
compare	Checks if a given strings can be matched by this expression.
find	Finds a range matching this regular expression in a string.
findAll	Find all ranges where this regular expression can mach the string.
findAllOverlapped	Find all ranges where this regular expression can mach the string, with possibly overlapped matches.
grab	Returns the part of a target string matched by this regular expression.
match	Matches this regular expression against a string.
replace	Replace a substring matching this regular expression with another string.
replaceAll	Replaces all the possible matches of this regular expression in a target with a given string.
split	Splits a string at match points.
study	Study the pattern after compilation.
subst	Replaces all the matches expanding placeholders.
version	Returns the PCRE version used by this binding.

Methods

captured

Return one of the captured (parenthesized) expressions.

Regex.captured( count )

count	Id of the captured substring, starting from 1; 0 represents all the matched string.
Return	A range defining a captured match.

This method returns one of the match ranges that has been determined by the last match, find or replace operation. If 0 is passed as count parameter, the whole match range is returned; each parenthesized expression match range can be retrieved passing 1 or above as count parameter. The order of parenthesized expression is given considering the first parenthesis. The returned value is a closed range describing the area where the capture had effect in the target string.

capturedCount

Return the count of captured (parenthesized) expressions.

Regex.capturedCount()

Return

Count of captured subranges.

This method returns available number of captured ranges after a successful match. This number is the amount of parenthesized expressions in the regular expression plus one.

See also: Regex.

compare

Checks if a given strings can be matched by this expression.

Regex.compare( string )

string	A string.
Return	0 if the string is matched by the regex pattern.

This method overloads the BOM compare method, so that this Regex instance can be used in direct comparations. Switch tests and equality tests will succeed if the pattern matches agains the given string.

find

Finds a range matching this regular expression in a string.

Regex.find( string, [start] )

string	A string in which the pattern has to be found.
start	An optional starting point in the string.
Return	A range where the pattern matches, or nil.

This function works as the method match(), but on success it immediately returns the range containing the area in the string parameter where the pattern has matched. Also, this function can be provided with an optional start parameter that can be used to begin the search for the pattern from an arbitrary point in the string.

Finds the first occourence of the pattern in the string. The returned ranged may be applied to the string in order to extract the desired substring.

If the pattern doesn't matches, returns nil.

findAll

Find all ranges where this regular expression can mach the string.

Regex.findAll( string, [start],[maxcount] )

string	String where to scan for the pattern.
start	Optional start position in the string.
maxcount	Optional maximum matches allowed .
Return	A vector of ranges where the pattern matches, or nil.

This function returns an array containing all the ranges where the pattern has matched; if the pattern could not match the string, an empty array is returned.

This method only returns the whole match, ignoring parenthesized expressions.

findAllOverlapped

Find all ranges where this regular expression can mach the string, with possibly overlapped matches.

Regex.findAllOverlapped( string, [start],[maxcount] )

string	String where to scan for the pattern.
start	Optional start position in the string.
maxcount	Optional maximum matches allowed .
Return	A vector of ranges where the pattern matches, or nil.

This function returns an array containing all the ranges where the pattern has matched; if the pattern could not match the string, an empty array is returned.

This method only returns the whole match, ignoring parenthesized expressions.

grab

Returns the part of a target string matched by this regular expression.

Regex.grab( string )

string	String where to scan for the pattern.
Return	The matching substring, or nil if the pattern doesn't match the string.

Searches for the pattern and stores all the captured subexpressions in an array that is then returned. If the match is negative, returns nil.

match

Matches this regular expression against a string.

Regex.match( string )

string	String where to scan for the pattern.
Return	True if the string is matched by the pattern, false otherwise.

This method searches for the pattern in the string given as parameter. If the match is successful, the method returns true. The match point can then be retrieved using the captured(0) method.

replace

Replace a substring matching this regular expression with another string.

Regex.replace( string, replacer, [start] )

string	String where to scan for the pattern.
replacer	The string to replace the matched pattern with.
start	Optional initial scan position.
Return	The string with the matching content replaced.

This method scans for the pattern in string, and if it's found, it is replaced with the string in the replacer parameter. The original string is untouched, and a new copy with the replaced value is returned. If the pattern can't match string, nil is returned. An optional start parameter can be given to begin the search for the pattern in string from a given position.

replaceAll

Replaces all the possible matches of this regular expression in a target with a given string.

Regex.replaceAll( string, replacer )

string	String where to scan for the pattern.
replacer	The string to replace the matched pattern with.
Return	The string with the matching content replaced, or nil if no change is perfomed.

This method replaces all the occurrences of the pattern in string with the replacer parameter. If a change can be performed, a modified instance of string is returned, else nil is returned.

split

Splits a string at match points.

Regex.split( string, [count],[getoken] )

string	The string to be split.
count	Maximum number of split instances.
getoken	Return also the found token.
Return	An array containing the string slices, or nil.

If the pattern matches the string, the part before the match is isolated. The operation is iteratively performed until the match can't be found anymore; at that point, the last string is returned.

If gettoken parameter is given and true, the found match is inserted between the isolated strings.

If count is given, a maximum number of matches is performed, then the array of split entities is returned. Notice that the this doesn't count tokens returned if the gettoken option is specified.

If the pattern doesn't matches, this method returns nil.

study

Study the pattern after compilation.

Regex.study()

It perform an extra compilation step; PCRE 7.6 manual suggests that this is useful only with recursive pattern.

subst

Replaces all the matches expanding placeholders.

Regex.subst( string, replacer )

string	String where to scan for the pattern.
replacer	The string to replace the matched pattern with.
Return	The string with the matching content replaced, or nil if no change is perfomed.

This method works exacly like Regex.replaceAll, but it expands backslash placeholders with captured expressions. Each captured expression can be addressed via standard substitution backslashes (0 is the whole expression, 1 is the first captured expression, 2 the second and so on).

   load regex
   
   r = Regex("a([0-9]+)b")
   > r.subst( 'a100b', 'Number was \1.' )

Note: Remember to use double backslash on double quoted strings.

version

Returns the PCRE version used by this binding.

Regex.version()

Return

A string containing a descriptive PCRE version message.

This function can be used to retreive the PCRE version that is currently used by the REGEX module.