<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html
PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" >
<head><meta content="text/html;charset=&quot;utf-8&quot;" http-equiv="Content-type"/><link href="faldoc.css" rel="stylesheet" type="text/css"/><title> - Class Regex</title></head><body class="faldoc"><ul class="navi_top"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="feathers_regex.html">Up: Regular Expression</a></li>
<li class="prev"><a href="feathers_regex.html">Previous: Regular Expression</a></li>
<li class="next"><a href="feathers_regex_RegexError.html">Next: Class RegexError</a></li>
<li class="clear"></li>
</ul><div id="page_body"><h1><span class="toc_number">2.11.1</span>Class Regex</h1><p class="brief">Regular expression binding encapsulation. </p>
<pre class="prototype">Class Regex( pattern, [options] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">pattern</td><td class="content"> The regular expression pattern to be compiled. </td></tr>
<tr class="optparam"><td class="name">options</td><td class="content"> Pattern compilation options. </td></tr>
<tr class="raise"><td class="name">Raise</td><td class="content"><table>
<tbody><tr><td class="name"><a href="feathers_regex_RegexError.html">RegexError</a></td><td class="content"> if the pattern is invalid. </td></tr>
</tbody>
</table>
</td></tr>
</tbody>
</table>
<p>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: </p>
<pre>
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
</pre><p>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: </p>
<pre>
PERL: /a pattern/i
Falcon: Regex( "a pattern", "i" )
</pre><p>The recognized options are (case sensitive): <ul><li><b>a</b>: 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. </li><li><b>i</b>: 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. </li><li><b>m</b>: 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"). </li></ul></p>
<p>- <b>s</b>: 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). <ul><li><b>f</b>: first line. Match must start before or at the first "n", or else it will fail. </li><li><b>g</b>: 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. </li><li><b>S</b>: 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. </li></ul></p>
<p>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 <a href="feathers_regex_RegexError.html">RegexError</a>. </p>
<table class="members">
<tbody><tr class="member_type"><td class="member_type" colspan="2">Methods</td></tr>
<tr><td><a href="#captured">captured</a></td><td>Return one of the captured (parenthesized) expressions. </td></tr>
<tr><td><a href="#capturedCount">capturedCount</a></td><td>Return the count of captured (parenthesized) expressions. </td></tr>
<tr><td><a href="#compare">compare</a></td><td>Checks if a given strings can be matched by this expression. </td></tr>
<tr><td><a href="#find">find</a></td><td>Finds a range matching this regular expression in a string. </td></tr>
<tr><td><a href="#findAll">findAll</a></td><td>Find all ranges where this regular expression can mach the string. </td></tr>
<tr><td><a href="#findAllOverlapped">findAllOverlapped</a></td><td>Find all ranges where this regular expression can mach the string, with possibly overlapped matches. </td></tr>
<tr><td><a href="#grab">grab</a></td><td>Returns the part of a target string matched by this regular expression. </td></tr>
<tr><td><a href="#match">match</a></td><td>Matches this regular expression against a string. </td></tr>
<tr><td><a href="#replace">replace</a></td><td>Replace a substring matching this regular expression with another string. </td></tr>
<tr><td><a href="#replaceAll">replaceAll</a></td><td>Replaces all the possible matches of this regular expression in a target with a given string. </td></tr>
<tr><td><a href="#split">split</a></td><td>Splits a string at match points. </td></tr>
<tr><td><a href="#study">study</a></td><td>Study the pattern after compilation. </td></tr>
<tr><td><a href="#subst">subst</a></td><td>Replaces all the matches expanding placeholders. </td></tr>
<tr><td><a href="#version">version</a></td><td>Returns the PCRE version used by this binding. </td></tr>
</tbody>
</table>
<h2>Methods</h2><h3><a name="captured">captured</a></h3><p class="brief">Return one of the captured (parenthesized) expressions. </p>
<pre class="prototype">Regex.captured( count )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">count</td><td class="content"> Id of the captured substring, starting from 1; 0 represents all the matched string. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">A range defining a captured match. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="capturedCount">capturedCount</a></h3><p class="brief">Return the count of captured (parenthesized) expressions. </p>
<pre class="prototype">Regex.capturedCount()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">Count of captured subranges. </td></tr>
</tbody>
</table>
<p>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. </p>
<p class="see_also">See also: <a href="feathers_regex_Regex.html">Regex</a>.</p>
<h3><a name="compare">compare</a></h3><p class="brief">Checks if a given strings can be matched by this expression. </p>
<pre class="prototype">Regex.compare( string )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> A string. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">0 if the string is matched by the regex pattern. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="find">find</a></h3><p class="brief">Finds a range matching this regular expression in a string. </p>
<pre class="prototype">Regex.find( string, [start] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> A string in which the pattern has to be found. </td></tr>
<tr class="optparam"><td class="name">start</td><td class="content"> An optional starting point in the string. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">A range where the pattern matches, or nil. </td></tr>
</tbody>
</table>
<p>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. </p>
<p>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. </p>
<p>If the pattern doesn't matches, returns nil. </p>
<h3><a name="findAll">findAll</a></h3><p class="brief">Find all ranges where this regular expression can mach the string. </p>
<pre class="prototype">Regex.findAll( string, [start],[maxcount] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="optparam"><td class="name">start</td><td class="content"> Optional start position in the string. </td></tr>
<tr class="optparam"><td class="name">maxcount</td><td class="content"> Optional maximum matches allowed . </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">A vector of ranges where the pattern matches, or nil. </td></tr>
</tbody>
</table>
<p>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. </p>
<p>This method only returns the whole match, ignoring parenthesized expressions. </p>
<h3><a name="findAllOverlapped">findAllOverlapped</a></h3><p class="brief">Find all ranges where this regular expression can mach the string, with possibly overlapped matches. </p>
<pre class="prototype">Regex.findAllOverlapped( string, [start],[maxcount] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="optparam"><td class="name">start</td><td class="content"> Optional start position in the string. </td></tr>
<tr class="optparam"><td class="name">maxcount</td><td class="content"> Optional maximum matches allowed . </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">A vector of ranges where the pattern matches, or nil. </td></tr>
</tbody>
</table>
<p>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. </p>
<p>This method only returns the whole match, ignoring parenthesized expressions. </p>
<h3><a name="grab">grab</a></h3><p class="brief">Returns the part of a target string matched by this regular expression. </p>
<pre class="prototype">Regex.grab( string )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The matching substring, or nil if the pattern doesn't match the string. </td></tr>
</tbody>
</table>
<p>Searches for the pattern and stores all the captured subexpressions in an array that is then returned. If the match is negative, returns nil. </p>
<h3><a name="match">match</a></h3><p class="brief">Matches this regular expression against a string. </p>
<pre class="prototype">Regex.match( string )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">True if the string is matched by the pattern, false otherwise. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="replace">replace</a></h3><p class="brief">Replace a substring matching this regular expression with another string. </p>
<pre class="prototype">Regex.replace( string, replacer, [start] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="param"><td class="name">replacer</td><td class="content"> The string to replace the matched pattern with. </td></tr>
<tr class="optparam"><td class="name">start</td><td class="content"> Optional initial scan position. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The string with the matching content replaced. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="replaceAll">replaceAll</a></h3><p class="brief">Replaces all the possible matches of this regular expression in a target with a given string. </p>
<pre class="prototype">Regex.replaceAll( string, replacer )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="param"><td class="name">replacer</td><td class="content"> The string to replace the matched pattern with. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The string with the matching content replaced, or nil if no change is perfomed. </td></tr>
</tbody>
</table>
<p>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. </p>
<h3><a name="split">split</a></h3><p class="brief">Splits a string at match points. </p>
<pre class="prototype">Regex.split( string, [count],[getoken] )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> The string to be split. </td></tr>
<tr class="optparam"><td class="name">count</td><td class="content"> Maximum number of split instances. </td></tr>
<tr class="optparam"><td class="name">getoken</td><td class="content"> Return also the found token. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">An array containing the string slices, or nil. </td></tr>
</tbody>
</table>
<p>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. </p>
<p>If <b>gettoken</b> parameter is given and true, the found match is inserted between the isolated strings. </p>
<p>If <b>count</b> 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 <b>gettoken</b> option is specified. </p>
<p>If the pattern doesn't matches, this method returns nil. </p>
<h3><a name="study">study</a></h3><p class="brief">Study the pattern after compilation. </p>
<pre class="prototype">Regex.study()</pre>
<p>It perform an extra compilation step; PCRE 7.6 manual suggests that this is useful only with recursive pattern. </p>
<h3><a name="subst">subst</a></h3><p class="brief">Replaces all the matches expanding placeholders. </p>
<pre class="prototype">Regex.subst( string, replacer )</pre>
<table class="prototype">
<tbody><tr class="param"><td class="name">string</td><td class="content"> String where to scan for the pattern. </td></tr>
<tr class="param"><td class="name">replacer</td><td class="content"> The string to replace the matched pattern with. </td></tr>
<tr class="return"><td class="name">Return</td><td class="content">The string with the matching content replaced, or nil if no change is perfomed. </td></tr>
</tbody>
</table>
<p>This method works exacly like <a href="feathers_regex_Regex.html#replaceAll">Regex.replaceAll</a>, 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). </p>
<pre>
load regex
r = Regex("a([0-9]+)b")
> r.subst( 'a100b', 'Number was \1.' )
</pre><p class='note'><b>Note:</b> Remember to use double backslash on double quoted strings. </p>
<h3><a name="version">version</a></h3><p class="brief">Returns the PCRE version used by this binding. </p>
<pre class="prototype">Regex.version()</pre>
<table class="prototype">
<tbody><tr class="return"><td class="name">Return</td><td class="content">A string containing a descriptive PCRE version message. </td></tr>
</tbody>
</table>
<p>This function can be used to retreive the PCRE version that is currently used by the REGEX module. </p>
</div><ul class="navi_bottom"><li class="top"><a href="index.html">Top: Table of contents</a></li>
<li class="up"><a href="feathers_regex.html">Up: Regular Expression</a></li>
<li class="prev"><a href="feathers_regex.html">Previous: Regular Expression</a></li>
<li class="next"><a href="feathers_regex_RegexError.html">Next: Class RegexError</a></li>
<li class="clear"></li>
</ul><div class="signature">Made with <a href="faldoc 3.0">http://www.falconpl.org</a></div></body></html>
