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

FINDING IMPLEMENTATIONS

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

WRITING A PARSER IMPLEMENTATION

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

SUPPORT

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

SOURCE

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

AUTHORS

261       •   Dave Rolsky <autarch@urth.org>
262
263       •   Iain Truskett <spoon@cpan.org>
264

COPYRIGHT AND LICENSE

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.38.0                      2023-07-2D0ateTime::Format::Builder::Parser(3)