DateTime::Format::Builder::Parser man page on Pidora

Man page or keyword search:  
man Server   31170 pages
apropos Keyword Search (all sections)
Output format
Pidora logo
[printable version]

DateTime::Format::BuilUser:Contributed PerDateTime::Format::Builder::Parser(3)

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

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.

CONSTRUCTORS
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 impelementation,
       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 the main docs.

       ·   on_match

       ·   on_fail

       ·   postprocess

       ·   preprocess

       ·   label

       ·   length may be a number or an arrayref of numbers indicating the
	   length of the input. This lets us optimise 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".

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

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

THANKS
       See DateTime::Format::Builder.

LICENCE AND COPYRIGHT
       Copyright (C) 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.

AUTHOR
       Iain Truskett <spoon@cpan.org>

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

perl v5.14.1			  2011-07-DateTime::Format::Builder::Parser(3)
[top]

List of man pages available for Pidora

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net