Regular expressions are hard. They are hard to create, and even harder to read after the fact. Regular expressions, while quite powerful, are a blight upon readable code. There is no easy way to know that '/^\d{4}\/\d{2}\/\d{2}$/' is a search for a string in the form of 'xxxx/xx/xx'. You have to know that ^ is the start of a line, \d is a digit, \/ is / escaped, etc.

Granted, once you know regular expressions, that information is portable across which ever language you use, be it PHP, Perl, Javascript, whatever. But getting to that point is not easy, and even after you are there, the fact remains:Regular expressions are not human parseable. This is where BunnyRegex comes in.

BunnyRegex is a BSD Licensed class wrapper around the preg_* functions of PHP. The whole point of its existence is to make working with regular expressions less like the memorization and usage of ancient Norse runes (Elder Futhark) and more like, you know, actual programming. BunnyRegex is also a great example of Fluent Programming and the implementation of mini-languages (more on this in a new entry). BunnyRegex is available on my personal wiki.

So, here is some code illustrating how BunnyRegex works. We are going to do the same regular expression for the string 'xxxx/xx/xx'.

include("BunnyRegex.php");

$pattern = new BunnyRegex();

$pattern->bol()        // ^
        ->digit()      // \d
        ->exactly(4)   // {4}
        ->string('/')  // /
        ->digit()      // \d
        ->exactly(2)   // {2}
        ->string('/')  // /
        ->digit()      // \d
        ->exactly(2)   // {2}
        ->eol();       // $

$pattern->match('2006/02/28'); // returns true
$pattern->numberOfMatches('2006/02/28'); // returns 1

There are a few things to notice here. First off, you will notice that the way this code is laid out is almost completely backwards from the way PCRE is normally written inside of PHP; usually the readable part of the code is the comments, and the unreadable part is the code itself. Second, you will notice that there is a chain of method calls, starting from the bol() (i.e. beginning of line) method and finishing off at the eol() method. And finally, you will notice that the regular expression can be re-used, as shown by the match() and numberOfMatches() method calls. So what is going on here?

Fluent Regular Expressions

Every method of BunnyRegex that helps build your regular expression returns an object reference to the current object. This means that you can chain together methods like This:

startCapture()->startGroup()->upper()->lower()->oneOrMore()->endGroup()->moreThan(1)->endCapture()

which is equivalent to this:

$pattern->startCapture();
$pattern->startGroup();
$pattern->upper();
$pattern->lower();
$pattern->oneOrMore();
$pattern->endGroup();
$pattern->moreThan(1);
$pattern->endCapture();

This method of programming is called "Fluent Programming" and depending on the situation, can make for much more readable code. When fluent programming is applied to BunnyRegex, it allows you to format your regular expression code in the same way that you format the rest of your code, with proper indentation of blocks. For example:

$pattern
    ->startCapture()
        ->startGroup()
            ->upper()
            ->lower()->oneOrMore()
        ->endGroup()
        ->moreThan(1)
    ->endCapture();

You can pretty well see what is going on here just by looking, as opposed to the string '((?[A-Z][a-z]+){2,})'. What is lost of course is brevity; those of you who enjoy being able to pound out something as powerful as "return every CamelCase word to me as an array" in just one line are not going to be impressed. Neither are those of you who feel somehow special by knowing and understanding cryptic regular expressions. However, those of you who work with regular expressions seldom enough not to remember every minute character/meta-character combination, but frequently enough so that it is a pain in the ass, then BunnyRegex is for you. The method names may even be slightly less memorable then the usual regex sigils, but they are about 100 times more readable.

I have found so far that the best way to format the regular expression is to give each component its own line, with exception to the repetition operators (noneOrOne(), noneOrMore(), oneOrMore(), moreThan(), between(), etc.) which should be grouped with the entity they are repeating. The nonGreedy operator should follow the repetition operator.

As you can see, this is a lot like a mini-language that is implemented right inside of php, rather then just a simple class. This is where fluent programming really shines because it allows you to do two things: 1) think about your problem in terms of the implementation of a mini-language and 2) wrap the solution of your problem in a reuseable, exportable software component. This idea of implementing a language to solve your problem is not a new one, the Scheme guys have been doing it for years, but it is really quite an effective way to think about and solve your problem. If the language you implement is sufficiently general, you can turn around and use it to solve other similar problems.

Matching, Grepping, Replacing and Splitting with BunnyRegex

Once you have built your regular expression, you probably want to do something with it. About the easiest thing that you can do is to simply get the raw regular expression with get(). You can then use the normal preg_* functions on that string. However, BunnyRegex also gives you access to the same functions from within (with slightly different names and semantics). Use whichever method you feel is comfortable. I am not going to document these, because their behavior so closely mirrors the preg_* functions. Check the PHP Manual for more info.

• match($subject) is similar to preg_match, except it will return a boolean as to whether or not the match failed or succeeded
• numberOfMatches($subject) is exactly the same as preg_match_all.
• captures($subject) will return the array of captures that preg_match would return in its 3rd argument.
• allCaptures($subject) is similar to the previous method, except it uses preg_match_all.
• grep($subjectArray) is preg_grep. It takes an array, and then returns an array of elements that match.

All of these methods take a (string) subject to match against as an argument, with exception to grep.

• replace($replacement, $subject, [$limit]) is preg_replace. No frills, no lace.
• replaceWithCallback($callback, $subject, [$limit]) is preg_replace_callback. No frills, no lace.

The final method is split($subject, [$allowempty], [$limit]) which, like most of the other methods, is a simple wrapper around the similarly named preg_split function.

As I mentioned earlier, you can run as many of the match methods on your regular expression as you like. You can even build a regular expression, match it, and then continue to build it and matching it:

$r = new BunnyRegex()
$r->bol()
  ->whitespace()->noneOrMore()
  ->string('*@');

if ($r->match($myString))
{
    $r->string('param');
    if ($r->match($myString))
    {
        ....
    }
}

I am not sure just how useful this is to people, but it shows just how flexable BunnyRegex is.

At any rate, I hope that this class will be useful to the PHP community, especially those who are tired of programming in Elder Futhark