On Apache
Under GNU General Public License
2025-11-21 17:36 @216.73.216.164 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)
DateTime::Format::Builder::ParsUserpContributed Perl DocumeDateTime::Format::Builder::Parser(3pm)
NAME
DateTime::Format::Builder::Parser - Parser creation
VERSION
version 0.83
SYNOPSIS
my $class = 'DateTime::Format::Builder::Parser';
my $parser = $class->create_single_parser(%specs);
DESCRIPTION
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.
METHODS
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.
Parameter Handling (implementations)
These methods allow implementations to have validation of their arguments in a standard
manner and due to "Parser"'s implementation, these methods also allow "Parser" to
determine which implementation to use.
Common parameters
These parameters appear for all parser implementations. These are primarily documented in
DateTime::Format::Builder.
o on_match
o on_fail
o postprocess
o preprocess
o label
o length
length may be a number or an arrayref of numbers indicating the length of the input.
This lets us optimize in the case of static length input. If supplying an arrayref of
numbers, please keep the number of numbers to a minimum.
params
my $params = $self->params;
validate( @_, $params );
Returns declared parameters and "common" parameters in a hashref suitable for handing to
Params::Validate's "validate" function.
params_all
my $all_params = $self->params_all;
Returns a hash of all the valid options. Not recommended for general use.
valid_params
__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.
whose_params
my $class = whose_params( $key );
Internal function which merely returns to which class a parameter is unique. If not
unique, returns "undef".
Organizing and Creating Parsers
create_single_parser
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".
merge_callbacks
Produce either undef or a single coderef from either undef, an empty array, a single
coderef or an array of coderefs
create_multiple_parsers
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.
sort_parsers
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_parser
"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.
FINDING IMPLEMENTATIONS
"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.
WRITING A PARSER IMPLEMENTATION
Naming your parser
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.
Declaring specification arguments
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.
Define create_parser
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".
Callbacks
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.
SEE ALSO
"datetime AT perl.org" mailing list.
http://datetime.perl.org/
perl, DateTime, DateTime::Format::Builder.
Params::Validate.
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.
SUPPORT
Bugs may be submitted at
<https://github.com/houseabsolute/DateTime-Format-Builder/issues>.
I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
SOURCE
The source code repository for DateTime-Format-Builder can be found at
<https://github.com/houseabsolute/DateTime-Format-Builder>.
AUTHORS
o Dave Rolsky <autarch AT urth.org>
o Iain Truskett <spoon AT cpan.org>
COPYRIGHT AND LICENSE
This software is Copyright (c) 2020 by Dave Rolsky.
This is free software, licensed under:
The Artistic License 2.0 (GPL Compatible)
The full text of the license can be found in the LICENSE file included with this
distribution.
perl v5.30.3 2020-08-11 DateTime::Format::Builder::Parser(3pm)
Generated by $Id: phpMan.php,v 4.55 2007/09/05 04:42:51 chedong Exp $ Author: Che Dong
On Apache
Under GNU General Public License
2025-11-21 17:36 @216.73.216.164 CrawledBy Mozilla/5.0 AppleWebKit/537.36 (KHTML, like Gecko; compatible; ClaudeBot/1.0; +claudebot@anthropic.com)