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):

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

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
capturedReturn one of the captured (parenthesized) expressions.
capturedCountReturn the count of captured (parenthesized) expressions.
compareChecks if a given strings can be matched by this expression.
findFinds a range matching this regular expression in a string.
findAllFind all ranges where this regular expression can mach the string.
findAllOverlappedFind all ranges where this regular expression can mach the string, with possibly overlapped matches.
grabReturns the part of a target string matched by this regular expression.
matchMatches this regular expression against a string.
replaceReplace a substring matching this regular expression with another string.
replaceAllReplaces all the possible matches of this regular expression in a target with a given string.
splitSplits a string at match points.
studyStudy the pattern after compilation.
substReplaces all the matches expanding placeholders.
versionReturns 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.
ReturnA 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()
ReturnCount 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.
Return0 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.
ReturnA 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 .
ReturnA 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 .
ReturnA 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.
ReturnThe 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.
ReturnTrue 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.
ReturnThe 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.
ReturnThe 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.
ReturnAn 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.
ReturnThe 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()
ReturnA 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.

Made with http://www.falconpl.org