diff options
| author | Robin Haberkorn <robin.haberkorn@googlemail.com> | 2010-12-29 16:26:25 +0100 |
|---|---|---|
| committer | Robin Haberkorn <robin.haberkorn@googlemail.com> | 2010-12-29 16:26:25 +0100 |
| commit | d3148268857e01116d5d3c99ac0a43bc6a54b13c (patch) | |
| tree | 6ae273025ef73942c0ac748e715a7f281a6af114 /doc | |
| download | lspipat-d3148268857e01116d5d3c99ac0a43bc6a54b13c.tar.gz | |
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/Makefile.am | 15 | ||||
| -rw-r--r-- | doc/html_custom.xsl | 6 | ||||
| -rw-r--r-- | doc/html_titlepage.spec.xml | 688 | ||||
| -rw-r--r-- | doc/lspipat.png | bin | 0 -> 4266 bytes | |||
| -rw-r--r-- | doc/pattern.txt | 1017 | ||||
| -rw-r--r-- | doc/reference.xml | 2005 |
6 files changed, 3731 insertions, 0 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am new file mode 100644 index 0000000..f8ff134 --- /dev/null +++ b/doc/Makefile.am @@ -0,0 +1,15 @@ +## Docbook processing - very simplistic at the moment + +DB_URI = http://docbook.sourceforge.net/release/xsl/current + +dist_doc_DATA = pattern.txt + +dist_html_DATA = reference.html lspipat.png +CLEANFILES = reference.html html_titlepage.xsl +EXTRA_DIST = reference.xml html_custom.xsl html_titlepage.spec.xml + +reference.html : reference.xml html_custom.xsl html_titlepage.xsl + @XSLTPROC@ @XSLT_FLAGS@ -o $@ html_custom.xsl $< + +html_titlepage.xsl : html_titlepage.spec.xml + @XSLTPROC@ @XSLT_FLAGS@ -o $@ $(DB_URI)/template/titlepage.xsl $< diff --git a/doc/html_custom.xsl b/doc/html_custom.xsl new file mode 100644 index 0000000..af94064 --- /dev/null +++ b/doc/html_custom.xsl @@ -0,0 +1,6 @@ +<?xml version='1.0'?> + +<stylesheet xmlns="http://www.w3.org/1999/XSL/Transform" version="1.0"> + <import href="http://docbook.sourceforge.net/release/xsl/current/html/docbook.xsl"/> + <import href="html_titlepage.xsl"/> +</stylesheet> diff --git a/doc/html_titlepage.spec.xml b/doc/html_titlepage.spec.xml new file mode 100644 index 0000000..ea44036 --- /dev/null +++ b/doc/html_titlepage.spec.xml @@ -0,0 +1,688 @@ +<t:templates xmlns:t="http://nwalsh.com/docbook/xsl/template/1.0" + xmlns:param="http://nwalsh.com/docbook/xsl/template/1.0/param" + xmlns:xsl="http://www.w3.org/1999/XSL/Transform"> + +<!-- ==================================================================== --> + +<t:titlepage t:element="article" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <mediaobject/> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="set" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="book" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <mediaobject/> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="part" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="division.title" + param:node="ancestor-or-self::part[1]"/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="partintro" t:wrapper="div"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="reference" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <hr/> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="refentry" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> +<!-- uncomment this if you want refentry titlepages + <title t:force="1" + t:named-template="refentry.title" + param:node="ancestor-or-self::refentry[1]"/> +--> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator/> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + + <t:titlepage t:element="dedication" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::dedication[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="acknowledgements" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::acknowledgements[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="preface" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="chapter" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="appendix" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="section" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect1" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect2" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect3" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect4" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="sect5" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<t:titlepage t:element="simplesect" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title/> + <subtitle/> + <corpauthor/> + <authorgroup/> + <author/> + <othercredit/> + <releaseinfo/> + <copyright/> + <legalnotice/> + <pubdate/> + <revision/> + <revhistory/> + <abstract/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + <xsl:if test="count(parent::*)='0'"><hr/></xsl:if> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="bibliography" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::bibliography[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="glossary" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::glossary[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="index" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::index[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +<t:titlepage t:element="setindex" t:wrapper="div" class="titlepage"> + <t:titlepage-content t:side="recto"> + <title + t:force="1" + t:named-template="component.title" + param:node="ancestor-or-self::setindex[1]"/> + <subtitle/> + </t:titlepage-content> + + <t:titlepage-content t:side="verso"> + </t:titlepage-content> + + <t:titlepage-separator> + </t:titlepage-separator> + + <t:titlepage-before t:side="recto"> + </t:titlepage-before> + + <t:titlepage-before t:side="verso"> + </t:titlepage-before> +</t:titlepage> + +<!-- ==================================================================== --> + +</t:templates> diff --git a/doc/lspipat.png b/doc/lspipat.png Binary files differnew file mode 100644 index 0000000..317751d --- /dev/null +++ b/doc/lspipat.png diff --git a/doc/pattern.txt b/doc/pattern.txt new file mode 100644 index 0000000..e0d1719 --- /dev/null +++ b/doc/pattern.txt @@ -0,0 +1,1017 @@ +Copyright (C) 2007,2008, Philip L. Budne +Copyright (C) 1998-2005, AdaCore + +This documentation (and the underlying software) developed from the +GNAT.SPITBOL.PATTERNS package of GNU Ada. GNAT was originally +developed by the GNAT team at New York University. Extensive +contributions were provided by Ada Core Technologies Inc. + +SPITBOL-like pattern construction and matching + +This child package of GNAT.SPITBOL provides a complete implementation +of the SPITBOL-like pattern construction and matching operations. This +package is based on Macro-SPITBOL created by Robert Dewar. + +This is a completely general patterm matching package based on the +pattern language of SNOBOL4, as implemented in SPITBOL. The pattern +language is modeled on context free grammars, with context sensitive +extensions that provide full (type 0) computational capabilities. + +------------------------------- +Pattern Matching Tutorial +------------------------------- + +A pattern matching operation (a call to one of the Match subprograms) +takes a subject string and a pattern, and optionally a replacement +string. The replacement string option is only allowed if the subject +is a variable. + +The pattern is matched against the subject string, and either the +match fails, or it succeeds matching a contiguous substring. If a +replacement string is specified, then the subject string is modified +by replacing the matched substring with the given replacement. + +Concatenation and Alternation +============================= + +A pattern consists of a series of pattern elements. The pattern is +built up using either the concatenation operator: + + A & B + + which means match A followed immediately by matching B, or the + alternation operator: + + A | B + + which means first attempt to match A, and then if that does not + succeed, match B. + + There is full backtracking, which means that if a given pattern + element fails to match, then previous alternatives are matched. + For example if we have the pattern: + + (A | B) & (C | D) & (E | F) + + First we attempt to match A, if that succeeds, then we go on to try + to match C, and if that succeeds, we go on to try to match E. If E + fails, then we try F. If F fails, then we go back and try matching + D instead of C. Let's make this explicit using a specific example, + and introducing the simplest kind of pattern element, which is a + literal string. The meaning of this pattern element is simply to + match the characters that correspond to the string characters. Now + let's rewrite the above pattern form with specific string literals + as the pattern elements: + + ("ABC" | "AB") & ("DEF" | "CDE") & ("GH" | "IJ") + + The following strings will be attempted in sequence: + + ABC . DEF . GH + ABC . DEF . IJ + ABC . CDE . GH + ABC . CDE . IJ + AB . DEF . GH + AB . DEF . IJ + AB . CDE . GH + AB . CDE . IJ + + Here we use the dot simply to separate the pieces of the string + matched by the three separate elements. + + Moving the Start Point + ====================== + + A pattern is not required to match starting at the first character + of the string, and is not required to match to the end of the string. + The first attempt does indeed attempt to match starting at the first + character of the string, trying all the possible alternatives. But + if all alternatives fail, then the starting point of the match is + moved one character, and all possible alternatives are attempted at + the new anchor point. + + The entire match fails only when every possible starting point has + been attempted. As an example, suppose that we had the subject + string + + "ABABCDEIJKL" + + matched using the pattern in the previous example: + + ("ABC" | "AB") & ("DEF" | "CDE") & ("GH" | "IJ") + + would succeed, afer two anchor point moves: + + "ABABCDEIJKL" + ^^^^^^^ + matched + section + + This mode of pattern matching is called the unanchored mode. It is + also possible to put the pattern matcher into anchored mode by + setting the global variable Anchored_Mode to True. This will cause + all subsequent matches to be performed in anchored mode, where the + match is required to start at the first character. + + We will also see later how the effect of an anchored match can be + obtained for a single specified anchor point if this is desired. + + Other Pattern Elements + ====================== + + In addition to strings (or single characters), there are many special + pattern elements that correspond to special predefined alternations: + + Arb Matches any string. First it matches the null string, and + then on a subsequent failure, matches one character, and + then two characters, and so on. It only fails if the + entire remaining string is matched. + + Bal Matches a non-empty string that is parentheses balanced + with respect to ordinary () characters. Examples of + balanced strings are "ABC", "A((B)C)", and "A(B)C(D)E". + Bal matches the shortest possible balanced string on the + first attempt, and if there is a subsequent failure, + attempts to extend the string. + + Abort Immediately aborts the entire pattern match, signalling + failure. This is a specialized pattern element, which is + useful in conjunction with some of the special pattern + elements that have side effects. + + Fail The null alternation. Matches no possible strings, so it + always signals failure. This is a specialized pattern + element, which is useful in conjunction with some of the + special pattern elements that have side effects. + + Fence Matches the null string at first, and then if a failure + causes alternatives to be sought, aborts the match (like + a Cancel). Note that using Fence at the start of a pattern + has the same effect as matching in anchored mode. + + Rem Matches from the current point to the last character in + the string. This is a specialized pattern element, which + is useful in conjunction with some of the special pattern + elements that have side effects. + + Succeed Repeatedly matches the null string (it is equivalent to + the alternation ("" | "" | "" ....). This is a special + pattern element, which is useful in conjunction with some + of the special pattern elements that have side effects. + + Pattern Construction Functions + ============================== + + The following functions construct additional pattern elements + + Any(S) Where S is a string, matches a single character that is + any one of the characters in S. Fails if the current + character is not one of the given set of characters. + + Arbno(P) Where P is any pattern, matches any number of instances + of the pattern, starting with zero occurrences. It is + thus equivalent to ("" | (P & ("" | (P & ("" ....)))). + The pattern P may contain any number of pattern elements + including the use of alternatiion and concatenation. + + Break(S) Where S is a string, matches a string of zero or more + characters up to but not including a break character + that is one of the characters given in the string S. + Can match the null string, but cannot match the last + character in the string, since a break character is + required to be present. + + BreakX(S) Where S is a string, behaves exactly like Break(S) when + it first matches, but if a string is successfully matched, + then a susequent failure causes an attempt to extend the + matched string. + + Fence(P) Where P is a pattern, attempts to match the pattern P + including trying all possible alternatives of P. If none + of these alternatives succeeds, then the Fence pattern + fails. If one alternative succeeds, then the pattern + match proceeds, but on a subsequent failure, no attempt + is made to search for alternative matches of P. The + pattern P may contain any number of pattern elements + including the use of alternatiion and concatenation. + + Len(N) Where N is a natural number, matches the given number of + characters. For example, Len(10) matches any string that + is exactly ten characters long. + + NotAny(S) Where S is a string, matches a single character that is + not one of the characters of S. Fails if the current + characer is one of the given set of characters. + + NSpan(S) Where S is a string, matches a string of zero or more + characters that is among the characters given in the + string. Always matches the longest possible such string. + Always succeeds, since it can match the null string. + + Pos(N) Where N is a natural number, matches the null string + if exactly N characters have been matched so far, and + otherwise fails. + + Rpos(N) Where N is a natural number, matches the null string + if exactly N characters remain to be matched, and + otherwise fails. + + Rtab(N) Where N is a natural number, matches characters from + the current position until exactly N characters remain + to be matched in the string. Fails if fewer than N + unmatched characters remain in the string. + + Tab(N) Where N is a natural number, matches characters from + the current position until exactly N characters have + been matched in all. Fails if more than N characters + have already been matched. + + Span(S) Where S is a string, matches a string of one or more + characters that is among the characters given in the + string. Always matches the longest possible such string. + Fails if the current character is not one of the given + set of characters. + + Recursive Pattern Matching + ========================== + + The plus operator (+P) where P is a pattern variable, creates + a recursive pattern that will, at pattern matching time, follow + the pointer to obtain the referenced pattern, and then match this + pattern. This may be used to construct recursive patterns. Consider + for example: + + P := ("A" | ("B" & (+P))) + + On the first attempt, this pattern attempts to match the string "A". + If this fails, then the alternative matches a "B", followed by an + attempt to match P again. This second attempt first attempts to + match "A", and so on. The result is a pattern that will match a + string of B's followed by a single A. + + This particular example could simply be written as NSpan('B') & 'A', + but the use of recursive patterns in the general case can construct + complex patterns which could not otherwise be built. + + Pattern Assignment Operations + ============================= + + In addition to the overall result of a pattern match, which indicates + success or failure, it is often useful to be able to keep track of + the pieces of the subject string that are matched by individual + pattern elements, or subsections of the pattern. + + The pattern assignment operators allow this capability. The first + form is the immediate assignment: + + P * S + + Here P is an arbitrary pattern, and S is a variable of type VString + that will be set to the substring matched by P. This assignment + happens during pattern matching, so if P matches more than once, + then the assignment happens more than once. + + The deferred assignment operation: + + P ** S + + avoids these multiple assignments by deferring the assignment to the + end of the match. If the entire match is successful, and if the + pattern P was part of the successful match, then at the end of the + matching operation the assignment to S of the string matching P is + performed. + + The cursor assignment operation: + + Setcur(N) + + assigns the current cursor position to the natural variable N. The + cursor position is defined as the count of characters that have been + matched so far (including any start point moves). + + Finally the operations * and ** may be used with values of type + Text_IO.File_Access. The effect is to do a Put_Line operation of + the matched substring. These are particularly useful in debugging + pattern matches. + + Deferred Matching + ================= + + The pattern construction functions (such as Len and Any) all permit + the use of pointers to natural or string values, or functions that + return natural or string values. These forms cause the actual value + to be obtained at pattern matching time. This allows interesting + possibilities for constructing dynamic patterns as illustrated in + the examples section. + + In addition the (+S) operator may be used where S is a pointer to + string or function returning string, with a similar deferred effect. + + A special use of deferred matching is the construction of predicate + functions. The element (+P) where P is an access to a function that + returns a Boolean value, causes the function to be called at the + time the element is matched. If the function returns True, then the + null string is matched, if the function returns False, then failure + is signalled and previous alternatives are sought. + + Deferred Replacement + ==================== + + The simple model given for pattern replacement (where the matched + substring is replaced by the string given as the third argument to + Match) works fine in simple cases, but this approach does not work + in the case where the expression used as the replacement string is + dependent on values set by the match. + + For example, suppose we want to find an instance of a parenthesized + character, and replace the parentheses with square brackets. At first + glance it would seem that: + + Match (Subject, '(' & Len (1) * Char & ')', '[' & Char & ']'); + + would do the trick, but that does not work, because the third + argument to Match gets evaluated too early, before the call to + Match, and before the pattern match has had a chance to set Char. + + To solve this problem we provide the deferred replacement capability. + With this approach, which of course is only needed if the pattern + involved has side effects, is to do the match in two stages. The + call to Match sets a pattern result in a variable of the private + type Match_Result, and then a subsequent Replace operation uses + this Match_Result object to perform the required replacement. + + Using this approach, we can now write the above operation properly + in a manner that will work: + + M : Match_Result; + ... + Match (Subject, '(' & Len (1) * Char & ')', M); + Replace (M, '[' & Char & ']'); + + As with other Match cases, there is a function and procedure form + of this match call. A call to Replace after a failed match has no + effect. Note that Subject should not be modified between the calls. + + Examples of Pattern Matching + ============================ + + First a simple example of the use of pattern replacement to remove + a line number from the start of a string. We assume that the line + number has the form of a string of decimal digits followed by a + period, followed by one or more spaces. + + Digs : constant Pattern := Span("0123456789"); + + Lnum : constant Pattern := Pos(0) & Digs & '.' & Span(' '); + + Now to use this pattern we simply do a match with a replacement: + + Match (Line, Lnum, ""); + + which replaces the line number by the null string. Note that it is + also possible to use an Ada.Strings.Maps.Character_Set value as an + argument to Span and similar functions, and in particular all the + useful constants 'in Ada.Strings.Maps.Constants are available. This + means that we could define Digs as: + + Digs : constant Pattern := Span(Decimal_Digit_Set); + + The style we use here, of defining constant patterns and then using + them is typical. It is possible to build up patterns dynamically, + but it is usually more efficient to build them in pieces in advance + using constant declarations. Note in particular that although it is + possible to construct a pattern directly as an argument for the + Match routine, it is much more efficient to preconstruct the pattern + as we did in this example. + + Now let's look at the use of pattern assignment to break a + string into sections. Suppose that the input string has two + unsigned decimal integers, separated by spaces or a comma, + with spaces allowed anywhere. Then we can isolate the two + numbers with the following pattern: + + Num1, Num2 : aliased VString; + + B : constant Pattern := NSpan(' '); + + N : constant Pattern := Span("0123456789"); + + T : constant Pattern := + NSpan(' ') & N * Num1 & Span(" ,") & N * Num2; + + The match operation Match (" 124, 257 ", T) would assign the + string 124 to Num1 and the string 257 to Num2. + + Now let's see how more complex elements can be built from the + set of primitive elements. The following pattern matches strings + that have the syntax of Ada 95 based literals: + + Digs : constant Pattern := Span(Decimal_Digit_Set); + UDigs : constant Pattern := Digs & Arbno('_' & Digs); + + Edig : constant Pattern := Span(Hexadecimal_Digit_Set); + UEdig : constant Pattern := Edig & Arbno('_' & Edig); + + Bnum : constant Pattern := Udigs & '#' & UEdig & '#'; + + A match against Bnum will now match the desired strings, e.g. + it will match 16#123_abc#, but not a#b#. However, this pattern + is not quite complete, since it does not allow colons to replace + the pound signs. The following is more complete: + + Bchar : constant Pattern := Any("#:"); + Bnum : constant Pattern := Udigs & Bchar & UEdig & Bchar; + + but that is still not quite right, since it allows # and : to be + mixed, and they are supposed to be used consistently. We solve + this by using a deferred match. + + Temp : aliased VString; + + Bnum : constant Pattern := + Udigs & Bchar * Temp & UEdig & (+Temp) + + Here the first instance of the base character is stored in Temp, and + then later in the pattern we rematch the value that was assigned. + + For an example of a recursive pattern, let's define a pattern + that is like the built in Bal, but the string matched is balanced + with respect to square brackets or curly brackets. + + The language for such strings might be defined in extended BNF as + + ELEMENT ::= <any character other than [] or {}> + | '[' BALANCED_STRING ']' + | '{' BALANCED_STRING '}' + + BALANCED_STRING ::= ELEMENT {ELEMENT} + + Here we use {} to indicate zero or more occurrences of a term, as + is common practice in extended BNF. Now we can translate the above + BNF into recursive patterns as follows: + + Element, Balanced_String : aliased Pattern; + . + . + . + Element := NotAny ("[]{}") + | + ('[' & (+Balanced_String) & ']') + | + ('{' & (+Balanced_String) & '}'); + + Balanced_String := Element & Arbno (Element); + + Note the important use of + here to refer to a pattern not yet + defined. Note also that we use assignments precisely because we + cannot refer to as yet undeclared variables in initializations. + + Now that this pattern is constructed, we can use it as though it + were a new primitive pattern element, and for example, the match: + + Match ("xy[ab{cd}]", Balanced_String * Current_Output & Fail); + + will generate the output: + + x + xy + xy[ab{cd}] + y + y[ab{cd}] + [ab{cd}] + a + ab + ab{cd} + b + b{cd} + {cd} + c + cd + d + + Note that the function of the fail here is simply to force the + pattern Balanced_String to match all possible alternatives. Studying + the operation of this pattern in detail is highly instructive. + + Finally we give a rather elaborate example of the use of deferred + matching. The following declarations build up a pattern which will + find the longest string of decimal digits in the subject string. + + Max, Cur : VString; + Loc : Natural; + + function GtS return Boolean is + begin + return Length (Cur) > Length (Max); + end GtS; + + Digit : constant Character_Set := Decimal_Digit_Set; + + Digs : constant Pattern := Span(Digit); + + Find : constant Pattern := + "" * Max & Fence & -- initialize Max to null + BreakX (Digit) & -- scan looking for digits + ((Span(Digit) * Cur & -- assign next string to Cur + (+GtS) & -- check size(Cur) > Size(Max) + Setcur(Loc)) -- if so, save location + * Max) & -- and assign to Max + Fail; -- seek all alternatives + + As we see from the comments here, complex patterns like this take + on aspects of sequential programs. In fact they are sequential + programs with general backtracking. In this pattern, we first use + a pattern assignment that matches null and assigns it to Max, so + that it is initialized for the new match. Now BreakX scans to the + next digit. Arb would do here, but BreakX will be more efficient. + Once we have found a digit, we scan out the longest string of + digits with Span, and assign it to Cur. The deferred call to GtS + tests if the string we assigned to Cur is the longest so far. If + not, then failure is signalled, and we seek alternatives (this + means that BreakX will extend and look for the next digit string). + If the call to GtS succeeds then the matched string is assigned + as the largest string so far into Max and its location is saved + in Loc. Finally Fail forces the match to fail and seek alternatives, + so that the entire string is searched. + + If the pattern Find is matched against a string, the variable Max + at the end of the pattern will have the longest string of digits, + and Loc will be the starting character location of the string. For + example, Match("ab123cd4657ef23", Find) will assign "4657" to Max + and 11 to Loc (indicating that the string ends with the eleventh + character of the string). + + Correspondence with Pattern Matching in SPITBOL + =============================================== + + Generally the Ada syntax and names correspond closely to SPITBOL + syntax for pattern matching construction. + + The basic pattern construction operators are renamed as follows: + + Spitbol Ada + + (space) & + | or + $ * + . ** + + The Ada operators were chosen so that the relative precedences of + these operators corresponds to that of the Spitbol operators, but + as always, the use of parentheses is advisable to clarify. + + The pattern construction operators all have similar names. + + The actual pattern matching syntax is modified in Ada as follows: + + Spitbol Ada + + X Y Match (X, Y); + X Y = Z Match (X, Y, Z); + + and pattern failure is indicated by returning a Boolean result from + the Match function (True for success, False for failure). + +----------------------- +Type Declarations +----------------------- + +type Pattern is private; + Type representing a pattern. This package provides a complete set of + operations for constructing patterns that can be used in the pattern + matching operations provided. + +type Boolean_Func is access function return Boolean; + General Boolean function type. When this type is used as a formal + parameter type in this package, it indicates a deferred predicate + pattern. The function will be called when the pattern element is + matched and failure signalled if False is returned. + +type Natural_Func is access function return Natural; + General Natural function type. When this type is used as a formal + parameter type in this package, it indicates a deferred pattern. + The function will be called when the pattern element is matched + to obtain the currently referenced Natural value. + +type VString_Func is access function return VString; + General VString function type. When this type is used as a formal + parameter type in this package, it indicates a deferred pattern. + The function will be called when the pattern element is matched + to obtain the currently referenced string value. + +subtype PString is String; + This subtype is used in the remainder of the package to indicate a + formal parameter that is converted to its corresponding pattern, + i.e. a pattern that matches the characters of the string. + +subtype PChar is Character; + Similarly, this subtype is used in the remainder of the package to + indicate a formal parameter that is converted to its corresponding + pattern, i.e. a pattern that matches this one character. + +subtype VString_Var is VString; +subtype Pattern_Var is Pattern; + These synonyms are used as formal parameter types to a function where, + if the language allowed, we would use in out parameters, but we are + not allowed to have in out parameters for functions. Instead we pass + actuals which must be variables, and with a bit of trickery in the + body, manage to interprete them properly as though they were indeed + in out parameters. + +-------------------------------- +Basic Pattern Construction +-------------------------------- + +function "&" (L : Pattern; R : Pattern) return Pattern; +function "&" (L : PString; R : Pattern) return Pattern; +function "&" (L : Pattern; R : PString) return Pattern; +function "&" (L : PChar; R : Pattern) return Pattern; +function "&" (L : Pattern; R : PChar) return Pattern; + + Pattern concatenation. Matches L followed by R + +function "or" (L : Pattern; R : Pattern) return Pattern; +function "or" (L : PString; R : Pattern) return Pattern; +function "or" (L : Pattern; R : PString) return Pattern; +function "or" (L : PString; R : PString) return Pattern; +function "or" (L : PChar; R : Pattern) return Pattern; +function "or" (L : Pattern; R : PChar) return Pattern; +function "or" (L : PChar; R : PChar) return Pattern; +function "or" (L : PString; R : PChar) return Pattern; +function "or" (L : PChar; R : PString) return Pattern; + Pattern alternation. Creates a pattern that will first try to match + L and then on a subsequent failure, attempts to match R instead. + +---------------------------------- +Pattern Assignment Functions +---------------------------------- + +function "*" (P : Pattern; Var : VString_Var) return Pattern; +function "*" (P : PString; Var : VString_Var) return Pattern; +function "*" (P : PChar; Var : VString_Var) return Pattern; + Matches P, and if the match succeeds, assigns the matched substring + to the given VString variable S. This assignment happens as soon as + the substring is matched, and if the pattern P1 is matched more than + once during the course of the match, then the assignment will occur + more than once. + +function "**" (P : Pattern; Var : VString_Var) return Pattern; +function "**" (P : PString; Var : VString_Var) return Pattern; +function "**" (P : PChar; Var : VString_Var) return Pattern; + Like "*" above, except that the assignment happens at most once + after the entire match is completed successfully. If the match + fails, then no assignment takes place. + +---------------------------------- +Deferred Matching Operations +---------------------------------- + +function "+" (Str : VString_Var) return Pattern; + Here Str must be a VString variable. This function constructs a + pattern which at pattern matching time will access the current + value of this variable, and match against these characters. + +function "+" (Str : VString_Func) return Pattern; + Constructs a pattern which at pattern matching time calls the given + function, and then matches against the string or character value + that is returned by the call. + +function "+" (P : Pattern_Var) return Pattern; + Here P must be a Pattern variable. This function constructs a + pattern which at pattern matching time will access the current + value of this variable, and match against the pattern value. + +function "+" (P : Boolean_Func) return Pattern; + Constructs a predicate pattern function that at pattern matching time + calls the given function. If True is returned, then the pattern matches. + If False is returned, then failure is signalled. + +-------------------------------- +Pattern Building Functions +-------------------------------- + +function Arb return Pattern; + Constructs a pattern that will match any string. On the first attempt, + the pattern matches a null string, then on each successive failure, it + matches one more character, and only fails if matching the entire rest + of the string. + +function Arbno (P : Pattern) return Pattern; +function Arbno (P : PString) return Pattern; +function Arbno (P : PChar) return Pattern; + Pattern repetition. First matches null, then on a subsequent failure + attempts to match an additional instance of the given pattern. + Equivalent to (but more efficient than) P & ("" | (P & ("" | ... + +function Any (Str : String) return Pattern; +function Any (Str : VString) return Pattern; +function Any (Str : Character) return Pattern; +function Any (Str : Character_Set) return Pattern; +function Any (Str : access VString) return Pattern; +function Any (Str : VString_Func) return Pattern; + Constructs a pattern that matches a single character that is one of + the characters in the given argument. The pattern fails if the current + character is not in Str. + +function Bal return Pattern; + Constructs a pattern that will match any non-empty string that is + parentheses balanced with respect to the normal parentheses characters. + Attempts to extend the string if a subsequent failure occurs. + +function Break (Str : String) return Pattern; +function Break (Str : VString) return Pattern; +function Break (Str : Character) return Pattern; +function Break (Str : Character_Set) return Pattern; +function Break (Str : access VString) return Pattern; +function Break (Str : VString_Func) return Pattern; + Constructs a pattern that matches a (possibly null) string which + is immediately followed by a character in the given argument. This + character is not part of the matched string. The pattern fails if + the remaining characters to be matched do not include any of the + characters in Str. + +function BreakX (Str : String) return Pattern; +function BreakX (Str : VString) return Pattern; +function BreakX (Str : Character) return Pattern; +function BreakX (Str : Character_Set) return Pattern; +function BreakX (Str : access VString) return Pattern; +function BreakX (Str : VString_Func) return Pattern; + Like Break, but the pattern attempts to extend on a failure to find + the next occurrence of a character in Str, and only fails when the + last such instance causes a failure. + +function Cancel return Pattern; + Constructs a pattern that immediately aborts the entire match + +function Fail return Pattern; + Constructs a pattern that always fails + +function Fence return Pattern; + Constructs a pattern that matches null on the first attempt, and then + causes the entire match to be aborted if a subsequent failure occurs. + +function Fence (P : Pattern) return Pattern; + Constructs a pattern that first matches P. if P fails, then the + constructed pattern fails. If P succeeds, then the match proceeds, + but if subsequent failure occurs, alternatives in P are not sought. + The idea of Fence is that each time the pattern is matched, just + one attempt is made to match P, without trying alternatives. + +function Len (Count : Natural) return Pattern; +function Len (Count : access Natural) return Pattern; +function Len (Count : Natural_Func) return Pattern; + Constructs a pattern that matches exactly the given number of + characters. The pattern fails if fewer than this number of characters + remain to be matched in the string. + +function NotAny (Str : String) return Pattern; +function NotAny (Str : VString) return Pattern; +function NotAny (Str : Character) return Pattern; +function NotAny (Str : Character_Set) return Pattern; +function NotAny (Str : access VString) return Pattern; +function NotAny (Str : VString_Func) return Pattern; + Constructs a pattern that matches a single character that is not + one of the characters in the given argument. The pattern Fails if + the current character is in Str. + +function NSpan (Str : String) return Pattern; +function NSpan (Str : VString) return Pattern; +function NSpan (Str : Character) return Pattern; +function NSpan (Str : Character_Set) return Pattern; +function NSpan (Str : access VString) return Pattern; +function NSpan (Str : VString_Func) return Pattern; + Constructs a pattern that matches the longest possible string + consisting entirely of characters from the given argument. The + string may be empty, so this pattern always succeeds. + +function Pos (Count : Natural) return Pattern; +function Pos (Count : access Natural) return Pattern; +function Pos (Count : Natural_Func) return Pattern; + Constructs a pattern that matches the null string if exactly Count + characters have already been matched, and otherwise fails. + +function Rem return Pattern; + Constructs a pattern that always succeeds, matching the remaining + unmatched characters in the pattern. + +function Rpos (Count : Natural) return Pattern; +function Rpos (Count : access Natural) return Pattern; +function Rpos (Count : Natural_Func) return Pattern; + Constructs a pattern that matches the null string if exactly Count + characters remain to be matched in the string, and otherwise fails. + +function Rtab (Count : Natural) return Pattern; +function Rtab (Count : access Natural) return Pattern; +function Rtab (Count : Natural_Func) return Pattern; + Constructs a pattern that matches from the current location until + exactly Count characters remain to be matched in the string. The + pattern fails if fewer than Count characters remain to be matched. + +function Setcur (Var : access Natural) return Pattern; + Constructs a pattern that matches the null string, and assigns the + current cursor position in the string. This value is the number of + characters matched so far. So it is zero at the start of the match. + +function Span (Str : String) return Pattern; +function Span (Str : VString) return Pattern; +function Span (Str : Character) return Pattern; +function Span (Str : Character_Set) return Pattern; +function Span (Str : access VString) return Pattern; +function Span (Str : VString_Func) return Pattern; + Constructs a pattern that matches the longest possible string + consisting entirely of characters from the given argument. The + string cannot be empty , so the pattern fails if the current + character is not one of the characters in Str. + +function Succeed return Pattern; + Constructs a pattern that succeeds matching null, both on the first + attempt, and on any rematch attempt, i.e. it is equivalent to an + infinite alternation of null strings. + +function Tab (Count : Natural) return Pattern; +function Tab (Count : access Natural) return Pattern; +function Tab (Count : Natural_Func) return Pattern; + Constructs a pattern that from the current location until Count + characters have been matched. The pattern fails if more than Count + characters have already been matched. + +--------------------------------- +Pattern Matching Operations +--------------------------------- + + The Match function performs an actual pattern matching operation. + The versions with three parameters perform a match without modifying + the subject string and return a Boolean result indicating if the + match is successful or not. The Anchor parameter is set to True to + obtain an anchored match in which the pattern is required to match + the first character of the string. In an unanchored match, which is + + the default, successive attempts are made to match the given pattern + at each character of the subject string until a match succeeds, or + until all possibilities have failed. + + Note that pattern assignment functions in the pattern may generate + side effects, so these functions are not necessarily pure. + +Anchored_Mode : Boolean := False; + This global variable can be set True to cause all subsequent pattern + matches to operate in anchored mode. In anchored mode, no attempt is + made to move the anchor point, so that if the match succeeds it must + succeed starting at the first character. Note that the effect of + anchored mode may be achieved in individual pattern matches by using + Fence or Pos(0) at the start of the pattern. + +Pattern_Stack_Overflow : exception; + Exception raised if internal pattern matching stack overflows. This + is typically the result of runaway pattern recursion. If there is a + genuine case of stack overflow, then either the match must be broken + down into simpler steps, or the stack limit must be reset. + +Stack_Size : constant Positive := 2000; + Size used for internal pattern matching stack. Increase this size if + complex patterns cause Pattern_Stack_Overflow to be raised. + + Simple match functions. The subject is matched against the pattern. + Any immediate or deferred assignments or writes are executed, and + the returned value indicates whether or not the match succeeded. + +function Match + (Subject : VString; + Pat : Pattern) return Boolean; + +function Match + (Subject : VString; + Pat : PString) return Boolean; + +function Match + (Subject : String; + Pat : Pattern) return Boolean; + +function Match + (Subject : String; + Pat : PString) return Boolean; + + Replacement functions. The subject is matched against the pattern. + Any immediate or deferred assignments or writes are executed, and + the returned value indicates whether or not the match succeeded. + If the match succeeds, then the matched part of the subject string + is replaced by the given Replace string. + +function Match + (Subject : VString_Var; + Pat : Pattern; + Replace : VString) return Boolean; + +function Match + (Subject : VString_Var; + Pat : PString; + Replace : VString) return Boolean; + +function Match + (Subject : VString_Var; + Pat : Pattern; + Replace : String) return Boolean; + +function Match + (Subject : VString_Var; + Pat : PString; + Replace : String) return Boolean; + +Deferred Replacement + +type Match_Result is private; + Type used to record result of pattern match + +subtype Match_Result_Var is Match_Result; + This synonyms is used as a formal parameter type to a function where, + if the language allowed, we would use an in out parameter, but we are + not allowed to have in out parameters for functions. Instead we pass + actuals which must be variables, and with a bit of trickery in the + body, manage to interprete them properly as though they were indeed + in out parameters. + +function Match + (Subject : VString_Var; + Pat : Pattern; + Result : Match_Result_Var) return Boolean; + +procedure Match + (Subject : in out VString; + Pat : Pattern; + Result : out Match_Result); + +procedure Replace + (Result : in out Match_Result; + Replace : VString); + Given a previous call to Match which set Result, performs a pattern + replacement if the match was successful. Has no effect if the match + failed. This call should immediately follow the Match call. + +------------------------ +Debugging Routines +------------------------ + + Debugging pattern matching operations can often be quite complex, + since there is no obvious way to trace the progress of the match. + The declarations in this section provide some debugging assistance. + +Debug_Mode : Boolean := False; + This global variable can be set True to generate debugging on all + subsequent calls to Match. The debugging output is a full trace of + the actions of the pattern matcher, written to Standard_Output. The + level of this information is intended to be comprehensible at the + abstract level of this package declaration. However, note that the + use of this switch often generates large amounts of output. + +function "*" (P : Pattern; Fil : File_Access) return Pattern; +function "*" (P : PString; Fil : File_Access) return Pattern; +function "*" (P : PChar; Fil : File_Access) return Pattern; +function "**" (P : Pattern; Fil : File_Access) return Pattern; +function "**" (P : PString; Fil : File_Access) return Pattern; +function "**" (P : PChar; Fil : File_Access) return Pattern; + These are similar to the corresponding pattern assignment operations + except that instead of setting the value of a variable, the matched + substring is written to the appropriate file. This can be useful in + following the progress of a match without generating the full amount + of information obtained by setting Debug_Mode to True. + +Terminal : constant File_Access := Standard_Error; +Output : constant File_Access := Standard_Output; + Two handy synonyms for use with the above pattern write operations + + Finally we have some routines that are useful for determining what + patterns are in use, particularly if they are constructed dynamically. + +function Image (P : Pattern) return String; +function Image (P : Pattern) return VString; + This procedures yield strings that corresponds to the syntax needed + to create the given pattern using the functions in this package. The + form of this string is such that it could actually be compiled and + evaluated to yield the required pattern except for references to + variables and functions, which are output using one of the following + forms: +-- + access Natural NP(16#...#) + access Pattern PP(16#...#) + access VString VP(16#...#) +-- + Natural_Func NF(16#...#) + VString_Func VF(16#...#) +-- + where 16#...# is the hex representation of the integer address that + corresponds to the given access value + +procedure Dump (P : Pattern); + This procedure writes information about the pattern to Standard_Out. + The format of this information is keyed to the internal data structures + used to implement patterns. The information provided by Dump is thus + more precise than that yielded by Image, but is also a bit more obscure + (i.e. it cannot be interpreted solely in terms of this spec, you have + to know something about the data structures). + +procedure Finalize (Object : in out Pattern); + Finalization routine used to release storage allocated for a pattern + + + + diff --git a/doc/reference.xml b/doc/reference.xml new file mode 100644 index 0000000..0e4d5be --- /dev/null +++ b/doc/reference.xml @@ -0,0 +1,2005 @@ +<?xml version="1.0"?> + +<!-- + LSPIPAT - LUA SPIPAT WRAPPER + Copyright (C) 2010, Robin Haberkorn + License: LGPL + + DOCUMENTATION AND MODULE REFERENCE +--> + +<book xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink"> + <info> + <title>SNOBOL/SPITBOL Patterns for Lua</title> + <subtitle>libspipat Lua wrapper</subtitle> + <titleabbrev>lspipat</titleabbrev> + + <author> + <personname><firstname>Robin</firstname> <surname>Haberkorn</surname></personname> + <email>robin.haberkorn at googlemail.com</email> + </author> + <copyright> + <year>2010</year><holder>Robin Haberkorn</holder> + </copyright> + + <mediaobject> + <imageobject><imagedata format="PNG" fileref="lspipat.png"/></imageobject> + </mediaobject> + + <abstract><para> + The following document is the <productname>lspipat</productname> + Lua 5.1 module documentation and reference. + </para></abstract> + </info> + + <acknowledgements> + <title>Thanks To...</title> + + <para> + <productname>lspipat</productname> would not be possible without: + </para> + <itemizedlist> + <listitem> + <firstname>Phil</firstname> <surname>Budne</surname>, for <productname>spipat</productname>. + <productname>lspipat</productname> is merely a <productname>spipat</productname> wrapper. + </listitem><listitem> + <firstname>Robert</firstname> <surname>Dewar</surname> who has created Macro SPITBOL and + the GNAT.Spitbol package. + <productname>spipat</productname> was derived from GNAT.Spitbol, which is based on Macro SPITBOL. + </listitem> + </itemizedlist> + </acknowledgements> + + <preface> + <title>Introduction</title> + + <para> + <productname>lspipat</productname> is a wrapper to <productname>spipat</productname> + that brings support for a first-class SNOBOL/SPITBOL-like pattern data type. + Patterns can be constructed and subsequently combined with other patterns, + strings, numbers and functions using binary and unary operators allowing + the construction of grammars describing any <emphasis>Context Free Language</emphasis>. + Patterns can be matched against any Lua string. + A major difference to other pattern matching techniques like regular expressions, besides + the supported language class, is the possibility to construct patterns/grammars in a + readable and intuitive way, somewhat reminiscent of the <emphasis>BNF</emphasis>. + </para><para> + They can include pattern elements that have side-effects (i.e. Lua code executed during + pattern matching) or produce and influence pattern elements dynamically. + For instance, functions can be specified that are executed during matching to produce + the parameters necessary for the interpretation of a pattern element. + Code can be embedded that generates entire patterns on the fly. + Matching previously matched substrings and implementing recursive patterns + is only one application of the powerful dynamic pattern elements traditionally + offered by SNOBOL pattern matching and thus by <productname>lspipat</productname>. + </para><para> + SNOBOL/SPITBOL pattern matching was traditionally used in compiler construction + and prototyping, artificial intelligence research and the humanities. + </para> + </preface> + + <chapter> + <title>Resources</title> + + <para> + These internet resources are more or less directly related to <productname>lspipat</productname> and + might be useful to you: + + <itemizedlist> + <listitem> + <link xlink:href="http://luaforge.net/projects/lspipat/">http://luaforge.net/projects/lspipat/</link>: + <productname>lspipat</productname> project page at LuaForge, downloads, bug tracker, etc. + </listitem><listitem> + <link xlink:href="http://www.snobol4.org/spipat/">http://www.snobol4.org/spipat/</link>: + <productname>libspipat</productname> downloads + </listitem><listitem> + <link xlink:href="http://pypi.python.org/pypi/spipat/">http://pypi.python.org/pypi/spipat/</link>: + <productname>libspipat's</productname> Python wrapper (included in <productname>libspipat</productname> + packages). + </listitem><listitem> + <link xlink:href="http://www.infeig.unige.ch/support/ada/gnatlb/g-spipat.html">http://www.infeig.unige.ch/support/ada/gnatlb/g-spipat.html</link>: + <productname>GNAT.Spitbol</productname> description. Also installed as <filename>pattern.txt</filename> by <productname>lspipat</productname>. + </listitem><listitem> + <link xlink:href="ftp://ftp.cs.arizona.edu/snobol/gb.pdf">ftp://ftp.cs.arizona.edu/snobol/gb.pdf</link>: + The SNOBOL4 Programming Language (The famous <emphasis>Green Book</emphasis>) + </listitem><listitem> + <link xlink:href="ftp://ftp.snobol4.com/spitman.pdf">ftp://ftp.snobol4.com/spitman.pdf</link>: + Macro SPITBOL Reference Manual + </listitem><listitem> + <link xlink:href="http://www.snobol4.org/">other interesting resources compiled by Phil Budne...</link> + </listitem> + </itemizedlist> + </para> + </chapter> + + <chapter> + <title>Comparison with SNOBOL</title> + + <para> + Just as patterns in <productname>SNOBOL</productname> are combined and constructed dynamically with + binary and unary operators, <productname>lspipat</productname> also uses operators available in + Lua to construct patterns in a simple and intuitive way. + The operators and pattern-construction functions were chosen, so the pattern construction syntax + is as similar as possible to <productname>SNOBOL</productname>/<productname>SPITBOL</productname>. + The following table shows a comparision of operators between + <productname>SPITBOL</productname> and <productname>lspipat</productname>: + </para> + <table xml:id="operator_comparison"> + <title>Comparision of SPITBOL and lspipat operators</title> + + <tgroup cols="4" colsep="1" rowsep="1"> + <colspec colnum="2" align="center"/> <!-- operators --> + <colspec colnum="3" align="center"/> + + <thead> + <row> + <entry>Operation</entry> + <entry>SPITBOL</entry> + <entry>lspipat</entry> + <entry>Notes</entry> + </row> + </thead><tbody> + <row> + <entry>Alternation</entry> + <entry><command>|</command></entry> + <entry><command>+</command></entry> + <entry morerows="1"><para> + Refer to <xref linkend="composition"/>. + Cannot be used to combine two <emphasis>strings</emphasis>. + </para></entry> + </row><row> + <entry>Concatenation</entry> + <entry><emphasis>(space)</emphasis></entry> + <entry><command>*</command></entry> + </row><row> + <entry>Immediate Assignment/Call</entry> + <entry><command>$</command></entry> + <entry><command>%</command></entry> + <entry morerows="1"><para> + <link linkend="assignment"><command>%</command> and <command>/</command></link> have the + <link xlink:href="http://www.lua.org/manual/5.1/manual.html#2.5.6">same precedence</link> + as <link linkend="concat"><command>*</command></link> in Lua. + Also only call versions are supported (see <xref linkend="deferring"/>). + </para></entry> + </row><row> + <entry>Deferred Assignment/Call</entry> + <entry><command>.</command></entry> + <entry><command>/</command></entry> + </row><row> + <entry morerows="1">Cursor Assignment</entry> + <entry morerows="1"><command>@</command> <emphasis>(unary)</emphasis></entry> + <entry><command>#</command> <emphasis>(unary)</emphasis></entry> + <entry morerows="1"><para> + Refer to <xref linkend="cursor"/>. + <productname>lspipat</productname> only supports a call version + (see <xref linkend="deferring"/>). + </para></entry> + </row><row> + <!-- <entry/> --> + <!-- <entry/> --> + <entry><command>Setcur</command></entry> + </row><row> + <entry>Defer Expression</entry> + <entry><command>*</command> <emphasis>(unary)</emphasis></entry> + <entry morerows="1"><command>-</command> <emphasis>(unary)</emphasis> or <command>Pred</command></entry> + <entry morerows="1"><para> + Refer to <xref linkend="predicate"/>. + In general, expressions can be wrapped in (anonymous) functions to defer them. + </para></entry> + </row><row> + <entry>Interrogation/Predicate</entry> + <entry><command>?</command> <emphasis>(unary)</emphasis></entry> + <!-- <entry/> --> + </row><row> + <entry morerows="1">Pattern Match</entry> + <entry><command>?</command></entry> + <entry morerows="1"><command>smatch</command></entry> + <entry morerows="1"><para> + Refer to <xref linkend="smatch"/>. + <code>S ? P</code> is roughly equivalent to <code>S:smatch(P)</code> in Lua. + </para></entry> + </row><row> + <!-- <entry/> --> + <entry><emphasis>(space)</emphasis></entry> + <!-- <entry/> --> + </row><row> + <entry>Substring Replacement</entry> + <entry><command>=</command></entry> + <entry><command>ssub</command></entry> + <entry><para> + Refer to <xref linkend="ssub"/>. + <code>S P = R</code> is roughly equivalent to <code>S:ssub(P, R, 1)</code> in Lua. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </chapter> + + <chapter> + <title>Installation</title> + + <para> + <productname>lspipat</productname> uses an autotools buildsystem. The standard + <filename>INSTALL</filename> file contains instructions on how to use it from + a package builder's perspective. + Nevertheless, there are some quirks that should be mentioned. + </para> + + <section> + <title>Dependencies</title> + + <itemizedlist> + <listitem><para> + <link xlink:href="http://www.snobol4.org/spipat/test/spipat-0.9.3%2b.tar.gz">spipat 0.9.3+</link>: + You are advised to apply the patch <filename>spipat-patches/0.9.3+_image.patch</filename> first + before building <productname>spipat</productname>, even though it is not mandatory. + It fixes a header file (so <productname>lspipat</productname> can make use of customized + <link linkend="tostring">render-to-string</link> functionality) and various bugs. + </para></listitem> + <listitem><para> + <link xlink:href="http://www.lua.org/download.html">Lua 5.1</link>: + You probably have this already. The <filename>configure</filename> script + should be able to cope with <productname>Ubuntu</productname> and + <link xlink:href="http://lua-users.org/wiki/LuaBinaries">Lua Binaries</link> + distributions. The standalone Lua compiler is only required if + <link linkend="precompile">compilation of Lua scripts</link> is enabled. + </para></listitem> + </itemizedlist> + </section> + + <section> + <title>Configuration Options</title> + + <para> + The following special <filename>configure</filename> script options + are supported: + </para> + <variablelist> + <varlistentry> + <term><arg choice="plain">--enable-lua-libdir=<replaceable>DIR</replaceable></arg></term> + <listitem><para> + Change the installation directory of <productname>lspipat</productname>. + It defaults to <filename>LIBDIR/lua/5.1</filename>. You probably want this to + point to some directory in Lua's + <link xlink:href="http://www.lua.org/manual/5.1/manual.html#pdf-require"> + module search path</link>, so the default should be ok. + </para></listitem> + </varlistentry> + <varlistentry xml:id="precompile"> + <term><arg choice="plain">--disable-lua-precompile</arg></term> + <listitem><para> + Disable precompilation of Lua source files. + Naturally, a Lua compiler will not be required when this option + is used. + </para></listitem> + </varlistentry> + <varlistentry> + <term><arg choice="plain">--disable-lua-strip</arg></term> + <listitem><para> + Do not strip (i.e. remove debugging symbols from) compiled + Lua sources. + </para></listitem> + </varlistentry> + <varlistentry> + <term><arg choice="plain">--disable-html-doc</arg></term> + <listitem><para> + Do not generate HTML documentation. The documentation is usually + derived from <productname>Docbook</productname> using + <application>XSLTProc</application>. + Disabling this may be useful if you have got some problem + with the tool chain but are satisfied with the precompiled + documentation in the distribution. + </para></listitem> + </varlistentry> + </variablelist> + <para> + Furthermore, you should note that <link linkend="tostring">render-to-string</link> results are not + reminiscent of <productname>lspipat</productname> syntax (used in this document) by default. + For <productname>lspipat</productname> to be able to customize these renderings, + <filename>configure</filename> has to find some <productname>spipat</productname> headers which + are not normally installed. + Therefore it is highly recommended to add spipat's source directory to the C include search path + using the <envar>CPPFLAGS</envar> variable before running <filename>configure</filename>. + </para> + </section> + + <para> + Thus, supposing that <productname>spipat</productname> sources are located in your home directory, + the most common way to install <productname>lspipat</productname> would be: + </para> + <informalexample> + <programlisting><![CDATA[./configure CPPFLAGS=-I~/spipat-0.9.3+ +make install]]></programlisting> + </informalexample> + </chapter> + + <chapter> + <title>Usage</title> + + <para> + After <productname>lspipat</productname> has been installed properly, you will + be able use it in your Lua program by simply requiring <literal>lspipat</literal> + (i.e. <code>require "lspipat"</code>). + </para><para> + The module table will be called <literal>spipat</literal>, but many functions + (especially pattern constructors) will be registered as globals as well. + Also, some operators will be overloaded. + For details on all that (operators, globals, etc.) refer to + <xref linkend="reference"/>. + </para> + </chapter> + + <chapter> + <title>Examples</title> + + <para> + The <filename>samples</filename> directory in the <productname>lspipat</productname> source package + contains some small examples that I hope give you some inspiration on how and where to use + <productname>lspipat</productname>. + </para> + <variablelist> + <varlistentry> + <term><filename>samples/exp2bf.lua</filename></term> + <listitem> + <cmdsynopsis><command>exp2bf.lua</command> <arg choice="plain"><replaceable>expression</replaceable></arg></cmdsynopsis> + <para> + Compiles simple arithmetic expressions to Brainfuck programs that when + executed evaluate the expression and print the result + (8-bit unsigned integer arithmetics). + Prints these programs to <emphasis>stdout</emphasis>. + </para><para> + Use that for whatever you can imagine ;-) + </para> + </listitem> + </varlistentry><varlistentry> + <term><filename>samples/wave.lua</filename></term> + <listitem> + <cmdsynopsis><command>wave.lua</command> <arg choice="plain"><replaceable>wavefile</replaceable></arg></cmdsynopsis> + <para> + Validates/parses <filename>WAV</filename> files + and prints some information about it. + </para><para> + This is an example of how to use <productname>lspipat</productname> + to do pattern matching on "binary" data (formats, protocols). Some + primitives were implemented in Lua for that reason - in the future + there might be a separate C-module to do the encoding/decoding of + integers in different byte-orders more efficiently. + </para> + </listitem> + </varlistentry><varlistentry> + <term><filename>samples/regexp.lua</filename></term> + <listitem><para> + Small regular expression example/test - uses a comprehensive regular + expression describing IPs. + </para></listitem> + </varlistentry> + </variablelist> + </chapter> + + <chapter xml:id="deferring"> + <title>Variable Deferring Techniques</title> + + <para> + In SNOBOL, arbitrary expressions could be <emphasis>deferred</emphasis> + (i.e. their evaluation could be deferred) by using the unary asterisk operator. + With <productname>lspipat</productname> however, you will have to pass functions + (which can be constructed anonymously) to the appropriate constructors to achieve + the same goal. + </para><para> + Deferring expressions which should be combined with other patterns is one + application of the <link linkend="predicate"><command>Pred</command> constructor</link> + and <command>-</command> operator respectively. + </para><para> + Deferring variables is just a special case of deferring expressions. + In this chapter, different ways of optimizing variable deferrings will be + explained using a simple example. + </para><para> + For instance if you would like to <link linkend="assignment">assign</link> a + matched quotation character to a local variable and use that to subsequently match + a simple quote/string, you could use function closures to write something like that: + </para> + <example> + <title>Function Closures for Deferring Purposes</title> + + <programlisting language="lua">local cquote +string = <link linkend="Any">Any</link>("\"'") / function(c) cquote = c end + * <link linkend="Break">Break</link>(function() return cquote end) + * -function() return cquote end</programlisting> + </example> + <para> + You may find this solution a bit verbose, compared with + SNOBOL's elegant syntax. + To save some typing you could define your own constructors + that take the name of a global variable (as a string) + and construct patterns whose arguments are retrieved by + a function closure accessing the globals table. + </para> + <example> + <title>Custom Constructors for Deferring Purposes</title> + + <programlisting language="lua">function _Break(name) + return <link linkend="Break">Break</link>(function() return _G[name] end) +end +function _Pred(name) + return -function() return _G[name] end +end + +string = <link linkend="Any">Any</link>("\"'") / function(c) cquote = c end + * _Break "cquote" + * _Pred "cquote"</programlisting> + </example> + <para> + Of course, if you do not want to pollute the global namespace + your custom functions could just as well access a local table. + Furthermore, you could optimize the code by defining one generic + table access function which is suitable to be used for + <productname>lspipat</productname>'s pattern constructors - + being able to pass so called <emphasis>cookies</emphasis> + to functions comes in handy. + </para> + <example> + <title>Generic Retrievers for Deferring Purposes</title> + + <programlisting language="lua">function getGlobal(name) return _G[name] end +function _Break(name) return <link linkend="Break">Break</link>(getGlobal, name) end +function _Pred(name) return <link linkend="Pred">Pred</link>(getGlobal, name) end +-- ...</programlisting> + </example> + <para> + Fortunately, <productname>lspipat</productname> already defines + such constructors (deferring global variables) for you. + Whereever possible, there will be versions of constructors + with leading underscores that work similar to the ones in + the example above. + You can of course overwrite these constructors, e.g. with + versions accessing a special local table. + </para> + + <section> + <title>Recursive Patterns</title> + + <para> + Recursive patterns can be implemented just as described above. + Supposing you want to match the repetition of the predefined pattern + <literal>P</literal> (<emphasis>greedy</emphasis>) you could write + something like that: + </para> + <example> + <title>Recursive Patterns</title> + + <programlisting language="lua"><![CDATA[foo = P * -"foo" + ""]]></programlisting> + </example> + <para> + Sometimes however when using global variables is inappropriate, + you might want to do the following trick: + </para> + <example> + <title>Recursive Pattern Trick</title> + + <programlisting language="lua"><![CDATA[local function foo() return foo end +foo = P * -foo + ""]]></programlisting> + </example> + <para> + It works because <literal>foo</literal> is still a function in the scope + of the assignment's right side, but a pattern afterwards so the + function - to which no (direct) reference exists anymore - will return + the pattern <literal>foo</literal> after the assignment. + </para> + </section> + </chapter> + + <reference xml:id="reference"> + <title>Module Reference</title> + + <partintro><para> + A compilation of all functions in the <productname>lspipat</productname> + module, global functions registered by the module, methods + and overloaded operators follows. + </para></partintro> + + <refentry xml:id="smatch"> + <refmeta><refentrytitle>smatch</refentrytitle></refmeta> + + <refnamediv> + <refname>smatch</refname> + <refpurpose>Perform pattern match on a subject string</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.smatch</command> + ( <arg choice="plain"><replaceable>subject</replaceable></arg> + <arg choice="plain">, <replaceable>pattern</replaceable></arg> + <arg>, <replaceable>flags</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><replaceable>subject</replaceable>:smatch</command> + ( <arg choice="plain"><replaceable>pattern</replaceable></arg> + <arg>, <replaceable>flags</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Tries to match <emphasis>pattern</emphasis> against <emphasis>subject</emphasis> + using the given <emphasis>flags</emphasis>. + </para> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist> + <listitem>subject (<emphasis>string</emphasis>): A string against which the pattern match will be performed</listitem> + <listitem>pattern (<emphasis>userdata</emphasis>): The pattern used for matching</listitem> + <listitem> + flags (<emphasis>number</emphasis> or <emphasis>nil</emphasis>): + Optional <productname>spipat</productname> flags. + </listitem> + </orderedlist> + + <refsect2 xml:id="spipat_flags"> + <title>Spipat Flags</title> + + <para> + Flags are added (e.g. <code>spipat.match_anchored + spipat.match_debug</code>), + due to the lack of a logical/binary <emphasis>or</emphasis> operator in Lua. + </para> + <itemizedlist> + <listitem> + <literal>spipat.match_anchored</literal>: Match in anchored mode + </listitem><listitem> + <literal>spipat.match_debug</literal>: + Match with progress being printed to <emphasis>stdout</emphasis>. + Useful for pattern debugging as the name suggests. + </listitem> + </itemizedlist> + </refsect2> + </refsect1><refsect1> + <title>Return Values</title> + + <para> + In case of an exception during matching, raises an error. + In case no substring matches, returns a single <emphasis>nil</emphasis> value. + Otherwise returns + </para> + <orderedlist> + <listitem><emphasis>number</emphasis>: Start of matched substring</listitem> + <listitem><emphasis>number</emphasis>: End of matched substring</listitem> + </orderedlist> + </refsect1> + </refentry> + + <refentry xml:id="ssub"> + <refmeta><refentrytitle>ssub</refentrytitle></refmeta> + + <refnamediv> + <refname>ssub</refname> + <refpurpose>Substitute substrings matching a pattern in a subject</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.ssub</command> + ( <arg choice="plain"><replaceable>subject</replaceable></arg> + <arg choice="plain">, <replaceable>pattern</replaceable></arg> + <arg choice="plain">, <replaceable>replacement</replaceable></arg> + <arg><arg choice="plain">, <replaceable>n</replaceable></arg><arg>, <replaceable>flags</replaceable></arg></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><replaceable>subject</replaceable>:ssub</command> + ( <arg choice="plain"><replaceable>pattern</replaceable></arg> + <arg choice="plain">, <replaceable>replacement</replaceable></arg> + <arg><arg choice="plain">, <replaceable>n</replaceable></arg><arg>, <replaceable>flags</replaceable></arg></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Substitutes regions in <emphasis>subject</emphasis> matching <emphasis>pattern</emphasis> either with a string + if <emphasis>replacement</emphasis> is a string or if <emphasis>replacement</emphasis> is a function, the result + of calling that function. This may be useful for deferring the evaluation of replacement strings + which depend on (are built from) results of the matching process (e.g. call-on-match or call-immediately function executions). + </para> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist> + <listitem>subject (<emphasis>string</emphasis>): The subject for the first pattern match</listitem> + <listitem>pattern (<emphasis>userdata</emphasis>): The pattern used for matching</listitem> + <listitem> + replacement (<emphasis>string</emphasis> or <emphasis>function</emphasis>): + Replacement string or a function that's executed after matching to produce the replacement string + </listitem><listitem> + n (<emphasis>number</emphasis> or <emphasis>nil</emphasis>): + Optional maximal number of match/replacement operations. The first match + is performed on <emphasis>subject</emphasis>, subsequent matches on the result of the preceding + replacements. Naturally replacement stops when the pattern does not match anymore. + If <emphasis>n</emphasis> is absent or nil, replacement only stops when <emphasis>pattern</emphasis> + does not match anymore. + </listitem><listitem> + flags (<emphasis>number</emphasis> or <emphasis>nil</emphasis>): + Optional <productname>spipat</productname> flags, as in <xref linkend="spipat_flags"/>. + </listitem> + </orderedlist> + </refsect1><refsect1> + <title>Return Values</title> + + <para> + In case of an exception during matching, raises an error. + Otherwise returns + </para> + <orderedlist> + <listitem> + <emphasis>string</emphasis>: The result of the last replacement performed or the original + <emphasis>subject</emphasis> if no substring matched at all + </listitem><listitem> + <emphasis>number</emphasis>: The number of match/replacement operations actually performed + </listitem> + </orderedlist> + </refsect1><refsect1> + <title>Example</title> + + <example> + <title>Replacements with spipat.ssub</title> + + <screen>> print(spipat.ssub("abc ccC bab", <link linkend="Span">Span</link>("abc") / function(s) str = s end, function() return "["..str:upper().."]" end, 2)) +[ABC] [CC]C BaB +></screen> + </example> + </refsect1> + </refentry> + + <refentry xml:id="siter"> + <refmeta><refentrytitle>siter</refentrytitle></refmeta> + + <refnamediv> + <refname>siter</refname> + <refpurpose>Return iterator of substrings matching a pattern in a subject</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.siter</command> + ( <arg choice="plain"><replaceable>subject</replaceable></arg> + <arg choice="plain">, <replaceable>pattern</replaceable></arg> + <arg>, <replaceable>flags</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><replaceable>subject</replaceable>:siter</command> + ( <arg choice="plain"><replaceable>pattern</replaceable></arg> + <arg>, <replaceable>flags</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Returns an iterator function performing a <emphasis>pattern</emphasis> match on <emphasis>subject</emphasis> + and returning the matched substring (start/end positions in <emphasis>subject</emphasis>). + Each time it is called, it begins matching where the last substring ended, but using the same + <emphasis>subject</emphasis>. + </para> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist> + <listitem>subject (<emphasis>string</emphasis>): The subject used for pattern matching</listitem> + <listitem> + pattern (<emphasis>userdata</emphasis>): The pattern used for matching. + Naturally, anchoring the <emphasis>pattern</emphasis> using any of the possible methods is nonsense. + </listitem><listitem> + flags (<emphasis>number</emphasis> or <emphasis>nil</emphasis>): + Optional <productname>spipat</productname> flags, as in <xref linkend="spipat_flags"/>. + </listitem> + </orderedlist> + </refsect1><refsect1> + <title>Return Values</title> + + <para> + In case of an exception during matching, raises an error. + Otherwise returns + </para> + <orderedlist><listitem> + <emphasis>function</emphasis>: The iterator function. Calling it returns + <orderedlist> + <listitem><emphasis>number</emphasis>: Start of matched substring</listitem> + <listitem><emphasis>number</emphasis>: End of matched substring</listitem> + </orderedlist> + </listitem></orderedlist> + </refsect1><refsect1> + <title>Example</title> + + <example xml:id="example_siter"> + <title>Iterating through substrings with spipat.siter</title> + + <screen>> str = "abc" +> for s, e in str:siter(<link linkend="Len">Len</link>(1)) do print(str:sub(s, e)) end +a +b +c +></screen> + </example> + </refsect1> + </refentry> + + <refentry xml:id="free"> + <refmeta><refentrytitle>free</refentrytitle></refmeta> + + <refnamediv> + <refname>free</refname> + <refpurpose>Finalize pattern</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.free</command>( <arg choice="plain"><replaceable>pattern</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><replaceable>pattern</replaceable>:free</command>() + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Finalizes <emphasis>pattern</emphasis>, i.e. frees memory associated with it and unreferences any + other Lua values (other patterns, functions, etc.) so they can get garbage collected. + </para><para> + Finalizing an already finalized <emphasis>pattern</emphasis> does nothing. + Using a finalized <emphasis>pattern</emphasis> in any function or operator working with a pattern + will raise an error. + </para> + <tip><para> + <command>free</command> does early what would otherwise be done when the pattern is garbage + collected, so in most cases you will not need it at all. + It may be useful when you would like to free a large pattern you do not need anymore but + removing all references to that pattern and enforcing a full garbage collection cycle + is not feasible. + </para></tip> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist><listitem> + pattern (<emphasis>userdata</emphasis>): The pattern to be finalized + </listitem></orderedlist> + </refsect1><refsect1> + <title>Return Values</title> + + <para> + Returns nothing. + </para> + </refsect1><refsect1> + <title>Example</title> + + <example> + <title>Finalizing a pattern</title> + + <screen>> p = <link linkend="Arb">Arb</link>() +> p:free() +> print(p * "foo") +stdin:1: Pattern already freed +></screen> + </example> + </refsect1> + </refentry> + + <refentry xml:id="conversion"> + <refmeta><refentrytitle>Conversion</refentrytitle></refmeta> + + <refnamediv xml:id="topattern"> + <refname>topattern</refname> + <refpurpose>Convert a value to a pattern</refpurpose> + </refnamediv> + <refnamediv xml:id="tostring"> + <refname>tostring</refname> + <refpurpose>Render a pattern as a string</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.topattern</command>( <arg choice="plain"><replaceable>value</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>topattern</command>( <arg choice="plain"><replaceable>value</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><replaceable>value</replaceable>:topattern</command>() + </cmdsynopsis> + + <cmdsynopsis> + <command>tostring</command>( <arg choice="plain"><replaceable>pattern</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>topattern</command> creates a pattern for a string or number, matching that string or number. + If <emphasis>value</emphasis> is already a pattern it returns that pattern without modification. + In case of an unsupported <emphasis>value</emphasis> type or miscelleaneous error, topattern always + returns nil. + </para> + <tip><para> + <command>topattern</command> is useful to explicitly create pattern, e.g. when an operator requires + at least one operand to be a pattern but both are strings, numbers or functions. + </para></tip> + <para> + Lua's <link xlink:href="http://www.lua.org/manual/5.1/manual.html#pdf-tostring">built-in <command>tostring</command></link> + function called on a <emphasis>pattern</emphasis> renders that pattern as a string reminiscent of + lspipat's pattern construction syntax. + </para> + <!-- + <note><para> + The C++ wrapper overloads different operators than <productname>lspipat</productname> does, + so <command>tostring</command> return values might look confusing if you are only used to + <productname>lspipat</productname>. + </para></note> + --> + <!-- + <warning><para> + spipat's rendering support is quite buggy and has to be considered <emphasis>experimental</emphasis> + at this point. You are advised not to use <command>tostring</command>. + For debugging purposes you might want to have a look at + <link linkend="dump"><command>spipat.dump</command></link>. + </para></warning> + --> + </refsect1><refsect1> + <title>Example</title> + + <example> + <title>Explicit pattern construction & implicit conversion to strings</title> + + <screen><![CDATA[> print("2" + 3) +5 +> print(topattern("2") + 3) +("2" + "3") +>]]></screen> + </example> + </refsect1> + </refentry> + + <refentry xml:id="dump"> + <refmeta><refentrytitle>dump</refentrytitle></refmeta> + + <refnamediv> + <refname>dump</refname> + <refpurpose>Dump a pattern to stdout</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.dump</command>( <arg choice="plain"><replaceable>pattern</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>dump</command> prints information about a <emphasis>pattern</emphasis> to + <emphasis>stdout</emphasis>. + The kind of information displayed is similar to <link linkend="tostring"> + <command>tostring</command>'s rendering</link>. + </para><para> + It is useful for debugging purposes. + </para> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist><listitem> + pattern (<emphasis>userdata</emphasis>): The pattern to be dumped + </listitem></orderedlist> + </refsect1><refsect1> + <title>Return Values</title> + + <para> + Returns nothing. + </para> + </refsect1> + </refentry> + + <refentry xml:id="composition"> + <refmeta><refentrytitle>Concatenation and Alternation</refentrytitle></refmeta> + + <refnamediv xml:id="concat"> + <refname>*</refname> + <refpurpose>Concatenate patterns</refpurpose> + </refnamediv> + <refnamediv xml:id="alternate"> + <refname>+</refname> + <refpurpose>Alternate patterns</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>*</command> + <arg choice="plain"><replaceable>value</replaceable></arg> + </cmdsynopsis><cmdsynopsis> + <arg choice="plain"><replaceable>value</replaceable></arg><command>*</command> + <arg choice="plain"><replaceable>pattern</replaceable></arg> + </cmdsynopsis><cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>*</command> + <arg choice="plain"><replaceable>pattern</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>+</command> + <arg choice="plain"><replaceable>value</replaceable></arg> + </cmdsynopsis><cmdsynopsis> + <arg choice="plain"><replaceable>value</replaceable></arg><command>+</command> + <arg choice="plain"><replaceable>pattern</replaceable></arg> + </cmdsynopsis><cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>+</command> + <arg choice="plain"><replaceable>pattern</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>*</command> operator constructs a concatenation of two <emphasis>values</emphasis> + if at least one of them is a <emphasis>pattern</emphasis> and returns the result as a <emphasis>pattern</emphasis>. + A concatenation matches the left operand immediately followed by the right operand. + </para><para> + The <command>+</command> operator constructs an alternation between two <emphasis>values</emphasis> + if at least one of them is a <emphasis>pattern</emphasis> and returns the result as a <emphasis>pattern</emphasis>. + An alternation matches the left operand and <emphasis>if unsuccessful</emphasis> the right operand. + </para><para> + The non-pattern <emphasis>values</emphasis> may be strings or numbers, which are matched + just like a <emphasis>pattern</emphasis> built by + <link linkend="topattern"><command>topattern</command></link>. + </para> + <note><para> + Even though the <emphasis>patterns</emphasis> participating in the composition will be copied, + references will be kept, so they will not be garbage collected until all <emphasis>patterns</emphasis> + using them are garbage collected. + </para></note> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Result of the pattern composition + </listitem></orderedlist> + </refsect1><refsect1> + <title>Example</title> + + <example> + <title>Concatenations and Alternations</title> + + <screen>> pat = (<link linkend="topattern">topattern</link>("ABC") + "AB") * (<link linkend="topattern">topattern</link>("DEF") + "CDE") * (<link linkend="topattern">topattern</link>("GH") + "IJ") +> assert(<link linkend="smatch">spipat.smatch</link>("ABCCDEGH", pat)) +> assert(<link linkend="smatch">spipat.smatch</link>("ABCDEFIJ", pat)) +></screen> + </example> + </refsect1> + </refentry> + + <refentry xml:id="assignment"> + <refmeta><refentrytitle>Assignment Calls</refentrytitle></refmeta> + + <refnamediv> + <refname>%</refname> + <refpurpose>Call Immediately</refpurpose> + </refnamediv><refnamediv> + <refname>/</refname> + <refpurpose>Deferred Call</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>%</command> + <arg choice="plain"><replaceable>function</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <arg choice="plain"><replaceable>pattern</replaceable></arg><command>/</command> + <arg choice="plain"><replaceable>function</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + The <command>%</command> operator constructs a pattern matching operand <emphasis>pattern</emphasis> and + calling a Lua <emphasis>function</emphasis> whenever <emphasis>pattern</emphasis> matches during a pattern + match (i.e. <emphasis>function</emphasis> may be called more than once while matching regardless of whether + the match fails or succeeds). + </para><para> + On the other hand, the <command>/</command> operator constructs a pattern matching operand + <emphasis>pattern</emphasis> and calling a Lua <emphasis>function</emphasis> at most once - only if + the match succeeds. + </para><para> + In both cases, <emphasis>function</emphasis> receives the following arguments when called: + <orderedlist><listitem> + <emphasis>string</emphasis>: The substring matched by <emphasis>pattern</emphasis> + </listitem></orderedlist> + Its return value is ignored. + </para> + <note><para> + Unlike assignment operators in <emphasis>SNOBOL</emphasis>, the <command>%</command> and <command>/</command> + operators in Lua have the <link xlink:href="http://www.lua.org/manual/5.1/manual.html#2.5.6">same precedence</link> + as the <link linkend="concat">concatenation operator <command>*</command></link>, + so using parentheses is advised. + </para></note> + <tip><para> + Deferred assignments (assign on match & assign immediately) are not directly possible but can be + easily implemented using function closures as described in <xref linkend="deferring"/>. + </para></tip> + <note> + <para> + Even though the <emphasis>pattern</emphasis> operands will be copied, references will be kept, + so they will not be garbage collected until all <emphasis>patterns</emphasis> + using them are garbage collected. + </para><para> + Furthermore, references to <emphasis>functions</emphasis> will be kept so they will not be + garbage collected until the patterns constructed by the operators are garbage collected. + </para> + </note> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the operators + </listitem></orderedlist> + </refsect1><refsect1> + <title>Example</title> + + See <xref linkend="example_siter"/>. + </refsect1> + </refentry> + + <refentry xml:id="cursor"> + <refmeta><refentrytitle>Cursor Assignment Calls</refentrytitle></refmeta> + + <refnamediv> + <refname>Setcur</refname> + <refpurpose>Cursor Assignment</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.Setcur</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>Setcur</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>#</command><arg choice="plain"><replaceable>function</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>spipat._Setcur</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>_Setcur</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>Setcur</command> is a pattern constructor returning a pattern matching the null string <literal>""</literal> + (i.e. always succeeds when matched) and immediately calling a Lua <emphasis>function</emphasis> when matched. + This <emphasis>function</emphasis> receives the following arguments when called: + <orderedlist> + <listitem> + <emphasis>number</emphasis>: The cursor in the subject string. + In other words, the number of characters matched so far from the beginning of the subject string. + </listitem><listitem> + <emphasis>cookie</emphasis>: Any Lua value specified as a cookie in the pattern constructor or + <emphasis>nil</emphasis> if no cookie was specified. + </listitem> + </orderedlist> + Its return value is ignored. + </para> + <tip><para> + The unary <command>#</command> operator is equivalent to the <command>Setcur</command> constructor with no + <emphasis>cookie</emphasis> specified. + </para></tip> + <para> + <command>_Setcur</command> is similar to <command>Setcur</command> but actually assigns the cursor position to + the global variable whose name is specified by a <emphasis>string</emphasis> value. + This means that <code>_Setcur(str)</code> does not assign the cursor position to the global variable <literal>str</literal> + but rather to the variable with the name <emphasis>str</emphasis> contains, e.g. <literal>foo</literal> if <code>str == "foo"</code>. + So generally <command>_Setcur</command> is equivalent to: + <informalexample> + <programlisting language="lua"><![CDATA[function _Setcur(val) + return #function(str) _G[val] = str end +end]]></programlisting> + </informalexample> + In a similar manner, other kinds of deferred assignments can be implemented + using function closures as described in <xref linkend="deferring"/>. + </para> + <note><para> + References to <emphasis>function</emphasis> and <emphasis>cookie</emphasis> will be kept so they will not be + garbage collected until the pattern constructed by <command>Setcur</command> is garbage collected. + </para></note> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the constructor + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry xml:id="predicate"> + <refmeta><refentrytitle>Predicates</refentrytitle></refmeta> + + <refnamediv xml:id="Pred"> + <refname>Pred</refname> + <refpurpose>Predicate Constructor</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.Pred</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>Pred</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>-</command><arg choice="plain"><replaceable>function</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>spipat._Pred</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>_Pred</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>-</command><arg choice="plain"><replaceable>string</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>Pred</command> constructs a pattern which allows you to transparently define its matching behaviour + using a <emphasis>function</emphasis> called when this pattern is attempted to be matched. + It receives the following arguments when invoked: + <orderedlist><listitem> + <emphasis>cookie</emphasis>: Any Lua value specified as a cookie in the pattern constructor or + <emphasis>nil</emphasis> if no cookie was specified. + </listitem></orderedlist> + </para><para> + The <emphasis>function's</emphasis> return value defines the behaviour dynamically, as shown in the following table: + + <table xml:id="dynfnc"> + <title>Dynamic Function Return Values</title> + + <tgroup cols="3" colsep="1" rowsep="1"> + <colspec colname="value"/> + <colspec colname="type"/> + <colspec colname="behaviour"/> + + <thead> + <row> + <entry>Value</entry> + <entry>Type</entry> + <entry>Behaviour</entry> + </row> + </thead><tbody> + <row> + <entry>nil</entry> + <entry>nil</entry> + <entry morerows="1"><para> + Match the <literal>""</literal> string, i.e. succeed. + </para></entry> + </row><row> + <entry>true</entry> + <entry morerows="1">boolean</entry> + </row><row> + <entry>false</entry> + <!-- <entry>boolean</entry> --> + <entry><para> + Pattern match fails, like when using the + <link linkend="Fail"><command>Fail</command> primitive</link>. + </para></entry> + </row><row> + <entry namest="value" nameend="type" align="center">any <emphasis>number</emphasis></entry> + <entry><para> + Try to match that number as a string, as if + <link linkend="topattern">converted to a pattern</link>. + </para></entry> + </row><row> + <entry namest="value" nameend="type" align="center">any <emphasis>string</emphasis></entry> + <entry><para> + Try to match that string, as if + <link linkend="topattern">converted to a pattern</link>. + </para></entry> + </row><row> + <entry namest="value" nameend="type" align="center">any <emphasis>pattern</emphasis></entry> + <entry><para> + Try to match that pattern. Returning a pattern assigned to a variable is the way + to implement recursive patterns. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <tip><para> + The unary <command>-</command> operator applied to a <emphasis>function</emphasis> is equivalent + to the <command>Pred</command> constructor with no <emphasis>cookie</emphasis> specified. + </para></tip> + <para> + <command>_Pred</command> is similar to <command>Pred</command> but actually gets the Lua value defining its behaviour from + the global variable whose name is specified by a <emphasis>string</emphasis> value. + This means that <code>_Pred(str)</code> does not get the value from the global variable <literal>str</literal> + but rather from the variable with the name <emphasis>str</emphasis> contains, e.g. <literal>foo</literal> if <code>str == "foo"</code>. + So generally <command>_Pred</command> is equivalent to: + <informalexample> + <programlisting language="lua"><![CDATA[function _Pred(val) + return -function() return _G[val] end +end]]></programlisting> + </informalexample> + In a similar manner, other kinds of variable deferring as well as recursive patterns can be implemented + using function closures as described in <xref linkend="deferring"/>. + </para> + <tip><para> + The unary <command>-</command> operator applied to a <emphasis>string</emphasis> which is not convertable to + a <emphasis>number</emphasis> is equivalent to the <command>_Pred</command> constructor - naturally this + <emphasis>should</emphasis> be true for all global variable names. + This constraint comes from the way Lua handles operations by default (it checks whether it is an arithmetic operation + before evaluating any metamethod - see <link xlink:href="http://www.lua.org/manual/5.1/manual.html#2.8">metatables</link>). + </para></tip> + <note><para> + References to <emphasis>function</emphasis> and <emphasis>cookie</emphasis> will be kept so they will not be + garbage collected until the pattern constructed by <command>Pred</command> is garbage collected. + </para></note> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the constructor + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry xml:id="string_primitives"> + <refmeta><refentrytitle>String Primitives</refentrytitle></refmeta> + + <refnamediv xml:id="Any"> + <refname>Any</refname> + <refpurpose>Match any character in a set</refpurpose> + </refnamediv> + <refnamediv> + <refname>NotAny</refname> + <refpurpose>Match any character not in a set</refpurpose> + </refnamediv> + <refnamediv xml:id="Break"> + <refname>Break</refname> + <refpurpose>Match characters up to a break character</refpurpose> + </refnamediv> + <refnamediv> + <refname>BreakX</refname> + <refpurpose>Match characters up to a break character (extending)</refpurpose> + </refnamediv> + <refnamediv> + <refname>NSpan</refname> + <refpurpose>Match nothing or characters from a set</refpurpose> + </refnamediv> + <refnamediv xml:id="Span"> + <refname>Span</refname> + <refpurpose>Match characters from a set</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command><arg>spipat.</arg>Any</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Any</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Any</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>NotAny</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>NotAny</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_NotAny</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>Break</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Break</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Break</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>BreakX</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>BreakX</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_BreakX</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>NSpan</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>NSpan</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_NSpan</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>Span</command>( <arg choice="plain"><replaceable>set</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Span</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Span</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + String primitives are pattern constructors that in their first form all take a <emphasis>string</emphasis> or + <emphasis>number</emphasis> (which is converted to a <emphasis>string</emphasis>) as their sole argument + (<emphasis>set</emphasis>). + </para><para> + In their second form they take a Lua <emphasis>function</emphasis> and an optional <emphasis>cookie</emphasis> + as arguments. When the constructed pattern is about to be matched, the <emphasis>function</emphasis> is called + and is supposed to return a <emphasis>string</emphasis> or <emphasis>number</emphasis> (which is converted to + a <emphasis>string</emphasis>) to supply the primitive's argument dynamically. + It receives the following arguments when invoked: + <orderedlist><listitem> + <emphasis>cookie</emphasis>: Any Lua value specified as a cookie in the pattern constructor or + <emphasis>nil</emphasis> if no cookie was specified. + </listitem></orderedlist> + </para><para> + The primitives with a leading underscore (e.g. <command>_Any</command>) are similar but actually get their argument + from a global variable with the name a <emphasis>string</emphasis> argument contains. + This means that for instance <code>_Any(str)</code> does not get its character set from the global variable <literal>str</literal> + but rather from the variable with the name <emphasis>str</emphasis> contains, e.g. <literal>foo</literal> if <code>str == "foo"</code>. + So generally <command>_Any</command> is equivalent to: + <informalexample> + <programlisting language="lua"><![CDATA[function _Any(val) + return Any(function() return _G[val] end) +end]]></programlisting> + </informalexample> + In a similar manner, other kinds of variable deferring can be implemented + using function closures as described in <xref linkend="deferring"/>. + </para> + <note><para> + References to <emphasis>function</emphasis> and <emphasis>cookie</emphasis> will be kept so they will not be + garbage collected until the pattern constructed is garbage collected. + </para></note> + <para> + The following table describes what these primitives do: + + <!-- Largely copied from the GNAT.SPITBOL docs --> + <table> + <title>String Primitives</title> + + <tgroup cols="2" colsep="1" rowsep="1"> + <colspec colwidth="10%"/> + + <thead> + <row> + <entry>Primitive</entry> + <entry>Description</entry> + </row> + </thead><tbody> + <row> + <entry><command>Any</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, matches a single character that is + any one of the characters in S. Fails if the current + character is not one of the given set of characters. + </para></entry> + </row><row> + <entry><command>NotAny</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, matches a single character that is + not one of the characters of S. Fails if the current + characer is one of the given set of characters. + </para></entry> + </row><row> + <entry><command>Break</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, matches a string of zero or more + characters up to but not including a break character + that is one of the characters given in the string S. + Can match the null string, but cannot match the last + character in the string, since a break character is + required to be present. + </para></entry> + </row><row> + <entry><command>BreakX</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, behaves exactly like <command>Break</command>(S) when + it first matches, but if a string is successfully matched, + then a susequent failure causes an attempt to extend the + matched string. + </para></entry> + </row><row> + <entry><command>NSpan</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, matches a string of zero or more + characters that is among the characters given in the + string. Always matches the longest possible such string. + Always succeeds, since it can match the null string. + </para></entry> + </row><row> + <entry><command>Span</command>( <arg choice="plain"><replaceable>S</replaceable></arg> )</entry> + <entry><para> + Where S is a string, matches a string of one or more + characters that is among the characters given in the + string. Always matches the longest possible such string. + Fails if the current character is not one of the given + set of characters. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the constructor + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry> + <refmeta><refentrytitle>Arbno</refentrytitle></refmeta> + + <refnamediv> + <refname>Arbno</refname> + <refpurpose>Matches a pattern any number of times</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.Arbno</command>( <arg choice="plain"><replaceable>P</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>Arbno</command>( <arg choice="plain"><replaceable>P</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Where P is any pattern, matches any number of instances + of the pattern, starting with zero occurrences. It is + thus equivalent to <code>("" + (P * ("" + (P * ("" ....))))</code>. + The pattern P may contain any number of pattern elements + including the use of alternation and concatenation. + </para><para> + <command>Arbno</command> is a pattern constructor taking exactly one argument which is + either a <emphasis>pattern</emphasis> or <emphasis>string</emphasis> (which is treated + like it is <link linkend="topattern">converted to a pattern</link> first). + </para> + <note><para> + A reference to <emphasis>P</emphasis> will be kept if it is a <emphasis>pattern</emphasis> + so it will not be garbage collected until the pattern constructed is garbage collected. + </para></note> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by <command>Arbno</command> + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry> + <refmeta><refentrytitle>Fence</refentrytitle></refmeta> + + <refnamediv> + <refname>Fence</refname> + <refpurpose>Abort match when alternations are sought</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.Fence</command>( <arg><replaceable>P</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>Fence</command>( <arg><replaceable>P</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>Fence</command> is a pattern constructor taking no or exactly one + <emphasis>pattern</emphasis> as an argument. + </para> + <note><para> + A reference to pattern <emphasis>P</emphasis> will be kept so it will not + be garbage collected until the pattern constructed is garbage collected. + </para></note> + <para> + The following table describes what the two versions do: + + <!-- Largely copied from the GNAT.SPITBOL docs --> + <table> + <title>Fence Primitive</title> + + <tgroup cols="2" colsep="1" rowsep="1"> + <colspec colwidth="10%"/> + + <thead> + <row> + <entry>Primitive</entry> + <entry>Description</entry> + </row> + </thead><tbody> + <row> + <entry><command>Fence</command>()</entry> + <entry><para> + Matches the null string at first, and then if a failure + causes alternatives to be sought, aborts the match (like + a Cancel). Note that using <command>Fence</command> at the + start of a pattern has the same effect as matching in anchored mode. + </para></entry> + </row><row> + <entry><command>Fence</command>( <arg choice="plain"><replaceable>P</replaceable></arg> )</entry> + <entry><para> + Where P is a pattern, attempts to match the pattern P + including trying all possible alternatives of P. If none + of these alternatives succeeds, then the <command>Fence</command> pattern + fails. If one alternative succeeds, then the pattern + match proceeds, but on a subsequent failure, no attempt + is made to search for alternative matches of P. The + pattern P may contain any number of pattern elements + including the use of alternatiion and concatenation. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by <command>Fence</command> + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry xml:id="uint_primitives"> + <refmeta><refentrytitle>Integer Primitives</refentrytitle></refmeta> + + <refnamediv xml:id="Len"> + <refname>Len</refname> + <refpurpose>Match a number of characters</refpurpose> + </refnamediv> + <refnamediv> + <refname>Pos</refname> + <refpurpose>Match null string if number of characters have been matched</refpurpose> + </refnamediv> + <refnamediv> + <refname>RPos</refname> + <refpurpose>Match null string if number of characters remain to be matched</refpurpose> + </refnamediv> + <refnamediv> + <refname>Tab</refname> + <refpurpose>Match characters until number of characters have been matched</refpurpose> + </refnamediv> + <refnamediv> + <refname>RTab</refname> + <refpurpose>Match characters until number of characters remain to be matched</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command><arg>spipat.</arg>Len</command>( <arg><replaceable>n</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Len</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Len</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>Pos</command>( <arg><replaceable>n</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Pos</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Pos</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>RPos</command>( <arg><replaceable>n</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>RPos</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_RPos</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>Tab</command>( <arg><replaceable>n</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>Tab</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_Tab</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + + <cmdsynopsis> + <command><arg>spipat.</arg>RTab</command>( <arg><replaceable>n</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>RTab</command> + ( <arg choice="plain"><replaceable>function</replaceable></arg><arg>, <replaceable>cookie</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command><arg>spipat.</arg>_RTab</command>( <arg choice="plain"><replaceable>string</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + Integer primitives are pattern constructors that in their first form all take a <emphasis>number</emphasis> or + <emphasis>string</emphasis> (which is converted to a <emphasis>number</emphasis>) as their sole argument + (<emphasis>n</emphasis>). + This <emphasis>number</emphasis> has to be an unsigned integer - sometimes a natural number depending on the + primitive. + </para> + <tip><para> + If the argument is ommitted, <emphasis>zero</emphasis> is assumed. + </para></tip> + <para> + In their second form the primitives take a Lua <emphasis>function</emphasis> and an optional <emphasis>cookie</emphasis> + as arguments. When the constructed pattern is about to be matched, the <emphasis>function</emphasis> is called + and is supposed to return a <emphasis>number</emphasis> or <emphasis>string</emphasis> (which is converted to + a <emphasis>number</emphasis>) to supply the primitive's argument dynamically. + It receives the following arguments when invoked: + <orderedlist><listitem> + <emphasis>cookie</emphasis>: Any Lua value specified as a cookie in the pattern constructor or + <emphasis>nil</emphasis> if no cookie was specified. + </listitem></orderedlist> + </para><para> + The primitives with a leading underscore (e.g. <command>_Len</command>) are similar but actually get their argument + from a global variable with the name a <emphasis>string</emphasis> argument contains. + This means that for instance <code>_Len(str)</code> does not get its argument from the global variable <literal>str</literal> + but rather from the variable with the name <emphasis>str</emphasis> contains, e.g. <literal>foo</literal> if <code>str == "foo"</code>. + So generally <command>_Len</command> is equivalent to: + <informalexample> + <programlisting language="lua"><![CDATA[function _Len(val) + return Len(function() return _G[val] end) +end]]></programlisting> + </informalexample> + In a similar manner, other kinds of variable deferring can be implemented + using function closures as described in <xref linkend="deferring"/>. + </para> + <note><para> + References to <emphasis>function</emphasis> and <emphasis>cookie</emphasis> will be kept so they will not be + garbage collected until the pattern constructed is garbage collected. + </para></note> + <para> + The following table describes what these primitives do: + + <!-- Largely copied from the GNAT.SPITBOL docs --> + <table> + <title>Integer Primitives</title> + + <tgroup cols="2" colsep="1" rowsep="1"> + <colspec colwidth="10%"/> + + <thead> + <row> + <entry>Primitive</entry> + <entry>Description</entry> + </row> + </thead><tbody> + <row> + <entry><command>Len</command>( <arg choice="plain"><replaceable>N</replaceable></arg> )</entry> + <entry><para> + Where N is a natural number, matches the given number of + characters. For example, <code>Len(10)</code> matches any string that + is exactly ten characters long. + </para></entry> + </row><row> + <entry><command>Pos</command>( <arg choice="plain"><replaceable>N</replaceable></arg> )</entry> + <entry><para> + Where N is a natural number, matches the null string + if exactly N characters have been matched so far, and + otherwise fails. + </para></entry> + </row><row> + <entry><command>RPos</command>( <arg choice="plain"><replaceable>N</replaceable></arg> )</entry> + <entry><para> + Where N is a natural number, matches the null string + if exactly N characters remain to be matched, and + otherwise fails. + </para></entry> + </row><row> + <entry><command>Tab</command>( <arg choice="plain"><replaceable>N</replaceable></arg> )</entry> + <entry><para> + Where N is a natural number, matches characters from + the current position until exactly N characters have + been matched in all. Fails if more than N characters + have already been matched. + </para></entry> + </row><row> + <entry><command>RTab</command>( <arg choice="plain"><replaceable>N</replaceable></arg> )</entry> + <entry><para> + Where N is a natural number, matches characters from + the current position until exactly N characters remain + to be matched in the string. Fails if fewer than N + unmatched characters remain in the string. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the constructor + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry xml:id="misc_primitives"> + <refmeta><refentrytitle>Miscelleanous Primitives</refentrytitle></refmeta> + + <refnamediv xml:id="Arb"> + <refname>Arb</refname> + <refpurpose>Matches any string</refpurpose> + </refnamediv> + <refnamediv> + <refname>Bal</refname> + <refpurpose>Matches parentheses balanced strings</refpurpose> + </refnamediv> + <refnamediv> + <refname>Abort</refname> + <refpurpose>Immediately abort pattern match</refpurpose> + </refnamediv> + <refnamediv xml:id="Fail"> + <refname>Fail</refname> + <refpurpose>Null alternation</refpurpose> + </refnamediv> + <refnamediv> + <refname>Rem</refname> + <refpurpose>Match the entire remaining subject string</refpurpose> + </refnamediv> + <refnamediv> + <refname>Succeed</refname> + <refpurpose>Match the null string in every alternative</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.Arb</command>() + </cmdsynopsis><cmdsynopsis> + <command>Arb</command>() + </cmdsynopsis><cmdsynopsis> + <command>spipat.Bal</command>() + </cmdsynopsis><cmdsynopsis> + <command>Bal</command>() + </cmdsynopsis><cmdsynopsis> + <command>spipat.Abort</command>() + </cmdsynopsis><cmdsynopsis> + <command>Abort</command>() + </cmdsynopsis><cmdsynopsis> + <command>spipat.Fail</command>() + </cmdsynopsis><cmdsynopsis> + <command>Fail</command>() + </cmdsynopsis><cmdsynopsis> + <command>spipat.Rem</command>() + </cmdsynopsis><cmdsynopsis> + <command>Rem</command>() + </cmdsynopsis><cmdsynopsis> + <command>spipat.Succeed</command>() + </cmdsynopsis><cmdsynopsis> + <command>Succeed</command>() + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + These are <emphasis>simple</emphasis> pattern constructor + functions. + </para><para> + The following table describes what these primitives do: + + <!-- Largely copied from the GNAT.SPITBOL docs --> + <table> + <title>Miscelleanous Primitives</title> + + <tgroup cols="2" colsep="1" rowsep="1"> + <colspec colwidth="10%"/> + + <thead> + <row> + <entry>Primitive</entry> + <entry>Description</entry> + </row> + </thead><tbody> + <row> + <entry><command>Arb</command>()</entry> + <entry><para> + Matches any string. First it matches the null string, and + then on a subsequent failure, matches one character, and + then two characters, and so on. It only fails if the + entire remaining string is matched. + </para></entry> + </row><row> + <entry><command>Bal</command>()</entry> + <entry><para> + Matches a non-empty string that is parentheses balanced + with respect to ordinary <literal>()</literal> characters. + Examples of balanced strings are <literal>"ABC"</literal>, + <literal>"A((B)C)"</literal>, and <literal>"A(B)C(D)E"</literal>. + <command>Bal</command> matches the shortest possible balanced + string on the first attempt, and if there is a subsequent failure, + attempts to extend the string. + </para></entry> + </row><row> + <entry><command>Abort</command>()</entry> + <entry><para> + Immediately aborts the entire pattern match, signalling + failure. This is a specialized pattern element, which is + useful in conjunction with some of the special pattern + elements that have side effects. + </para></entry> + </row><row> + <entry><command>Fail</command>()</entry> + <entry><para> + The null alternation. Matches no possible strings, so it + always signals failure. This is a specialized pattern + element, which is useful in conjunction with some of the + special pattern elements that have side effects. + </para></entry> + </row><row> + <entry><command>Rem</command>()</entry> + <entry><para> + Matches from the current point to the last character in + the string. This is a specialized pattern element, which + is useful in conjunction with some of the special pattern + elements that have side effects. + </para></entry> + </row><row> + <entry><command>Succeed</command>()</entry> + <entry><para> + Repeatedly matches the null string (it is equivalent to + the alternation <code>("" + "" + "" ....)</code>. This is a special + pattern element, which is useful in conjunction with some + of the special pattern elements that have side effects. + </para></entry> + </row> + </tbody> + </tgroup> + </table> + </para> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by the constructor + </listitem></orderedlist> + </refsect1> + <!--<refsect1> + <title>Example</title> + + </refsect1>--> <!-- TODO --> + </refentry> + + <refentry xml:id="RegExp"> + <refmeta><refentrytitle>POSIX Extended Regular Expressions</refentrytitle></refmeta> + + <refnamediv> + <refname>RegExp</refname> + <refpurpose>Matches a pattern equivalent to a regular expression</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>spipat.RegExp</command> + ( <arg choice="plain"><replaceable>expression</replaceable></arg><arg>, <replaceable>captures</replaceable></arg> ) + </cmdsynopsis><cmdsynopsis> + <command>RegExp</command> + ( <arg choice="plain"><replaceable>expression</replaceable></arg><arg>, <replaceable>captures</replaceable></arg> ) + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para> + <command>RegExp</command> constructs from a + <link xlink:href="http://www.opengroup.org/onlinepubs/7990989775/xbd/re.html#tag_007_004"> + POSIX Extended Regular Expression</link>, a pattern that is equivalent to that regular + <emphasis>expression</emphasis> and can be combined with other patterns freely. + </para><para> + It can optionally construct the pattern to save the <emphasis>captures</emphasis> + from a regular expression match in a Lua <emphasis>table</emphasis>. + </para> + <warning><para> + Even though this implementation should support almost all elements of EREs, + it is considered <emphasis>experimental</emphasis>. + You are advised to use the usual pattern construction primitives. + </para></warning> + </refsect1><refsect1> + <title>Parameters</title> + + <orderedlist> + <listitem> + expression (<emphasis>string</emphasis>): The POSIX ERE which is compiled + to a pattern. + </listitem><listitem> + captures (<emphasis>table</emphasis>): Optional table, or more precisely + array, to hold subexpression captures. + Naturally, it has to exist when <command>RegExp</command> is called. + When a subexpression is captured (i.e. the pattern equivalent to what is + enclosed in parentheses), the matching string is added to the + end of the table. + Thus taken that <emphasis>captures</emphasis> is initially empty, if + <code>RegExp("(a(b))", captures)</code> matches, <emphasis>captures</emphasis> + will be <code>{"b", "ab"}</code>. + </listitem> + </orderedlist> + </refsect1><refsect1> + <title>Return Values</title> + + <orderedlist><listitem> + <emphasis>pattern</emphasis> (userdata): Pattern built by <command>RegExp</command> + </listitem></orderedlist> + </refsect1><refsect1> + <title>Example</title> + + <example> + <title>Regular Expressions</title> + + <screen><![CDATA[> print(RegExp "^[[:digit:]]*?(abc\\.|de?)") +Pos(0) * Arbno(Any(<CS>)) * ("abc." + "d" * ("" + "e")) +>]]></screen> + </example> + </refsect1> + </refentry> + </reference> +</book> |
