NAME¶

DateTime::Format::Builder - Create DateTime parser classes and objects.

VERSION¶

version 0.81

SYNOPSIS¶

    package DateTime::Format::Brief;
    use DateTime::Format::Builder
    (
        parsers => {
            parse_datetime => [
            {
                regex => qr/^(\d{4})(\d\d)(\d\d)(\d\d)(\d\d)(\d\d)$/,
                params => [qw( year month day hour minute second )],
            },
            {
                regex => qr/^(\d{4})(\d\d)(\d\d)$/,
                params => [qw( year month day )],
            },
            ],
        }
    );

DESCRIPTION¶

DateTime::Format::Builder creates DateTime parsers. Many string formats of dates and times are simple and just require a basic regular expression to extract the relevant information. Builder provides a simple way to do this without writing reams of structural code.

Builder provides a number of methods, most of which you'll never need, or at least rarely need. They're provided more for exposing of the module's innards to any subclasses, or for when you need to do something slightly beyond what I expected.

This creates the end methods. Coderefs die on bad parses, return "DateTime" objects on good parse.

TUTORIAL¶

See DateTime::Format::Builder::Tutorial.

ERROR HANDLING AND BAD PARSES¶

Often, I will speak of "undef" being returned, however that's not strictly true.

When a simple single specification is given for a method, the method isn't given a single parser directly. It's given a wrapper that will call "on_fail()" if the single parser returns "undef". The single parser must return "undef" so that a multiple parser can work nicely and actual errors can be thrown from any of the callbacks.

Similarly, any multiple parsers will only call "on_fail()" right at the end when it's tried all it could.

"on_fail()" (see later) is defined, by default, to throw an error.

Multiple parser specifications can also specify "on_fail" with a coderef as an argument in the options block. This will take precedence over the inheritable and over-ridable method.

That said, don't throw real errors from callbacks in multiple parser specifications unless you really want parsing to stop right there and not try any other parsers.

In summary: calling a method will result in either a "DateTime" object being returned or an error being thrown (unless you've overridden "on_fail()" or "create_method()", or you've specified a "on_fail" key to a multiple parser specification).

Individual parsers (be they multiple parsers or single parsers) will return either the "DateTime" object or "undef".

SINGLE SPECIFICATIONS¶

A single specification is a hash ref of instructions on how to create a parser.

The precise set of keys and values varies according to parser type. There are some common ones though:

• length is an optional parameter that can be used to specify that this particular regex is only applicable to strings of a certain fixed length. This can be used to make parsers more efficient. It's strongly recommended that any parser that can use this parameter does.

  You may happily specify the same length twice. The parsers will be tried in order of specification.

  You can also specify multiple lengths by giving it an arrayref of numbers rather than just a single scalar. If doing so, please keep the number of lengths to a minimum.

  If any specifications without lengths are given and the particular length parser fails, then the non-length parsers are tried.

  This parameter is ignored unless the specification is part of a multiple parser specification.

• label provides a name for the specification and is passed to some of the callbacks about to mentioned.
• on_match and on_fail are callbacks. Both routines will be called with parameters of:

•

preprocess is a callback provided for cleaning up input prior to parsing. It's given a hash as arguments with the following keys:

•

postprocess is the last code stop before "DateTime->new()" is called. It's given the same arguments as preprocess. This allows it to modify the parsed parameters after the parse and before the creation of the object. For example, you might use:

    {
        regex  => qr/^(\d\d) (\d\d) (\d\d)$/,
        params => [qw( year  month  day   )],
        postprocess => \&_fix_year,
    }
    

where "_fix_year" is defined as:

    sub _fix_year
    {
        my %args = @_;
        my ($date, $p) = @args{qw( input parsed )};
        $p->{year} += $p->{year} > 69 ? 1900 : 2000;
        return 1;
    }
    

This will cause the two digit years to be corrected according to the cut off. If the year was '69' or lower, then it is made into 2069 (or 2045, or whatever the year was parsed as). Otherwise it is assumed to be 19xx. The DateTime::Format::Mail module uses code similar to this (only it allows the cut off to be configured and it doesn't use Builder).

Note: It is very important to return an explicit value from the postprocess callback. If the return value is false then the parse is taken to have failed. If the return value is true, then the parse is taken to have succeeded and "DateTime->new()" is called.

See the documentation for the individual parsers for their valid keys.

Parsers at the time of writing are:

• DateTime::Format::Builder::Parser::Regex - provides regular expression based parsing.
• DateTime::Format::Builder::Parser::Strptime - provides strptime based parsing.

MULTIPLE SPECIFICATIONS¶

These are very easily described as an array of single specifications.

Note that if the first element of the array is an arrayref, then you're specifying options.

• preprocess lets you specify a preprocessor that is called before any of the parsers are tried. This lets you do things like strip off timezones or any unnecessary data. The most common use people have for it at present is to get the input date to a particular length so that the length is usable (DateTime::Format::ICal would use it to strip off the variable length timezone).

  Arguments are as for the single parser preprocess variant with the exception that label is never given.

• on_fail should be a reference to a subroutine that is called if the parser fails. If this is not provided, the default action is to call "DateTime::Format::Builder::on_fail", or the "on_fail" method of the subclass of DTFB that was used to create the parser.

EXECUTION FLOW¶

Builder allows you to plug in a fair few callbacks, which can make following how a parse failed (or succeeded unexpectedly) somewhat tricky.

       my $dt = $class->parse_datetime( $string );

      my $dt = $class->complex_parse( $string );

METHODS¶

In the general course of things you won't need any of the methods. Life often throws unexpected things at us so the methods are all available for use.

   use DateTime::Format::Builder ( blah blah blah )

   use DateTime::Format::Builder;
   DateTime::Format::Builder->create_class( blah blah blah );

SUBCLASSING¶

In the rest of the documentation I've often lied in order to get some of the ideas across more easily. The thing is, this module's very flexible. You can get markedly different behaviour from simply subclassing it and overriding some methods.

USING BUILDER OBJECTS aka USERS USING BUILDER¶

The methods listed in the METHODS section are all you generally need when creating your own class. Sometimes you may not want a full blown class to parse something just for this one program. Some methods are provided to make that task easier.

    my $parser = DateTime::Format::Builder->new();

    my $clone = $parser->new();

    my $clone_of_clone = $clone->clone();

    $parser->parser(
        regex  => qr/^ (\d{4}) (\d\d) (\d\d) $/x;
        params => [qw( year    month  day    )],
    );

   $parser->set_parser( $coderef );

   my $code = $parser->get_parser();

   my $dt = $parser->parse_datetime( "1979 07 16" );

LONGER EXAMPLES¶

Some longer examples are provided in the distribution. These implement some of the common parsing DateTime modules using Builder. Each of them are, or were, drop in replacements for the modules at the time of writing them.

THANKS¶

Dave Rolsky (DROLSKY) for kickstarting the DateTime project, writing DateTime::Format::ICal and DateTime::Format::MySQL, and some much needed review.

Joshua Hoblitt (JHOBLITT) for the concept, some of the API, impetus for writing the multilength code (both one length with multiple parsers and single parser with multiple lengths), blame for the Regex custom constructor code, spotting a bug in Dispatch, and more much needed review.

Kellan Elliott-McCrea (KELLAN) for even more review, suggestions, DateTime::Format::W3CDTF and the encouragement to rewrite these docs almost 100%!

Claus Färber (CFAERBER) for having me get around to fixing the auto-constructor writing, providing the 'args'/'self' patch, and suggesting the multi-callbacks.

Rick Measham (RICKM) for DateTime::Format::Strptime which Builder now supports.

Matthew McGillis for pointing out that "on_fail" overriding should be simpler.

Simon Cozens (SIMON) for saying it was cool.

SUPPORT¶

Support for this module is provided via the datetime@perl.org email list. See http://lists.perl.org/ for more details.

Alternatively, log them via the CPAN RT system via the web or email:

    http://rt.cpan.org/NoAuth/ReportBug.html?Queue=DateTime%3A%3AFormat%3A%3ABuilder
    bug-datetime-format-builder@rt.cpan.org

This makes it much easier for me to track things and thus means your problem is less likely to be neglected.

SEE ALSO¶

"datetime@perl.org" mailing list.

http://datetime.perl.org/

perl, DateTime, DateTime::Format::Builder::Tutorial, DateTime::Format::Builder::Parser

AUTHORS¶

• Dave Rolsky <autarch@urth.org>
• Iain Truskett

COPYRIGHT AND LICENSE¶

This software is Copyright (c) 2013 by Dave Rolsky.

This is free software, licensed under:

  The Artistic License 2.0 (GPL Compatible)