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 );
23
25 This module makes the functionality of the perltidy utility available
26 to perl scripts. Any or all of the input parameters may be omitted, in
27 which case the @ARGV array will be used to provide input parameters as
28 described in the perltidy(1) man page.
29 For example, the perltidy script is basically just this:
31 use Perl::Tidy;
33 Perl::Tidy::perltidy();
34 The module accepts input and output streams by a variety of methods.
36 The following list of parameters may be any of a the following: a file‐
37 name, an ARRAY reference, a SCALAR reference, or an object with either
38 a getline or print method, as appropriate.
39 source - the source of the script to be formatted
41 destination - the destination of the formatted output
42 stderr - standard error output
43 perltidyrc - the .perltidyrc file
44 logfile - the .LOG file stream, if any
45 errorfile - the .ERR file stream, if any
46 dump_options - ref to a hash to receive parameters (see below),
47 dump_options_type - controls contents of dump_options
48 dump_getopt_flags - ref to a hash to receive Getopt flags
49 dump_options_category - ref to a hash giving category of options
50 dump_abbreviations - ref to a hash giving all abbreviations
51 The following chart illustrates the logic used to decide how to treat a
53 parameter.
54 ref($param) $param is assumed to be:
56 ----------- ---------------------
57 undef a filename
58 SCALAR ref to string
59 ARRAY ref to array
60 (other) object with getline (if source) or print method
61 If the parameter is an object, and the object has a close method, that
63 close method will be called at the end of the stream.
64 source
66 If the source parameter is given, it defines the source of the
67 input stream.
68 destination
70 If the destination parameter is given, it will be used to define
71 the file or memory location to receive output of perltidy.
72 stderr
74 The stderr parameter allows the calling program to capture the out‐
75 put to what would otherwise go to the standard error output device.
76 perltidyrc
78 If the perltidyrc file is given, it will be used instead of any
79 .perltidyrc configuration file that would otherwise be used.
80 argv
82 If the argv parameter is given, it will be used instead of the
83 @ARGV array. The argv parameter may be a string, a reference to a
84 string, or a reference to an array. If it is a string or reference
85 to a string, it will be parsed into an array of items just as if it
86 were a command line string.
87 dump_options
89 If the dump_options parameter is given, it must be the reference to
90 a hash. In this case, the parameters contained in any perltidyrc
91 configuration file will be placed in this hash and perltidy will
92 return immediately. This is equivalent to running perltidy with
93 --dump-options, except that the perameters are returned in a hash
94 rather than dumped to standard output. Also, by default only the
95 parameters in the perltidyrc file are returned, but this can be
96 changed (see the next parameter). This parameter provides a conve‐
97 nient method for external programs to read a perltidyrc file. An
98 example program using this feature, perltidyrc_dump.pl, is included
99 in the distribution.
100 Any combination of the dump_ parameters may be used together.
102 dump_options_type
104 This parameter is a string which can be used to control the parame‐
105 ters placed in the hash reference supplied by dump_options. The
106 possible values are 'perltidyrc' (default) and 'full'. The 'full'
107 parameter causes both the default options plus any options found in
108 a perltidyrc file to be returned.
109 dump_getopt_flags
111 If the dump_getopt_flags parameter is given, it must be the refer‐
112 ence to a hash. This hash will receive all of the parameters that
113 perltidy understands and flags that are passed to Getopt::Long.
114 This parameter may be used alone or with the dump_options flag.
115 Perltidy will exit immediately after filling this hash. See the
116 demo program perltidyrc_dump.pl for example usage.
117 dump_options_category
119 If the dump_options_category parameter is given, it must be the
120 reference to a hash. This hash will receive a hash with keys equal
121 to all long parameter names and values equal to the title of the
122 corresponding section of the perltidy manual. See the demo program
123 perltidyrc_dump.pl for example usage.
124 dump_abbreviations
126 If the dump_abbreviations parameter is given, it must be the refer‐
127 ence to a hash. This hash will receive all abbreviations used by
128 Perl::Tidy. See the demo program perltidyrc_dump.pl for example
129 usage.
130
132 The following example passes perltidy a snippet as a reference to a
133 string and receives the result back in a reference to an array.
134 use Perl::Tidy;
136 # some messy source code to format
138 my $source = <<'EOM';
139 use strict;
140 my @editors=('Emacs', 'Vi '); my $rand = rand();
141 print "A poll of 10 random programmers gave these results:\n";
142 foreach(0..10) {
143 my $i=int ($rand+rand());
144 print " $editors[$i] users are from Venus" . ", " .
145 "$editors[1-$i] users are from Mars" .
146 "\n";
147 }
148 EOM
149 # We'll pass it as ref to SCALAR and receive it in a ref to ARRAY
151 my @dest;
152 perltidy( source => \$source, destination => \@dest );
153 foreach (@dest) {print}
154
156 The formatter parameter is an optional callback object which allows the
157 calling program to receive tokenized lines directly from perltidy for
158 further specialized processing. When this parameter is used, the two
159 formatting options which are built into perltidy (beautification or
160 html) are ignored. The following diagram illustrates the logical flow:
161 ⎪-- (normal route) -> code beautification
163 caller->perltidy->⎪-- (-html flag ) -> create html
164 ⎪-- (formatter given)-> callback to write_line
165 This can be useful for processing perl scripts in some way. The param‐
167 eter $formatter in the perltidy call,
168 formatter => $formatter,
170 is an object created by the caller with a "write_line" method which
172 will accept and process tokenized lines, one line per call. Here is a
173 simple example of a "write_line" which merely prints the line number,
174 the line type (as determined by perltidy), and the text of the line:
175 sub write_line {
177 # This is called from perltidy line-by-line
179 my $self = shift;
180 my $line_of_tokens = shift;
181 my $line_type = $line_of_tokens->{_line_type};
182 my $input_line_number = $line_of_tokens->{_line_number};
183 my $input_line = $line_of_tokens->{_line_text};
184 print "$input_line_number:$line_type:$input_line";
185 }
186 The complete program, perllinetype, is contained in the examples sec‐
188 tion of the source distribution. As this example shows, the callback
189 method receives a parameter $line_of_tokens, which is a reference to a
190 hash of other useful information. This example uses these hash
191 entries:
192 $line_of_tokens->{_line_number} - the line number (1,2,...)
194 $line_of_tokens->{_line_text} - the text of the line
195 $line_of_tokens->{_line_type} - the type of the line, one of:
196 SYSTEM - system-specific code before hash-bang line
198 CODE - line of perl code (including comments)
199 POD_START - line starting pod, such as '=head'
200 POD - pod documentation text
201 POD_END - last line of pod section, '=cut'
202 HERE - text of here-document
203 HERE_END - last line of here-doc (target word)
204 FORMAT - format section
205 FORMAT_END - last line of format section, '.'
206 DATA_START - __DATA__ line
207 DATA - unidentified text following __DATA__
208 END_START - __END__ line
209 END - unidentified text following __END__
210 ERROR - we are in big trouble, probably not a perl script
211 Most applications will be only interested in lines of type CODE. For
213 another example, let's write a program which checks for one of the so-
214 called naughty matching variables "&`", $&, and $', which can slow down
215 processing. Here is a write_line, from the example program
216 find_naughty.pl, which does that:
217 sub write_line {
219 # This is called back from perltidy line-by-line
221 # We're looking for $`, $&, and $'
222 my ( $self, $line_of_tokens ) = @_;
223 # pull out some stuff we might need
225 my $line_type = $line_of_tokens->{_line_type};
226 my $input_line_number = $line_of_tokens->{_line_number};
227 my $input_line = $line_of_tokens->{_line_text};
228 my $rtoken_type = $line_of_tokens->{_rtoken_type};
229 my $rtokens = $line_of_tokens->{_rtokens};
230 chomp $input_line;
231 # skip comments, pod, etc
233 return if ( $line_type ne 'CODE' );
234 # loop over tokens looking for $`, $&, and $'
236 for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) {
237 # we only want to examine token types 'i' (identifier)
239 next unless $$rtoken_type[$j] eq 'i';
240 # pull out the actual token text
242 my $token = $$rtokens[$j];
243 # and check it
245 if ( $token =~ /^\$[\`\&\']$/ ) {
246 print STDERR
247 "$input_line_number: $token\n";
248 }
249 }
250 }
251 This example pulls out these tokenization variables from the
253 $line_of_tokens hash reference:
254 $rtoken_type = $line_of_tokens->{_rtoken_type};
256 $rtokens = $line_of_tokens->{_rtokens};
257 The variable $rtoken_type is a reference to an array of token type
259 codes, and $rtokens is a reference to a corresponding array of token
260 text. These are obviously only defined for lines of type CODE.
261 Perltidy classifies tokens into types, and has a brief code for each
262 type. You can get a complete list at any time by running perltidy from
263 the command line with
264 perltidy --dump-token-types
266 In the present example, we are only looking for tokens of type i (iden‐
268 tifiers), so the for loop skips past all other types. When an identi‐
269 fier is found, its actual text is checked to see if it is one being
270 sought. If so, the above write_line prints the token and its line num‐
271 ber.
272 The formatter feature is relatively new in perltidy, and further docu‐
274 mentation needs to be written to complete its description. However,
275 several example programs have been written and can be found in the
276 examples section of the source distribution. Probably the best way to
277 get started is to find one of the examples which most closely matches
278 your application and start modifying it.
279 For help with perltidy's pecular way of breaking lines into tokens, you
281 might run, from the command line,
282 perltidy -D filename
284 where filename is a short script of interest. This will produce file‐
286 name.DEBUG with interleaved lines of text and their token types. The
287 -D flag has been in perltidy from the beginning for this purpose. If
288 you want to see the code which creates this file, it is
289 "write_debug_entry" in Tidy.pm.
290
292 &perltidy
293
295 Thanks to Hugh Myers who developed the initial modular interface to
296 perltidy.
297
299 This man page documents Perl::Tidy version 20070508.
300
302 Steve Hancock
303 perltidy at users.sourceforge.net
304
306 The perltidy(1) man page describes all of the features of perltidy. It
307 can be found at http://perltidy.sourceforge.net.
308perl v5.8.8 2007-05-08 Perl::Tidy(3)