chromatic > Regexp-English > Regexp::English

Download:
Regexp-English-1.01.tar.gz

Dependencies

Annotate this POD

CPAN RT

Open  0
View/Report Bugs
Module Version: 1.01   Source  

NAME ^

Regexp::English - Perl module to create regular expressions more verbosely

SYNOPSIS ^

        use Regexp::English;

        my $re = Regexp::English
                -> start_of_line
                -> literal('Flippers')
                -> literal(':')
                -> optional
                        -> whitespace_char
                -> end
                -> remember
                        -> multiple
                                -> digit;

        while (<INPUT>) {
                if (my $match = $re->match($_)) {
                        print "$match\n";
                }
        }

DESCRIPTION ^

Regexp::English provides an alternate regular expression syntax, one that is slightly more verbose than the standard mechanisms. In addition, it adds a few convenient features, like incremental expression building and bound captures.

You can access almost every regular expression available in Regexp::English can through a method, though some are also (or only) available as functions. These methods fall into several categories: characters, quantifiers, groupings, and miscellaneous. The division wouldn't be so rough if the latter had a better name.

All methods return the Regexp::English object, so you can chain method calls as in the example above. Though there is a new() method, you can use any character method, or remember(), to create an object.

To perform a match, use the match() method. Alternately, if you use a Regexp::English object as if it were a compiled regular expression, the module will automatically compile it behind the scenes.

Characters

Character methods correspond to standard regular expression characters and metacharacters, for the most part. As a little bit of syntactic sugar, most of these methods have plurals, negations, and negated plurals. This is more clear looking at them. Though the point of these is to be available as calls on a new Regexp::English object while building up larger regular expressions, you may also used them as class methods to access regular expression atoms which you then use in larger regular expressions. This isn't entirely pretty, but it ought to work just about everywhere.

Quantifiers

Quantifiers provide a mechanism to specify how many items to expect, in general or specific terms. You may have these exported into the calling package's namespace with the :standard argument to the use() call, but the preferred interface is to use them as method calls. This is slightly more complicated, but cleaner conceptually. The interface may change slightly in the future, if someone comes up with something even better.

By default, quantifiers operate on the next arguments, not the previous ones. (It is much easier to program this way.) For example, to match multiple digits, you might write:

        my $re = Regexp::English->new()
                ->multiple()
                        ->digits();

The indentation should make this more clear.

Quantifiers persist until something attempts a match or something calls the corresponding end() method. As match() calls end() internally, attempting a match closes all active quantifiersThere is currently no way to re-open a quantifier even if you add to a Regexp::English object. This is a non-trivial problem (as the author understands it), and there's no good solution for it in normal regular expressions anyway.

If you have imported the quantifiers, you can pass the quantifiables as arguments:

        use Regexp::English ':standard';

        my $re = Regexp::English->new()
                ->multiple('a');

This closes the open quantifier for you automatically. Though this syntax is slightly more visually appealing, it does involve exporting quite a few methods into your namespace, so it is not the default behavior. Besides that, if you get in this habit, you'll eventually have to use the :all tag. It's better to make a habit of using the method calls, or to push Vahe to write Regexp::Easy. :)

Groupings

Groupings function much the same as quantifiers, though they have semantic differences. The most important similarity is that you can use them with the function or the method interface. The method interface is nicer, but see the documentation for end() for more information.

Groupings generally correspond to advanced Perl regular expression features like lookaheads and lookbehinds. If you find yourself using them on a regular basis, you're probably ready to graduate to hand-rolled regular expressions (or to contribute code to improve Regexp::English.

Miscellaneous

These subroutines don't really fit anywhere else. They're useful, and mostly cool.

EXPORTS ^

By default, there are no exports. This is an object oriented module, and this is how it should be. You can import the Quantifier and Grouping subroutines by providing the :standard argument to the use() line and the Character methods with the :chars tag.

        use Regexp::English qw( :standard :chars );

You can also use the :all tag:

        use Regexp::English ':all';

This interface may change slightly in the future. If you find yourself exporting things, you should look into Vahe Sarkissian's upcoming Regexp::Easy module. This is probably news to him, too.

TODO ^

AUTHOR ^

chromatic, chromatic at wgz dot org, with many suggestions from Vahe Sarkissian and Damian Conway.

COPYRIGHT ^

Copyright (c) 2001-2002, 2005, 2011 by chromatic. Most rights reserved.

This program is free software; you can use, modify, and redistribute it under the same terms as Perl 5.12 itself.

See http://www.perl.com/perl/misc/Artistic.html

SEE ALSO ^

perlre

syntax highlighting: