DateTime::Format::Builder::Parser - Parser creation
my $class = 'DateTime::Format::Builder::Parser';
my $parser = $class->create_single_parser( %specs );
This is a utility class for DateTime::Format::Builder that
handles creation of parsers. It is to here that Builder delegates
most of its responsibilities.
There are two sorts of methods in this class. Those used by
parser implementations and those used by Builder. It is
generally unlikely the user will want to use any of them.
They are presented, grouped according to use.
These methods allow implementations to have validation of
their arguments in a standard manner and due to Parser's
impelementation, these methods also allow Parser to
determine which implementation to use.
These parameters appear for all parser implementations. These are primarily documented in the main docs.
my $params = $self->params();
validate( @_, $params );
Returns declared parameters and common parameters in a hashref
suitable for handing to Params::Validate's validate function.
my $all_params = $self->params_all();
Returns a hash of all the valid options. Not recommended for general use.
__PACKAGE__->valid_params( %params );
Arguments are as per Params::Validate's validate function.
This method is used to declare what your valid arguments are in
a parser specification.
my $class = whose_params( $key );
Internal function which merely returns to which class a
parameter is unique. If not unique, returns undef.
This takes a single specification and returns a coderef that is a parser that suits that specification. This is the end of the line for all the parser creation methods. It delegates no further.
If a coderef is specified, then that coderef is immediately returned (it is assumed to be appropriate).
The single specification (if not a coderef) can be either a hashref or a hash. The keys and values must be as per the specification.
It is here that any arrays of callbacks are unified. It is also here that any parser implementations are used. With the spec that's given, the keys are looked at and whichever module is the first to have a unique key in the spec is the one to whom the spec is given.
Note: please declare a valid_params argument with an
uppercase letter. For example, if you're writing
DateTime::Format::Builder::Parser::Fnord, declare a
parameter called Fnord. Similarly, DTFBP::Strptime
should have Strptime and DTFBP::Regex should have
Regex. These latter two don't for backwards compatibility
reasons.
The returned parser will return either a DateTime object
or undef.
Produce either undef or a single coderef from either undef, an empty array, a single coderef or an array of coderefs
Given the options block (as made from create_parser())
and a list of single parser specifications, this returns a
coderef that returns either the resultant DateTime object
or undef.
It first sorts the specifications using sort_parsers()
and then creates the function based on what that returned.
This takes the list of specifications and sorts them while turning the specifications into parsers. It returns two values: the first is a hashref containing all the length based parsers. The second is an array containing all the other parsers.
If any of the specs are not code or hash references, then it
will call croak().
Code references are put directly into the 'other' array. Any
hash references without length keys are run through
create_single_parser() and the resultant parser is placed
in the 'other' array.
Hash references with length keys are run through
create_single_parser(), but the resultant parser is used
as the value in the length hashref with the length being the
key. If two or more parsers have the same length
specified then an error is thrown.
create_class() is mostly a wrapper around
create_parser() that does loops and stuff and calls
create_parser() to create the actual parsers.
create_parser() takes the parser specifications (be they
single specifications or multiple specifications) and
returns an anonymous coderef that is suitable for use as a
method. The coderef will call croak() in the event of
being unable to parse the single string it expects as input.
The simplest input is that of a single specification,
presented just as a plain hash, not a hashref. This is
passed directly to create_single_parser() with the return
value from that being wrapped in a function that lets it
croak() on failure, with that wrapper being returned.
If the first argument to create_parser() is an arrayref,
then that is taken to be an options block (as per the
multiple parser specification documented earlier).
Any further arguments should be either hashrefs or coderefs.
If the first argument after the optional arrayref is not a
hashref or coderef then that argument and all remaining
arguments are passed off to create_single_parser()
directly. If the first argument is a hashref or coderef,
then it and the remaining arguments are passed to
create_multiple_parsers().
The resultant coderef from calling either of the creation
methods is then wrapped in a function that calls croak()
in event of failure or the DateTime object in event of
success.
Parser automatically loads any parser classes in @INC.
To be loaded automatically, you must be a
DateTime::Format::Builder::Parser::XXX module.
To be invisible, and not loaded, start your class with a lower class letter. These are ignored.
Create a module and name it in the form
DateTime::Format::Builder::Parser::XXX
where XXX is whatever you like,
so long as it doesn't start with a
lower case letter.
Alternatively, call it something completely different if you don't mind the users explicitly loading your module.
I'd recommend keeping within the DateTime::Format::Builder
namespace though --- at the time of writing I've not given
thought to what non-auto loaded ones should be called. Any
ideas, please email me.
Call <DateTime::Format::Builder::Parser-valid_params()>> with
Params::Validate style arguments. For example:
DateTime::Format::Builder::Parser->valid_params(
params => { type => ARRAYREF },
Regex => { type => SCALARREF, callbacks => {
'is a regex' => sub { ref(shift) eq 'Regexp' }
}}
);
Start one of the key names with a capital letter. Ideally that key should match the XXX from earlier. This will be used to help identify which module a parser specification should be given to.
The key names on_match, on_fail, postprocess, preprocess,
label and length are predefined. You are recommended to make use
of them. You may ignore length as sort_parsers takes care of that.
A class method of the name create_parser that does the following:
Its arguments are as for a normal method (i.e. class as first argument).
The other arguments are the result from a call to Params::Validate
according to your specification (the valid_params earlier), i.e. a
hash of argument name and value.
The return value should be a coderef that takes a date string as its
first argument and returns either a DateTime object or undef.
It is preferred that you support some callbacks to your parsers.
In particular, preprocess, on_match, on_fail and
postprocess. See the main Builder
docs for the appropriate placing of calls to the callbacks.
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://perl.dellah.org/rt/dtbuilder
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 DateTime::Format::Builder.
Copyright © Iain Truskett, 2003. All rights reserved.
This library is free software; you can redistribute it and/or modify it under the same terms as Perl itself, either Perl version 5.000 or, at your option, any later version of Perl 5 you may have available.
The full text of the licences can be found in the Artistic and COPYING files included with this module, or in perlartistic and perlgpl as supplied with Perl 5.8.1 and later.
Iain Truskett <spoon@cpan.org>
datetime@perl.org mailing list.
http://datetime.perl.org/
perl, DateTime, DateTime::Format::Builder.
DateTime::Format::Builder::Parser::generic, DateTime::Format::Builder::Parser::Dispatch, DateTime::Format::Builder::Parser::Quick, DateTime::Format::Builder::Parser::Regex, DateTime::Format::Builder::Parser::Strptime.