1DateTime::Format::BuildUesre:r:PCaornsterri(b3u)ted PerlDaDtoecTuimmeen:t:aFtoiromnat::Builder::Parser(3)
2
3
4
6 DateTime::Format::Builder::Parser - Parser creation
7
9 version 0.83
10
12 my $class = 'DateTime::Format::Builder::Parser';
13 my $parser = $class->create_single_parser(%specs);
14
16 This is a utility class for DateTime::Format::Builder that handles
17 creation of parsers. It is to here that "Builder" delegates most of its
18 responsibilities.
19
21 There are two sorts of methods in this class. Those used by parser
22 implementations and those used by "Builder". It is generally unlikely
23 the user will want to use any of them.
24
25 They are presented, grouped according to use.
26
27 Parameter Handling (implementations)
28 These methods allow implementations to have validation of their
29 arguments in a standard manner and due to "Parser"'s implementation,
30 these methods also allow "Parser" to determine which implementation to
31 use.
32
33 Common parameters
34
35 These parameters appear for all parser implementations. These are
36 primarily documented in DateTime::Format::Builder.
37
38 • on_match
39
40 • on_fail
41
42 • postprocess
43
44 • preprocess
45
46 • label
47
48 • length
49
50 length may be a number or an arrayref of numbers indicating the
51 length of the input. This lets us optimize in the case of static
52 length input. If supplying an arrayref of numbers, please keep the
53 number of numbers to a minimum.
54
55 params
56
57 my $params = $self->params;
58 validate( @_, $params );
59
60 Returns declared parameters and "common" parameters in a hashref
61 suitable for handing to Params::Validate's "validate" function.
62
63 params_all
64
65 my $all_params = $self->params_all;
66
67 Returns a hash of all the valid options. Not recommended for general
68 use.
69
70 valid_params
71
72 __PACKAGE__->valid_params(%params);
73
74 Arguments are as per Params::Validate's "validate" function. This
75 method is used to declare what your valid arguments are in a parser
76 specification.
77
78 whose_params
79
80 my $class = whose_params( $key );
81
82 Internal function which merely returns to which class a parameter is
83 unique. If not unique, returns "undef".
84
85 Organizing and Creating Parsers
86 create_single_parser
87
88 This takes a single specification and returns a coderef that is a
89 parser that suits that specification. This is the end of the line for
90 all the parser creation methods. It delegates no further.
91
92 If a coderef is specified, then that coderef is immediately returned
93 (it is assumed to be appropriate).
94
95 The single specification (if not a coderef) can be either a hashref or
96 a hash. The keys and values must be as per the specification.
97
98 It is here that any arrays of callbacks are unified. It is also here
99 that any parser implementations are used. With the spec that's given,
100 the keys are looked at and whichever module is the first to have a
101 unique key in the spec is the one to whom the spec is given.
102
103 Note: please declare a "valid_params" argument with an uppercase
104 letter. For example, if you're writing
105 "DateTime::Format::Builder::Parser::Fnord", declare a parameter called
106 "Fnord". Similarly, "DTFBP::Strptime" should have "Strptime" and
107 "DTFBP::Regex" should have "Regex". These latter two don't for
108 backwards compatibility reasons.
109
110 The returned parser will return either a "DateTime" object or "undef".
111
112 merge_callbacks
113
114 Produce either undef or a single coderef from either undef, an empty
115 array, a single coderef or an array of coderefs
116
117 create_multiple_parsers
118 Given the options block (as made from "create_parser") and a list of
119 single parser specifications, this returns a coderef that returns
120 either the resultant "DateTime" object or "undef".
121
122 It first sorts the specifications using "sort_parsers" and then creates
123 the function based on what that returned.
124
125 sort_parsers
126 This takes the list of specifications and sorts them while turning the
127 specifications into parsers. It returns two values: the first is a
128 hashref containing all the length based parsers. The second is an array
129 containing all the other parsers.
130
131 If any of the specs are not code or hash references, then it will call
132 "croak".
133
134 Code references are put directly into the 'other' array. Any hash
135 references without length keys are run through "create_single_parser"
136 and the resultant parser is placed in the 'other' array.
137
138 Hash references with length keys are run through
139 "create_single_parser", but the resultant parser is used as the value
140 in the length hashref with the length being the key. If two or more
141 parsers have the same length specified then an error is thrown.
142
143 create_parser
144 "create_class" is mostly a wrapper around "create_parser" that does
145 loops and stuff and calls "create_parser" to create the actual parsers.
146
147 "create_parser" takes the parser specifications (be they single
148 specifications or multiple specifications) and returns an anonymous
149 coderef that is suitable for use as a method. The coderef will call
150 "croak" in the event of being unable to parse the single string it
151 expects as input.
152
153 The simplest input is that of a single specification, presented just as
154 a plain hash, not a hashref. This is passed directly to
155 "create_single_parser" with the return value from that being wrapped in
156 a function that lets it "croak" on failure, with that wrapper being
157 returned.
158
159 If the first argument to "create_parser" is an arrayref, then that is
160 taken to be an options block (as per the multiple parser specification
161 documented earlier).
162
163 Any further arguments should be either hashrefs or coderefs. If the
164 first argument after the optional arrayref is not a hashref or coderef
165 then that argument and all remaining arguments are passed off to
166 "create_single_parser" directly. If the first argument is a hashref or
167 coderef, then it and the remaining arguments are passed to
168 "create_multiple_parsers".
169
170 The resultant coderef from calling either of the creation methods is
171 then wrapped in a function that calls "croak" in event of failure or
172 the "DateTime" object in event of success.
173
175 "Parser" automatically loads any parser classes in @INC.
176
177 To be loaded automatically, you must be a
178 "DateTime::Format::Builder::Parser::XXX" module.
179
180 To be invisible, and not loaded, start your class with a lower class
181 letter. These are ignored.
182
184 Naming your parser
185 Create a module and name it in the form
186 "DateTime::Format::Builder::Parser::XXX" where XXX is whatever you
187 like, so long as it doesn't start with a lower case letter.
188
189 Alternatively, call it something completely different if you don't mind
190 the users explicitly loading your module.
191
192 I'd recommend keeping within the "DateTime::Format::Builder" namespace
193 though --- at the time of writing I've not given thought to what non-
194 auto loaded ones should be called. Any ideas, please email me.
195
196 Declaring specification arguments
197 Call "<DateTime::Format::Builder::Parser-"valid_params>> with
198 "Params::Validate" style arguments. For example:
199
200 DateTime::Format::Builder::Parser->valid_params(
201 params => { type => ARRAYREF },
202 Regex => {
203 type => SCALARREF,
204 callbacks => {
205 'is a regex' => sub { ref(shift) eq 'Regexp' }
206 }
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 A class method of the name "create_parser" that does the following:
220
221 Its arguments are as for a normal method (i.e. class as first
222 argument). The other arguments are the result from a call to
223 "Params::Validate" according to your specification (the "valid_params"
224 earlier), i.e. a hash of argument name and value.
225
226 The return value should be a coderef that takes a date string as its
227 first argument and returns either a "DateTime" object or "undef".
228
229 Callbacks
230 It is preferred that you support some callbacks to your parsers. In
231 particular, "preprocess", "on_match", "on_fail" and "postprocess". See
232 the main Builder docs for the appropriate placing of calls to the
233 callbacks.
234
236 "datetime@perl.org" mailing list.
237
238 http://datetime.perl.org/
239
240 perl, DateTime, DateTime::Format::Builder.
241
242 Params::Validate.
243
244 DateTime::Format::Builder::Parser::generic,
245 DateTime::Format::Builder::Parser::Dispatch,
246 DateTime::Format::Builder::Parser::Quick,
247 DateTime::Format::Builder::Parser::Regex,
248 DateTime::Format::Builder::Parser::Strptime.
249
251 Bugs may be submitted at
252 <https://github.com/houseabsolute/DateTime-Format-Builder/issues>.
253
254 I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
255
257 The source code repository for DateTime-Format-Builder can be found at
258 <https://github.com/houseabsolute/DateTime-Format-Builder>.
259
261 • Dave Rolsky <autarch@urth.org>
262
263 • Iain Truskett <spoon@cpan.org>
264
266 This software is Copyright (c) 2020 by Dave Rolsky.
267
268 This is free software, licensed under:
269
270 The Artistic License 2.0 (GPL Compatible)
271
272 The full text of the license can be found in the LICENSE file included
273 with this distribution.
274
275
276
277perl v5.32.1 2021-03-2D5ateTime::Format::Builder::Parser(3)