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
37 filename, an ARRAY reference, a SCALAR reference, or an object with
38 either 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
75 output to what would otherwise go to the standard error output
76 device.
77 perltidyrc
79 If the perltidyrc file is given, it will be used instead of any
80 .perltidyrc configuration file that would otherwise be used.
81 argv
83 If the argv parameter is given, it will be used instead of the
84 @ARGV array. The argv parameter may be a string, a reference to a
85 string, or a reference to an array. If it is a string or reference
86 to a string, it will be parsed into an array of items just as if it
87 were a command line string.
88 dump_options
90 If the dump_options parameter is given, it must be the reference to
91 a hash. In this case, the parameters contained in any perltidyrc
92 configuration file will be placed in this hash and perltidy will
93 return immediately. This is equivalent to running perltidy with
94 --dump-options, except that the perameters are returned in a hash
95 rather than dumped to standard output. Also, by default only the
96 parameters in the perltidyrc file are returned, but this can be
97 changed (see the next parameter). This parameter provides a
98 convenient method for external programs to read a perltidyrc file.
99 An example program using this feature, perltidyrc_dump.pl, is
100 included in the distribution.
101 Any combination of the dump_ parameters may be used together.
103 dump_options_type
105 This parameter is a string which can be used to control the
106 parameters placed in the hash reference supplied by dump_options.
107 The possible values are 'perltidyrc' (default) and 'full'. The
108 'full' parameter causes both the default options plus any options
109 found in a perltidyrc file to be returned.
110 dump_getopt_flags
112 If the dump_getopt_flags parameter is given, it must be the
113 reference to a hash. This hash will receive all of the parameters
114 that perltidy understands and flags that are passed to
115 Getopt::Long. This parameter may be used alone or with the
116 dump_options flag. Perltidy will exit immediately after filling
117 this hash. See the demo program perltidyrc_dump.pl for example
118 usage.
119 dump_options_category
121 If the dump_options_category parameter is given, it must be the
122 reference to a hash. This hash will receive a hash with keys equal
123 to all long parameter names and values equal to the title of the
124 corresponding section of the perltidy manual. See the demo program
125 perltidyrc_dump.pl for example usage.
126 dump_abbreviations
128 If the dump_abbreviations parameter is given, it must be the
129 reference to a hash. This hash will receive all abbreviations used
130 by Perl::Tidy. See the demo program perltidyrc_dump.pl for example
131 usage.
132
134 The following example passes perltidy a snippet as a reference to a
135 string and receives the result back in a reference to an array.
136 use Perl::Tidy;
138 # some messy source code to format
140 my $source = <<'EOM';
141 use strict;
142 my @editors=('Emacs', 'Vi '); my $rand = rand();
143 print "A poll of 10 random programmers gave these results:\n";
144 foreach(0..10) {
145 my $i=int ($rand+rand());
146 print " $editors[$i] users are from Venus" . ", " .
147 "$editors[1-$i] users are from Mars" .
148 "\n";
149 }
150 EOM
151 # We'll pass it as ref to SCALAR and receive it in a ref to ARRAY
153 my @dest;
154 perltidy( source => \$source, destination => \@dest );
155 foreach (@dest) {print}
156
158 The formatter parameter is an optional callback object which allows the
159 calling program to receive tokenized lines directly from perltidy for
160 further specialized processing. When this parameter is used, the two
161 formatting options which are built into perltidy (beautification or
162 html) are ignored. The following diagram illustrates the logical flow:
163 |-- (normal route) -> code beautification
165 caller->perltidy->|-- (-html flag ) -> create html
166 |-- (formatter given)-> callback to write_line
167 This can be useful for processing perl scripts in some way. The
169 parameter $formatter in the perltidy call,
170 formatter => $formatter,
172 is an object created by the caller with a "write_line" method which
174 will accept and process tokenized lines, one line per call. Here is a
175 simple example of a "write_line" which merely prints the line number,
176 the line type (as determined by perltidy), and the text of the line:
177 sub write_line {
179 # This is called from perltidy line-by-line
181 my $self = shift;
182 my $line_of_tokens = shift;
183 my $line_type = $line_of_tokens->{_line_type};
184 my $input_line_number = $line_of_tokens->{_line_number};
185 my $input_line = $line_of_tokens->{_line_text};
186 print "$input_line_number:$line_type:$input_line";
187 }
188 The complete program, perllinetype, is contained in the examples
190 section of the source distribution. As this example shows, the
191 callback method receives a parameter $line_of_tokens, which is a
192 reference to a hash of other useful information. This example uses
193 these hash entries:
194 $line_of_tokens->{_line_number} - the line number (1,2,...)
196 $line_of_tokens->{_line_text} - the text of the line
197 $line_of_tokens->{_line_type} - the type of the line, one of:
198 SYSTEM - system-specific code before hash-bang line
200 CODE - line of perl code (including comments)
201 POD_START - line starting pod, such as '=head'
202 POD - pod documentation text
203 POD_END - last line of pod section, '=cut'
204 HERE - text of here-document
205 HERE_END - last line of here-doc (target word)
206 FORMAT - format section
207 FORMAT_END - last line of format section, '.'
208 DATA_START - __DATA__ line
209 DATA - unidentified text following __DATA__
210 END_START - __END__ line
211 END - unidentified text following __END__
212 ERROR - we are in big trouble, probably not a perl script
213 Most applications will be only interested in lines of type CODE. For
215 another example, let's write a program which checks for one of the so-
216 called naughty matching variables "&`", $&, and "$'", which can slow
217 down processing. Here is a write_line, from the example program
218 find_naughty.pl, which does that:
219 sub write_line {
221 # This is called back from perltidy line-by-line
223 # We're looking for $`, $&, and $'
224 my ( $self, $line_of_tokens ) = @_;
225 # pull out some stuff we might need
227 my $line_type = $line_of_tokens->{_line_type};
228 my $input_line_number = $line_of_tokens->{_line_number};
229 my $input_line = $line_of_tokens->{_line_text};
230 my $rtoken_type = $line_of_tokens->{_rtoken_type};
231 my $rtokens = $line_of_tokens->{_rtokens};
232 chomp $input_line;
233 # skip comments, pod, etc
235 return if ( $line_type ne 'CODE' );
236 # loop over tokens looking for $`, $&, and $'
238 for ( my $j = 0 ; $j < @$rtoken_type ; $j++ ) {
239 # we only want to examine token types 'i' (identifier)
241 next unless $$rtoken_type[$j] eq 'i';
242 # pull out the actual token text
244 my $token = $$rtokens[$j];
245 # and check it
247 if ( $token =~ /^\$[\`\&\']$/ ) {
248 print STDERR
249 "$input_line_number: $token\n";
250 }
251 }
252 }
253 This example pulls out these tokenization variables from the
255 $line_of_tokens hash reference:
256 $rtoken_type = $line_of_tokens->{_rtoken_type};
258 $rtokens = $line_of_tokens->{_rtokens};
259 The variable $rtoken_type is a reference to an array of token type
261 codes, and $rtokens is a reference to a corresponding array of token
262 text. These are obviously only defined for lines of type CODE.
263 Perltidy classifies tokens into types, and has a brief code for each
264 type. You can get a complete list at any time by running perltidy from
265 the command line with
266 perltidy --dump-token-types
268 In the present example, we are only looking for tokens of type i
270 (identifiers), so the for loop skips past all other types. When an
271 identifier is found, its actual text is checked to see if it is one
272 being sought. If so, the above write_line prints the token and its
273 line number.
274 The formatter feature is relatively new in perltidy, and further
276 documentation needs to be written to complete its description.
277 However, several example programs have been written and can be found in
278 the examples section of the source distribution. Probably the best way
279 to get started is to find one of the examples which most closely
280 matches your application and start modifying it.
281 For help with perltidy's pecular way of breaking lines into tokens, you
283 might run, from the command line,
284 perltidy -D filename
286 where filename is a short script of interest. This will produce
288 filename.DEBUG with interleaved lines of text and their token types.
289 The -D flag has been in perltidy from the beginning for this purpose.
290 If you want to see the code which creates this file, it is
291 "write_debug_entry" in Tidy.pm.
292
294 &perltidy
295
297 Thanks to Hugh Myers who developed the initial modular interface to
298 perltidy.
299
301 This man page documents Perl::Tidy version 20090616.
302
304 Steve Hancock
305 perltidy at users.sourceforge.net
306
308 The perltidy(1) man page describes all of the features of perltidy. It
309 can be found at http://perltidy.sourceforge.net.
310perl v5.10.1 2009-06-16 Perl::Tidy(3)