DateTime::Format::Builder::Parser - Parser creation

       •   Dave Rolsky <autarch@urth.org>

       •   Iain Truskett <spoon@cpan.org>

       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)

       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.

       "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.

       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.

   ParameterHandling(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.

       Commonparameters

       These parameters appear for all parser implementations.  These are primarily documented in
       DateTime::Format::Builder.

       •   on_match

       •   on_fail

       •   postprocess

       •   preprocess

       •   label

       •   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".

   OrganizingandCreatingParserscreate_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 withlength 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.

       DateTime::Format::Builder::Parser - Parser creation

       "datetime@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.

       The    source     code     repository     for     DateTime-Format-Builder     can     be     found     at
       <https://github.com/houseabsolute/DateTime-Format-Builder>.

       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".

           my $class  = 'DateTime::Format::Builder::Parser';
           my $parser = $class->create_single_parser(%specs);

       version 0.83

Namingyourparser
       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.

   Declaringspecificationarguments
       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.

   Definecreate_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.