many changes -- see Changelog

author: shmuz <shmuz> 2007-04-19 07:02:33 +0000
committer: shmuz <shmuz> 2007-04-19 07:02:33 +0000
commit: 0ff6b1ed54f366b76dc74be466ead118c94e3ab4 (patch)
tree: 9a2338a7a7dea8b259ce8a447b293aa7d317c065 /doc
parent: 63cdc5a4fa6b6f11f782c40995779a2a3af6db98 (diff)
download: lrexlib-0ff6b1ed54f366b76dc74be466ead118c94e3ab4.tar.gz
3 files changed, 473 insertions, 313 deletions
diff --git a/doc/index.html b/doc/index.html
index 299032b..342e9ec 100755
--- a/doc/index.html
+++ b/doc/index.html
@@ -4,12 +4,12 @@
 <head>
 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
 <meta name="generator" content="Docutils 0.5: http://docutils.sourceforge.net/" />
-<title>Lrexlib 2.1</title>
+<title>Lrexlib 2.2</title>
 <link rel="stylesheet" href="lrexlib.css" type="text/css" />
 </head>
 <body>
-<div class="document" id="lrexlib-2-1">
-<h1 class="title">Lrexlib 2.1</h1>
+<div class="document" id="lrexlib-2-2">
+<h1 class="title">Lrexlib 2.2</h1>
 
 <div class="line-block">
 <div class="line">by Reuben Thomas (<a class="reference" href="mailto:rrt&#64;sc3d.org">rrt&#64;sc3d.org</a>)</div>
@@ -39,7 +39,7 @@ Gammon for adding support for PCRE named subpatterns.</p>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-02-13 15:21 UTC.
+Generated on: 2007-04-19 07:44 UTC.
 
 </div>
 </body>
diff --git a/doc/manual.html b/doc/manual.html
index 3fbd173..e360da5 100755
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -16,26 +16,31 @@
 <ul class="simple">
 <li><a class="reference" href="#introduction" id="id1" name="id1">Introduction</a></li>
 <li><a class="reference" href="#notes" id="id2" name="id2">Notes</a></li>
-<li><a class="reference" href="#lrexlib-functions" id="id3" name="id3">Lrexlib Functions</a><ul>
+<li><a class="reference" href="#common-pcre-and-posix-functions-and-methods" id="id3" name="id3">Common (PCRE and POSIX) functions and methods</a><ul>
 <li><a class="reference" href="#match" id="id4" name="id4">match</a></li>
 <li><a class="reference" href="#find" id="id5" name="id5">find</a></li>
 <li><a class="reference" href="#gmatch" id="id6" name="id6">gmatch</a></li>
 <li><a class="reference" href="#gsub" id="id7" name="id7">gsub</a></li>
 <li><a class="reference" href="#split" id="id8" name="id8">split</a></li>
-<li><a class="reference" href="#plainfind" id="id9" name="id9">plainfind</a></li>
+<li><a class="reference" href="#flags" id="id9" name="id9">flags</a></li>
 <li><a class="reference" href="#new" id="id10" name="id10">new</a></li>
-<li><a class="reference" href="#flags" id="id11" name="id11">flags</a></li>
-<li><a class="reference" href="#config" id="id12" name="id12">config</a></li>
-<li><a class="reference" href="#version" id="id13" name="id13">version</a></li>
+<li><a class="reference" href="#tfind" id="id11" name="id11">tfind</a></li>
+<li><a class="reference" href="#exec" id="id12" name="id12">exec</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#lrexlib-methods" id="id14" name="id14">Lrexlib Methods</a><ul>
-<li><a class="reference" href="#tfind" id="id15" name="id15">tfind</a></li>
-<li><a class="reference" href="#exec" id="id16" name="id16">exec</a></li>
-<li><a class="reference" href="#dfa-exec" id="id17" name="id17">dfa_exec</a></li>
+<li><a class="reference" href="#pcre-only-functions-and-methods" id="id13" name="id13">PCRE-only functions and methods</a><ul>
+<li><a class="reference" href="#maketables" id="id14" name="id14">maketables</a></li>
+<li><a class="reference" href="#settables" id="id15" name="id15">settables</a></li>
+<li><a class="reference" href="#config" id="id16" name="id16">config</a></li>
+<li><a class="reference" href="#version" id="id17" name="id17">version</a></li>
+<li><a class="reference" href="#dfa-exec" id="id18" name="id18">dfa_exec</a></li>
 </ul>
 </li>
-<li><a class="reference" href="#incompatibilities-with-the-previous-versions" id="id18" name="id18">Incompatibilities with the Previous Versions</a></li>
+<li><a class="reference" href="#other-functions" id="id19" name="id19">Other functions</a><ul>
+<li><a class="reference" href="#plainfind" id="id20" name="id20">plainfind</a></li>
+</ul>
+</li>
+<li><a class="reference" href="#incompatibilities-with-the-previous-versions" id="id21" name="id21">Incompatibilities with the Previous Versions</a></li>
 </ul>
 </div>
 <hr class="docutils" />
@@ -97,10 +102,22 @@ e.g. Spencer's.</li>
 </blockquote>
 </li>
 </ol>
+<ol class="arabic" id="locale" start="7">
+<li><p class="first">Parameter <em>locale</em> (<em>lo</em>) can be either a string (e.g., &quot;French_France.1252&quot;),
+or a userdata obtained from a call to <a class="reference" href="#maketables">maketables</a>. The default value that
+Lrexlib uses when the parameter is not supplied or <tt class="docutils literal"><span class="pre">nil</span></tt>, is:</p>
+<blockquote>
+<ul class="simple">
+<li>the built-in PCRE set of character tables - when Lrexlib is loaded.</li>
+<li>determined by the last call to <a class="reference" href="#settables">settables</a>.</li>
+</ul>
+</blockquote>
+</li>
+</ol>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h2><a class="toc-backref" href="#id3" id="lrexlib-functions" name="lrexlib-functions">Lrexlib Functions</a></h2>
+<h2><a class="toc-backref" href="#id3" id="common-pcre-and-posix-functions-and-methods" name="common-pcre-and-posix-functions-and-methods">Common (PCRE and POSIX) functions and methods</a></h2>
 <div class="section">
 <h3><a class="toc-backref" href="#id4" id="match" name="match">match</a></h3>
 <p><tt class="funcdef docutils literal"><span class="pre">rex.match</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[cf],</span> <span class="pre">[ef],</span> <span class="pre">[lo])</span></tt></p>
@@ -151,8 +168,10 @@ e.g. Spencer's.</li>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string
+or
+userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -224,8 +243,10 @@ substring is returned.</li>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string
+or
+userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -259,9 +280,9 @@ the string <em>subj</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="15%" />
-<col width="53%" />
-<col width="10%" />
-<col width="22%" />
+<col width="51%" />
+<col width="13%" />
+<col width="21%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Parameter</th>
@@ -293,8 +314,10 @@ the string <em>subj</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string
+or
+userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -361,8 +384,8 @@ for, or control function, or nil</td>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string or userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -486,9 +509,9 @@ the string <em>subj</em>, subject to flags <em>cf</em> and <em>ef</em>.</p>
 <table border="1" class="docutils">
 <colgroup>
 <col width="15%" />
-<col width="53%" />
-<col width="10%" />
-<col width="22%" />
+<col width="51%" />
+<col width="13%" />
+<col width="21%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Parameter</th>
@@ -521,8 +544,10 @@ pattern)</td>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string
+or
+userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -543,24 +568,24 @@ subject.</p>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id9" id="plainfind" name="plainfind">plainfind</a></h3>
-<p><tt class="funcdef docutils literal"><span class="pre">rex.plainfind</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[ci])</span></tt></p>
-<p>The function searches for the first match of the string <em>patt</em> in the subject
-<em>subj</em>, starting from offset <em>init</em>.</p>
+<h3><a class="toc-backref" href="#id9" id="flags" name="flags">flags</a></h3>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.flags</span> <span class="pre">([tb])</span></tt></p>
+<p>This function returns a table containing numeric values of the constants defined
+by the used regex library (either PCRE or POSIX). Those constants are keyed by
+their names (strings). If the table argument <em>tb</em> is supplied then it is used as
+the output table, else a new table is created.</p>
+<p>The constants contained in the returned table can then be used in most functions
+and methods where <em>compilation flags</em> or <em>execution flags</em> can be specified.
+They can also be used for comparing with return codes of some functions and
+methods for determining the reason of failure. For details, see <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> and <a class="reference" href="http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">POSIX</a>
+documentation.</p>
 <blockquote>
-<ul class="simple">
-<li>The string <em>patt</em> is not regular expression, all its characters stand for
-themselves.</li>
-<li>Both strings <em>subj</em> and <em>patt</em> can have embedded zeros.</li>
-<li>The flag <em>ci</em> specifies case-insensitive search (current locale is used).</li>
-<li>This function uses neither PCRE nor POSIX regex library.</li>
-</ul>
 <table border="1" class="docutils">
 <colgroup>
-<col width="16%" />
-<col width="47%" />
-<col width="14%" />
-<col width="23%" />
+<col width="15%" />
+<col width="52%" />
+<col width="13%" />
+<col width="21%" />
 </colgroup>
 <thead valign="bottom">
 <tr><th class="head">Parameter</th>
@@ -570,40 +595,18 @@ themselves.</li>
 </tr>
 </thead>
 <tbody valign="top">
-<tr><td>subj</td>
-<td>subject</td>
-<td>string</td>
-<td>n/a</td>
-</tr>
-<tr><td>patt</td>
-<td>text to find</td>
-<td>string</td>
-<td>n/a</td>
-</tr>
-<tr><td>[init]</td>
-<td>start offset in the subject
-(can be negative)</td>
-<td>number</td>
-<td>1</td>
-</tr>
-<tr><td>[ci]</td>
-<td>case insensitive search</td>
-<td>boolean</td>
-<td><tt class="docutils literal"><span class="pre">false</span></tt></td>
+<tr><td>[tb]</td>
+<td>a table for placing results into</td>
+<td>table</td>
+<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
 </tr>
 </tbody>
 </table>
 </blockquote>
 <dl class="docutils">
-<dt><strong>Returns on success:</strong></dt>
-<dd><ol class="first last arabic simple">
-<li>The start point of the match (a number).</li>
-<li>The end point of the match (a number).</li>
-</ol>
-</dd>
-<dt><strong>Returns on failure:</strong></dt>
+<dt><strong>Returns:</strong></dt>
 <dd><ol class="first last arabic simple">
-<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
+<li>A table filled with the results.</li>
 </ol>
 </dd>
 </dl>
@@ -646,8 +649,10 @@ collected.</p>
 </tr>
 <tr><td>[lo]</td>
 <td>[PCRE] locale</td>
-<td>string</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+<td>string
+or
+userdata</td>
+<td><a class="reference" href="#locale">locale</a></td>
 </tr>
 </tbody>
 </table>
@@ -662,104 +667,7 @@ collected.</p>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id11" id="flags" name="flags">flags</a></h3>
-<p><tt class="funcdef docutils literal"><span class="pre">rex.flags</span> <span class="pre">([tb])</span></tt></p>
-<p>This function returns a table containing numeric values of the constants defined
-by the used regex library (either PCRE or POSIX). Those constants are keyed by
-their names (strings). If the table argument <em>tb</em> is supplied then it is used as
-the output table, else a new table is created.</p>
-<p>The constants contained in the returned table can then be used in most functions
-and methods where <em>compilation flags</em> or <em>execution flags</em> can be specified.
-They can also be used for comparing with return codes of some functions and
-methods for determining the reason of failure. For details, see <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> and <a class="reference" href="http://www.opengroup.org/onlinepubs/009695399/basedefs/xbd_chap09.html">POSIX</a>
-documentation.</p>
-<blockquote>
-<table border="1" class="docutils">
-<colgroup>
-<col width="15%" />
-<col width="52%" />
-<col width="13%" />
-<col width="21%" />
-</colgroup>
-<thead valign="bottom">
-<tr><th class="head">Parameter</th>
-<th class="head">Description</th>
-<th class="head">Type</th>
-<th class="head">Default Value</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr><td>[tb]</td>
-<td>a table for placing results into</td>
-<td>table</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
-</tr>
-</tbody>
-</table>
-</blockquote>
-<dl class="docutils">
-<dt><strong>Returns:</strong></dt>
-<dd><ol class="first last arabic simple">
-<li>A table filled with the results.</li>
-</ol>
-</dd>
-</dl>
-</div>
-<hr class="docutils" />
-<div class="section">
-<h3><a class="toc-backref" href="#id12" id="config" name="config">config</a></h3>
-<p>[PCRE 4.0 and later. See <em>pcre_config</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
-<p><tt class="funcdef docutils literal"><span class="pre">rex.config</span> <span class="pre">([tb])</span></tt></p>
-<p>This function returns a table containing the values of the configuration
-parameters used at PCRE library build-time. Those parameters (numbers) are
-keyed by their names (strings). If the table argument <em>tb</em> is supplied then it
-is used as the output table, else a new table is created.</p>
-<blockquote>
-<table border="1" class="docutils">
-<colgroup>
-<col width="15%" />
-<col width="52%" />
-<col width="13%" />
-<col width="21%" />
-</colgroup>
-<thead valign="bottom">
-<tr><th class="head">Parameter</th>
-<th class="head">Description</th>
-<th class="head">Type</th>
-<th class="head">Default Value</th>
-</tr>
-</thead>
-<tbody valign="top">
-<tr><td>[tb]</td>
-<td>a table for placing results into</td>
-<td>table</td>
-<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
-</tr>
-</tbody>
-</table>
-</blockquote>
-<dl class="docutils">
-<dt><strong>Returns:</strong></dt>
-<dd><ol class="first last arabic simple">
-<li>A table filled with the results.</li>
-</ol>
-</dd>
-</dl>
-</div>
-<hr class="docutils" />
-<div class="section">
-<h3><a class="toc-backref" href="#id13" id="version" name="version">version</a></h3>
-<p>[PCRE only. See <em>pcre_version</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
-<p><tt class="funcdef docutils literal"><span class="pre">rex.version</span> <span class="pre">()</span></tt></p>
-<p>This function returns a string containing the version of the used PCRE library
-and its release date.</p>
-</div>
-</div>
-<hr class="docutils" />
-<div class="section">
-<h2><a class="toc-backref" href="#id14" id="lrexlib-methods" name="lrexlib-methods">Lrexlib Methods</a></h2>
-<div class="section">
-<h3><a class="toc-backref" href="#id15" id="tfind" name="tfind">tfind</a></h3>
+<h3><a class="toc-backref" href="#id11" id="tfind" name="tfind">tfind</a></h3>
 <p><tt class="funcdef docutils literal"><span class="pre">r:tfind</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef])</span></tt></p>
 <p>The method searches for the first match of the compiled regexp <em>r</em> in the
 string <em>subj</em>, starting from offset <em>init</em>, subject to execution flags <em>ef</em>.</p>
@@ -834,7 +742,7 @@ names (strings).</li>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id16" id="exec" name="exec">exec</a></h3>
+<h3><a class="toc-backref" href="#id12" id="exec" name="exec">exec</a></h3>
 <p><tt class="funcdef docutils literal"><span class="pre">r:exec</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef])</span></tt></p>
 <p>The method searches for the first match of the compiled regexp <em>r</em> in the
 string <em>subj</em>, starting from offset <em>init</em>, subject to execution flags <em>ef</em>.</p>
@@ -905,9 +813,114 @@ substring matches keyed by their correspondent subpattern names
 { 12,14,16,19 }.</dd>
 </dl>
 </div>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h2><a class="toc-backref" href="#id13" id="pcre-only-functions-and-methods" name="pcre-only-functions-and-methods">PCRE-only functions and methods</a></h2>
+<div class="section">
+<h3><a class="toc-backref" href="#id14" id="maketables" name="maketables">maketables</a></h3>
+<p>[PCRE only. See <em>pcre_maketables</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.maketables</span> <span class="pre">()</span></tt></p>
+<p>Creates a table set corresponding to the current active locale and returns it as
+a userdata. The returned value can be passed to the function <a class="reference" href="#settables">settables</a> and to
+any Lrexlib function accepting the <em>locale</em> parameter.</p>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h3><a class="toc-backref" href="#id15" id="settables" name="settables">settables</a></h3>
+<p>[PCRE only]</p>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.settables</span> <span class="pre">([tables])</span></tt></p>
+<p>This function replaces the default set of character tables, by the one supplied
+in the parameter <em>tables</em>.</p>
+<p>The <em>tables</em> parameter should be either a userdata, obtained from a call to
+<a class="reference" href="#maketables">maketables</a>, or <tt class="docutils literal"><span class="pre">nil</span></tt>. In the latter case, the built-in PCRE set of tables
+becomes the default.</p>
+<p>Lrexlib maintains one &quot;default&quot; set of character tables, in addition to the set
+built-in into PCRE. When a Lrexlib function accepting the <em>locale</em> argument is
+called with that argument omitted, then the default set of character tables is
+used.</p>
+<p>The initial default set of tables is the built-in PCRE set.</p>
+<blockquote>
+<table border="1" class="docutils">
+<colgroup>
+<col width="15%" />
+<col width="52%" />
+<col width="13%" />
+<col width="21%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">Parameter</th>
+<th class="head">Description</th>
+<th class="head">Type</th>
+<th class="head">Default Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>[tables]</td>
+<td>See the above description.</td>
+<td>userdata</td>
+<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+<dl class="docutils">
+<dt><strong>Returns:</strong></dt>
+<dd>The old value of the default set (<tt class="docutils literal"><span class="pre">nil</span></tt> for the built-in PCRE set).</dd>
+</dl>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h3><a class="toc-backref" href="#id16" id="config" name="config">config</a></h3>
+<p>[PCRE 4.0 and later. See <em>pcre_config</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.config</span> <span class="pre">([tb])</span></tt></p>
+<p>This function returns a table containing the values of the configuration
+parameters used at PCRE library build-time. Those parameters (numbers) are
+keyed by their names (strings). If the table argument <em>tb</em> is supplied then it
+is used as the output table, else a new table is created.</p>
+<blockquote>
+<table border="1" class="docutils">
+<colgroup>
+<col width="15%" />
+<col width="52%" />
+<col width="13%" />
+<col width="21%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">Parameter</th>
+<th class="head">Description</th>
+<th class="head">Type</th>
+<th class="head">Default Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>[tb]</td>
+<td>a table for placing results into</td>
+<td>table</td>
+<td><tt class="docutils literal"><span class="pre">nil</span></tt></td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+<dl class="docutils">
+<dt><strong>Returns:</strong></dt>
+<dd><ol class="first last arabic simple">
+<li>A table filled with the results.</li>
+</ol>
+</dd>
+</dl>
+</div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id17" id="dfa-exec" name="dfa-exec">dfa_exec</a></h3>
+<h3><a class="toc-backref" href="#id17" id="version" name="version">version</a></h3>
+<p>[PCRE only. See <em>pcre_version</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.version</span> <span class="pre">()</span></tt></p>
+<p>This function returns a string containing the version of the used PCRE library
+and its release date.</p>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h3><a class="toc-backref" href="#id18" id="dfa-exec" name="dfa-exec">dfa_exec</a></h3>
 <p>[PCRE 6.0 and later. See <em>pcre_dfa_exec</em> in the <a class="reference" href="http://www.pcre.org/pcre.txt">PCRE</a> docs.]</p>
 <p><tt class="funcdef docutils literal"><span class="pre">r:dfa_exec</span> <span class="pre">(subj,</span> <span class="pre">[init],</span> <span class="pre">[ef],</span> <span class="pre">[ovecsize],</span> <span class="pre">[wscount])</span></tt></p>
 <p>The method matches a compiled regular expression <em>r</em> against a given subject
@@ -985,8 +998,78 @@ and 25 then the function returns the following: 10, { 25,20,15 }, 3.</dd>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h2><a class="toc-backref" href="#id18" id="incompatibilities-with-the-previous-versions" name="incompatibilities-with-the-previous-versions">Incompatibilities with the Previous Versions</a></h2>
-<p><strong>Incompatibilities with the version 1.19:</strong></p>
+<h2><a class="toc-backref" href="#id19" id="other-functions" name="other-functions">Other functions</a></h2>
+<div class="section">
+<h3><a class="toc-backref" href="#id20" id="plainfind" name="plainfind">plainfind</a></h3>
+<p><tt class="funcdef docutils literal"><span class="pre">rex.plainfind</span> <span class="pre">(subj,</span> <span class="pre">patt,</span> <span class="pre">[init],</span> <span class="pre">[ci])</span></tt></p>
+<p>The function searches for the first match of the string <em>patt</em> in the subject
+<em>subj</em>, starting from offset <em>init</em>.</p>
+<blockquote>
+<ul class="simple">
+<li>The string <em>patt</em> is not regular expression, all its characters stand for
+themselves.</li>
+<li>Both strings <em>subj</em> and <em>patt</em> can have embedded zeros.</li>
+<li>The flag <em>ci</em> specifies case-insensitive search (current locale is used).</li>
+<li>This function uses neither PCRE nor POSIX regex library.</li>
+</ul>
+<table border="1" class="docutils">
+<colgroup>
+<col width="16%" />
+<col width="47%" />
+<col width="14%" />
+<col width="23%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head">Parameter</th>
+<th class="head">Description</th>
+<th class="head">Type</th>
+<th class="head">Default Value</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td>subj</td>
+<td>subject</td>
+<td>string</td>
+<td>n/a</td>
+</tr>
+<tr><td>patt</td>
+<td>text to find</td>
+<td>string</td>
+<td>n/a</td>
+</tr>
+<tr><td>[init]</td>
+<td>start offset in the subject
+(can be negative)</td>
+<td>number</td>
+<td>1</td>
+</tr>
+<tr><td>[ci]</td>
+<td>case insensitive search</td>
+<td>boolean</td>
+<td><tt class="docutils literal"><span class="pre">false</span></tt></td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+<dl class="docutils">
+<dt><strong>Returns on success:</strong></dt>
+<dd><ol class="first last arabic simple">
+<li>The start point of the match (a number).</li>
+<li>The end point of the match (a number).</li>
+</ol>
+</dd>
+<dt><strong>Returns on failure:</strong></dt>
+<dd><ol class="first last arabic simple">
+<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
+</ol>
+</dd>
+</dl>
+</div>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h2><a class="toc-backref" href="#id21" id="incompatibilities-with-the-previous-versions" name="incompatibilities-with-the-previous-versions">Incompatibilities with the Previous Versions</a></h2>
+<p><strong>Incompatibilities between the versions 2.0 and 1.19:</strong></p>
 <blockquote>
 <ol class="arabic simple">
 <li>Lua 5.1 is required</li>
@@ -996,11 +1079,12 @@ and 25 then the function returns the following: 10, { 25,20,15 }, 3.</dd>
 <li>Method <tt class="docutils literal"><span class="pre">match</span></tt> renamed to <a class="reference" href="#tfind">tfind</a></li>
 <li>Method <tt class="docutils literal"><span class="pre">gmatch</span></tt> removed (similar functionality is provided by function
 <a class="reference" href="#gmatch">gmatch</a>)</li>
-<li>Method <a class="reference" href="#exec">exec</a>: the returned table may additionally contain <em>named
-subpatterns</em> (PCRE only)</li>
+<li>Methods <a class="reference" href="#tfind">tfind</a> and <a class="reference" href="#exec">exec</a>: 2 values are returned on failure</li>
+<li>(PCRE) <a class="reference" href="#exec">exec</a>: the returned table may additionally contain <em>named
+subpatterns</em></li>
 </ol>
 </blockquote>
-<p><strong>Incompatibilities with the version 2.0:</strong></p>
+<p><strong>Incompatibilities between the versions 2.1 and 2.0:</strong></p>
 <blockquote>
 <ol class="arabic simple">
 <li><a class="reference" href="#match">match</a>, <a class="reference" href="#find">find</a>, <a class="reference" href="#tfind">tfind</a>, <a class="reference" href="#exec">exec</a>, <a class="reference" href="#dfa-exec">dfa_exec</a>: only one value (a <tt class="docutils literal"><span class="pre">nil</span></tt>) is
@@ -1008,17 +1092,20 @@ returned when the subject does not match the pattern. Any other failure
 generates an error.</li>
 </ol>
 </blockquote>
-<p><strong>Incompatibilities with the version 2.1:</strong></p>
+<p><strong>Incompatibilities between the versions 2.2 and 2.1:</strong></p>
 <blockquote>
 <ol class="arabic simple">
 <li><a class="reference" href="#gsub">gsub</a>: a special &quot;break&quot; return of <em>repl</em> function is deprecated.</li>
+<li>(PCRE) <a class="reference" href="#gsub">gsub</a>, <a class="reference" href="#gmatch">gmatch</a>: after finding an empty match at the current
+position, the functions try to find a non-empty match anchored to the same
+position.</li>
 </ol>
 </blockquote>
 </div>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-03-17 09:55 UTC.
+Generated on: 2007-04-17 16:16 UTC.
 
 </div>
 </body>
diff --git a/doc/manual.txt b/doc/manual.txt
index e9bca04..b833cf7 100755
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -65,10 +65,19 @@ Notes
      * REG_STARTEND for those POSIX regex libraries that support it,
        e.g. Spencer's.
 
+.. _locale:
+
+7. Parameter *locale* (*lo*) can be either a string (e.g., "French_France.1252"),
+   or a userdata obtained from a call to maketables_. The default value that
+   Lrexlib uses when the parameter is not supplied or ``nil``, is:
+
+     * the built-in PCRE set of character tables - when Lrexlib is loaded.
+     * determined by the last call to settables_.
+
 ------------------------------------------------------------
 
-Lrexlib Functions
-~~~~~~~~~~~~~~~~~
+Common (PCRE and POSIX) functions and methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 match
 -----
@@ -94,7 +103,9 @@ PCRE: A locale *lo* may be specified.
   +---------+-------------------------------+--------+-------------+
   |  [ef]   |  execution flags (bitwise OR) | number |     ef_     |
   +---------+-------------------------------+--------+-------------+
-  |  [lo]   |[PCRE] locale                  | string |   ``nil``   |
+  |  [lo]   |[PCRE] locale                  |string  |locale_      |
+  |         |                               |or      |             |
+  |         |                               |userdata|             |
   +---------+-------------------------------+--------+-------------+
 
 **Returns on success:**
@@ -132,7 +143,9 @@ PCRE: A locale *lo* may be specified.
   +---------+-------------------------------+--------+-------------+
   |  [ef]   |  execution flags (bitwise OR) | number |      ef_    |
   +---------+-------------------------------+--------+-------------+
-  |  [lo]   |[PCRE] locale                  | string |   ``nil``   |
+  |  [lo]   |[PCRE] locale                  |string  |locale_      |
+  |         |                               |or      |             |
+  |         |                               |userdata|             |
   +---------+-------------------------------+--------+-------------+
 
 **Returns on success:**
@@ -158,19 +171,21 @@ the string *subj*, subject to flags *cf* and *ef*.
 
 PCRE: A locale *lo* may be specified.
 
-  +---------+-------------------------------+------+-------------+
-  |Parameter|      Description              | Type |Default Value|
-  +=========+===============================+======+=============+
-  |  subj   |        subject                |string|     n/a     |
-  +---------+-------------------------------+------+-------------+
-  |  patt   |regular expression pattern     |string|     n/a     |
-  +---------+-------------------------------+------+-------------+
-  |  [cf]   |compilation flags (bitwise OR) |number|     cf_     |
-  +---------+-------------------------------+------+-------------+
-  |  [ef]   |execution flags (bitwise OR)   |number|     ef_     |
-  +---------+-------------------------------+------+-------------+
-  |  [lo]   |[PCRE] locale                  |string|   ``nil``   |
-  +---------+-------------------------------+------+-------------+
+  +---------+-------------------------------+--------+-------------+
+  |Parameter|      Description              | Type   |Default Value|
+  +=========+===============================+========+=============+
+  |  subj   |        subject                |string  |     n/a     |
+  +---------+-------------------------------+--------+-------------+
+  |  patt   |regular expression pattern     |string  |     n/a     |
+  +---------+-------------------------------+--------+-------------+
+  |  [cf]   |compilation flags (bitwise OR) |number  |     cf_     |
+  +---------+-------------------------------+--------+-------------+
+  |  [ef]   |execution flags (bitwise OR)   |number  |     ef_     |
+  +---------+-------------------------------+--------+-------------+
+  |  [lo]   |[PCRE] locale                  |string  |locale_      |
+  |         |                               |or      |             |
+  |         |                               |userdata|             |
+  +---------+-------------------------------+--------+-------------+
 
 The iterator function is called by Lua. On every iteration (that is, on every
 match), it returns all captures in the order they appear in the pattern (or the
@@ -206,7 +221,8 @@ PCRE: A locale *lo* may be specified.
   +---------+-----------------------------------+-------------------------+-------------+
   |  [ef]   |execution flags (bitwise OR)       |         number          |     ef_     |
   +---------+-----------------------------------+-------------------------+-------------+
-  |  [lo]   |[PCRE] locale                      |         string          |   ``nil``   |
+  |  [lo]   |[PCRE] locale                      | string or userdata      |locale_      |
+  |         |                                   |                         |             |
   +---------+-----------------------------------+-------------------------+-------------+
 
 **Returns:**
@@ -311,20 +327,22 @@ the string *subj*, subject to flags *cf* and *ef*.
 
 PCRE: A locale *lo* may be specified.
 
-  +---------+-------------------------------+------+-------------+
-  |Parameter|      Description              | Type |Default Value|
-  +=========+===============================+======+=============+
-  |  subj   |        subject                |string|     n/a     |
-  +---------+-------------------------------+------+-------------+
-  |   sep   |separator (regular expression  |string|     n/a     |
-  |         |pattern)                       |      |             |
-  +---------+-------------------------------+------+-------------+
-  |  [cf]   |compilation flags (bitwise OR) |number|     cf_     |
-  +---------+-------------------------------+------+-------------+
-  |  [ef]   |execution flags (bitwise OR)   |number|     ef_     |
-  +---------+-------------------------------+------+-------------+
-  |  [lo]   |[PCRE] locale                  |string|   ``nil``   |
-  +---------+-------------------------------+------+-------------+
+  +---------+-------------------------------+--------+-------------+
+  |Parameter|      Description              | Type   |Default Value|
+  +=========+===============================+========+=============+
+  |  subj   |        subject                |string  |     n/a     |
+  +---------+-------------------------------+--------+-------------+
+  |   sep   |separator (regular expression  |string  |     n/a     |
+  |         |pattern)                       |        |             |
+  +---------+-------------------------------+--------+-------------+
+  |  [cf]   |compilation flags (bitwise OR) |number  |     cf_     |
+  +---------+-------------------------------+--------+-------------+
+  |  [ef]   |execution flags (bitwise OR)   |number  |     ef_     |
+  +---------+-------------------------------+--------+-------------+
+  |  [lo]   |[PCRE] locale                  |string  |locale_      |
+  |         |                               |or      |             |
+  |         |                               |userdata|             |
+  +---------+-------------------------------+--------+-------------+
 
 **On every iteration pass, the iterator returns:**
 
@@ -340,70 +358,6 @@ subject.
 
 ------------------------------------------------------------
 
-plainfind
----------
-
-:funcdef:`rex.plainfind (subj, patt, [init], [ci])`
-
-The function searches for the first match of the string *patt* in the subject
-*subj*, starting from offset *init*.
-
-  * The string *patt* is not regular expression, all its characters stand for
-    themselves.
-  * Both strings *subj* and *patt* can have embedded zeros.
-  * The flag *ci* specifies case-insensitive search (current locale is used).
-  * This function uses neither PCRE nor POSIX regex library.
-
-  +---------+---------------------------+--------+-------------+
-  |Parameter|        Description        |  Type  |Default Value|
-  +=========+===========================+========+=============+
-  |  subj   |          subject          | string |     n/a     |
-  +---------+---------------------------+--------+-------------+
-  |  patt   |       text to find        | string |     n/a     |
-  +---------+---------------------------+--------+-------------+
-  | [init]  |start offset in the subject| number |      1      |
-  |         |(can be negative)          |        |             |
-  +---------+---------------------------+--------+-------------+
-  |  [ci]   |case insensitive search    |boolean |  ``false``  |
-  +---------+---------------------------+--------+-------------+
-
-**Returns on success:**
-  1. The start point of the match (a number).
-  2. The end point of the match (a number).
-
-**Returns on failure:**
-  1. ``nil``
-
-------------------------------------------------------------
-
-new
----
-
-:funcdef:`rex.new (patt, [cf], [lo])`
-
-The functions compiles regular expression *patt* into a regular expression
-object whose internal representation is correspondent to the library used (PCRE
-or POSIX regex).  The returned result then can be used by the methods `tfind`_,
-`exec`_ and `dfa_exec`_.  Regular expression objects are automatically garbage
-collected.
-
-PCRE: A locale *lo* may be specified.
-
-  +---------+-------------------------------+--------+-------------+
-  |Parameter|        Description            |  Type  |Default Value|
-  +=========+===============================+========+=============+
-  |  patt   |regular expression pattern     | string |     n/a     |
-  +---------+-------------------------------+--------+-------------+
-  |  [cf]   |compilation flags (bitwise OR) | number |     cf_     |
-  +---------+-------------------------------+--------+-------------+
-  |  [lo]   |[PCRE] locale                  | string |   ``nil``   |
-  +---------+-------------------------------+--------+-------------+
-
-**Returns:**
- 1. Compiled regular expression (a userdata).
-
-------------------------------------------------------------
-
 flags
 -----
 
@@ -431,44 +385,36 @@ documentation.
 
 ------------------------------------------------------------
 
-config
-------
+new
+---
 
-[PCRE 4.0 and later. See *pcre_config* in the PCRE_ docs.]
+:funcdef:`rex.new (patt, [cf], [lo])`
 
-:funcdef:`rex.config ([tb])`
+The functions compiles regular expression *patt* into a regular expression
+object whose internal representation is correspondent to the library used (PCRE
+or POSIX regex).  The returned result then can be used by the methods `tfind`_,
+`exec`_ and `dfa_exec`_.  Regular expression objects are automatically garbage
+collected.
 
-This function returns a table containing the values of the configuration
-parameters used at PCRE library build-time. Those parameters (numbers) are
-keyed by their names (strings). If the table argument *tb* is supplied then it
-is used as the output table, else a new table is created.
+PCRE: A locale *lo* may be specified.
 
-  +---------+--------------------------------+--------+-------------+
-  |Parameter|        Description             |  Type  |Default Value|
-  +=========+================================+========+=============+
-  |  [tb]   |a table for placing results into| table  |  ``nil``    |
-  +---------+--------------------------------+--------+-------------+
+  +---------+-------------------------------+--------+-------------+
+  |Parameter|        Description            |  Type  |Default Value|
+  +=========+===============================+========+=============+
+  |  patt   |regular expression pattern     | string |     n/a     |
+  +---------+-------------------------------+--------+-------------+
+  |  [cf]   |compilation flags (bitwise OR) | number |     cf_     |
+  +---------+-------------------------------+--------+-------------+
+  |  [lo]   |[PCRE] locale                  |string  |locale_      |
+  |         |                               |or      |             |
+  |         |                               |userdata|             |
+  +---------+-------------------------------+--------+-------------+
 
 **Returns:**
- 1. A table filled with the results.
-
-------------------------------------------------------------
-
-version
--------
-
-[PCRE only. See *pcre_version* in the PCRE_ docs.]
-
-:funcdef:`rex.version ()`
-
-This function returns a string containing the version of the used PCRE library
-and its release date.
+ 1. Compiled regular expression (a userdata).
 
 ------------------------------------------------------------
 
-Lrexlib Methods
-~~~~~~~~~~~~~~~
-
 tfind
 -----
 
@@ -554,6 +500,90 @@ string *subj*, starting from offset *init*, subject to execution flags *ef*.
 
 ------------------------------------------------------------
 
+PCRE-only functions and methods
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+maketables
+----------
+
+[PCRE only. See *pcre_maketables* in the PCRE_ docs.]
+
+:funcdef:`rex.maketables ()`
+
+Creates a table set corresponding to the current active locale and returns it as
+a userdata. The returned value can be passed to the function settables_ and to
+any Lrexlib function accepting the *locale* parameter.
+
+------------------------------------------------------------
+
+settables
+---------
+
+[PCRE only]
+
+:funcdef:`rex.settables ([tables])`
+
+This function replaces the default set of character tables, by the one supplied
+in the parameter *tables*.
+
+The *tables* parameter should be either a userdata, obtained from a call to
+maketables_, or ``nil``. In the latter case, the built-in PCRE set of tables
+becomes the default.
+
+Lrexlib maintains one "default" set of character tables, in addition to the set
+built-in into PCRE. When a Lrexlib function accepting the *locale* argument is
+called with that argument omitted, then the default set of character tables is
+used.
+
+The initial default set of tables is the built-in PCRE set.
+
+  +---------+--------------------------------+--------+-------------+
+  |Parameter|        Description             |  Type  |Default Value|
+  +=========+================================+========+=============+
+  |[tables] |See the above description.      |userdata|  ``nil``    |
+  |         |                                |        |             |
+  +---------+--------------------------------+--------+-------------+
+
+**Returns:**
+ The old value of the default set (``nil`` for the built-in PCRE set).
+
+------------------------------------------------------------
+
+config
+------
+
+[PCRE 4.0 and later. See *pcre_config* in the PCRE_ docs.]
+
+:funcdef:`rex.config ([tb])`
+
+This function returns a table containing the values of the configuration
+parameters used at PCRE library build-time. Those parameters (numbers) are
+keyed by their names (strings). If the table argument *tb* is supplied then it
+is used as the output table, else a new table is created.
+
+  +---------+--------------------------------+--------+-------------+
+  |Parameter|        Description             |  Type  |Default Value|
+  +=========+================================+========+=============+
+  |  [tb]   |a table for placing results into| table  |  ``nil``    |
+  +---------+--------------------------------+--------+-------------+
+
+**Returns:**
+ 1. A table filled with the results.
+
+------------------------------------------------------------
+
+version
+-------
+
+[PCRE only. See *pcre_version* in the PCRE_ docs.]
+
+:funcdef:`rex.version ()`
+
+This function returns a string containing the version of the used PCRE library
+and its release date.
+
+------------------------------------------------------------
+
 dfa_exec
 --------
 
@@ -597,10 +627,49 @@ string *subj*, using a DFA matching algorithm.
 
 ------------------------------------------------------------
 
+Other functions
+~~~~~~~~~~~~~~~
+
+plainfind
+---------
+
+:funcdef:`rex.plainfind (subj, patt, [init], [ci])`
+
+The function searches for the first match of the string *patt* in the subject
+*subj*, starting from offset *init*.
+
+  * The string *patt* is not regular expression, all its characters stand for
+    themselves.
+  * Both strings *subj* and *patt* can have embedded zeros.
+  * The flag *ci* specifies case-insensitive search (current locale is used).
+  * This function uses neither PCRE nor POSIX regex library.
+
+  +---------+---------------------------+--------+-------------+
+  |Parameter|        Description        |  Type  |Default Value|
+  +=========+===========================+========+=============+
+  |  subj   |          subject          | string |     n/a     |
+  +---------+---------------------------+--------+-------------+
+  |  patt   |       text to find        | string |     n/a     |
+  +---------+---------------------------+--------+-------------+
+  | [init]  |start offset in the subject| number |      1      |
+  |         |(can be negative)          |        |             |
+  +---------+---------------------------+--------+-------------+
+  |  [ci]   |case insensitive search    |boolean |  ``false``  |
+  +---------+---------------------------+--------+-------------+
+
+**Returns on success:**
+  1. The start point of the match (a number).
+  2. The end point of the match (a number).
+
+**Returns on failure:**
+  1. ``nil``
+
+------------------------------------------------------------
+
 Incompatibilities with the Previous Versions
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-**Incompatibilities with the version 1.19:**
+**Incompatibilities between the versions 2.0 and 1.19:**
 
   1. Lua 5.1 is required
   #. Functions ``newPCRE`` and ``newPOSIX`` renamed to new_
@@ -609,16 +678,20 @@ Incompatibilities with the Previous Versions
   #. Method ``match`` renamed to tfind_
   #. Method ``gmatch`` removed (similar functionality is provided by function
      gmatch_)
-  #. Method exec_: the returned table may additionally contain *named
-     subpatterns* (PCRE only)
+  #. Methods tfind_ and exec_: 2 values are returned on failure
+  #. (PCRE) exec_: the returned table may additionally contain *named
+     subpatterns*
 
-**Incompatibilities with the version 2.0:**
+**Incompatibilities between the versions 2.1 and 2.0:**
 
   1. match_, find_, tfind_, exec_, dfa_exec_: only one value (a ``nil``) is
      returned when the subject does not match the pattern. Any other failure
      generates an error.
 
-**Incompatibilities with the version 2.1:**
+**Incompatibilities between the versions 2.2 and 2.1:**
 
   1. gsub_: a special "break" return of *repl* function is deprecated.
+  #. (PCRE) gsub_, gmatch_: after finding an empty match at the current
+     position, the functions try to find a non-empty match anchored to the same
+     position.
author	shmuz <shmuz>	2007-04-19 07:02:33 +0000
committer	shmuz <shmuz>	2007-04-19 07:02:33 +0000
commit	0ff6b1ed54f366b76dc74be466ead118c94e3ab4 (patch)
tree	9a2338a7a7dea8b259ce8a447b293aa7d317c065 /doc
parent	63cdc5a4fa6b6f11f782c40995779a2a3af6db98 (diff)
download	lrexlib-0ff6b1ed54f366b76dc74be466ead118c94e3ab4.tar.gz