                       Lua rexlib release 1.18
                       -----------------------

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


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.

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.

Note for Lua 4 users: release 8.1 of the library, which works with
Lua 4, is still available.

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

Thanks to Thatcher Ulrich for bug and warning fixes.


Synopsis
--------

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

The library provides POSIX and PCRE regular expression matching:

rex.newPOSIX(p[, cf])
        returns a POSIX regular expression object for the pattern p,
        subject to compilation flags cf (a number).

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

rex.newPCRE(p[, cf[, lo]])
        returns a PCRE regular expression object for the pattern p,
        subject to compilation flags cf (a number) and locale lo (a
        string).

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

rex.versionPCRE()
        returns a string containing version and release date of the
        used PCRE library.

r:match(s[, st[, ef]])
        returns
          * the start and end point of the first match of the compiled
            regexp r in the string s, starting from offset st (a
            number), subject to execution flags 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).

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.
        * 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 }.

r:gmatch(s, f[, n[, ef]])
        * tries to match the regex r against s up to n times (or as
          many as possible if n is either not given or is not a
          positive number), subject to execution flags ef;
        * each time there is a match, f is called as f(m, t), where m
          is the matched string and t is a table of substring matches
          (this table contains false in the positions where the
          corresponding sub-pattern did not match.);
        * if f returns a true value, then gmatch immediately returns;
        * gmatch returns the number of matches made.

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 not
patterns.)


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
