1Perl::Tidy(3) User Contributed Perl Documentation Perl::Tidy(3)
2
6 Perl::Tidy - Parses and beautifies perl source
7
9 use Perl::Tidy;
10 Perl::Tidy::perltidy(
12 source => $source,
13 destination => $destination,
14 stderr => $stderr,
15 argv => $argv,
16 perltidyrc => $perltidyrc,
17 logfile => $logfile,
18 errorfile => $errorfile,
19 formatter => $formatter, # callback object (see below)
20 dump_options => $dump_options,
21 dump_options_type => $dump_options_type,
22 prefilter => $prefilter_coderef,
23 postfilter => $postfilter_coderef,
24 );
25
27 This module makes the functionality of the perltidy utility available
28 to perl scripts. Any or all of the input parameters may be omitted, in
29 which case the @ARGV array will be used to provide input parameters as
30 described in the perltidy(1) man page.
31 For example, the perltidy script is basically just this:
33 use Perl::Tidy;
35 Perl::Tidy::perltidy();
36 The module accepts input and output streams by a variety of methods.
38 The following list of parameters may be any of a the following: a
39 filename, an ARRAY reference, a SCALAR reference, or an object with
40 either a getline or print method, as appropriate.
41 source - the source of the script to be formatted
43 destination - the destination of the formatted output
44 stderr - standard error output
45 perltidyrc - the .perltidyrc file
46 logfile - the .LOG file stream, if any
47 errorfile - the .ERR file stream, if any
48 dump_options - ref to a hash to receive parameters (see below),
49 dump_options_type - controls contents of dump_options
50 dump_getopt_flags - ref to a hash to receive Getopt flags
51 dump_options_category - ref to a hash giving category of options
52 dump_abbreviations - ref to a hash giving all abbreviations
53 The following chart illustrates the logic used to decide how to treat a
55 parameter.
56 ref($param) $param is assumed to be:
58 ----------- ---------------------
59 undef a filename
60 SCALAR ref to string
61 ARRAY ref to array
62 (other) object with getline (if source) or print method
63 If the parameter is an object, and the object has a close method, that
65 close method will be called at the end of the stream.
66 source
68 If the source parameter is given, it defines the source of the
69 input stream.
70 destination
72 If the destination parameter is given, it will be used to define
73 the file or memory location to receive output of perltidy.
74 stderr
76 The stderr parameter allows the calling program to capture the
77 output to what would otherwise go to the standard error output
78 device.
79 perltidyrc
81 If the perltidyrc file is given, it will be used instead of any
82 .perltidyrc configuration file that would otherwise be used.
83 argv
85 If the argv parameter is given, it will be used instead of the
86 @ARGV array. The argv parameter may be a string, a reference to a
87 string, or a reference to an array. If it is a string or reference
88 to a string, it will be parsed into an array of items just as if it
89 were a command line string.
90 dump_options
92 If the dump_options parameter is given, it must be the reference to
93 a hash. In this case, the parameters contained in any perltidyrc
94 configuration file will be placed in this hash and perltidy will
95 return immediately. This is equivalent to running perltidy with
96 --dump-options, except that the perameters are returned in a hash
97 rather than dumped to standard output. Also, by default only the
98 parameters in the perltidyrc file are returned, but this can be
99 changed (see the next parameter). This parameter provides a
100 convenient method for external programs to read a perltidyrc file.
101 An example program using this feature, perltidyrc_dump.pl, is
102 included in the distribution.
103 Any combination of the dump_ parameters may be used together.
105 dump_options_type
107 This parameter is a string which can be used to control the
108 parameters placed in the hash reference supplied by dump_options.
109 The possible values are 'perltidyrc' (default) and 'full'. The
110 'full' parameter causes both the default options plus any options
111 found in a perltidyrc file to be returned.
112 dump_getopt_flags
114 If the dump_getopt_flags parameter is given, it must be the
115 reference to a hash. This hash will receive all of the parameters
116 that perltidy understands and flags that are passed to
117 Getopt::Long. This parameter may be used alone or with the
118 dump_options flag. Perltidy will exit immediately after filling
119 this hash. See the demo program perltidyrc_dump.pl for example
120 usage.
121 dump_options_category
123 If the dump_options_category parameter is given, it must be the
124 reference to a hash. This hash will receive a hash with keys equal
125 to all long parameter names and values equal to the title of the
126 corresponding section of the perltidy manual. See the demo program
127 perltidyrc_dump.pl for example usage.
128 dump_abbreviations
130 If the dump_abbreviations parameter is given, it must be the
131 reference to a hash. This hash will receive all abbreviations used
132 by Perl::Tidy. See the demo program perltidyrc_dump.pl for example
133 usage.
134 prefilter
136 A code reference that will be applied to the source before tidying.
137 It is expected to take the full content as a string in its input,
138 and output the transformed content.
139 postfilter
141 A code reference that will be applied to the tidied result before
142 outputting. It is expected to take the full content as a string in
143 its input, and output the transformed content.
144 Note: A convenient way to check the function of your custom
146 prefilter and postfilter code is to use the --notidy option, first
147 with just the prefilter and then with both the prefilter and
148 postfilter. See also the file filter_example.pl in the perltidy
149 distribution.
150
152 The following example passes perltidy a snippet as a reference to a
153 string and receives the result back in a reference to an array.
154 use Perl::Tidy;
156 # some messy source code to format
158 my $source = <<'EOM';
159 use strict;
160 my @editors=('Emacs', 'Vi '); my $rand = rand();
161 print "A poll of 10 random programmers gave these results:\n";
162 foreach(0..10) {
163 my $i=int ($rand+rand());
164 print " $editors[$i] users are from Venus" . ", " .
165 "$editors[1-$i] users are from Mars" .
166 "\n";
167 }
168 EOM
169 # We'll pass it as ref to SCALAR and receive it in a ref to ARRAY
171 my @dest;
172 perltidy( source => \$source, destination => \@dest );
173 foreach (@dest) {print}
174
176 The formatter parameter is an optional callback object which allows the
177 calling program to receive tokenized lines directly from perltidy for
178 further specialized processing. When this parameter is used, the two
179 formatting options which are built into perltidy (beautification or
180 html) are ignored. The following diagram illustrates the logical flow:
181 |-- (normal route) -> code beautification
183 caller->perltidy->|-- (-html flag ) -> create html
184 |-- (formatter given)-> callback to write_line
185 This can be useful for processing perl scripts in some way. The
187 parameter $formatter in the perltidy call,
188 formatter => $formatter,
190 is an object created by the caller with a "write_line" method which
192 will accept and process tokenized lines, one line per call. Here is a
193 simple example of a "write_line" which merely prints the line number,
194 the line type (as determined by perltidy), and the text of the line:
195 sub write_line {
197 # This is called from perltidy line-by-line
199 my $self = shift;
200 my $line_of_tokens = shift;
201 my $line_type = $line_of_tokens->{_line_type};
202 my $input_line_number = $line_of_tokens->{_line_number};
203 my $input_line = $line_of_tokens->{_line_text};
204 print "$input_line_number:$line_type:$input_line";
205 }
206 The complete program, perllinetype, is contained in the examples
208 section of the source distribution. As this example shows, the
209 callback method receives a parameter $line_of_tokens, which is a
210 reference to a hash of other useful information. This example uses
211 these hash entries:
212 $line_of_tokens->{_line_number} - the line number (1,2,...)
214 $line_of_tokens->{_line_text} - the text of the line
215 $line_of_tokens->{_line_type} - the type of the line, one of:
216 SYSTEM - system-specific code before hash-bang line
218 CODE - line of perl code (including comments)
219 POD_START - line starting pod, such as '=head'
220 POD - pod documentation text
221 POD_END - last line of pod section, '=cut'
222 HERE - text of here-document
223 HERE_END - last line of here-doc (target word)
224 FORMAT - format section
225 FORMAT_END - last line of format section, '.'
226 DATA_START - __DATA__ line
227 DATA - unidentified text following __DATA__
228 END_START - __END__ line
229 END - unidentified text following __END__
230 ERROR - we are in big trouble, probably not a perl script
231 Most applications will be only interested in lines of type CODE. For
233 another example, let's write a program which checks for one of the so-
234 called naughty matching variables "&`", $&, and "$'", which can slow
235 down processing. Here is a write_line, from the example program
236 find_naughty.pl, which does that:
237 sub write_line {
239 # This is called back from perltidy line-by-line
241 # We're looking for $`, $&, and $'
242 my ( $self, $line_of_tokens ) = @_;
243 # pull out some stuff we might need
245 my $line_type = $line_of_tokens->{_line_type};
246 my $input_line_number = $line_of_tokens->{_line_number};
247 my $input_line = $line_of_tokens->{_line_text};
248 my $rtoken_type = $line_of_tokens->{_rtoken_type};
249 my $rtokens = $line_of_tokens->{_rtokens};
250 chomp $input_line;
251 # skip comments, pod, etc
253 return if ( $line_type ne 'CODE' );
254 # loop over tokens looking for $`, $&, and $'
256 for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) {
257 # we only want to examine token types 'i' (identifier)
259 next unless $$rtoken_type[$j] eq 'i';
260 # pull out the actual token text
262 my $token = $$rtokens[$j];
263 # and check it
265 if ( $token =~ /^\$[\`\&\']$/ ) {
266 print STDERR
267 "$input_line_number: $token\n";
268 }
269 }
270 }
271 This example pulls out these tokenization variables from the
273 $line_of_tokens hash reference:
274 $rtoken_type = $line_of_tokens->{_rtoken_type};
276 $rtokens = $line_of_tokens->{_rtokens};
277 The variable $rtoken_type is a reference to an array of token type
279 codes, and $rtokens is a reference to a corresponding array of token
280 text. These are obviously only defined for lines of type CODE.
281 Perltidy classifies tokens into types, and has a brief code for each
282 type. You can get a complete list at any time by running perltidy from
283 the command line with
284 perltidy --dump-token-types
286 In the present example, we are only looking for tokens of type i
288 (identifiers), so the for loop skips past all other types. When an
289 identifier is found, its actual text is checked to see if it is one
290 being sought. If so, the above write_line prints the token and its
291 line number.
292 The formatter feature is relatively new in perltidy, and further
294 documentation needs to be written to complete its description.
295 However, several example programs have been written and can be found in
296 the examples section of the source distribution. Probably the best way
297 to get started is to find one of the examples which most closely
298 matches your application and start modifying it.
299 For help with perltidy's pecular way of breaking lines into tokens, you
301 might run, from the command line,
302 perltidy -D filename
304 where filename is a short script of interest. This will produce
306 filename.DEBUG with interleaved lines of text and their token types.
307 The -D flag has been in perltidy from the beginning for this purpose.
308 If you want to see the code which creates this file, it is
309 "write_debug_entry" in Tidy.pm.
310
312 &perltidy
313
315 Thanks to Hugh Myers who developed the initial modular interface to
316 perltidy.
317
319 This man page documents Perl::Tidy version 20101217.
320
322 Steve Hancock
323 perltidy at users.sourceforge.net
324
326 The perltidy(1) man page describes all of the features of perltidy. It
327 can be found at http://perltidy.sourceforge.net.
328perl v5.12.2 2010-12-13 Perl::Tidy(3)