DateTime::Format::Builder::Parser - phpMan

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.

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

  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
    *   Dave Rolsky <autarch AT urth.org>

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