DateTime::Format::Builder::Parser(3pm)

1DateTime::Format::BuildUesre:r:PCaornsterri(b3u)ted PerlDaDtoecTuimmeen:t:aFtoiromnat::Builder::Parser(3)
2
3
4

NAME

6       DateTime::Format::Builder::Parser - Parser creation
7

SYNOPSIS

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

DESCRIPTION

13       This is a utility class for DateTime::Format::Builder that handles
14       creation of parsers. It is to here that "Builder" delegates most of its
15       responsibilities.
16

CONSTRUCTORS

METHODS

19       There are two sorts of methods in this class. Those used by parser
20       implementations and those used by "Builder". It is generally unlikely
21       the user will want to use any of them.
22
23       They are presented, grouped according to use.
24
25   Parameter Handling (implementations)
26       These methods allow implementations to have validation of their
27       arguments in a standard manner and due to "Parser"'s impelementation,
28       these methods also allow "Parser" to determine which implementation to
29       use.
30
31       Common parameters
32
33       These parameters appear for all parser implementations.  These are
34       primarily documented in the main docs.
35
36       ·   on_match
37
38       ·   on_fail
39
40       ·   postprocess
41
42       ·   preprocess
43
44       ·   label
45
46       ·   length may be a number or an arrayref of numbers indicating the
47           length of the input. This lets us optimise in the case of static
48           length input. If supplying an arrayref of numbers, please keep the
49           number of numbers to a minimum.
50
51       params
52
53           my $params = $self->params();
54           validate( @_, $params );
55
56       Returns declared parameters and "common" parameters in a hashref
57       suitable for handing to Params::Validate's "validate" function.
58
59       params_all
60
61           my $all_params = $self->params_all();
62
63       Returns a hash of all the valid options. Not recommended for general
64       use.
65
66       valid_params
67
68           __PACKAGE__->valid_params( %params );
69
70       Arguments are as per Params::Validate's "validate" function.  This
71       method is used to declare what your valid arguments are in a parser
72       specification.
73
74       whose_params
75
76           my $class = whose_params( $key );
77
78       Internal function which merely returns to which class a parameter is
79       unique. If not unique, returns "undef".
80
81   Organising and Creating Parsers
82       create_single_parser
83
84       This takes a single specification and returns a coderef that is a
85       parser that suits that specification. This is the end of the line for
86       all the parser creation methods. It delegates no further.
87
88       If a coderef is specified, then that coderef is immediately returned
89       (it is assumed to be appropriate).
90
91       The single specification (if not a coderef) can be either a hashref or
92       a hash. The keys and values must be as per the specification.
93
94       It is here that any arrays of callbacks are unified. It is also here
95       that any parser implementations are used. With the spec that's given,
96       the keys are looked at and whichever module is the first to have a
97       unique key in the spec is the one to whom the spec is given.
98
99       Note: please declare a "valid_params" argument with an uppercase
100       letter. For example, if you're writing
101       "DateTime::Format::Builder::Parser::Fnord", declare a parameter called
102       "Fnord". Similarly, "DTFBP::Strptime" should have "Strptime" and
103       "DTFBP::Regex" should have "Regex". These latter two don't for
104       backwards compatibility reasons.
105
106       The returned parser will return either a "DateTime" object or "undef".
107
108       merge_callbacks
109
110       Produce either undef or a single coderef from either undef, an empty
111       array, a single coderef or an array of coderefs
112
113   create_multiple_parsers
114       Given the options block (as made from "create_parser()") and a list of
115       single parser specifications, this returns a coderef that returns
116       either the resultant "DateTime" object or "undef".
117
118       It first sorts the specifications using "sort_parsers()" and then
119       creates the function based on what that returned.
120
121   sort_parsers
122       This takes the list of specifications and sorts them while turning the
123       specifications into parsers. It returns two values: the first is a
124       hashref containing all the length based parsers. The second is an array
125       containing all the other parsers.
126
127       If any of the specs are not code or hash references, then it will call
128       "croak()".
129
130       Code references are put directly into the 'other' array. Any hash
131       references without length keys are run through "create_single_parser()"
132       and the resultant parser is placed in the 'other' array.
133
134       Hash references with length keys are run through
135       "create_single_parser()", but the resultant parser is used as the value
136       in the length hashref with the length being the key. If two or more
137       parsers have the same length specified then an error is thrown.
138
139   create_parser
140       "create_class()" is mostly a wrapper around "create_parser()" that does
141       loops and stuff and calls "create_parser()" to create the actual
142       parsers.
143
144       "create_parser()" takes the parser specifications (be they single
145       specifications or multiple specifications) and returns an anonymous
146       coderef that is suitable for use as a method. The coderef will call
147       "croak()" in the event of being unable to parse the single string it
148       expects as input.
149
150       The simplest input is that of a single specification, presented just as
151       a plain hash, not a hashref. This is passed directly to
152       "create_single_parser()" with the return value from that being wrapped
153       in a function that lets it "croak()" on failure, with that wrapper
154       being returned.
155
156       If the first argument to "create_parser()" is an arrayref, then that is
157       taken to be an options block (as per the multiple parser specification
158       documented earlier).
159
160       Any further arguments should be either hashrefs or coderefs.  If the
161       first argument after the optional arrayref is not a hashref or coderef
162       then that argument and all remaining arguments are passed off to
163       "create_single_parser()" directly. If the first argument is a hashref
164       or coderef, then it and the remaining arguments are passed to
165       "create_multiple_parsers()".
166
167       The resultant coderef from calling either of the creation methods is
168       then wrapped in a function that calls "croak()" in event of failure or
169       the "DateTime" object in event of success.
170

FINDING IMPLEMENTATIONS

172       "Parser" automatically loads any parser classes in @INC.
173
174       To be loaded automatically, you must be a
175       "DateTime::Format::Builder::Parser::XXX" module.
176
177       To be invisible, and not loaded, start your class with a lower class
178       letter. These are ignored.
179

WRITING A PARSER IMPLEMENTATION

181   Naming your parser
182       Create a module and name it in the form
183       "DateTime::Format::Builder::Parser::XXX" where XXX is whatever you
184       like, so long as it doesn't start with a lower case letter.
185
186       Alternatively, call it something completely different if you don't mind
187       the users explicitly loading your module.
188
189       I'd recommend keeping within the "DateTime::Format::Builder" namespace
190       though --- at the time of writing I've not given thought to what non-
191       auto loaded ones should be called. Any ideas, please email me.
192
193   Declaring specification arguments
194       Call "<DateTime::Format::Builder::Parser-"valid_params()>> with
195       "Params::Validate" style arguments. For example:
196
197          DateTime::Format::Builder::Parser->valid_params(
198              params => { type => ARRAYREF },
199              Regex  => { type => SCALARREF, callbacks => {
200                 'is a regex' => sub { ref(shift) eq 'Regexp' }
201              }}
202          );
203
204       Start one of the key names with a capital letter. Ideally that key
205       should match the XXX from earlier. This will be used to help identify
206       which module a parser specification should be given to.
207
208       The key names on_match, on_fail, postprocess, preprocess, label and
209       length are predefined. You are recommended to make use of them. You may
210       ignore length as "sort_parsers" takes care of that.
211
212   Define create_parser
213       A class method of the name "create_parser" that does the following:
214
215       Its arguments are as for a normal method (i.e. class as first
216       argument).  The other arguments are the result from a call to
217       "Params::Validate" according to your specification (the "valid_params"
218       earlier), i.e. a hash of argument name and value.
219
220       The return value should be a coderef that takes a date string as its
221       first argument and returns either a "DateTime" object or "undef".
222
223   Callbacks
224       It is preferred that you support some callbacks to your parsers.  In
225       particular, "preprocess", "on_match", "on_fail" and "postprocess". See
226       the main Builder docs for the appropriate placing of calls to the
227       callbacks.
228

SUPPORT

230       Support for this module is provided via the datetime@perl.org email
231       list. See http://lists.perl.org/ for more details.
232
233       Alternatively, log them via the CPAN RT system via the web or email:
234
235           http://perl.dellah.org/rt/dtbuilder
236           bug-datetime-format-builder@rt.cpan.org
237
238       This makes it much easier for me to track things and thus means your
239       problem is less likely to be neglected.
240

THANKS

242       See DateTime::Format::Builder.
243

LICENCE AND COPYRIGHT

245       Copyright (C) Iain Truskett, 2003. All rights reserved.
246
247       This library is free software; you can redistribute it and/or modify it
248       under the same terms as Perl itself, either Perl version 5.000 or, at
249       your option, any later version of Perl 5 you may have available.
250
251       The full text of the licences can be found in the Artistic and COPYING
252       files included with this module, or in perlartistic and perlgpl as
253       supplied with Perl 5.8.1 and later.
254

AUTHOR

256       Iain Truskett <spoon@cpan.org>
257