describe PCRE cflags as a string

2 files changed, 195 insertions, 130 deletions

diff --git a/doc/manual.html b/doc/manual.html
index e360da5..25a2754 100755
--- a/doc/manual.html
+++ b/doc/manual.html
@@ -29,11 +29,11 @@
 </ul>
 </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>
+<li><a class="reference" href="#dfa-exec" id="id14" name="id14">dfa_exec</a></li>
+<li><a class="reference" href="#maketables" id="id15" name="id15">maketables</a></li>
+<li><a class="reference" href="#settables" id="id16" name="id16">settables</a></li>
+<li><a class="reference" href="#config" id="id17" name="id17">config</a></li>
+<li><a class="reference" href="#version" id="id18" name="id18">version</a></li>
 </ul>
 </li>
 <li><a class="reference" href="#other-functions" id="id19" name="id19">Other functions</a><ul>
@@ -87,6 +87,56 @@ the parameter is not supplied or <tt class="docutils literal"><span class="pre">
 <li>REG_EXTENDED for POSIX regex library</li>
 </ul>
 </blockquote>
+<p>For PCRE, <em>cf</em> may also be supplied as a string, whose characters stand for
+PCRE compilation flags. Combinations of the following characters (case
+sensitive) are supported:</p>
+<blockquote>
+<table border="1" class="docutils">
+<colgroup>
+<col width="45%" />
+<col width="55%" />
+</colgroup>
+<thead valign="bottom">
+<tr><th class="head"><p class="first last"><strong>Character</strong></p>
+</th>
+<th class="head"><p class="first last"><strong>PCRE flag</strong></p>
+</th>
+</tr>
+</thead>
+<tbody valign="top">
+<tr><td><p class="first last"><strong>i</strong></p>
+</td>
+<td><p class="first last">PCRE_CASELESS</p>
+</td>
+</tr>
+<tr><td><p class="first last"><strong>m</strong></p>
+</td>
+<td><p class="first last">PCRE_MULTILINE</p>
+</td>
+</tr>
+<tr><td><p class="first last"><strong>s</strong></p>
+</td>
+<td><p class="first last">PCRE_DOTALL</p>
+</td>
+</tr>
+<tr><td><p class="first last"><strong>x</strong></p>
+</td>
+<td><p class="first last">PCRE_EXTENDED</p>
+</td>
+</tr>
+<tr><td><p class="first last"><strong>U</strong></p>
+</td>
+<td><p class="first last">PCRE_UNGREEDY</p>
+</td>
+</tr>
+<tr><td><p class="first last"><strong>X</strong></p>
+</td>
+<td><p class="first last">PCRE_EXTRA</p>
+</td>
+</tr>
+</tbody>
+</table>
+</blockquote>
 </li>
 </ol>
 <ol class="arabic" id="ef" start="6">
@@ -818,7 +868,84 @@ substring matches keyed by their correspondent subpattern names
 <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>
+<h3><a class="toc-backref" href="#id14" 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
+string <em>subj</em>, using a DFA matching algorithm.</p>
+<blockquote>
+<table border="1" class="docutils">
+<colgroup>
+<col width="15%" />
+<col width="54%" />
+<col width="12%" />
+<col width="19%" />
+</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>r</td>
+<td>regex object produced by <a class="reference" href="#new">new</a></td>
+<td>userdata</td>
+<td>n/a</td>
+</tr>
+<tr><td>subj</td>
+<td>subject</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>[ef]</td>
+<td>execution flags (bitwise OR)</td>
+<td>number</td>
+<td><a class="reference" href="#ef">ef</a></td>
+</tr>
+<tr><td>[ovecsize]</td>
+<td>size of the array for result offsets</td>
+<td>number</td>
+<td>100</td>
+</tr>
+<tr><td>[wscount]</td>
+<td>number of elements in the working
+space array</td>
+<td>number</td>
+<td>50</td>
+</tr>
+</tbody>
+</table>
+</blockquote>
+<dl class="docutils">
+<dt><strong>Returns on success (either full or partial match):</strong></dt>
+<dd><ol class="first last arabic simple">
+<li>The start point of the matches found (a number).</li>
+<li>A table containing the end points of the matches found, the longer matches
+first.</li>
+<li>The return value of the underlying <em>pcre_dfa_exec</em> call (a number).</li>
+</ol>
+</dd>
+<dt><strong>Returns on failure (no match):</strong></dt>
+<dd><ol class="first last arabic simple">
+<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
+</ol>
+</dd>
+<dt><strong>Example:</strong></dt>
+<dd>If there are 3 matches found starting at offset 10 and ending at offsets 15, 20
+and 25 then the function returns the following: 10, { 25,20,15 }, 3.</dd>
+</dl>
+</div>
+<hr class="docutils" />
+<div class="section">
+<h3><a class="toc-backref" href="#id15" 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
@@ -827,7 +954,7 @@ 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>
+<h3><a class="toc-backref" href="#id16" 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
@@ -871,7 +998,7 @@ used.</p>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id16" id="config" name="config">config</a></h3>
+<h3><a class="toc-backref" href="#id17" 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
@@ -912,89 +1039,12 @@ is used as the output table, else a new table is created.</p>
 </div>
 <hr class="docutils" />
 <div class="section">
-<h3><a class="toc-backref" href="#id17" id="version" name="version">version</a></h3>
+<h3><a class="toc-backref" href="#id18" 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
-string <em>subj</em>, using a DFA matching algorithm.</p>
-<blockquote>
-<table border="1" class="docutils">
-<colgroup>
-<col width="15%" />
-<col width="54%" />
-<col width="12%" />
-<col width="19%" />
-</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>r</td>
-<td>regex object produced by <a class="reference" href="#new">new</a></td>
-<td>userdata</td>
-<td>n/a</td>
-</tr>
-<tr><td>subj</td>
-<td>subject</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>[ef]</td>
-<td>execution flags (bitwise OR)</td>
-<td>number</td>
-<td><a class="reference" href="#ef">ef</a></td>
-</tr>
-<tr><td>[ovecsize]</td>
-<td>size of the array for result offsets</td>
-<td>number</td>
-<td>100</td>
-</tr>
-<tr><td>[wscount]</td>
-<td>number of elements in the working
-space array</td>
-<td>number</td>
-<td>50</td>
-</tr>
-</tbody>
-</table>
-</blockquote>
-<dl class="docutils">
-<dt><strong>Returns on success (either full or partial match):</strong></dt>
-<dd><ol class="first last arabic simple">
-<li>The start point of the matches found (a number).</li>
-<li>A table containing the end points of the matches found, the longer matches
-first.</li>
-<li>The return value of the underlying <em>pcre_dfa_exec</em> call (a number).</li>
-</ol>
-</dd>
-<dt><strong>Returns on failure (no match):</strong></dt>
-<dd><ol class="first last arabic simple">
-<li><tt class="docutils literal"><span class="pre">nil</span></tt></li>
-</ol>
-</dd>
-<dt><strong>Example:</strong></dt>
-<dd>If there are 3 matches found starting at offset 10 and ending at offsets 15, 20
-and 25 then the function returns the following: 10, { 25,20,15 }, 3.</dd>
-</dl>
-</div>
 </div>
 <hr class="docutils" />
 <div class="section">
@@ -1105,7 +1155,7 @@ position.</li>
 </div>
 <div class="footer">
 <hr class="footer" />
-Generated on: 2007-04-17 16:16 UTC.
+Generated on: 2007-05-02 10:06 UTC.
 
 </div>
 </body>
diff --git a/doc/manual.txt b/doc/manual.txt
index b833cf7..0b71419 100755
--- a/doc/manual.txt
+++ b/doc/manual.txt
@@ -55,6 +55,21 @@ Notes
      * 0 for PCRE
      * REG_EXTENDED for POSIX regex library
 
+   For PCRE, *cf* may also be supplied as a string, whose characters stand for
+   PCRE compilation flags. Combinations of the following characters (case
+   sensitive) are supported:
+
+      ===============   ==================
+       **Character**      **PCRE flag**
+      ===============   ==================
+       **i**              PCRE_CASELESS
+       **m**              PCRE_MULTILINE
+       **s**              PCRE_DOTALL
+       **x**              PCRE_EXTENDED
+       **U**              PCRE_UNGREEDY
+       **X**              PCRE_EXTRA
+      ===============   ==================
+
 .. _ef:
 
 6. The default value for *execution flags* (*ef*) that Lrexlib uses when
@@ -503,6 +518,49 @@ string *subj*, starting from offset *init*, subject to execution flags *ef*.
 PCRE-only functions and methods
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
+dfa_exec
+--------
+
+[PCRE 6.0 and later. See *pcre_dfa_exec* in the PCRE_ docs.]
+
+:funcdef:`r:dfa_exec (subj, [init], [ef], [ovecsize], [wscount])`
+
+The method matches a compiled regular expression *r* against a given subject
+string *subj*, using a DFA matching algorithm.
+
+  +----------+-------------------------------------+--------+-------------+
+  |Parameter |                 Description         |  Type  |Default Value|
+  +==========+=====================================+========+=============+
+  |    r     | regex object produced by new_       |userdata|     n/a     |
+  +----------+-------------------------------------+--------+-------------+
+  |  subj    |                   subject           | string |     n/a     |
+  +----------+-------------------------------------+--------+-------------+
+  | [init]   |start offset in the subject          | number |      1      |
+  |          |(can be negative)                    |        |             |
+  +----------+-------------------------------------+--------+-------------+
+  |   [ef]   |  execution flags (bitwise OR)       | number |     ef_     |
+  +----------+-------------------------------------+--------+-------------+
+  |[ovecsize]|size of the array for result offsets | number |     100     |
+  +----------+-------------------------------------+--------+-------------+
+  |[wscount] |number of elements in the working    | number |     50      |
+  |          |space array                          |        |             |
+  +----------+-------------------------------------+--------+-------------+
+
+**Returns on success (either full or partial match):**
+ 1. The start point of the matches found (a number).
+ 2. A table containing the end points of the matches found, the longer matches
+    first.
+ 3. The return value of the underlying *pcre_dfa_exec* call (a number).
+
+**Returns on failure (no match):**
+ 1. ``nil``
+
+**Example:**
+ If there are 3 matches found starting at offset 10 and ending at offsets 15, 20
+ and 25 then the function returns the following: 10, { 25,20,15 }, 3.
+
+------------------------------------------------------------
+
 maketables
 ----------
 
@@ -584,49 +642,6 @@ and its release date.
 
 ------------------------------------------------------------
 
-dfa_exec
---------
-
-[PCRE 6.0 and later. See *pcre_dfa_exec* in the PCRE_ docs.]
-
-:funcdef:`r:dfa_exec (subj, [init], [ef], [ovecsize], [wscount])`
-
-The method matches a compiled regular expression *r* against a given subject
-string *subj*, using a DFA matching algorithm.
-
-  +----------+-------------------------------------+--------+-------------+
-  |Parameter |                 Description         |  Type  |Default Value|
-  +==========+=====================================+========+=============+
-  |    r     | regex object produced by new_       |userdata|     n/a     |
-  +----------+-------------------------------------+--------+-------------+
-  |  subj    |                   subject           | string |     n/a     |
-  +----------+-------------------------------------+--------+-------------+
-  | [init]   |start offset in the subject          | number |      1      |
-  |          |(can be negative)                    |        |             |
-  +----------+-------------------------------------+--------+-------------+
-  |   [ef]   |  execution flags (bitwise OR)       | number |     ef_     |
-  +----------+-------------------------------------+--------+-------------+
-  |[ovecsize]|size of the array for result offsets | number |     100     |
-  +----------+-------------------------------------+--------+-------------+
-  |[wscount] |number of elements in the working    | number |     50      |
-  |          |space array                          |        |             |
-  +----------+-------------------------------------+--------+-------------+
-
-**Returns on success (either full or partial match):**
- 1. The start point of the matches found (a number).
- 2. A table containing the end points of the matches found, the longer matches
-    first.
- 3. The return value of the underlying *pcre_dfa_exec* call (a number).
-
-**Returns on failure (no match):**
- 1. ``nil``
-
-**Example:**
- If there are 3 matches found starting at offset 10 and ending at offsets 15, 20
- and 25 then the function returns the following: 10, { 25,20,15 }, 3.
-
-------------------------------------------------------------
-
 Other functions
 ~~~~~~~~~~~~~~~