/usr/share/doc/libbobcat4-dev/man/pattern.3.html

<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::Pattern</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::Pattern</h1>
<h2 id="author">libbobcat-dev_4.04.00-x.tar.gz</h2>
<h2 id="date">2005-2016</h2>

<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    figure {text-align: center;}
    img {vertical-align: center;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title"></h1>

<!DOCTYPE html><html><head>
<meta charset="UTF-8">
<title>FBB::Pattern(3bobcat)</title>
<style type="text/css">
    figure {text-align: center;}
    img {vertical-align: center;}
    figure {text-align: center;}
    img {vertical-align: center;}
    figure {text-align: center;}
    img {vertical-align: center;}
</style>
<link rev="made" href="mailto:Frank B. Brokken: f.b.brokken@rug.nl">
</head>
<body text="#27408B" bgcolor="#FFFAF0">
<hr/>
<h1 id="title">FBB::Pattern(3bobcat)</h1>
<h2 id="author">libbobcat-dev_4.04.00-x.tar.gz Pattern matcher</h2>
<h2 id="date">2005-2016</h2>


<p>
<h2 >NAME</h2>FBB::Pattern - Performs RE pattern matching
<p>
<h2 >SYNOPSIS</h2>
    <strong >#include &lt;bobcat/pattern&gt;</strong><br/>
    Linking option: <em >-lbobcat</em> 
<p>
<h2 >DESCRIPTION</h2>
    <strong >Pattern</strong> objects may be used for Regular Expression (RE) pattern
matching. The class is a wrapper around the <strong >regcomp</strong>(3) family of
functions. By default it uses `extended regular expressions', requiring you to
escape multipliers and bounding-characters when they should be interpreted as
ordinary characters (i.e., <em >*, +, ?, ^, $, |, (, ), [, ], {, }</em> should be
escaped when used as literal characters).
<p>
The <strong >Pattern</strong> class supports the use of the following (Perl-like)
special escape sequences: <br/>
        \b - indicating a word-boundary <br/>
        \d - indicating a digit (<em >[[:digit:]]</em>) character <br/>
        \s - indicating a white-space (<em >[:space:]</em>) character <br/>
        \w - indicating a word (<em >[:alnum:]</em>) character
<p>
The corresponding capitals (e.g., <strong >\W</strong>) define the complementary
character sets. The capitalized character set shorthands are not expanded
inside explicit character-classes (i.e., <em >[ ... ]</em> constructions). So
<em >[\W]</em> represents a set of two characters: <em >\</em> and <em >W</em>.
<p>
As the backslash (<em >\</em>) is treated as a special character it should be
handled carefully. <strong >Pattern</strong> converts the escape sequences <em >\d \s \w</em> (and
outside of explicit character classes the sequences <em >\D \S \W</em>) to their
respective character classes. All other escape sequences are kept as is, and
the resulting regular expression is offered to the pattern matching
compilation function <strong >regcomp</strong>(3). This function will again interpret
escape sequences. Consequently some care should be exercised when defining
patterns containing escape sequences. Here are the rules:
    <ul>
    <li> Special escape sequences (like <em >\d</em>) are converted to character
classes. E.g.,
        <pre>

    ---------------------------------------------------------
    Specify:    Converts to:    regcomp uses:      Matches:
    ---------------------------------------------------------
    \d          [[:digit:]]     [[:digit:]]        3
    ---------------------------------------------------------
        
</pre>

    <li> Ordinary escape sequences (like <em >\x</em>) are kept as-is. E.g.,
        <pre>

    ---------------------------------------------------------
    Specify:    Converts to:    regcomp uses:      Matches:
    ---------------------------------------------------------
    \x          \x              x                  x
    ---------------------------------------------------------
        
</pre>

    <li> To specify a literal escape sequence, it must be written twice. E.g.,
        <pre>

    ---------------------------------------------------------
    Specify:    Converts to:    regcomp uses:      Matches:
    ---------------------------------------------------------
    \\x         \\x             \x                 \x
    ---------------------------------------------------------
        
</pre>

    </ul>
<p>
<h2 >NAMESPACE</h2>
    <strong >FBB</strong><br/>
    All constructors, members, operators and manipulators, mentioned in this
man-page, are defined in the namespace <strong >FBB</strong>.
<p>
<h2 >INHERITS FROM</h2>
    -
<p>
<h2 >TYPEDEF</h2>
    <ul>
    <li> <strong >Pattern::Position</strong>:<br/> 
        A nested type representing the offsets of the first character and
the offset beyond the last character of the matched text or indexed
subexpression, defined as <em >std::pair&lt;std::string::size_type,
std::string::size_type&gt;</em>.
    </ul>
<p>
<h2 >CONSTRUCTORS</h2>
    <ul>
    <li> <strong >Pattern()</strong>:<br/>
        The default constructor defines no pattern, but is available as a
placeholder for, e.g., containers requiring default constructors. A
<strong >Pattern</strong> object thus constructed cannot be used to match patterns, but
can be the <em >lvalue</em> in assignments where another <strong >Pattern</strong> object is
the <em >rvalue</em>. However, it can receive a pattern using the member
<strong >setPattern()</strong> (see below). An <strong >FBB::Exception</strong> object is thrown if the object
could not be constructed.
    <li> <strong >Pattern(std::string const &amp;pattern, 
                            bool caseSensitive = true, 
                            size_t nSub = 10,
                        int options = REG_EXTENDED | REG_NEWLINE)</strong>:<br/>
        This constructor compiles <em >pattern</em>, preparing the <strong >Pattern</strong>
object for pattern matches. The second parameter determines whether case
sensitive matching will be used (the default) or not. Subexpressions are
defined by parentheses pairs. Each matching pair defines a subexpression,
where the order-number of their opening parentheses determines the
subexpression's index. By default at most 10 subexpressions are recognized.
The <em >options</em> flags may be:
<p>
REG_EXTENDED: <br/> 
                   Use POSIX Extended Regular Expression syntax when
                    interpreting regex.  If not set, POSIX Basic Regular
                    Expression syntax is used.
<p>
REG_NOSUB: <br/>
                    Support for substring addressing of matches is  not
                    required.   The  nmatch  and  pmatch  parameters to
                    regexec are ignored if the pattern buffer  supplied
                    was compiled with this flag set.
<p>
REG_NEWLINE: <br/>
                    Match-any-character  operators  don't  match a newline.
<p>
A non-matching list ([^...])  not containing a newline
                    does not match a newline.
<p>
Match-beginning-of-line operator (^) matches the empty
                    string immediately after a newline, regardless of whether
                    eflags, the execution flags of regexec, contains
                    REG_NOTBOL.
<p>
Match-end-of-line operator ($)  matches  the  empty
                    string  immediately before a newline, regardless of
                    whether eflags contains REG_NOTEOL.
    </ul>
<p>
<em >Pattern</em> offers  copy and move constructors.
<p>
<h2 >MEMBER FUNCTIONS</h2>
     All members of <strong >std::ostringstream</strong> and <strong >  std::exception</strong> are
available, as <strong >Pattern</strong> inherits from these classes.
    <ul>
    <li> <strong >std::string before() const</strong>:<br/>  
        Following a successful match, <strong >before()</strong> returns the text before the
matched text.
    <li> <strong >std::string beyond() const</strong>:<br/>
        Following a successful match, <strong >beyond()</strong> returns the text beyond the
matched text.
    <li> <strong >size_t end() const</strong>:<br/>
        Returns the number of matched elements (text and
subexpressions). <strong >end()</strong> is the lowest index value for which <strong >position()</strong>
returns two <em >std::string::npos</em> values (see the <strong >position()</strong> member
function, below).
    <li> <strong >void match(std::string const &amp;text, int options = 0)</strong>:<br/>
       Match a string with a pattern.  If the text could not be matched, an
<strong >Exception</strong> exception is thrown , using <strong >Pattern::match()</strong> as its prefix-text.
<p>
Options may be:
<p>
REG_NOTBOL: <br/>
                   The match-beginning-of-line operator always fails to match
                    (but see the compilation flag REG_NEWLINE above) This flag
                    may be used when different portions of a string are passed
                    to regexec and the beginning of the string should not be
                    interpreted as the beginning of the line.
<p>
REG_NOTEOL: <br/>
                    The  match-end-of-line  operator  always  fails  to
                    match  (but  see  the  compilation flag REG_NEWLINE)
    <li> <strong >std::string matched() const</strong>:<br/>
        Following a successful match, this function returns the matched text.
    <li> <strong >std::string const &amp;pattern() const</strong>:<br/>
        This member function returns the pattern that is offered to
<strong >regcomp</strong>(3). It returns the contents of a <em >static</em> string that is
overwritten at each construction of a <strong >Pattern</strong> object and at each call of
the <em >setPattern()</em> member function.
    <li> <strong >Pattern::Position position(size_t index) const</strong>:<br/> 
        With <em >index == 0</em> the fully matched text is returned (identical to
<em >matched()</em>). Other index values return the corresponding
subexpressions. <strong >std::string::npos, std::string::npos</strong> is returned if index
is at least <strong >end()</strong> (which may happen at index value 0).
    <li> <strong >void setPattern(std::string const &amp;pattern, 
                            bool caseSensitive = true, 
                            size_t nSub = 10,
                        int options = REG_EXTENDED | REG_NEWLINE)</strong>:<br/>
        This member function installs a new  compiled <em >pattern</em> in its
<strong >Pattern</strong> object. This member's parameters are identical to the second
constructor's parameters. Refer to that constructor for details about the
parameters. Like the constructor, an <strong >FBB::Exception</strong> exception is thrown if the
new pattern could not be compiled.
    <li> <strong >void swap(Pattern &amp;other)</strong>:<br/>
        The contents of the current object and the <em >other</em> object are
swapped. 
    </ul>
<p>
<h2 >OVERLOADED OPERATORS</h2>
<p>
<ul>
    <li> <strong >Pattern &amp;operator=(Pattern &amp;other)</strong>:<br/> 
        A standard overloaded assignment operator.
    <li> <strong >std::string operator[](size_t index) const</strong>:<br/>
        Returns the matched text (for index 0) or the text of a
subexpression. An empty string is returned for index values which are at least
<strong >end()</strong>.
    <li> <strong >Pattern &amp;operator&lt;&lt;(int matchOptions)</strong>:<br/>
        Defines match-options to be used with the following overloaded
operator. 
    <li> <strong >bool operator&lt;&lt;(std::string const &amp;text)</strong>:<br/>
        Performs a <strong >match(text, matchOptions)</strong> call, catching any exception
that might be thrown. If no <em >matchOptions</em> were set using the above
overloaded operator, none are used. The options set this way are not `sticky':
when necessary, they have to be re-inserted before each new pattern
matching. The function returns <strong >true</strong> if the matching was successful,
<strong >false</strong> otherwise.
    </ul>
<p>
<h2 >EXAMPLE</h2>
    <pre >
/*
                              driver.cc
*/

#include "driver.h"

#include &lt;bobcat/pattern&gt;

using namespace std;
using namespace FBB;


void showSubstr(string const &amp;str)
{
    static int 
        count = 1;

    cout &lt;&lt; "String " &lt;&lt; count++ &lt;&lt; " is '" &lt;&lt; str &lt;&lt; "'\n";
}


int main(int argc, char **argv)
{
    {
        Pattern one("one");
        Pattern two(one);
        Pattern three("a");
        Pattern four;
        three = two;
    }

    try 
    {
        Pattern pattern("aap|noot|mies");

        {
            Pattern extra(Pattern(pattern));
        }
    
        if (pattern &lt;&lt; "noot")
            cout &lt;&lt; "noot matches\n";
        else
            cout &lt;&lt; ": noot doesn't match\n";
    }
    catch (exception const &amp;e)
    {
        cout &lt;&lt; e.what() &lt;&lt; ": compilation failed" &lt;&lt; endl;
    }
        
    string pat = "\\d+";

    while (true)
    {
        cout &lt;&lt; "Pattern: '" &lt;&lt; pat &lt;&lt; "'\n";

        try
        {
            Pattern patt(pat, argc == 1);   // case sensitive by default,
                                            // any arg for case insensitive

            cout &lt;&lt; "Compiled pattern: " &lt;&lt; patt.pattern() &lt;&lt; endl;

            Pattern pattern;
            pattern = patt;                 // assignment operator

            while (true)
            {
                cout &lt;&lt; "string to match : ";

                string st;
                getline(cin, st);
                if (st == "")
                    break;
                cout &lt;&lt; "String: '" &lt;&lt; st &lt;&lt; "'\n";
                try
                {
                    pattern.match(st);

                    Pattern p3(pattern);
        
                    cout &lt;&lt; "before:  " &lt;&lt; p3.before() &lt;&lt; "\n"
                            "matched: " &lt;&lt; p3.matched() &lt;&lt; "\n"  
                            "beyond:  " &lt;&lt; pattern.beyond() &lt;&lt; "\n"  
                            "end() = " &lt;&lt; pattern.end() &lt;&lt; endl;
        
                    for (size_t idx = 0; idx &lt; pattern.end(); ++idx)
                    {
                        string str = pattern[idx];
            
                        if (str == "")
                            cout &lt;&lt; "part " &lt;&lt; idx &lt;&lt; " not present\n";
                        else
                        {
                            Pattern::Position pos = pattern.position(idx);
        
                            cout &lt;&lt; "part " &lt;&lt; idx &lt;&lt; ": '" &lt;&lt; str &lt;&lt; "' (" &lt;&lt;
                                    pos.first &lt;&lt; "-" &lt;&lt; pos.second &lt;&lt; ")\n";
                        }
                    }
                }
                catch (exception const &amp;e)
                {
                    cout &lt;&lt; e.what() &lt;&lt; ": " &lt;&lt; st &lt;&lt; " doesn't match" &lt;&lt; endl;
                    continue;
                }
            }
        }            
        catch (exception const &amp;e)
        {
            cout &lt;&lt; e.what() &lt;&lt; ": compilation failed" &lt;&lt; endl;
        }

        cout &lt;&lt; "New pattern: ";

        if (!getline(cin, pat) || !pat.length())
            return 0;
    }
}





</pre>

<p>
<h2 >FILES</h2>
    <em >bobcat/pattern</em> - defines the class interface
<p>
<h2 >SEE ALSO</h2>
    <strong >bobcat</strong>(7), <strong >regcomp</strong>(3), <strong >regex</strong>(3), <strong >regex</strong>(7)
<p>
<h2 >BUGS</h2>
    Using <em >Pattern</em> objects as static data members of classes (or as global
objects) is potentially dangerous. If the object files defining these static
data members are stored in a dynamic library they may not be initialized
properly or timely, and their eventual destruction may result in a
segmentation fault. This is a well-known problem with static data, see, e.g.,
<em >http://www.parashift.com/c++-faq-lite/ctors.html#faq-10.15</em>. In situations
like this prefer the use of a (shared, unique) pointer to a <em >Pattern</em>,
initializing the pointer when, e.g., first used.
<p>

<h2 >DISTRIBUTION FILES</h2>
    <ul>
    <li> <em >bobcat_4.04.00-x.dsc</em>: detached signature;
    <li> <em >bobcat_4.04.00-x.tar.gz</em>: source archive;
    <li> <em >bobcat_4.04.00-x_i386.changes</em>: change log;
    <li> <em >libbobcat1_4.04.00-x_*.deb</em>: debian package holding the
            libraries;
    <li> <em >libbobcat1-dev_4.04.00-x_*.deb</em>: debian package holding the
            libraries, headers and manual pages;
    <li> <em >http://sourceforge.net/projects/bobcat</em>: public archive location;
    </ul>
<p>
<h2 >BOBCAT</h2>
    Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.
<p>
<h2 >COPYRIGHT</h2>
    This is free software, distributed under the terms of the 
    GNU General Public License (GPL).
<p>
<h2 >AUTHOR</h2>
    Frank B. Brokken (<strong >f.b.brokken@rug.nl</strong>).
<p>
libbobcat-dev 4.04.00-1 / usr / share / doc / libbobcat4-dev / man / pattern.3.html
