includefile(include/header)

COMMENT(manpage, section, releasedate, archive, short name)
manpage(FBB::Pattern)(3bobcat)(_CurYrs_)(libbobcat-dev__CurVers_)
                    (Pattern matcher)

manpagename(FBB::Pattern)(Performs RE pattern matching)

manpagesynopsis()
    bf(#include <bobcat/pattern>)nl()
    Linking option: tt(-lbobcat)

manpagedescription()
    bf(Pattern) objects may be used for Regular Expression (RE) pattern
matching. The class is a wrapper around the bf(regcomp)(3) family of
functions. By default it uses `extended regular expressions', requiring you to
escape multipliers and bounding-characters when they must be interpreted as
ordinary characters (i.e., tt(*, +, ?, ^, $, |, (, ), [, ], {, }) must be
escaped when used as literal characters).

    The bf(Pattern) class supports the following (Perl-like)
special escape sequences: nl()
        \b - indicating a word-boundary nl()
        \d - indicating a digit (tt([[:digit:]])) character nl()
        \s - indicating a white-space (tt([:space:])) character nl()
        \w - indicating a word (tt([:alnum:])) character

    The corresponding capitals (e.g., bf(\W)) define the complementary
character sets. Note that the capitalized character set shorthands are not
expanded inside explicit character-classes (i.e., tt([ ... ])
constructions). E.g., tt([\W]) represents a set of two characters: tt(\) and
tt(W).

    As the backslash (tt(\)) is treated as a special character it should be
handled carefully. bf(Pattern) converts the escape sequences tt(\d \s \w) (and
outside of explicit character classes the sequences tt(\D \S \W)) to their
respective character classes. All other escape sequences are kept as-is, and
the resulting regular expression is passed to the pattern matching compilation
function bf(regcomp)(3). The tt(regcomp) function interprets escape
sequences. Consequently some care should be exercised when defining patterns
containing escape sequences. Here are the rules:
    itemization(
    it() Special escape sequences (like tt(\d)) are converted to character
classes. E.g.,
        verb(
    ---------------------------------------------------------
    Specify:    Converts to:    regcomp uses:      Matches:
    ---------------------------------------------------------
    \d          [[:digit:]]     [[:digit:]]        3
    ---------------------------------------------------------
        )
    it() Ordinary escape sequences (like tt(\x)) are kept as-is. E.g.,
        verb(
    ---------------------------------------------------------
    Specify:    Converts to:    regcomp uses:      Matches:
    ---------------------------------------------------------
    \x          \x              x                  x
    ---------------------------------------------------------
        )
    it() To specify literal escape sequences, Raw String Literals are advised,
    as they don't require doubling escape sequences. E.g., the following
    regular expression matches an (alpha-numeric) word, followed by optional
    blanks, a colon, more optional blanks and a (decimal) number:
        verb(
    R"((\w+)\s*:\s*\d+)"
        )
    Furthermore, by using (raw) string concatenation in source file  the
    legibility of complex regular expressions is greatly improved. The above
    regular expression could also be specified as
        verb(
    R"((\w+))"      // a word
    R"(\s*:)"       // then ':', maybe first some space chars
    R"(\s*\d+)"     // then digits, maybe first some space chars
        )

    )

includefile(include/namespace)

manpagesection(INHERITS FROM)
    -

manpagesection(TYPEDEF)
    itemization(
    itb(Pattern::Position)
        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 tt(std::pair<size_t, size_t>).
    )

manpagesection(OPTIONS)
    The following options can be specified with the non-default constructor
    and the tt(match) member (see below):

    itemization(
    it() REG_EXTENDED:nl() 
       Used by default: POSIX Extended Regular Expression syntax when
        interpreting regex.  If not set, POSIX Basic Regular Expression syntax
        is used;

    it() REG_NOSUB:nl()
       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;

    it() REG_NEWLINE:nl()
        Used by default: match-any-character operators don't match newlines.

        A non-matching list ([^...])  not containing a newline does not match
        a newline.

        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.

        Match-end-of-line operator ($) matches the empty string immediately
        before a newline, regardless of whether eflags contains REG_NOTEOL.
    )

manpagesection(CONSTRUCTORS)
    itemization(
    itb(Pattern())
       The default constructor does not define a pattern, but can be used in
        e.g., containers requiring default constructors;

    itb(Pattern(std::string const &pattern,
                            bool caseSensitive = true,
                            size_t nSub = 10,
                        int options = REG_EXTENDED | REG_NEWLINE))
       This constructor compiles tt(pattern), preparing the bf(Pattern) object
        for pattern matches. The second parameter determines whether case
        sensitive matching will be used (the default) or not. Subexpressions
        are defined by pairs of parentheses. 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.
    )

    Copy and move constructors (and assignment operators) are available.

manpagesection(MEMBER FUNCTIONS)
    itemization(
    itb(std::string before() const)
       Following a successful match, bf(before()) returns the text before the
        matched text;

    itb(std::string beyond() const)
       Following a successful match, bf(beyond()) returns the text beyond the
        matched text;

    itb(size_t end() const)
       Returns the number of matched elements (the full pattern and
        subexpressions). When no match was obtained tt(string::npos) is
        returned. When specifying index values bf(end()) or beyond then+nl()
            tt(position(idx)) returns two tt(std::string::npos);nl()
            tt(operator[](idx)) returns an empty string;

    itb(void match(std::string const &text, int options = 0))
       Match a string with a pattern.  If the text could not be matched, an
        bf(Exception)(3bobcat) exception is thrown, using
        bf(Pattern::match()) as its prefix-text;

    itb(std::string matched() const) Following a successful match, this
        function returns the (completely) matched text;

    itb(std::string const &pattern() const)
        This member function returns the pattern that was specified by the
        constructor and by the tt(setPattern) member;

    itb(Pattern::Position position(size_t index) const)
       When specifying em(index 0) the begin and end index values of the fully
        matched text is returned. Other index values return the begin and end
        index values of the specified (parenthesized) sub-expression. When
        index is at least bf(end()) a 
       tt(Position{ string::npos, string::npos }) value is returned;

    itb(void setPattern(std::string const &pattern,
                            bool caseSensitive = true,
                            size_t nSub = 10,
                        int options = REG_EXTENDED | REG_NEWLINE))
       This member function redefines tt(pattern) as the regular expression
        used my subsequent tt(match)-member calls.  An bf(FBB::Exception)
        exception is thrown if the new pattern could not be compiled;

    itb(void swap(Pattern &other))
       The content of the current object and the tt(other) object are
        swapped.
    )

manpagesection(OVERLOADED OPERATORS)

    itemization(
    itb(std::string operator[](size_t index) const)
       Returns (for tt(index) value 0) the fully matched text or (for larger
        tt(index) values up to the value returned by tt(end())) the text of
        sub-expression tt(index). An empty string is returned for index values
        at least equal to tt(end());

    itb(Pattern &operator<<(int matchOptions))
        Sets match-options to be used (once) with the following overloaded
        operator;

    itb(bool operator<<(std::string const &text))
       Performs a bf(match(text, matchOptions)) call, catching any exception
        that might be thrown. If no em(matchOptions) were set using
        tt(operator<<(int matchOptions)) no match-options 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
        bf(true) if the matching was successful, bf(false) otherwise.
    )

manpagesection(EXAMPLE)
    verbinclude(../../pattern/driver/driver.cc)

manpagefiles()
    em(bobcat/pattern) - defines the class interface

manpageseealso()
    bf(bobcat)(7), bf(regcomp)(3), bf(regex)(3), bf(regex)(7)

manpagebugs()
    None reported.

includefile(include/trailer)
