Main index  |  Module description  |  Classes

ClassRegex

class Regex( pattern, [options] )

Regular expression binding encapsulation.


Member list

Constructor
init Compiles the regular expression patterns and initializes the instance.
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.
study Study the pattern after compilation.
version Returns the PCRE version used by this binding.

Class methods

init()

Compiles the regular expression patterns and initializes the instance.

Regex.init( pattern, [options] )
pattern

The regular expression pattern to be compiled.

options

Pattern compilation options.

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

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.

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.

Returns:

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

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

compare()

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

Regex.compare( string )
string

A string.

Returns:

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.

Returns:

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 .

Returns:

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 .

Returns:

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.

Returns:

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.

Returns:

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.

Returns:

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, [start], [maxCount] )
string

String where to scan for the pattern.

replacer

The string to replace the matched pattern with.

start

Optional initial scan position.

maxCount

optional maximum replacements.

Returns:

The string with the matching content replaced.

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. An if an optional start parameter is given, the search and replacement is performed beginning at the given point, and if a maxCount is given, only maxCount replacements, at maximum, will be performed.

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.

version()

Returns the PCRE version used by this binding.

Regex.version( )
Returns:

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.


Main index  |  Module description  |  Classes
Made with Faldoc 1.0.0