=head1 NAME

rex - regular expressions (Lua rexlib)

=head1 OVERVIEW

This archive contains the lrexlib regular expression library for Lua
5.0. The Makefile provided builds it into shared libraries called
libluarex_posix.so and libluarex_pcre.so, which can be used with
loadlib.

The initialisation function (for use with C<loadlib>) is C<luaopen_rex>.

The library provides POSIX and PCRE regular expression matching:

=head1 REFERENCE

=head2 C<rex.newPOSIX>

  rex.newPOSIX(p[, cf])

returns a POSIX regular expression object for the pattern C<p>,
subject to compilation flags C<cf> (a number).

=head2 C<rex.flagsPOSIX>

  rex.flagsPOSIX()

returns a table with available POSIX flags (numbers) keyed by
their names (strings).

=head2 C<rex.newPCRE>

  rex.newPCRE(p[, cf[, lo]])

returns a PCRE regular expression object for the pattern C<p>,
subject to compilation flags C<cf> (a number) and locale C<lo> (a
string).

=head2 C<rex.flagsPCRE>

  rex.flagsPCRE()

returns a table with available PCRE flags (numbers) keyed by
their names (strings).

=head2 C<rex.versionPCRE>

  rex.versionPCRE()

returns a string containing version and release date of the
used PCRE library.

=head2 C<r:match>

  r:match(s[, st[, ef]])

returns

* the start and end point of the first match of the compiled
regexp C<r> in the string C<s>, starting from offset C<st> (a
number), subject to execution flags C<ef> (a number);

* substring matches ("captures" in Lua terminology) are
returned as a third result, in a table (this table
contains false in the positions where the corresponding
sub-pattern did not match);

* PCRE: if named subpatterns are used then the table
also contains substring matches keyed by their
correspondent subpattern names (strings).

=head2 C<r:exec>

  r:exec(s[, st[, ef]])

This function is like r:match except that a table returned
as a third result contains offsets of substring matches
rather than substring matches themselves.

* PCRE: that table will not contain string keys, even if
named subpatterns are used.

For example, if the whole match is at offsets 10,20 and
substring matches are at offsets 12,14 and 16,19 then the
function returns the following: 10, 20, { 12,14,16,19 }.

=head2 C<r:gmatch>

  r:gmatch(s, f[, n[, ef]])

Tries to match the regex C<r> against C<s> up to C<n> times (or as
many as possible if C<n> is either not given or is not a positive
number), subject to execution flags ef;

Each time there is a match, C<f> is called as C<f(m, t)>, where C<m>
is the matched string and C<t> is a table of substring matches (this
table contains false in the positions where the corresponding
sub-pattern did not match.);

* PCRE: if "named subpatterns" are used then the table also
contains substring matches keyed by their correspondent
subpattern names (strings).

If C<f> returns a true value, then C<gmatch> immediately returns;
gmatch returns the number of matches made.

=head2 Additional Notes

Optional arguments supplied as nil are treated as if they had been
omitted. Regular expression objects are automatically garbage
collected.

If the library is compiled against Henry Spencer's regex library, then
regular expressions and the strings to match them against may contain
NULs. (For PCRE, strings to be matched may contain NULs but patterns
may not.)

It may be useful to define:

  -- Default constructor (use PCREs)
  setmetatable(rex, {__call =
                 function (self, p, cf, lo)
                   return self.newPCRE(p, cf, lo)
                 end})
  
  -- partial string.find equivalent
  function rex.find(s, p, st)
    return rex(p):match(s, st)
  end
  
  -- partial string.gsub equivalent
  function rex.gsub(s, p, f, n)
    return rex(p):gmatch(s, f, n)
  end

=head1 VERSION

This is version 1.19.

=head1 CREDITS

by Shmuel Zeigerman (shmuz _ at _ actcom.co.il) [maintainer]
and Reuben Thomas (rrt _ at _ sc3d.org)

Thanks to Thatcher Ulrich for bug and warning fixes.
Thanks to Nick Gammon for adding support for PCRE named subpatterns.

=head1 CONTACT

Please report bugs and make suggestions to Shmuel, who is the current
maintainer.

=head1 LICENSE

Lrexlib is copyright Reuben Thomas 2000-2004 and copyright Shmuel
Zeigerman 2004, and is released under the MIT license, like Lua (see
http://www.lua.org/copyright.html for the full license; it's basically
the same as the BSD license). There is no warranty.