.\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "DateTime::Format::Builder::Parser 3"
.TH DateTime::Format::Builder::Parser 3 "2020-08-09" "perl v5.26.3" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
DateTime::Format::Builder::Parser \- Parser creation
.SH "VERSION"
.IX Header "VERSION"
version 0.83
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
.Vb 2
\&    my $class  = \*(AqDateTime::Format::Builder::Parser\*(Aq;
\&    my $parser = $class\->create_single_parser(%specs);
.Ve
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
This is a utility class for DateTime::Format::Builder that handles creation
of parsers. It is to here that \f(CW\*(C`Builder\*(C'\fR delegates most of its
responsibilities.
.SH "METHODS"
.IX Header "METHODS"
There are two sorts of methods in this class. Those used by parser
implementations and those used by \f(CW\*(C`Builder\*(C'\fR. It is generally unlikely the
user will want to use any of them.
.PP
They are presented, grouped according to use.
.SS "Parameter Handling (implementations)"
.IX Subsection "Parameter Handling (implementations)"
These methods allow implementations to have validation of their arguments in a
standard manner and due to \f(CW\*(C`Parser\*(C'\fR's implementation, these methods also
allow \f(CW\*(C`Parser\*(C'\fR to determine which implementation to use.
.PP
\fICommon parameters\fR
.IX Subsection "Common parameters"
.PP
These parameters appear for all parser implementations.  These are primarily
documented in DateTime::Format::Builder.
.IP "\(bu" 4
on_match
.IP "\(bu" 4
on_fail
.IP "\(bu" 4
postprocess
.IP "\(bu" 4
preprocess
.IP "\(bu" 4
label
.IP "\(bu" 4
length
.Sp
\&\fBlength\fR 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.
.PP
\fIparams\fR
.IX Subsection "params"
.PP
.Vb 2
\&    my $params = $self\->params;
\&    validate( @_, $params );
.Ve
.PP
Returns declared parameters and \f(CW\*(C`common\*(C'\fR parameters in a hashref suitable for
handing to Params::Validate's \f(CW\*(C`validate\*(C'\fR function.
.PP
\fIparams_all\fR
.IX Subsection "params_all"
.PP
.Vb 1
\&    my $all_params = $self\->params_all;
.Ve
.PP
Returns a hash of all the valid options. Not recommended for general use.
.PP
\fIvalid_params\fR
.IX Subsection "valid_params"
.PP
.Vb 1
\&    _\|_PACKAGE_\|_\->valid_params(%params);
.Ve
.PP
Arguments are as per Params::Validate's \f(CW\*(C`validate\*(C'\fR function.  This method
is used to declare what your valid arguments are in a parser specification.
.PP
\fIwhose_params\fR
.IX Subsection "whose_params"
.PP
.Vb 1
\&    my $class = whose_params( $key );
.Ve
.PP
Internal function which merely returns to which class a parameter is
unique. If not unique, returns \f(CW\*(C`undef\*(C'\fR.
.SS "Organizing and Creating Parsers"
.IX Subsection "Organizing and Creating Parsers"
\fIcreate_single_parser\fR
.IX Subsection "create_single_parser"
.PP
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.
.PP
If a coderef is specified, then that coderef is immediately returned (it is
assumed to be appropriate).
.PP
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.
.PP
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.
.PP
\&\fBNote\fR: please declare a \f(CW\*(C`valid_params\*(C'\fR argument with an uppercase
letter. For example, if you're writing
\&\f(CW\*(C`DateTime::Format::Builder::Parser::Fnord\*(C'\fR, declare a parameter called
\&\f(CW\*(C`Fnord\*(C'\fR. Similarly, \f(CW\*(C`DTFBP::Strptime\*(C'\fR should have \f(CW\*(C`Strptime\*(C'\fR and
\&\f(CW\*(C`DTFBP::Regex\*(C'\fR should have \f(CW\*(C`Regex\*(C'\fR. These latter two don't for backwards
compatibility reasons.
.PP
The returned parser will return either a \f(CW\*(C`DateTime\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR.
.PP
\fImerge_callbacks\fR
.IX Subsection "merge_callbacks"
.PP
Produce either undef or a single coderef from either undef, an empty array, a
single coderef or an array of coderefs
.SS "create_multiple_parsers"
.IX Subsection "create_multiple_parsers"
Given the options block (as made from \f(CW\*(C`create_parser\*(C'\fR) and a list of single
parser specifications, this returns a coderef that returns either the
resultant \f(CW\*(C`DateTime\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR.
.PP
It first sorts the specifications using \f(CW\*(C`sort_parsers\*(C'\fR and then creates the
function based on what that returned.
.SS "sort_parsers"
.IX Subsection "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.
.PP
If any of the specs are not code or hash references, then it will call
\&\f(CW\*(C`croak\*(C'\fR.
.PP
Code references are put directly into the 'other' array. Any hash references
without \fIlength\fR keys are run through \f(CW\*(C`create_single_parser\*(C'\fR and the
resultant parser is placed in the 'other' array.
.PP
Hash references \fBwith\fR \fIlength\fR keys are run through
\&\f(CW\*(C`create_single_parser\*(C'\fR, 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 \fIlength\fR specified then an error is thrown.
.SS "create_parser"
.IX Subsection "create_parser"
\&\f(CW\*(C`create_class\*(C'\fR is mostly a wrapper around \f(CW\*(C`create_parser\*(C'\fR that does loops
and stuff and calls \f(CW\*(C`create_parser\*(C'\fR to create the actual parsers.
.PP
\&\f(CW\*(C`create_parser\*(C'\fR 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 \f(CW\*(C`croak\*(C'\fR in the
event of being unable to parse the single string it expects as input.
.PP
The simplest input is that of a single specification, presented just as a
plain hash, not a hashref. This is passed directly to \f(CW\*(C`create_single_parser\*(C'\fR
with the return value from that being wrapped in a function that lets it
\&\f(CW\*(C`croak\*(C'\fR on failure, with that wrapper being returned.
.PP
If the first argument to \f(CW\*(C`create_parser\*(C'\fR is an arrayref, then that is taken
to be an options block (as per the multiple parser specification documented
earlier).
.PP
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 \f(CW\*(C`create_single_parser\*(C'\fR
directly. If the first argument is a hashref or coderef, then it and the
remaining arguments are passed to \f(CW\*(C`create_multiple_parsers\*(C'\fR.
.PP
The resultant coderef from calling either of the creation methods is then
wrapped in a function that calls \f(CW\*(C`croak\*(C'\fR in event of failure or the
\&\f(CW\*(C`DateTime\*(C'\fR object in event of success.
.SH "FINDING IMPLEMENTATIONS"
.IX Header "FINDING IMPLEMENTATIONS"
\&\f(CW\*(C`Parser\*(C'\fR automatically loads any parser classes in \f(CW@INC\fR.
.PP
To be loaded automatically, you must be a
\&\f(CW\*(C`DateTime::Format::Builder::Parser::XXX\*(C'\fR module.
.PP
To be invisible, and not loaded, start your class with a lower class
letter. These are ignored.
.SH "WRITING A PARSER IMPLEMENTATION"
.IX Header "WRITING A PARSER IMPLEMENTATION"
.SS "Naming your parser"
.IX Subsection "Naming your parser"
Create a module and name it in the form
\&\f(CW\*(C`DateTime::Format::Builder::Parser::XXX\*(C'\fR where \fI\s-1XXX\s0\fR is whatever you like,
so long as it doesn't start with a lower case letter.
.PP
Alternatively, call it something completely different if you don't mind the
users explicitly loading your module.
.PP
I'd recommend keeping within the \f(CW\*(C`DateTime::Format::Builder\*(C'\fR 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.
.SS "Declaring specification arguments"
.IX Subsection "Declaring specification arguments"
Call \f(CW\*(C`<DateTime::Format::Builder::Parser\-\*(C'\fRvalid_params>> with
\&\f(CW\*(C`Params::Validate\*(C'\fR style arguments. For example:
.PP
.Vb 9
\&    DateTime::Format::Builder::Parser\->valid_params(
\&        params => { type => ARRAYREF },
\&        Regex  => {
\&            type      => SCALARREF,
\&            callbacks => {
\&                \*(Aqis a regex\*(Aq => sub { ref(shift) eq \*(AqRegexp\*(Aq }
\&            }
\&        }
\&    );
.Ve
.PP
Start one of the key names with a capital letter. Ideally that key should
match the \fI\s-1XXX\s0\fR from earlier. This will be used to help identify which module
a parser specification should be given to.
.PP
The key names \fIon_match\fR, \fIon_fail\fR, \fIpostprocess\fR, \fIpreprocess\fR, \fIlabel\fR
and \fIlength\fR are predefined. You are recommended to make use of them. You may
ignore \fIlength\fR as \f(CW\*(C`sort_parsers\*(C'\fR takes care of that.
.SS "Define create_parser"
.IX Subsection "Define create_parser"
A class method of the name \f(CW\*(C`create_parser\*(C'\fR that does the following:
.PP
Its arguments are as for a normal method (i.e. class as first argument).  The
other arguments are the result from a call to \f(CW\*(C`Params::Validate\*(C'\fR according to
your specification (the \f(CW\*(C`valid_params\*(C'\fR earlier), i.e. a hash of argument name
and value.
.PP
The return value should be a coderef that takes a date string as its first
argument and returns either a \f(CW\*(C`DateTime\*(C'\fR object or \f(CW\*(C`undef\*(C'\fR.
.SS "Callbacks"
.IX Subsection "Callbacks"
It is preferred that you support some callbacks to your parsers.  In
particular, \f(CW\*(C`preprocess\*(C'\fR, \f(CW\*(C`on_match\*(C'\fR, \f(CW\*(C`on_fail\*(C'\fR and \f(CW\*(C`postprocess\*(C'\fR. See the
main Builder docs for the appropriate placing of
calls to the callbacks.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\f(CW\*(C`datetime@perl.org\*(C'\fR mailing list.
.PP
http://datetime.perl.org/
.PP
perl, DateTime, DateTime::Format::Builder.
.PP
Params::Validate.
.PP
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.
.SH "SUPPORT"
.IX Header "SUPPORT"
Bugs may be submitted at <https://github.com/houseabsolute/DateTime\-Format\-Builder/issues>.
.PP
I am also usually active on \s-1IRC\s0 as 'autarch' on \f(CW\*(C`irc://irc.perl.org\*(C'\fR.
.SH "SOURCE"
.IX Header "SOURCE"
The source code repository for DateTime-Format-Builder can be found at <https://github.com/houseabsolute/DateTime\-Format\-Builder>.
.SH "AUTHORS"
.IX Header "AUTHORS"
.IP "\(bu" 4
Dave Rolsky <autarch@urth.org>
.IP "\(bu" 4
Iain Truskett <spoon@cpan.org>
.SH "COPYRIGHT AND LICENSE"
.IX Header "COPYRIGHT AND LICENSE"
This software is Copyright (c) 2020 by Dave Rolsky.
.PP
This is free software, licensed under:
.PP
.Vb 1
\&  The Artistic License 2.0 (GPL Compatible)
.Ve
.PP
The full text of the license can be found in the
\&\fI\s-1LICENSE\s0\fR file included with this distribution.