Debian Codegraph @

README

raw
1 NAME
2 Devel::Declare::Parser - Higher level interface to Devel-Declare
3
4 DESCRIPTION
5 Devel-Declare-Parser is a higher-level API sitting on top of
6 Devel::Declare. It is used by Devel::Declare::Exporter to simplify
7 exporting of Devel::Declare magic. Writing custom parsers usually only
8 requires subclassing this module and overriding a couple methods.
9
10 DOCUMENTATION
11 Devel::Declare::Interface
12 This is the primary interface for those who want to use
13 Devel-Declare-Parser magic, and don't want to use Exporter-Declare.
14
15 Devel::Declare::Parser
16 This Document covers the API for Devel::Declare::Parser. This API is
17 a useful reference when writing or modifying a custom parser.
18
19 SYNOPSIS
20 package Devel::Declare::Parser::MyParser;
21 use strict;
22 use warnings;
23
24 use base 'Devel::Declare::Parser';
25 use Devel::Declare::Interface;
26
27 # Create an accessor (See INTERNALS WARNING below)
28 __PACKAGE__->add_accessor( 'my_accessor' );
29
30 # Register the parser for use.
31 Devel::Declare::Interface::register_parser( 'myparser' );
32
33 # Override the rewrite() method to take the parsed bits (parts) and put the
34 # ones you want into new_parts.
35 sub rewrite {
36 my $self = shift;
37
38 my $parts = $self->parts;
39
40 $new_parts = $self->process_parts( $parts );
41
42 $self->new_parts( $new_parts );
43 1;
44 }
45
46 1;
47
48 OVERVIEW
49 This is a brief overview of how a parser is used.
50
51 WORKFLOW
52 Parser is constructed
53 Name, Declarator, and Offset are provided by Devel::Declare.
54
55 The process() method is called
56 The process method calls all of the following in sequence, if any
57 returns false, process() will return.
58
59 pre_parse()
60 Check if we want to process the line at all.
61
62 parse() Turn the line into 'parts' (see below).
63
64 post_parse()
65 Hook, currently does nothing.
66
67 rewrite()
68 Hook, currently takes all the arguments between the
69 declarator and the codeblock/semicolon (which have been
70 turned into 'parts' structures in the parts() attribute) and
71 puts them into the new_parts() attribute.
72
73 This is usually the method you want to override.
74
75 write_line()
76 Opens, fills in, and closes the line as a string, then
77 rewrites the actual line using Devel::Declare.
78
79 edit_line()
80 Hook, currently does nothing.
81
82 "PARTS"
83 'Parts' are datastructures created by the parse() method. Every argument
84 on the line (space separated) up until an opening curly brace ({) or a
85 semicolon (;) will be turned into a part. Here are the parts to expect:
86
87 Parts will either be a plain string, or an arrayref containing a string
88 and the quote character used to define the string. "String" or [
89 "String", '"' ]. Variables and operators (excluding those containing
90 only string characters) are typically the only parts left in a plain
91 string form.
92
93 See the format_parts() method for an easy way to get what you need from
94 a 'part' datastructure.
95
96 Bareword or Package Name
97 A bareword name is anything that starts with [a-zA-z] and contains
98 only alpha-numerics plus underscore. It is also not quoted. Examples
99 include my_name, something5, etc.
100
101 The structure will be an arrayref, the first element will be the
102 string form of the bareword name, the second element will be undef.
103
104 Example:
105
106 # my_keyword My::Package;
107 $part = [
108 'My::Package',
109 undef,
110 ];
111
112 # my_keyword some_name;
113 $part = [
114 "some_name",
115 undef,
116 ];
117
118 Quoted or Enclosed Element
119 A quoted or enclosed element includes strings quoted with single or
120 double quotes, and text contained within opening and closing
121 brackets, braces or parens (excluding the curly brace '{').
122
123 Example Structures:
124
125 # my_keyword "double quoted string";
126 $part = [
127 'double quoted string',
128 '"',
129 ];
130
131 # my_keyword 'single quoted string';
132 $part = [
133 'double quoted string',
134 '"',
135 ];
136
137 # my_keyword ... ( a => 'b', c => 'd' );
138 $part = [
139 " a => 'b', c => 'd' ",
140 "(",
141 ];
142
143 Variable or Operator
144 Anything starting with a non-alphanumeric, non-quoting character
145 will be placed as-is (not interpolated) into a string. This catches
146 most variables and operators, the exception are alpha-numeric
147 operators such as 'eq', 'gt', 'cmp', etc. Eventually I plan to add
148 logic to catch all operators, but it appears I will have to
149 hard-code them.
150
151 # my_keyword $variable
152 $part = '$variable';
153
154 # my_keyword <=>
155 $part = '<=>';
156
157 EVENTUAL OUTPUT
158 Parser is designed such that it will transform any and all uses of your
159 keyword into proper function calls.
160
161 That is this:
162
163 function x { ... }
164
165 Will become this:
166
167 function( 'x', sub { ... });
168
169 Note Parser does not read in the entire codeblock, rather it injects a
170 statement into the start of the block that uses a callback to attach the
171 ');' to the end of the statement. This is per the documentation of
172 Devel::Declare. Reading in the entire sub is not a desirable scenario.
173
174 DEVEL-DECLARE-PARSER API
175 INTERNALS WARNING
176 Parser objects are blessed arrays, not hashrefs.
177
178 If you want to create a new accessor use the add_accessor() class
179 method. It will take care of assigning an unused array element to the
180 attribute, and will create a read/write accessor sub for you.
181
182 __PACKAGE__->add_accessor( 'my_accessor' );
183
184 There are many public and private methods on the parser base class. Only
185 the public methods are fully documented. Be sure to refer often to the
186 list of private methods at the end of this document, accidently
187 overriding a private method could have devastating consequences.
188
189 CLASS METHODS
190 $class->new( $name, $declarator, $offset )
191 The constructor, "DO NOT OVERRIDE THIS!"
192
193 $class->DEBUG($bool)
194 Turn debugging on/off. This will output the line after it has been
195 modified, as well as some context information.
196
197 NOTE: This has a global effect, all parsers will start debugging.
198
199 UTILITY METHODS
200 bail( @messages )
201 Like croak, dies providing you context information. Since any death
202 occurs inside the parser, carp provides useless information.
203
204 diag( @message )
205 Like carp, warns providing you context information. Since the warn
206 occurs inside the parser carp provides useless information.
207
208 end_quote($start_char)
209 Find the end-character for the provide starting quote character. As
210 in '{' returns '}' and '(' returns ')'. If there is no counter-part
211 the start character is returned: "'" returns "'".
212
213 filename()
214 Filename the rewrite is occurring against.
215
216 linenum()
217 Linenum the rewrite is occurring on.
218
219 format_part()
220 Returns the stringified form of a part datastructure. For variables
221 and operators that is just the item itself as a string. For
222 barewords or package names it is the item itself with single quotes
223 wrapped around it. For quoted items it is the string wrapped in its
224 proper quoting characters. If a second parameter is provided (and
225 true) no single quotes will be added to barewords.
226
227 ACCESSORS
228 These are the read/write accessors used by Parser. Not all of these act
229 on an array element, some will directly alter the current line.
230
231 line()
232 This will retrieve the current line from Devel-Declare. If given a
233 value, that value will be set as the current line using
234 Devel-Declare.
235
236 name()
237 Name of the declarator as provided via the parser.
238
239 declarator()
240 Name of the declarator as provided via the Devel-Declare.
241
242 original_offset()
243 Offset on the line when the parsing was started.
244
245 offset()
246 Current line offset.
247
248 parts()
249 Arrayref of parts (may be undef)
250
251 new_parts()
252 Arrayref of new parts (may be undef)
253
254 end_char()
255 Will be set to the character just after the completely parsed line
256 (usually '{' or ';')
257
258 prototype()
259 Used internally for prototype tracking.
260
261 contained()
262 True if the parser determined this was a contained call. This means
263 your keyword was followed by an opening paren, and the statement
264 ended with a closing paren and semicolon. By default Parser will not
265 modify such lines.
266
267 OVERRIDABLE METHODS
268 These are methods you can, should, or may override in your baseclass.
269
270 quote_chars()
271 Specify the starting characters for quoted strings. (returns a list)
272
273 end_chars()
274 Characters to recognise as end of statement characters (';' and '{')
275 (returns a list)
276
277 inject()
278 Code to inject into functions enhanced by this parser.
279
280 pre_parse()
281 Check if we want to process the line at all.
282
283 parse()
284 Turn the line into 'parts'.
285
286 post_parse()
287 Hook, currently does nothing.
288
289 rewrite()
290 Hook, currently takes all the arguments between the declarator and
291 the codeblock/semicolon (which have been turned into 'parts'
292 structures in the parts() attribute) and puts them into the
293 new_parts() attribute.
294
295 This is usually the method you want to override.
296
297 write_line()
298 Opens, fills in, and closes the line as a string, then rewrites the
299 actual line using Devel::Declare.
300
301 edit_line()
302 Hook, currently does nothing.
303
304 open_line()
305 Usually returns '('. This is how to start a line following your
306 keyword
307
308 close_line()
309 End the line, this means either re-inserting the opening '{' on the
310 codeblock, along with any injections, or returning ');'
311
312 POSITION TRACKING
313 advance( $num_chars )
314 Advances the offset by $num_chars.
315
316 skip_declarator()
317 Skips the declarator at the start of the line.
318
319 skipspace()
320 Advances the offset past any whitespace.
321
322 LINE EXAMINATION (NON-MODIFYING)
323 These are used by pre_parse() to examine the line prior to any
324 modification.
325
326 is_contained()
327 True if the line is of the format:
328
329 keyword( ... );
330
331 is_arrow_contained()
332 True if the line is of the format:
333
334 keyword word_or_string => ( ... );
335
336 is_defenition()
337 True if the line matches the regex m/sub[\s\n]+$name/sm
338
339 PART EXAMINATION
340 These are methods that let you investigate the parts already parsed and
341 placed in the parts() attribute.
342
343 has_non_string_or_quote_parts()
344 Returns a list of parts that are not strings, quotes, or barewords.
345
346 has_string_or_quote_parts()
347 Returns a list of parts that are strings, quotes, or barewords.
348
349 has_keyword( $word )
350 Check for a keyword in the parts
351
352 has_comma()
353 has_fat_comma()
354
355 LINE EXAMINATION (MODIFYING)
356 This examines the line returning part structures and removing elements
357 from the line each time they are called.
358
359 strip_item()
360 strip_length()
361 strip_remaining_items()
362
363 LOOKING AHEAD
364 These methods help the parser determine what comes next in a line. In
365 most cases these are non-modifying.
366
367 peek_is_block()
368 peek_is_end()
369 peek_is_other()
370 peek_is_quote()
371 peek_is_word()
372 peek_item()
373 peek_item_type()
374 peek_num_chars()
375 peek_other()
376 peek_quote()
377 peek_remaining()
378 peek_word()
379
380 PRIVATE METHODS
381 Do not use these, and definitely do not override them in a subclass.
382
383 _block_end_injection()
384 _debug()
385 _edit_block_end()
386 _item_via_()
387 _linestr_offset_from_dd()
388 _move_via_()
389 _peek_is_package()
390 _peek_is_word()
391 _quoted_from_dd()
392 _scope_end()
393 _stash()
394 _unstash()
395
396 FENNEC PROJECT
397 This module is part of the Fennec project. See Fennec for more details.
398 Fennec is a project to develop an extendable and powerful testing
399 framework. Together the tools that make up the Fennec framework provide
400 a potent testing environment.
401
402 The tools provided by Fennec are also useful on their own. Sometimes a
403 tool created for Fennec is useful outside the greator framework. Such
404 tools are turned into their own projects. This is one such project.
405
406 Fennec - The core framework
407 The primary Fennec project that ties them all together.
408
409 AUTHORS
410 Chad Granum [email protected]
411
412 COPYRIGHT
413 Copyright (C) 2010 Chad Granum
414
415 Devel-Declare-Parser is free software; Standard perl licence.
416
417 Devel-Declare-Parser is distributed in the hope that it will be useful,
418 but WITHOUT ANY WARRANTY; without even the implied warranty of
419 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the license for
420 more details.
421