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 cre‐
14       ation 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
27       These methods allow implementations to have validation of their argu‐
28       ments in a standard manner and due to "Parser"'s impelementation, these
29       methods also allow "Parser" to determine which implementation to use.
30
31       Common parameters
32
33       These parameters appear for all parser implementations.  These are pri‐
34       marily 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 suit‐
57       able 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
83       create_single_parser
84
85       This takes a single specification and returns a coderef that is a
86       parser that suits that specification. This is the end of the line for
87       all the parser creation methods. It delegates no further.
88
89       If a coderef is specified, then that coderef is immediately returned
90       (it is assumed to be appropriate).
91
92       The single specification (if not a coderef) can be either a hashref or
93       a hash. The keys and values must be as per the specification.
94
95       It is here that any arrays of callbacks are unified. It is also here
96       that any parser implementations are used. With the spec that's given,
97       the keys are looked at and whichever module is the first to have a
98       unique key in the spec is the one to whom the spec is given.
99
100       Note: please declare a "valid_params" argument with an uppercase let‐
101       ter. For example, if you're writing "DateTime::For‐
102       mat::Builder::Parser::Fnord", declare a parameter called "Fnord". Simi‐
103       larly, "DTFBP::Strptime" should have "Strptime" and "DTFBP::Regex"
104       should have "Regex". These latter two don't for backwards compatibility
105       reasons.
106
107       The returned parser will return either a "DateTime" object or "undef".
108
109       merge_callbacks
110
111       Produce either undef or a single coderef from either undef, an empty
112       array, a single coderef or an array of coderefs
113
114       create_multiple_parsers
115
116       Given the options block (as made from "create_parser()") and a list of
117       single parser specifications, this returns a coderef that returns
118       either the resultant "DateTime" object or "undef".
119
120       It first sorts the specifications using "sort_parsers()" and then cre‐
121       ates the function based on what that returned.
122
123       sort_parsers
124
125       This takes the list of specifications and sorts them while turning the
126       specifications into parsers. It returns two values: the first is a
127       hashref containing all the length based parsers. The second is an array
128       containing all the other parsers.
129
130       If any of the specs are not code or hash references, then it will call
131       "croak()".
132
133       Code references are put directly into the 'other' array. Any hash ref‐
134       erences without length keys are run through "create_single_parser()"
135       and the resultant parser is placed in the 'other' array.
136
137       Hash references with length keys are run through "create_sin‐
138       gle_parser()", but the resultant parser is used as the value in the
139       length hashref with the length being the key. If two or more parsers
140       have the same length specified then an error is thrown.
141
142       create_parser
143
144       "create_class()" is mostly a wrapper around "create_parser()" that does
145       loops and stuff and calls "create_parser()" to create the actual
146       parsers.
147
148       "create_parser()" takes the parser specifications (be they single spec‐
149       ifications or multiple specifications) and returns an anonymous coderef
150       that is suitable for use as a method. The coderef will call "croak()"
151       in the event of being unable to parse the single string it expects as
152       input.
153
154       The simplest input is that of a single specification, presented just as
155       a plain hash, not a hashref. This is passed directly to "create_sin‐
156       gle_parser()" with the return value from that being wrapped in a func‐
157       tion that lets it "croak()" on failure, with that wrapper being
158       returned.
159
160       If the first argument to "create_parser()" is an arrayref, then that is
161       taken to be an options block (as per the multiple parser specification
162       documented earlier).
163
164       Any further arguments should be either hashrefs or coderefs.  If the
165       first argument after the optional arrayref is not a hashref or coderef
166       then that argument and all remaining arguments are passed off to "cre‐
167       ate_single_parser()" directly. If the first argument is a hashref or
168       coderef, then it and the remaining arguments are passed to "create_mul‐
169       tiple_parsers()".
170
171       The resultant coderef from calling either of the creation methods is
172       then wrapped in a function that calls "croak()" in event of failure or
173       the "DateTime" object in event of success.
174

FINDING IMPLEMENTATIONS

176       "Parser" automatically loads any parser classes in @INC.
177
178       To be loaded automatically, you must be a "DateTime::For‐
179       mat::Builder::Parser::XXX" module.
180
181       To be invisible, and not loaded, start your class with a lower class
182       letter. These are ignored.
183

WRITING A PARSER IMPLEMENTATION

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

SUPPORT

238       Support for this module is provided via the datetime@perl.org email
239       list. See http://lists.perl.org/ for more details.
240
241       Alternatively, log them via the CPAN RT system via the web or email:
242
243           http://perl.dellah.org/rt/dtbuilder
244           bug-datetime-format-builder@rt.cpan.org
245
246       This makes it much easier for me to track things and thus means your
247       problem is less likely to be neglected.
248

THANKS

250       See DateTime::Format::Builder.
251

LICENCE AND COPYRIGHT

253       Copyright (C) Iain Truskett, 2003. All rights reserved.
254
255       This library is free software; you can redistribute it and/or modify it
256       under the same terms as Perl itself, either Perl version 5.000 or, at
257       your option, any later version of Perl 5 you may have available.
258
259       The full text of the licences can be found in the Artistic and COPYING
260       files included with this module, or in perlartistic and perlgpl as sup‐
261       plied with Perl 5.8.1 and later.
262

AUTHOR

264       Iain Truskett <spoon@cpan.org>
265