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

CONSTRUCTORS

METHODS

22       There are two sorts of methods in this class. Those used by parser
23       implementations and those used by "Builder". It is generally unlikely
24       the user will want to use any of them.
25
26       They are presented, grouped according to use.
27
28   Parameter Handling (implementations)
29       These methods allow implementations to have validation of their
30       arguments in a standard manner and due to "Parser"'s impelementation,
31       these methods also allow "Parser" to determine which implementation to
32       use.
33
34       Common parameters
35
36       These parameters appear for all parser implementations.  These are
37       primarily documented in DateTime::Format::Builder.
38
39       ·   on_match
40
41       ·   on_fail
42
43       ·   postprocess
44
45       ·   preprocess
46
47       ·   label
48
49       ·   length may be a number or an arrayref of numbers indicating the
50           length of the input. This lets us optimise in the case of static
51           length input. If supplying an arrayref of numbers, please keep the
52           number of numbers to a minimum.
53
54       params
55
56           my $params = $self->params();
57           validate( @_, $params );
58
59       Returns declared parameters and "common" parameters in a hashref
60       suitable for handing to Params::Validate's "validate" function.
61
62       params_all
63
64           my $all_params = $self->params_all();
65
66       Returns a hash of all the valid options. Not recommended for general
67       use.
68
69       valid_params
70
71           __PACKAGE__->valid_params( %params );
72
73       Arguments are as per Params::Validate's "validate" function.  This
74       method is used to declare what your valid arguments are in a parser
75       specification.
76
77       whose_params
78
79           my $class = whose_params( $key );
80
81       Internal function which merely returns to which class a parameter is
82       unique. If not unique, returns "undef".
83
84   Organising and Creating Parsers
85       create_single_parser
86
87       This takes a single specification and returns a coderef that is a
88       parser that suits that specification. This is the end of the line for
89       all the parser creation methods. It delegates no further.
90
91       If a coderef is specified, then that coderef is immediately returned
92       (it is assumed to be appropriate).
93
94       The single specification (if not a coderef) can be either a hashref or
95       a hash. The keys and values must be as per the specification.
96
97       It is here that any arrays of callbacks are unified. It is also here
98       that any parser implementations are used. With the spec that's given,
99       the keys are looked at and whichever module is the first to have a
100       unique key in the spec is the one to whom the spec is given.
101
102       Note: please declare a "valid_params" argument with an uppercase
103       letter. For example, if you're writing
104       "DateTime::Format::Builder::Parser::Fnord", declare a parameter called
105       "Fnord". Similarly, "DTFBP::Strptime" should have "Strptime" and
106       "DTFBP::Regex" should have "Regex". These latter two don't for
107       backwards compatibility reasons.
108
109       The returned parser will return either a "DateTime" object or "undef".
110
111       merge_callbacks
112
113       Produce either undef or a single coderef from either undef, an empty
114       array, a single coderef or an array of coderefs
115
116   create_multiple_parsers
117       Given the options block (as made from "create_parser()") and a list of
118       single parser specifications, this returns a coderef that returns
119       either the resultant "DateTime" object or "undef".
120
121       It first sorts the specifications using "sort_parsers()" and then
122       creates the function based on what that returned.
123
124   sort_parsers
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
134       references 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
138       "create_single_parser()", but the resultant parser is used as the value
139       in the length hashref with the length being the key. If two or more
140       parsers have the same length specified then an error is thrown.
141
142   create_parser
143       "create_class()" is mostly a wrapper around "create_parser()" that does
144       loops and stuff and calls "create_parser()" to create the actual
145       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
156       in a function that lets it "croak()" on failure, with that wrapper
157       being 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
167       or 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  => { type => SCALARREF, callbacks => {
203                 'is a regex' => sub { ref(shift) eq 'Regexp' }
204              }}
205          );
206
207       Start one of the key names with a capital letter. Ideally that key
208       should match the XXX from earlier. This will be used to help identify
209       which module a parser specification should be given to.
210
211       The key names on_match, on_fail, postprocess, preprocess, label and
212       length are predefined. You are recommended to make use of them. You may
213       ignore length as "sort_parsers" takes care of that.
214
215   Define create_parser
216       A class method of the name "create_parser" that does the following:
217
218       Its arguments are as for a normal method (i.e. class as first
219       argument).  The other arguments are the result from a call to
220       "Params::Validate" according to your specification (the "valid_params"
221       earlier), i.e. a hash of argument name and value.
222
223       The return value should be a coderef that takes a date string as its
224       first argument and returns either a "DateTime" object or "undef".
225
226   Callbacks
227       It is preferred that you support some callbacks to your parsers.  In
228       particular, "preprocess", "on_match", "on_fail" and "postprocess". See
229       the main Builder docs for the appropriate placing of calls to the
230       callbacks.
231

SUPPORT

233       See DateTime::Format::Builder for details.
234

AUTHORS

251       ·   Dave Rolsky <autarch@urth.org>
252
253       ·   Iain Truskett
254

COPYRIGHT AND LICENSE

256       This software is Copyright (c) 2013 by Dave Rolsky.
257
258       This is free software, licensed under:
259
260         The Artistic License 2.0 (GPL Compatible)
261
262
263
264perl v5.28.0                      2018-07-1D4ateTime::Format::Builder::Parser(3)