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

VERSION

9       version 0.82
10

SYNOPSIS

12           my $class = 'DateTime::Format::Builder::Parser';
13           my $parser = $class->create_single_parser( %specs );
14

DESCRIPTION

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

METHODS

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

FINDING IMPLEMENTATIONS

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

WRITING A PARSER IMPLEMENTATION

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

SUPPORT

247       Bugs may be submitted at
248       <http://rt.cpan.org/Public/Dist/Display.html?Name=DateTime-Format-Builder>
249       or via email to bug-datetime-format-builder@rt.cpan.org <mailto:bug-
250       datetime-format-builder@rt.cpan.org>.
251
252       I am also usually active on IRC as 'autarch' on "irc://irc.perl.org".
253

SOURCE

255       The source code repository for DateTime-Format-Builder can be found at
256       <https://github.com/houseabsolute/DateTime-Format-Builder>.
257

AUTHORS

259       ·   Dave Rolsky <autarch@urth.org>
260
261       ·   Iain Truskett
262

COPYRIGHT AND LICENSE

264       This software is Copyright (c) 2019 by Dave Rolsky.
265
266       This is free software, licensed under:
267
268         The Artistic License 2.0 (GPL Compatible)
269
270       The full text of the license can be found in the LICENSE file included
271       with this distribution.
272
273
274
275perl v5.30.0                      2019-07-2D6ateTime::Format::Builder::Parser(3)