Commit | Line | Data |
---|---|---|
86530b38 AT |
1 | #!/import/bw/tools/local/perl-5.8.0/bin/perl |
2 | ||
3 | eval 'exec /import/bw/tools/local/perl-5.8.0/bin/perl -S $0 ${1+"$@"}' | |
4 | if 0; # not running under some shell | |
5 | package main; | |
6 | ||
7 | use Perl::Tidy; | |
8 | ||
9 | my $arg_string = undef; | |
10 | ||
11 | # give Macs a chance to provide command line parameters | |
12 | if ($^O =~ /Mac/) { | |
13 | $arg_string = | |
14 | MacPerl::Ask( 'Please enter @ARGV (-h for help)', | |
15 | defined $ARGV[0] ? "\"$ARGV[0]\"" : "" ); | |
16 | } | |
17 | ||
18 | Perl::Tidy::perltidy(argv => $arg_string); | |
19 | ||
20 | __END__ | |
21 | ||
22 | =head1 NAME | |
23 | ||
24 | perltidy - a perl script indenter and reformatter | |
25 | ||
26 | =head1 SYNOPSIS | |
27 | ||
28 | perltidy [ options ] file1 file2 file3 ... | |
29 | (output goes to file1.tdy, file2.tdy, file3.tdy, ...) | |
30 | perltidy [ options ] file1 -o outfile | |
31 | perltidy [ options ] file1 -st >outfile | |
32 | perltidy [ options ] <infile >outfile | |
33 | ||
34 | =head1 DESCRIPTION | |
35 | ||
36 | Perltidy reads a perl script and writes an indented, reformatted script. | |
37 | ||
38 | Many users will find enough information in L<"EXAMPLES"> to get | |
39 | started. New users may benefit from the short tutorial | |
40 | which can be found at | |
41 | http://perltidy.sourceforge.net/tutorial.html | |
42 | ||
43 | A convenient aid to systematically defining a set of style parameters | |
44 | can be found at | |
45 | http://perltidy.sourceforge.net/stylekey.html | |
46 | ||
47 | Perltidy can produce output on either of two modes, depending on the | |
48 | existence of an B<-html> flag. Without this flag, the output is passed | |
49 | through a formatter. The default formatting tries to follow the | |
50 | recommendations in perlstyle(1), but it can be controlled in detail with | |
51 | numerous input parameters, which are described in L<"FORMATTING | |
52 | OPTIONS">. | |
53 | ||
54 | When the B<-html> flag is given, the output is passed through an HTML | |
55 | formatter which is described in L<"HTML OPTIONS">. | |
56 | ||
57 | =head1 EXAMPLES | |
58 | ||
59 | perltidy somefile.pl | |
60 | ||
61 | This will produce a file F<somefile.pl.tdy> containing the script reformatted | |
62 | using the default options, which approximate the style suggested in | |
63 | perlstyle(1). Perltidy never changes the input file. | |
64 | ||
65 | perltidy *.pl | |
66 | ||
67 | Execute perltidy on all F<.pl> files in the current directory with the | |
68 | default options. The output will be in files with an appended F<.tdy> | |
69 | extension. For any file with an error, there will be a file with extension | |
70 | F<.ERR>. | |
71 | ||
72 | perltidy -b file1.pl file2.pl | |
73 | ||
74 | Modify F<file1.pl> and F<file1.pl> in place, and backup the originals to | |
75 | F<file1.pl.bak> and F<file2.pl.bak>. If F<file1.pl.bak> and/or F<file2.pl.bak> | |
76 | already exist, they will be overwritten. | |
77 | ||
78 | perltidy -gnu somefile.pl | |
79 | ||
80 | Execute perltidy on file F<somefile.pl> with a style which approximates the | |
81 | GNU Coding Standards for C programs. The output will be F<somefile.pl.tdy>. | |
82 | ||
83 | perltidy -i=3 somefile.pl | |
84 | ||
85 | Execute perltidy on file F<somefile.pl>, with 3 columns for each level of | |
86 | indentation (B<-i=3>) instead of the default 4 columns. There will not be any | |
87 | tabs in the reformatted script, except for any which already exist in comments, | |
88 | pod documents, quotes, and here documents. Output will be F<somefile.pl.tdy>. | |
89 | ||
90 | perltidy -i=3 -et=8 somefile.pl | |
91 | ||
92 | Same as the previous example, except that leading whitespace will | |
93 | be entabbed with one tab character per 8 spaces. | |
94 | ||
95 | perltidy -ce -l=72 somefile.pl | |
96 | ||
97 | Execute perltidy on file F<somefile.pl> with all defaults except use "cuddled | |
98 | elses" (B<-ce>) and a maximum line length of 72 columns (B<-l=72>) instead of | |
99 | the default 80 columns. | |
100 | ||
101 | perltidy -g somefile.pl | |
102 | ||
103 | Execute perltidy on file F<somefile.pl> and save a log file F<somefile.pl.LOG> | |
104 | which shows the nesting of braces, parentheses, and square brackets at | |
105 | the start of every line. | |
106 | ||
107 | perltidy -html somefile.pl | |
108 | ||
109 | This will produce a file F<somefile.pl.html> containing the script with | |
110 | html markup. The output file will contain an embedded style sheet in | |
111 | the <HEAD> section which may be edited to change the appearance. | |
112 | ||
113 | perltidy -html -css=mystyle.css somefile.pl | |
114 | ||
115 | This will produce a file F<somefile.pl.html> containing the script with | |
116 | html markup. This output file will contain a link to a separate style | |
117 | sheet file F<mystyle.css>. If the file F<mystyle.css> does not exist, | |
118 | it will be created. If it exists, it will not be overwritten. | |
119 | ||
120 | perltidy -html -pre somefile.pl | |
121 | ||
122 | Write an html snippet with only the PRE section to F<somefile.pl.html>. | |
123 | This is useful when code snippets are being formatted for inclusion in a | |
124 | larger web page. No style sheet will be written in this case. | |
125 | ||
126 | perltidy -html -ss >mystyle.css | |
127 | ||
128 | Write a style sheet to F<mystyle.css> and exit. | |
129 | ||
130 | perltidy -html -frm mymodule.pm | |
131 | ||
132 | Write html with a frame holding a table of contents and the source code. The | |
133 | output files will be F<mymodule.pm.html> (the frame), F<mymodule.pm.toc.html> | |
134 | (the table of contents), and F<mymodule.pm.src.html> (the source code). | |
135 | ||
136 | =head1 OPTIONS - OVERVIEW | |
137 | ||
138 | The entire command line is scanned for options, and they are processed | |
139 | before any files are processed. As a result, it does not matter | |
140 | whether flags are before or after any filenames. However, the relative | |
141 | order of parameters is important, with later parameters overriding the | |
142 | values of earlier parameters. | |
143 | ||
144 | For each parameter, there is a long name and a short name. The short | |
145 | names are convenient for keyboard input, while the long names are | |
146 | self-documenting and therefore useful in scripts. It is customary to | |
147 | use two leading dashes for long names, but one may be used. | |
148 | ||
149 | Most parameters which serve as on/off flags can be negated with a | |
150 | leading "n" (for the short name) or a leading "no" or "no-" (for the | |
151 | long name). For example, the flag to outdent long quotes is is B<-olq> | |
152 | or B<--outdent-long-quotes>. The flag to skip this is B<-nolq> | |
153 | or B<--nooutdent-long-quotes> or B<--no-outdent-long-quotes>. | |
154 | ||
155 | Options may not be bundled together. In other words, options B<-q> and | |
156 | B<-g> may NOT be entered as B<-qg>. | |
157 | ||
158 | Option names may be terminated early as long as they are uniquely identified. | |
159 | For example, instead of B<-dump-token-types>, it would be sufficient to enter | |
160 | B<-dump-tok>, or even B<-dump-t>, to uniquely identify this command. | |
161 | ||
162 | =head2 I/O control | |
163 | ||
164 | The following parameters concern the files which are read and written. | |
165 | ||
166 | =over 4 | |
167 | ||
168 | =item B<-h>, B<--help> | |
169 | ||
170 | Show summary of usage and exit. | |
171 | ||
172 | =item B<-o>=filename, B<--outfile>=filename | |
173 | ||
174 | Name of the output file (only if a single input file is being | |
175 | processed). If no output file is specified, and output is not | |
176 | redirected to the standard output, the output will go to F<filename.tdy>. | |
177 | ||
178 | =item B<-st>, B<--standard-output> | |
179 | ||
180 | Perltidy must be able to operate on an arbitrarily large number of files | |
181 | in a single run, with each output being directed to a different output | |
182 | file. Obviously this would conflict with outputting to the single | |
183 | standard output device, so a special flag, B<-st>, is required to | |
184 | request outputting to the standard output. For example, | |
185 | ||
186 | perltidy somefile.pl -st >somefile.new.pl | |
187 | ||
188 | This option may only be used if there is just a single input file. | |
189 | The default is B<-nst> or B<-nostandard-output>. | |
190 | ||
191 | =item B<-se>, B<--standard-error-output> | |
192 | ||
193 | If perltidy detects an error when processing file F<somefile.pl>, its | |
194 | default behavior is to write error messages to file F<somefile.pl.ERR>. | |
195 | Use B<-se> to cause all error messages to be sent to the standard error | |
196 | output stream instead. This directive may be negated with B<-nse>. | |
197 | Thus, you may place B<-se> in a F<.perltidyrc> and override it when | |
198 | desired with B<-nse> on the command line. | |
199 | ||
200 | =item B<-oext>=ext, B<--output-file-extension>=ext | |
201 | ||
202 | Change the extension of the output file to be F<ext> instead of the | |
203 | default F<tdy> (or F<html> in case the -B<-html> option is used). | |
204 | See L<Specifying File Extensions>. | |
205 | ||
206 | =item B<-opath>=path, B<--output-path>=path | |
207 | ||
208 | When perltidy creates a filename for an output file, by default it merely | |
209 | appends an extension to the path and basename of the input file. This | |
210 | parameter causes the path to be changed to F<path> instead. | |
211 | ||
212 | The path should end in a valid path separator character, but perltidy will try | |
213 | to add one if it is missing. | |
214 | ||
215 | For example | |
216 | ||
217 | perltidy somefile.pl -opath=/tmp/ | |
218 | ||
219 | will produce F</tmp/somefile.pl.tdy>. Otherwise, F<somefile.pl.tdy> will | |
220 | appear in whatever directory contains F<somefile.pl>. | |
221 | ||
222 | If the path contains spaces, it should be placed in quotes. | |
223 | ||
224 | This parameter will be ignored if output is being directed to standard output, | |
225 | or if it is being specified explicitly with the B<-o=s> parameter. | |
226 | ||
227 | =item B<-b>, B<--backup-and-modify-in-place> | |
228 | ||
229 | Modify the input file or files in-place and save the original with the | |
230 | extension F<.bak>. Any existing F<.bak> file will be deleted. See next item | |
231 | for changing the default backup extension. | |
232 | ||
233 | A B<-b> flag will be ignored if input is from standard input, or | |
234 | if the B<-html> flag is set. | |
235 | ||
236 | =item B<-bext>=ext, B<--backup-file-extension>=ext | |
237 | ||
238 | Change the extension of the backup file to be something other than the | |
239 | default F<.bak>. See L<Specifying File Extensions>. | |
240 | ||
241 | =item B<-w>, B<--warning-output> | |
242 | ||
243 | Setting B<-w> causes any non-critical warning | |
244 | messages to be reported as errors. These include messages | |
245 | about possible pod problems, possibly bad starting indentation level, | |
246 | and cautions about indirect object usage. The default, B<-nw> or | |
247 | B<--nowarning-output>, is not to include these warnings. | |
248 | ||
249 | =item B<-q>, B<--quiet> | |
250 | ||
251 | Deactivate error messages and syntax checking (for running under | |
252 | an editor). | |
253 | ||
254 | For example, if you use a vi-style editor, such as vim, you may execute | |
255 | perltidy as a filter from within the editor using something like | |
256 | ||
257 | :n1,n2!perltidy -q | |
258 | ||
259 | where C<n1,n2> represents the selected text. Without the B<-q> flag, | |
260 | any error message may mess up your screen, so be prepared to use your | |
261 | "undo" key. | |
262 | ||
263 | =item B<-log>, B<--logfile> | |
264 | ||
265 | Save the F<.LOG> file, which has many useful diagnostics. Perltidy always | |
266 | creates a F<.LOG> file, but by default it is deleted unless a program bug is | |
267 | suspected. Setting the B<-log> flag forces the log file to be saved. | |
268 | ||
269 | =item B<-g=n>, B<--logfile-gap=n> | |
270 | ||
271 | Set maximum interval between input code lines in the logfile. This purpose of | |
272 | this flag is to assist in debugging nesting errors. The value of C<n> is | |
273 | optional. If you set the flag B<-g> without the value of C<n>, it will be | |
274 | taken to be 1, meaning that every line will be written to the log file. This | |
275 | can be helpful if you are looking for a brace, paren, or bracket nesting error. | |
276 | ||
277 | Setting B<-g> also causes the logfile to be saved, so it is not necessary to | |
278 | also include B<-log>. | |
279 | ||
280 | If no B<-g> flag is given, a value of 50 will be used, meaning that at least | |
281 | every 50th line will be recorded in the logfile. This helps prevent | |
282 | excessively long log files. | |
283 | ||
284 | Setting a negative value of C<n> is the same as not setting B<-g> at all. | |
285 | ||
286 | =item B<-npro> B<--noprofile> | |
287 | ||
288 | Ignore any F<.perltidyrc> command file. Normally, perltidy looks first in | |
289 | your current directory for a F<.perltidyrc> file of parameters. (The format | |
290 | is described below). If it finds one, it applies those options to the | |
291 | initial default values, and then it applies any that have been defined | |
292 | on the command line. If no F<.perltidyrc> file is found, it looks for one | |
293 | in your home directory. | |
294 | ||
295 | If you set the B<-npro> flag, perltidy will not look for this file. | |
296 | ||
297 | =item B<-pro=filename> or B<--profile=filename> | |
298 | ||
299 | To simplify testing and switching .perltidyrc files, this command may be | |
300 | used to specify a configuration file which will override the default | |
301 | name of .perltidyrc. There must not be a space on either side of the | |
302 | '=' sign. For example, the line | |
303 | ||
304 | perltidy -pro=testcfg | |
305 | ||
306 | would cause file F<testcfg> to be used instead of the | |
307 | default F<.perltidyrc>. | |
308 | ||
309 | =item B<-opt>, B<--show-options> | |
310 | ||
311 | Write a list of all options used to the F<.LOG> file. | |
312 | Please see B<--dump-options> for a simpler way to do this. | |
313 | ||
314 | =item B<-f>, B<--force-read-binary> | |
315 | ||
316 | Force perltidy to process binary files. To avoid producing excessive | |
317 | error messages, perltidy skips files identified by the system as non-text. | |
318 | However, valid perl scripts containing binary data may sometimes be identified | |
319 | as non-text, and this flag forces perltidy to process them. | |
320 | ||
321 | =back | |
322 | ||
323 | =head1 FORMATTING OPTIONS | |
324 | ||
325 | =head2 Basic Options | |
326 | ||
327 | =over 4 | |
328 | ||
329 | =item B<-l=n>, B<--maximum-line-length=n> | |
330 | ||
331 | The default maximum line length is n=80 characters. Perltidy will try | |
332 | to find line break points to keep lines below this length. However, long | |
333 | quotes and side comments may cause lines to exceed this length. | |
334 | Setting B<-l=0> is equivalent to setting B<-l=(a large number)>. | |
335 | ||
336 | =item B<-i=n>, B<--indent-columns=n> | |
337 | ||
338 | Use n columns per indentation level (default n=4). | |
339 | ||
340 | =item tabs | |
341 | ||
342 | Using tab characters will almost certainly lead to future portability | |
343 | and maintenance problems, so the default and recommendation is not to | |
344 | use them. For those who prefer tabs, however, there are two different | |
345 | options. | |
346 | ||
347 | Except for possibly introducing tab indentation characters, as outlined | |
348 | below, perltidy does not introduce any tab characters into your file, | |
349 | and it removes any tabs from the code (unless requested not to do so | |
350 | with B<-fws>). If you have any tabs in your comments, quotes, or | |
351 | here-documents, they will remain. | |
352 | ||
353 | =over 4 | |
354 | ||
355 | =item B<-et=n>, B<--entab-leading-whitespace> | |
356 | ||
357 | This flag causes each B<n> initial space characters to be replaced by | |
358 | one tab character. Note that the integer B<n> is completely independent | |
359 | of the integer specified for indentation parameter, B<-i=n>. | |
360 | ||
361 | =item B<-t>, B<--tabs> | |
362 | ||
363 | This flag causes one leading tab character to be inserted for each level | |
364 | of indentation. Certain other features are incompatible with this | |
365 | option, and if these options are also given, then a warning message will | |
366 | be issued and this flag will be unset. One example is the B<-lp> | |
367 | option. | |
368 | ||
369 | =back | |
370 | ||
371 | =item B<-syn>, B<--check-syntax> | |
372 | ||
373 | This flag causes perltidy to run C<perl -c -T> to check syntax of input | |
374 | and output. (To change the flags passed to perl, see the next | |
375 | item, B<-pscf>). The results are written to the F<.LOG> file, which | |
376 | will be saved if an error is detected in the output script. The output | |
377 | script is not checked if the input script has a syntax error. Perltidy | |
378 | does its own checking, but this option employs perl to get a "second | |
379 | opinion". | |
380 | ||
381 | If perl reports errors in the input file, they will not be reported in | |
382 | the error output unless the B<-warning-output> flag is given. | |
383 | ||
384 | The default is B<not> to do this type of syntax checking (although | |
385 | perltidy will still do as much self-checking as possible). The reason | |
386 | is that it causes all code in BEGIN blocks to be executed, for all | |
387 | modules being used, and this opens the door to security issues and | |
388 | infinite loops when running perltidy. | |
389 | ||
390 | =item B<-pscf=s>, B<-perl-syntax-check-flags=s> | |
391 | ||
392 | When perl is invoked to check syntax, the normal flags are C<-c -T>. In | |
393 | addition, if the B<-x> flag is given to perltidy, then perl will also be | |
394 | passed a B<-x> flag. It should not normally be necessary to change | |
395 | these flags, but it can be done with the B<-pscf=s> flag. For example, | |
396 | if the taint flag, C<-T>, is not wanted, the flag could be set to be just | |
397 | B<-pscf=-c>. | |
398 | ||
399 | Perltidy will pass your string to perl with the exception that it will | |
400 | add a B<-c> and B<-x> if appropriate. The F<.LOG> file will show | |
401 | exactly what flags were passed to perl. | |
402 | ||
403 | =item B<-io>, B<--indent-only> | |
404 | ||
405 | This flag is used to deactivate all formatting and line break changes. | |
406 | When it is in effect, the only change to the script will be indentation. | |
407 | And any flags controlling whitespace and newlines will be ignored. You | |
408 | might want to use this if you are perfectly happy with your whitespace | |
409 | and line breaks, and merely want perltidy to handle the indentation. | |
410 | (This also speeds up perltidy by well over a factor of two, so it might be | |
411 | useful when perltidy is merely being used to help find a brace error in | |
412 | a large script). | |
413 | ||
414 | Setting this flag is equivalent to setting B<--freeze-newlines> and | |
415 | B<--freeze-whitespace>. | |
416 | ||
417 | =item B<-ole=s>, B<--output-line-ending=s> | |
418 | ||
419 | where s=C<win>, C<dos>, C<unix>, or C<mac>. This flag tells perltidy | |
420 | to output line endings for a specific system. Normally, | |
421 | perltidy writes files with the line separator character of the host | |
422 | system. The C<win> and C<dos> flags have an identical result. | |
423 | B<NOTE>: This only works under unix-like systems and is ignored under | |
424 | other systems. | |
425 | ||
426 | =item B<-ple>, B<--preserve-line-endings> | |
427 | ||
428 | This flag tells perltidy to write its output files with the same line | |
429 | endings as the input file, if possible. It should work for | |
430 | B<dos>, B<unix>, and B<mac> line endings. It will only work if perltidy | |
431 | input comes from a filename (rather than stdin, for example). If | |
432 | perltidy has trouble determining the input file line ending, it will | |
433 | revert to the default behavior of using the line ending of the host system. | |
434 | B<NOTE>: This only works under unix-like systems and is ignored under | |
435 | other systems. | |
436 | ||
437 | =back | |
438 | ||
439 | =head2 Code Indentation Control | |
440 | ||
441 | =over 4 | |
442 | ||
443 | =item B<-ci=n>, B<--continuation-indentation=n> | |
444 | ||
445 | Continuation indentation is extra indentation spaces applied when | |
446 | a long line is broken. The default is n=2, illustrated here: | |
447 | ||
448 | my $level = # -ci=2 | |
449 | ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level; | |
450 | ||
451 | The same example, with n=0, is a little harder to read: | |
452 | ||
453 | my $level = # -ci=0 | |
454 | ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level; | |
455 | ||
456 | The value given to B<-ci> is also used by some commands when a small | |
457 | space is required. Examples are commands for outdenting labels, | |
458 | B<-ola>, and control keywords, B<-okw>. | |
459 | ||
460 | When default values are not used, it is suggested that the value B<n> | |
461 | given with B<-ci=n> be no more than about one-half of the number of | |
462 | spaces assigned to a full indentation level on the B<-i=n> command. | |
463 | ||
464 | =item B<-sil=n> B<--starting-indentation-level=n> | |
465 | ||
466 | By default, perltidy examines the input file and tries to determine the | |
467 | starting indentation level. While it is often zero, it may not be | |
468 | zero for a code snippet being sent from an editing session. If the | |
469 | default method does not work correctly, or you want to change the | |
470 | starting level, use B<-sil=n>, to force the starting level to be n. | |
471 | ||
472 | =item List indentation using B<-lp>, B<--line-up-parentheses> | |
473 | ||
474 | By default, perltidy indents lists with 4 spaces, or whatever value | |
475 | is specified with B<-i=n>. Here is a small list formatted in this way: | |
476 | ||
477 | # perltidy (default) | |
478 | @month_of_year = ( | |
479 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
480 | 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
481 | ); | |
482 | ||
483 | Use the B<-lp> flag to add extra indentation to cause the data to begin | |
484 | past the opening parentheses of a sub call or list, or opening square | |
485 | bracket of an anonymous array, or opening curly brace of an anonymous | |
486 | hash. With this option, the above list would become: | |
487 | ||
488 | # perltidy -lp | |
489 | @month_of_year = ( | |
490 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
491 | 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
492 | ); | |
493 | ||
494 | If the available line length (see B<-l=n> ) does not permit this much | |
495 | space, perltidy will use less. For alternate placement of the | |
496 | closing paren, see the next section. | |
497 | ||
498 | This option has no effect on code BLOCKS, such as if/then/else blocks, | |
499 | which always use whatever is specified with B<-i=n>. Also, the | |
500 | existence of line breaks and/or block comments between the opening and | |
501 | closing parens may cause perltidy to temporarily revert to its default | |
502 | method. | |
503 | ||
504 | Note: The B<-lp> option may not be used together with the B<-t> tabs option. | |
505 | It may, however, be used with the B<-et=n> tab method. | |
506 | ||
507 | In addition, any parameter which significantly restricts the ability of | |
508 | perltidy to choose newlines will conflict with B<-lp> and will cause | |
509 | B<-lp> to be deactivated. These include B<-io>, B<-fnl>, B<-nanl>, and | |
510 | B<-ndnl>. The reason is that the B<-lp> indentation style can require | |
511 | the careful coordination of an arbitrary number of break points in | |
512 | hierarchical lists, and these flags may prevent that. | |
513 | ||
514 | =item B<-cti=n>, B<--closing-token-indentation> | |
515 | ||
516 | The B<-cti=n> flag controls the indentation of a line beginning with | |
517 | a C<)>, C<]>, or a non-block C<}>. Such a line receives: | |
518 | ||
519 | -cti = 0 no extra indentation (default) | |
520 | -cti = 1 extra indentation such that the closing token | |
521 | aligns with its opening token. | |
522 | -cti = 2 one extra indentation level if the line looks like: | |
523 | ); or ]; or }; | |
524 | ||
525 | The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous | |
526 | section). | |
527 | ||
528 | # perltidy -lp -cti=1 | |
529 | @month_of_year = ( | |
530 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
531 | 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
532 | ); | |
533 | ||
534 | # perltidy -lp -cti=2 | |
535 | @month_of_year = ( | |
536 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', | |
537 | 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec' | |
538 | ); | |
539 | ||
540 | These flags are merely hints to the formatter and they may not always be | |
541 | followed. In particular, if -lp is not being used, the indentation for | |
542 | B<cti=1> is constrained to be no more than one indentation level. | |
543 | ||
544 | If desired, this control can be applied independently to each of the | |
545 | closing container token types. In fact, B<-cti=n> is merely an | |
546 | abbreviation for B<-cpi=n -csbi=n -cbi=n>, where: | |
547 | B<-cpi> or B<-closing-paren-indentation> controls B<)>'s, | |
548 | B<-csbi> or B<-closing-square-bracket-indentation> controls B<]>'s, | |
549 | B<-cbi> or B<-closing-brace-indentation> controls non-block B<}>'s. | |
550 | ||
551 | =item B<-icp>, B<--indent-closing-paren> | |
552 | ||
553 | The B<-icp> flag is equivalent to | |
554 | B<-cti=2>, described in the previous section. The B<-nicp> flag is | |
555 | equivalent B<-cti=0>. They are included for backwards compatability. | |
556 | ||
557 | =item B<-icb>, B<--indent-closing-brace> | |
558 | ||
559 | The B<-icb> option leaves a brace which terminates a code block | |
560 | indented with the same indentation as the previous line. For example, | |
561 | ||
562 | if ($task) { | |
563 | yyy(); | |
564 | } # -icb | |
565 | else { | |
566 | zzz(); | |
567 | } | |
568 | ||
569 | The default is not to do this, indicated by B<-nicb>. | |
570 | ||
571 | =item B<-olq>, B<--outdent-long-quotes> | |
572 | ||
573 | When B<-olq> is set, lines which is a quoted string longer than the | |
574 | value B<maximum-line-length> will have their indentation removed to make | |
575 | them more readable. This is the default. To prevent such out-denting, | |
576 | use B<-nolq> or B<--nooutdent-long-lines>. | |
577 | ||
578 | =item B<-oll>, B<--outdent-long-lines> | |
579 | ||
580 | This command is equivalent to B<--outdent-long-quotes> and | |
581 | B<--outdent-long-comments>, and it is included for compatibility with previous | |
582 | versions of perltidy. The negation of this also works, B<-noll> or | |
583 | B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>. | |
584 | ||
585 | =item Outdenting Labels: B<-ola>, B<--outdent-labels> | |
586 | ||
587 | This command will cause labels to be outdented by 2 spaces (or whatever B<-ci> | |
588 | has been set to), if possible. This is the default. For example: | |
589 | ||
590 | my $i; | |
591 | LOOP: while ( $i = <FOTOS> ) { | |
592 | chomp($i); | |
593 | next unless $i; | |
594 | fixit($i); | |
595 | } | |
596 | ||
597 | Use B<-nola> to not outdent labels. | |
598 | ||
599 | =item Outdenting Keywords | |
600 | ||
601 | =over 4 | |
602 | ||
603 | =item B<-okw>, B<--outdent-keywords> | |
604 | ||
605 | The command B<-okw> will will cause certain leading control keywords to | |
606 | be outdented by 2 spaces (or whatever B<-ci> has been set to), if | |
607 | possible. By default, these keywords are C<redo>, C<next>, C<last>, | |
608 | C<goto>, and C<return>. The intention is to make these control keywords | |
609 | easier to see. To change this list of keywords being outdented, see | |
610 | the next section. | |
611 | ||
612 | For example, using C<perltidy -okw> on the previous example gives: | |
613 | ||
614 | my $i; | |
615 | LOOP: while ( $i = <FOTOS> ) { | |
616 | chomp($i); | |
617 | next unless $i; | |
618 | fixit($i); | |
619 | } | |
620 | ||
621 | The default is not to do this. | |
622 | ||
623 | =item Specifying Outdented Keywords: B<-okwl=string>, B<--outdent-keyword-list=string> | |
624 | ||
625 | This command can be used to change the keywords which are outdented with | |
626 | the B<-okw> command. The parameter B<string> is a required list of perl | |
627 | keywords, which should be placed in quotes if there are more than one. | |
628 | By itself, it does not cause any outdenting to occur, so the B<-okw> | |
629 | command is still required. | |
630 | ||
631 | For example, the commands C<-okwl="next last redo goto" -okw> will cause | |
632 | those four keywords to be outdented. It is probably simplest to place | |
633 | any B<-okwl> command in a F<.perltidyrc> file. | |
634 | ||
635 | =back | |
636 | ||
637 | =back | |
638 | ||
639 | =head2 Whitespace Control | |
640 | ||
641 | Whitespace refers to the blank space between variables, operators, | |
642 | and other code tokens. | |
643 | ||
644 | =over 4 | |
645 | ||
646 | =item B<-fws>, B<--freeze-whitespace> | |
647 | ||
648 | This flag causes your original whitespace to remain unchanged, and | |
649 | causes the rest of the whitespace commands in this section, the | |
650 | Code Indentation section, and | |
651 | the Comment Control section to be ignored. | |
652 | ||
653 | =item Tightness of curly braces, parentheses, and square brackets. | |
654 | ||
655 | Here the term "tightness" will mean the closeness with which | |
656 | pairs of enclosing tokens, such as parentheses, contain the quantities | |
657 | within. A numerical value of 0, 1, or 2 defines the tightness, with | |
658 | 0 being least tight and 2 being most tight. Spaces within containers | |
659 | are always symmetric, so if there is a space after a C<(> then there | |
660 | will be a space before the corresponding C<)>. | |
661 | ||
662 | The B<-pt=n> or B<--paren-tightness=n> parameter controls the space within | |
663 | parens. The example below shows the effect of the three possible | |
664 | values, 0, 1, and 2: | |
665 | ||
666 | if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 | |
667 | if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) | |
668 | if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 | |
669 | ||
670 | When n is 0, there is always a space to the right of a '(' and to the left | |
671 | of a ')'. For n=2 there is never a space. For n=1, the default, there | |
672 | is a space unless the quantity within the parens is a single token, such | |
673 | as an identifier or quoted string. | |
674 | ||
675 | Likewise, the parameter B<-sbt=n> or B<--square-bracket-tightness=n> | |
676 | controls the space within square brackets, as illustrated below. | |
677 | ||
678 | $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0 | |
679 | $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default) | |
680 | $width = $col[$j + $k] - $col[$j]; # -sbt=2 | |
681 | ||
682 | Curly braces which do not contain code blocks are controlled by | |
683 | the parameter B<-bt=n> or B<--brace-tightness=n>. | |
684 | ||
685 | $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0 | |
686 | $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default) | |
687 | $obj->{$parsed_sql->{'table'}[0]}; # -bt=2 | |
688 | ||
689 | And finally, curly braces which contain blocks of code are controlled by the | |
690 | parameter B<-bbt=n> or B<--block-brace-tightness=n> as illustrated in the | |
691 | example below. | |
692 | ||
693 | %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default) | |
694 | %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1 | |
695 | %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2 | |
696 | ||
697 | =item B<-sts>, B<--space-terminal-semicolon> | |
698 | ||
699 | Some programmers prefer a space before all terminal semicolons. The | |
700 | default is for no such space, and is indicated with B<-nsts> or | |
701 | B<--nospace-terminal-semicolon>. | |
702 | ||
703 | $i = 1 ; # -sts | |
704 | $i = 1; # -nsts (default) | |
705 | ||
706 | =item B<-sfs>, B<--space-for-semicolon> | |
707 | ||
708 | Semicolons within B<for> loops may sometimes be hard to see, | |
709 | particularly when commas are also present. This option places spaces on | |
710 | both sides of these special semicolons, and is the default. Use | |
711 | B<-nsfs> or B<--nospace-for-semicolon> to deactivate it. | |
712 | ||
713 | for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default) | |
714 | for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs | |
715 | ||
716 | =item B<-asc>, B<--add-semicolons> | |
717 | ||
718 | Setting B<-asc> allows perltidy to add any missing optional semicolon at the end | |
719 | of a line which is followed by a closing curly brace on the next line. This | |
720 | is the default, and may be deactivated with B<-nasc> or B<--noadd-semicolons>. | |
721 | ||
722 | =item B<-dsm>, B<--delete-semicolons> | |
723 | ||
724 | Setting B<-dsm> allows perltidy to delete extra semicolons which are | |
725 | simply empty statements. This is the default, and may be deactivated | |
726 | with B<-ndsm> or B<--nodelete-semicolons>. (Such semicolons are not | |
727 | deleted, however, if they would promote a side comment to a block | |
728 | comment). | |
729 | ||
730 | =item B<-aws>, B<--add-whitespace> | |
731 | ||
732 | Setting this option allows perltidy to add certain whitespace improve | |
733 | code readability. This is the default. If you do not want any | |
734 | whitespace added, but are willing to have some whitespace deleted, use | |
735 | B<-naws>. (Use B<-fws> to leave whitespace completely unchanged). | |
736 | ||
737 | =item B<-dws>, B<--delete-old-whitespace> | |
738 | ||
739 | Setting this option allows perltidy to remove some old whitespace | |
740 | between characters, if necessary. This is the default. If you | |
741 | do not want any old whitespace removed, use B<-ndws> or | |
742 | B<--nodelete-old-whitespace>. | |
743 | ||
744 | =item Detailed whitespace controls around tokens | |
745 | ||
746 | For those who want more detailed control over the whitespace around | |
747 | tokens, there are four parameters which can directly modify the default | |
748 | whitespace rules built into perltidy for any token. They are: | |
749 | ||
750 | B<-wls=s> or B<--want-left-space=s>, | |
751 | ||
752 | B<-nwls=s> or B<--nowant-left-space=s>, | |
753 | ||
754 | B<-wrs=s> or B<--want-right-space=s>, | |
755 | ||
756 | B<-nwrs=s> or B<--nowant-right-space=s>. | |
757 | ||
758 | These parameters are each followed by a quoted string, B<s>, containing a | |
759 | list of token types. No more than one of each of these parameters | |
760 | should be specified, because repeating a command-line parameter | |
761 | always overwrites the previous one before perltidy ever sees it. | |
762 | ||
763 | To illustrate how these are used, suppose it is desired that there be no | |
764 | space on either side of the token types B<= + - / *>. The following two | |
765 | parameters would specify this desire: | |
766 | ||
767 | -nwls="= + - / *" -nwrs="= + - / *" | |
768 | ||
769 | (Note that the token types are in quotes, and that they are separated by | |
770 | spaces). With these modified whitespace rules, the following line of math: | |
771 | ||
772 | $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a ); | |
773 | ||
774 | becomes this: | |
775 | ||
776 | $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a ); | |
777 | ||
778 | These parameters should be considered to be hints to perltidy rather | |
779 | than fixed rules, because perltidy must try to resolve conflicts that | |
780 | arise between them and all of the other rules that it uses. One | |
781 | conflict that can arise is if, between two tokens, the left token wants | |
782 | a space and the right one doesn't. In this case, the token not wanting | |
783 | a space takes priority. | |
784 | ||
785 | It is necessary to have a list of all token types in order to create | |
786 | this type of input. Such a list can be obtained by the command | |
787 | B<-dump-token-types>. | |
788 | ||
789 | =item Space between keyword and opening paren | |
790 | ||
791 | When an opening paren follows a keyword, no space is introduced after the | |
792 | keyword, unless it is (by default) one of these: | |
793 | ||
794 | my local our and or eq ne if else elsif until unless | |
795 | while for foreach return switch case given when | |
796 | ||
797 | These defaults can be modified with two commands: | |
798 | ||
799 | B<-sak=s> or B<--space-after-keyword=s> adds keywords. | |
800 | ||
801 | B<-nsak=s> or B<--nospace-after-keyword=s> removes keywords. | |
802 | ||
803 | where B<s> is a list of keywords (in quotes if necessary). For example, | |
804 | ||
805 | my ( $a, $b, $c ) = @_; # default | |
806 | my( $a, $b, $c ) = @_; # -nsak="my local our" | |
807 | ||
808 | =item Trimming whitespace around C<qw> quotes | |
809 | ||
810 | B<-tqw> or B<--trim-qw> provide the default behavior of trimming | |
811 | spaces around multi-line C<qw> quotes and indenting them appropriately. | |
812 | ||
813 | B<-ntqw> or B<--notrim-qw> cause leading and trailing whitespace around | |
814 | multi-line C<qw> quotes to be left unchanged. This option will not | |
815 | normally be necessary, but was added for testing purposes, because in | |
816 | some versions of perl, trimming C<qw> quotes changes the syntax tree. | |
817 | ||
818 | =back | |
819 | ||
820 | =head2 Comment Controls | |
821 | ||
822 | Perltidy has a number of ways to control the appearance of both block comments | |
823 | and side comments. The term B<block comment> here refers to a full-line | |
824 | comment, whereas B<side comment> will refer to a comment which appears on a | |
825 | line to the right of some code. | |
826 | ||
827 | =over 4 | |
828 | ||
829 | =item B<-ibc>, B<--indent-block-comments> | |
830 | ||
831 | Block comments normally look best when they are indented to the same | |
832 | level as the code which follows them. This is the default behavior, but | |
833 | you may use B<-nibc> to keep block comments left-justified. Here is an | |
834 | example: | |
835 | ||
836 | # this comment is indented (-ibc, default) | |
837 | if ($task) { yyy(); } | |
838 | ||
839 | The alternative is B<-nibc>: | |
840 | ||
841 | # this comment is not indented (-nibc) | |
842 | if ($task) { yyy(); } | |
843 | ||
844 | See also the next item, B<-isbc>, as well as B<-sbc>, for other ways to | |
845 | have some indented and some outdented block comments. | |
846 | ||
847 | =item B<-isbc>, B<--indent-spaced-block-comments> | |
848 | ||
849 | If there is no leading space on the line, then the comment will not be | |
850 | indented, and otherwise it may be. | |
851 | ||
852 | If both B<-ibc> and B<-isbc> are set, then B<-isbc> takes priority. | |
853 | ||
854 | =item B<-olc>, B<--outdent-long-comments> | |
855 | ||
856 | When B<-olc> is set, lines which are full-line (block) comments longer | |
857 | than the value B<maximum-line-length> will have their indentation | |
858 | removed. The default is not to do this. | |
859 | ||
860 | =item B<-msc=n>, B<--minimum-space-to-comment=n> | |
861 | ||
862 | Side comments look best when lined up several spaces to the right of | |
863 | code. Perltidy will try to keep comments at least n spaces to the | |
864 | right. The default is n=4 spaces. | |
865 | ||
866 | =item B<-hsc>, B<--hanging-side-comments> | |
867 | ||
868 | By default, perltidy tries to identify and align "hanging side | |
869 | comments", which are something like this: | |
870 | ||
871 | my $IGNORE = 0; # This is a side comment | |
872 | # This is a hanging side comment | |
873 | # And so is this | |
874 | ||
875 | A comment is considered to be a hanging side comment if (1) it immediately | |
876 | follows a line with a side comment, or another hanging side comment, and | |
877 | (2) there is some leading whitespace on the line. | |
878 | To deactivate this feature, use B<-nhsc> or B<--nohanging-side-comments>. | |
879 | If block comments are preceded by a blank line, or have no leading | |
880 | whitespace, they will not be mistaken as hanging side comments. | |
881 | ||
882 | =item Closing Side Comments | |
883 | ||
884 | A closing side comment is a special comment which perltidy can | |
885 | automatically create and place after the closing brace of a code block. | |
886 | They can be useful for code maintenance and debugging. The command | |
887 | B<-csc> (or B<-closing-side-comments>) adds or updates closing side | |
888 | comments. For example, here is a small code snippet | |
889 | ||
890 | sub message { | |
891 | if ( !defined( $_[0] ) ) { | |
892 | print("Hello, World\n"); | |
893 | } | |
894 | else { | |
895 | print( $_[0], "\n" ); | |
896 | } | |
897 | } | |
898 | ||
899 | And here is the result of processing with C<perltidy -csc>: | |
900 | ||
901 | sub message { | |
902 | if ( !defined( $_[0] ) ) { | |
903 | print("Hello, World\n"); | |
904 | } | |
905 | else { | |
906 | print( $_[0], "\n" ); | |
907 | } | |
908 | } ## end sub message | |
909 | ||
910 | A closing side comment was added for C<sub message> in this case, but not | |
911 | for the C<if> and C<else> blocks, because they were below the 6 line | |
912 | cutoff limit for adding closing side comments. This limit may be | |
913 | changed with the B<-csci> command, described below. | |
914 | ||
915 | The command B<-dcsc> (or B<--delete-closing-side-comments>) reverses this | |
916 | process and removes these comments. | |
917 | ||
918 | Several commands are available to modify the behavior of these two basic | |
919 | commands, B<-csc> and B<-dcsc>: | |
920 | ||
921 | =over 4 | |
922 | ||
923 | =item B<-csci=n>, or B<-closing-side-comment-interval=n> | |
924 | ||
925 | where C<n> is the minimum number of lines that a block must have in | |
926 | order for a closing side comment to be added. The default value is | |
927 | C<n=6>. To illustrate: | |
928 | ||
929 | # perltidy -csci=2 -csc | |
930 | sub message { | |
931 | if ( !defined( $_[0] ) ) { | |
932 | print("Hello, World\n"); | |
933 | } ## end if ( !defined( $_[0] )) | |
934 | else { | |
935 | print( $_[0], "\n" ); | |
936 | } ## end else [ if ( !defined( $_[0] )) | |
937 | } ## end sub message | |
938 | ||
939 | Now the C<if> and C<else> blocks are commented. However, now this has | |
940 | become very cluttered. | |
941 | ||
942 | =item B<-cscp=string>, or B<-closing-side-comment-prefix=string> | |
943 | ||
944 | where string is the prefix used before the name of the block type. The | |
945 | default prefix, shown above, is C<## end>. This string will be added to | |
946 | closing side comments, and it will also be used to recognize them in | |
947 | order to update, delete, and format them. Any comment identified as a | |
948 | closing side comment will be placed just a single space to the right of | |
949 | its closing brace. | |
950 | ||
951 | =item B<-cscl=string>, or B<-closing-side-comment-list-string> | |
952 | ||
953 | where C<string> is a list of block types to be tagged with closing side | |
954 | comments. By default, all code block types preceded by a keyword or | |
955 | label (such as C<if>, C<sub>, and so on) will be tagged. The B<-cscl> | |
956 | command changes the default list to be any selected block types; see | |
957 | L<Specifying Block Types>. | |
958 | For example, the following command | |
959 | requests that only C<sub>'s, labels, C<BEGIN>, and C<END> blocks be | |
960 | affected by any B<-csc> or B<-dcsc> operation: | |
961 | ||
962 | -cscl="sub : BEGIN END" | |
963 | ||
964 | =item B<-csct=n>, or B<-closing-side-comment-maximum-text=n> | |
965 | ||
966 | The text appended to certain block types, such as an C<if> block, is | |
967 | whatever lies between the keyword introducing the block, such as C<if>, | |
968 | and the opening brace. Since this might be too much text for a side | |
969 | comment, there needs to be a limit, and that is the purpose of this | |
970 | parameter. The default value is C<n=20>, meaning that no additional | |
971 | tokens will be appended to this text after its length reaches 20 | |
972 | characters. Omitted text is indicated with C<...>. (Tokens, including | |
973 | sub names, are never truncated, however, so actual lengths may exceed | |
974 | this). To illustrate, in the above example, the appended text of the | |
975 | first block is C< ( !defined( $_[0] )...>. The existing limit of | |
976 | C<n=20> caused this text to be truncated, as indicated by the C<...>. | |
977 | ||
978 | =item B<-csce=n>, or B<-closing-side-comment-else-flag=n> | |
979 | ||
980 | The default, B<n=0>, places the text of the opening C<if> statement after any | |
981 | terminal C<else>. | |
982 | ||
983 | If B<n=2> is used, then each C<elsif> is also given the text of the opening | |
984 | C<if> statement. Also, an C<else> will include the text of a preceding | |
985 | C<elsif> statement. Note that this may result some long closing | |
986 | side comments. | |
987 | ||
988 | If B<n=1> is used, the results will be the same as B<n=2> whenever the | |
989 | resulting line length is less than the maximum allowed. | |
990 | ||
991 | =item B<-cscw>, or B<-closing-side-comment-warnings> | |
992 | ||
993 | This parameter is intended to help make the initial transition to the use of | |
994 | closing side comments. | |
995 | It causes two | |
996 | things to happen if a closing side comment replaces an existing, different | |
997 | closing side comment: first, an error message will be issued, and second, the | |
998 | original side comment will be placed alone on a new specially marked comment | |
999 | line for later attention. | |
1000 | ||
1001 | The intent is to avoid clobbering existing hand-written side comments | |
1002 | which happen to match the pattern of closing side comments. This flag | |
1003 | should only be needed on the first run with B<-csc>. | |
1004 | ||
1005 | =back | |
1006 | ||
1007 | B<Important Notes on Closing Side Comments:> | |
1008 | ||
1009 | =over 4 | |
1010 | ||
1011 | =item * | |
1012 | ||
1013 | Closing side comments are only placed on lines terminated with a closing | |
1014 | brace. Certain closing styles, such as the use of cuddled elses | |
1015 | (B<-ce>), preclude the generation of some closing side comments. | |
1016 | ||
1017 | =item * | |
1018 | ||
1019 | Please note that adding or deleting of closing side comments takes | |
1020 | place only through the commands B<-csc> or B<-dcsc>. The other commands, | |
1021 | if used, merely modify the behavior of these two commands. | |
1022 | ||
1023 | =item * | |
1024 | ||
1025 | It is recommended that the B<-cscw> flag be used along with B<-csc> on | |
1026 | the first use of perltidy on a given file. This will prevent loss of | |
1027 | any existing side comment data which happens to have the csc prefix. | |
1028 | ||
1029 | =item * | |
1030 | ||
1031 | Once you use B<-csc>, you should continue to use it so that any | |
1032 | closing side comments remain correct as code changes. Otherwise, these | |
1033 | comments will become incorrect as the code is updated. | |
1034 | ||
1035 | =item * | |
1036 | ||
1037 | If you edit the closing side comments generated by perltidy, you must also | |
1038 | change the prefix to be different from the closing side comment prefix. | |
1039 | Otherwise, your edits will be lost when you rerun perltidy with B<-csc>. For | |
1040 | example, you could simply change C<## end> to be C<## End>, since the test is | |
1041 | case sensitive. You may also want to use the B<-ssc> flag to keep these | |
1042 | modified closing side comments spaced the same as actual closing side comments. | |
1043 | ||
1044 | =item * | |
1045 | ||
1046 | Temporarily generating closing side comments is a useful technique for | |
1047 | exploring and/or debugging a perl script, especially one written by someone | |
1048 | else. You can always remove them with B<-dcsc>. | |
1049 | ||
1050 | =back | |
1051 | ||
1052 | =item Static Block Comments | |
1053 | ||
1054 | Static block comments are block comments with a special leading pattern, | |
1055 | C<##> by default, which will be treated slightly differently from other | |
1056 | block comments. They effectively behave as if they had glue along their | |
1057 | left and top edges, because they stick to the left edge and previous line | |
1058 | when there is no blank spaces in those places. This option is | |
1059 | particularly useful for controlling how commented code is displayed. | |
1060 | ||
1061 | =over 4 | |
1062 | ||
1063 | =item B<-sbc>, B<--static-block-comments> | |
1064 | ||
1065 | When B<-sbc> is used, a block comment with a special leading pattern, C<##> by | |
1066 | default, will be treated specially. | |
1067 | ||
1068 | Comments so identified are treated as follows: | |
1069 | ||
1070 | =over 4 | |
1071 | ||
1072 | =item * | |
1073 | ||
1074 | If there is no leading space on the line, then the comment will not | |
1075 | be indented, and otherwise it may be, | |
1076 | ||
1077 | =item * | |
1078 | ||
1079 | no new blank line will be | |
1080 | inserted before such a comment, and | |
1081 | ||
1082 | =item * | |
1083 | ||
1084 | such a comment will never become | |
1085 | a hanging side comment. | |
1086 | ||
1087 | =back | |
1088 | ||
1089 | For example, assuming C<@month_of_year> is | |
1090 | left-adjusted: | |
1091 | ||
1092 | @month_of_year = ( # -sbc (default) | |
1093 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', | |
1094 | ## 'Dec', 'Nov' | |
1095 | 'Nov', 'Dec'); | |
1096 | ||
1097 | Without this convention, the above code would become | |
1098 | ||
1099 | @month_of_year = ( # -nsbc | |
1100 | 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', | |
1101 | ||
1102 | ## 'Dec', 'Nov' | |
1103 | 'Nov', 'Dec' | |
1104 | ); | |
1105 | ||
1106 | which is not as clear. | |
1107 | The default is to use B<-sbc>. This may be deactivated with B<-nsbc>. | |
1108 | ||
1109 | =item B<-sbcp=string>, B<--static-block-comment-prefix=string> | |
1110 | ||
1111 | This parameter defines the prefix used to identify static block comments | |
1112 | when the B<-sbc> parameter is set. The default prefix is C<##>, | |
1113 | corresponding to C<-sbcp=##>. The first character must be a C<#> | |
1114 | symbol, since this must only match comments. As a simple example, to | |
1115 | identify all comments as static block comments, one would use C<-sbcp=#>. | |
1116 | ||
1117 | Please note that B<-sbcp> merely defines the pattern used to identify static | |
1118 | block comments; it will not be used unless the switch B<-sbc> is set. Also, | |
1119 | please be aware that this string is used in a perl regular expression which | |
1120 | identifies these comments, so it must enable a valid regular expression to be | |
1121 | formed. | |
1122 | ||
1123 | =item B<-osbc>, B<--outdent-static-block-comments> | |
1124 | ||
1125 | The command B<-osbc> will will cause static block comments to be outdented by 2 | |
1126 | spaces (or whatever B<-ci=n> has been set to), if possible. | |
1127 | ||
1128 | =back | |
1129 | ||
1130 | =item Static Side Comments | |
1131 | ||
1132 | Static side comments are side comments with a special leading pattern. | |
1133 | This option can be useful for controlling how commented code is displayed | |
1134 | when it is a side comment. | |
1135 | ||
1136 | =over 4 | |
1137 | ||
1138 | =item B<-ssc>, B<--static-side-comments> | |
1139 | ||
1140 | When B<-ssc> is used, a side comment with a static leading pattern, which is | |
1141 | C<##> by default, will be be spaced only a single space from previous | |
1142 | character, and it will not be vertically aligned with other side comments. | |
1143 | ||
1144 | The default is B<-nssc>. | |
1145 | ||
1146 | =item B<-sscp=string>, B<--static-side-comment-prefix=string> | |
1147 | ||
1148 | This parameter defines the prefix used to identify static side comments | |
1149 | when the B<-ssc> parameter is set. The default prefix is C<##>, | |
1150 | corresponding to C<-sscp=##>. | |
1151 | ||
1152 | Please note that B<-sscp> merely defines the pattern used to identify | |
1153 | static side comments; it will not be used unless the switch B<-ssc> is | |
1154 | set. Also, note that this string is used in a perl regular expression | |
1155 | which identifies these comments, so it must enable a valid regular | |
1156 | expression to be formed. | |
1157 | ||
1158 | =back | |
1159 | ||
1160 | ||
1161 | =back | |
1162 | ||
1163 | =head2 Line Break Control | |
1164 | ||
1165 | =over 4 | |
1166 | ||
1167 | =item B<-fnl>, B<--freeze-newlines> | |
1168 | ||
1169 | If you do not want any changes to the line breaks in your script, set | |
1170 | B<-fnl>, and they will remain fixed, and the rest of the commands in | |
1171 | this section and sections | |
1172 | L<Controlling List Formatting>, | |
1173 | L<Retaining or Ignoring Existing Line Breaks>, and | |
1174 | L<Blank Line Control> will be ignored. You may want to use B<-noll> | |
1175 | with this. | |
1176 | ||
1177 | =item B<-ce>, B<--cuddled-else> | |
1178 | ||
1179 | Enable the "cuddled else" style, in which C<else> and C<elsif> are | |
1180 | follow immediately after the curly brace closing the previous block. | |
1181 | The default is not to use cuddled elses, and is indicated with the flag | |
1182 | B<-nce> or B<--nocuddled-else>. Here is a comparison of the | |
1183 | alternatives: | |
1184 | ||
1185 | if ($task) { | |
1186 | yyy(); | |
1187 | } else { # -ce | |
1188 | zzz(); | |
1189 | } | |
1190 | ||
1191 | if ($task) { | |
1192 | yyy(); | |
1193 | } | |
1194 | else { # -nce (default) | |
1195 | zzz(); | |
1196 | } | |
1197 | ||
1198 | =item B<-bl>, B<--opening-brace-on-new-line> | |
1199 | ||
1200 | Use the flag B<-bl> to place the opening brace on a new line: | |
1201 | ||
1202 | if ( $input_file eq '-' ) # -bl | |
1203 | { | |
1204 | important_function(); | |
1205 | } | |
1206 | ||
1207 | This flag applies to all structural blocks, including sub's (unless | |
1208 | the B<-sbl> flag is set -- see next item). | |
1209 | ||
1210 | The default style, B<-nbl>, places an opening brace on the same line as | |
1211 | the keyword introducing it. For example, | |
1212 | ||
1213 | if ( $input_file eq '-' ) { # -nbl (default) | |
1214 | ||
1215 | =item B<-sbl>, B<--opening-sub-brace-on-new-line> | |
1216 | ||
1217 | The flag B<-sbl> can be used to override the value of B<-bl> for | |
1218 | opening sub braces. For example, | |
1219 | ||
1220 | perltidy -sbl | |
1221 | ||
1222 | produces this result: | |
1223 | ||
1224 | sub message | |
1225 | { | |
1226 | if (!defined($_[0])) { | |
1227 | print("Hello, World\n"); | |
1228 | } | |
1229 | else { | |
1230 | print($_[0], "\n"); | |
1231 | } | |
1232 | } | |
1233 | ||
1234 | This flag is negated with B<-nsbl>. If B<-sbl> is not specified, | |
1235 | the value of B<-bl> is used. | |
1236 | ||
1237 | =item B<-bli>, B<--brace-left-and-indent> | |
1238 | ||
1239 | The flag B<-bli> is the same as B<-bl> but in addition it causes one | |
1240 | unit of continuation indentation ( see B<-ci> ) to be placed before | |
1241 | an opening and closing block braces. | |
1242 | ||
1243 | For example, | |
1244 | ||
1245 | if ( $input_file eq '-' ) # -bli | |
1246 | { | |
1247 | important_function(); | |
1248 | } | |
1249 | ||
1250 | By default, this extra indentation occurs for blocks of type: | |
1251 | B<if>, B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>, | |
1252 | B<while>, B<until>, and also with a preceding label. The next item | |
1253 | shows how to change this. | |
1254 | ||
1255 | =item B<-blil=s>, B<--brace-left-and-indent-list=s> | |
1256 | ||
1257 | Use this parameter to change the types of block braces for which the | |
1258 | B<-bli> flag applies; see L<Specifying Block Types>. For example, | |
1259 | B<-blil='if elsif else'> would apply it to only C<if/elsif/else> blocks. | |
1260 | ||
1261 | =item B<-bar>, B<--opening-brace-always-on-right> | |
1262 | ||
1263 | The default style, B<-nbl> places the opening brace on a new | |
1264 | line if it does not fit on the same line as the opening keyword, like | |
1265 | this: | |
1266 | ||
1267 | if ( $bigwasteofspace1 && $bigwasteofspace2 | |
1268 | || $bigwasteofspace3 && $bigwasteofspace4 ) | |
1269 | { | |
1270 | big_waste_of_time(); | |
1271 | } | |
1272 | ||
1273 | To force the opening brace to always be on the right, use the B<-bar> | |
1274 | flag. In this case, the above example becomes | |
1275 | ||
1276 | if ( $bigwasteofspace1 && $bigwasteofspace2 | |
1277 | || $bigwasteofspace3 && $bigwasteofspace4 ) { | |
1278 | big_waste_of_time(); | |
1279 | } | |
1280 | ||
1281 | A conflict occurs if both B<-bl> and B<-bar> are specified. | |
1282 | ||
1283 | =item Vertical tightness of non-block curly braces, parentheses, and square brackets. | |
1284 | ||
1285 | These parameters control what shall be called vertical tightness. Here are the | |
1286 | main points: | |
1287 | ||
1288 | =over 4 | |
1289 | ||
1290 | =item * | |
1291 | ||
1292 | Opening tokens (except for block braces) are controlled by B<-vt=n>, or | |
1293 | B<--vertical-tightness=n>, where | |
1294 | ||
1295 | -vt=0 always break a line after opening token (default). | |
1296 | -vt=1 do not break unless this would produce more than one | |
1297 | step in indentation in a line. | |
1298 | -vt=2 never break a line after opening token | |
1299 | ||
1300 | =item * | |
1301 | ||
1302 | You must also use the B<-lp> flag when you use the B<-vt> flag; the | |
1303 | reason is explained below. | |
1304 | ||
1305 | =item * | |
1306 | ||
1307 | Closing tokens (except for block braces) are controlled by B<-vtc=n>, or | |
1308 | B<--vertical-tightness-closing=n>, where | |
1309 | ||
1310 | -vtc=0 always break a line before a closing token (default), | |
1311 | -vtc=1 do not break before a closing token which is followed | |
1312 | by a semicolon or another closing token, and is not in | |
1313 | a list environment. | |
1314 | -vtc=2 never break before a closing token. | |
1315 | ||
1316 | The rules for B<-vtc=1> are designed to maintain a reasonable balance | |
1317 | between tightness and readability in complex lists. | |
1318 | ||
1319 | =item * | |
1320 | ||
1321 | Different controls may be applied to to different token types, | |
1322 | and it is also possible to control block braces; see below. | |
1323 | ||
1324 | =item * | |
1325 | ||
1326 | Finally, please note that these vertical tightness flags are merely | |
1327 | hints to the formatter, and it cannot always follow them. Things which | |
1328 | make it difficult or impossible include comments, blank lines, blocks of | |
1329 | code within a list, and possibly the lack of the B<-lp> parameter. | |
1330 | Also, these flags may be ignored for very small lists (2 or 3 lines in | |
1331 | length). | |
1332 | ||
1333 | =back | |
1334 | ||
1335 | Here are some examples: | |
1336 | ||
1337 | # perltidy -lp -vt=0 -vtc=0 | |
1338 | %romanNumerals = ( | |
1339 | one => 'I', | |
1340 | two => 'II', | |
1341 | three => 'III', | |
1342 | four => 'IV', | |
1343 | ); | |
1344 | ||
1345 | # perltidy -lp -vt=1 -vtc=0 | |
1346 | %romanNumerals = ( one => 'I', | |
1347 | two => 'II', | |
1348 | three => 'III', | |
1349 | four => 'IV', | |
1350 | ); | |
1351 | ||
1352 | # perltidy -lp -vt=1 -vtc=1 | |
1353 | %romanNumerals = ( one => 'I', | |
1354 | two => 'II', | |
1355 | three => 'III', | |
1356 | four => 'IV', ); | |
1357 | ||
1358 | The difference between B<-vt=1> and B<-vt=2> is shown here: | |
1359 | ||
1360 | # perltidy -lp -vt=1 | |
1361 | $init->add( | |
1362 | mysprintf( "(void)find_threadsv(%s);", | |
1363 | cstring( $threadsv_names[ $op->targ ] ) | |
1364 | ) | |
1365 | ); | |
1366 | ||
1367 | # perltidy -lp -vt=2 | |
1368 | $init->add( mysprintf( "(void)find_threadsv(%s);", | |
1369 | cstring( $threadsv_names[ $op->targ ] ) | |
1370 | ) | |
1371 | ); | |
1372 | ||
1373 | With B<-vt=1>, the line ending in C<add(> does not combine with the next | |
1374 | line because the next line is not balanced. This can help with | |
1375 | readability, but B<-vt=2> can be used to ignore this rule. | |
1376 | ||
1377 | The tightest, and least readable, code is produced with both C<-vt=2> and | |
1378 | C<-vtc=2>: | |
1379 | ||
1380 | # perltidy -lp -vt=2 -vtc=2 | |
1381 | $init->add( mysprintf( "(void)find_threadsv(%s);", | |
1382 | cstring( $threadsv_names[ $op->targ ] ) ) ); | |
1383 | ||
1384 | Notice how the code in all of these examples collapses vertically as | |
1385 | B<-vt> increases, but the indentation remains unchanged. This is | |
1386 | because perltidy implements the B<-vt> parameter by first formatting as | |
1387 | if B<-vt=0>, and then simply overwriting one output line on top of the | |
1388 | next, if possible, to achieve the desired vertical tightness. The | |
1389 | B<-lp> indentation style has been designed to allow this vertical | |
1390 | collapse to occur, which is why it is required for the B<-vt> parameter. | |
1391 | ||
1392 | The B<-vt=n> and B<-vtc=n> parameters apply to each type of container | |
1393 | token. If desired, vertical tightness controls can be applied | |
1394 | independently to each of the closing container token types. | |
1395 | ||
1396 | The parameters for controlling parentheses are B<-pvt=n> or | |
1397 | B<--paren-vertical-tightness=n>, and B<-pcvt=n> or | |
1398 | B<--paren-vertical-tightness-closing=n>. | |
1399 | ||
1400 | Likewise, the parameters for square brackets are B<-sbvt=n> or | |
1401 | B<--square-bracket-vertical-tightness=n>, and B<-sbcvt=n> or | |
1402 | B<--square-bracket-vertical-tightness-closing=n>. | |
1403 | ||
1404 | Finally, the parameters for controlling non-code block braces are | |
1405 | B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bcvt=n> or | |
1406 | B<--brace-vertical-tightness-closing=n>. | |
1407 | ||
1408 | In fact, the parameter B<-vt=n> is actually just an abbreviation for | |
1409 | B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation | |
1410 | for B<-pvtc=n -bvtc=n sbvtc=n>. | |
1411 | ||
1412 | =item B<-bbvt=n> or B<--block-brace-vertical-tightness=n> | |
1413 | ||
1414 | The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies | |
1415 | to opening code block braces. | |
1416 | ||
1417 | -bbvt=0 break after opening block brace (default). | |
1418 | -bbvt=1 do not break unless this would produce more than one | |
1419 | step in indentation in a line. | |
1420 | -bbvt=2 do not break after opening block brace. | |
1421 | ||
1422 | It is necessary to also use either B<-bl> or B<-bli> for this to work, | |
1423 | because, as with other vertical tightness controls, it is implemented by | |
1424 | simply overwriting a line ending with an opening block brace with the | |
1425 | subsequent line. For example: | |
1426 | ||
1427 | # perltidy -bli -bbvt=0 | |
1428 | if ( open( FILE, "< $File" ) ) | |
1429 | { | |
1430 | while ( $File = <FILE> ) | |
1431 | { | |
1432 | $In .= $File; | |
1433 | $count++; | |
1434 | } | |
1435 | close(FILE); | |
1436 | } | |
1437 | ||
1438 | # perltidy -bli -bbvt=1 | |
1439 | if ( open( FILE, "< $File" ) ) | |
1440 | { while ( $File = <FILE> ) | |
1441 | { $In .= $File; | |
1442 | $count++; | |
1443 | } | |
1444 | close(FILE); | |
1445 | } | |
1446 | ||
1447 | By default this applies to blocks associated with keywords B<if>, | |
1448 | B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>, B<while>, | |
1449 | B<until>, and also with a preceding label. This can be changed with | |
1450 | the parameter B<-bbvtl=string>, or | |
1451 | B<--block-brace-vertical-tightness-list=string>, where B<string> is a | |
1452 | space-separated list of block types. For more information on the | |
1453 | possible values of this string, see L<Specifying Block Types> | |
1454 | ||
1455 | For example, if we want to just apply this style to C<if>, | |
1456 | C<elsif>, and C<else> blocks, we could use | |
1457 | C<perltidy -bli -bbvt -bbvtl='if elsif else'>. | |
1458 | ||
1459 | There is no vertical tightness control for closing block braces; with | |
1460 | the exception of one-line blocks, they will normally remain on a | |
1461 | separate line. | |
1462 | ||
1463 | =item B<-dnl>, B<--delete-old-newlines> | |
1464 | ||
1465 | By default, perltidy first deletes all old line break locations, and then it | |
1466 | looks for good break points to match the desired line length. Use B<-ndnl> | |
1467 | or B<--nodelete-old-newlines> to force perltidy to retain all old line break | |
1468 | points. | |
1469 | ||
1470 | =item B<-anl>, B<--add-newlines> | |
1471 | ||
1472 | By default, perltidy will add line breaks when necessary to create | |
1473 | continuations of long lines and to improve the script appearance. Use | |
1474 | B<-nanl> or B<-noadd-newlines> to prevent any new line breaks. | |
1475 | ||
1476 | This flag does not prevent perltidy from eliminating existing line | |
1477 | breaks; see B<-freeze-newlines> to completely prevent changes to line | |
1478 | break points. | |
1479 | ||
1480 | =item Controlling whether perltidy breaks before or after operators | |
1481 | ||
1482 | Two command line parameters provide some control over whether | |
1483 | a line break should be before or after specific token types. | |
1484 | ||
1485 | B<-wba=s> or B<--want-break-after=s>, and | |
1486 | ||
1487 | B<-wbb=s> or B<--want-break-before=s>. | |
1488 | ||
1489 | These parameters are each followed by a quoted string, B<s>, containing | |
1490 | a list of token types (separated only by spaces). No more than one of each | |
1491 | of these parameters should be specified, because repeating a | |
1492 | command-line parameter always overwrites the previous one before | |
1493 | perltidy ever sees it. | |
1494 | ||
1495 | By default, perltidy breaks B<after> these token types: | |
1496 | % + - * / x != == >= <= =~ !~ < > | & >= < | |
1497 | = **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x= | |
1498 | ||
1499 | And perltidy breaks B<before> these token types by default: | |
1500 | . << >> -> && || | |
1501 | ||
1502 | To illustrate, to cause a break after a concatenation operator, C<'.'>, | |
1503 | rather than before it, the command line would be | |
1504 | ||
1505 | -wba="." | |
1506 | ||
1507 | As another example, the following command would cause a break before | |
1508 | math operators C<'+'>, C<'-'>, C<'/'>, and C<'*'>: | |
1509 | ||
1510 | -wbb="+ - / *" | |
1511 | ||
1512 | These commands should work well for most of the token types that | |
1513 | perltidy uses (use B<--dump-token-types> for a list). However, for a | |
1514 | few token types there may be conflicts with hardwired logic which cause | |
1515 | unexpected results. One example is curly braces, which should be | |
1516 | controlled with the parameter B<bl> provided for that purpose. | |
1517 | ||
1518 | =back | |
1519 | ||
1520 | =head2 Controlling List Formatting | |
1521 | ||
1522 | Perltidy attempts to place comma-separated arrays of values in tables | |
1523 | which look good. Its default algorithms usually work well, and they | |
1524 | have been improving with each release, but several parameters are | |
1525 | available to control list formatting. | |
1526 | ||
1527 | =over 4 | |
1528 | ||
1529 | =item B<-boc>, B<--break-at-old-comma-breakpoints> | |
1530 | ||
1531 | This flag tells perltidy to try to break at all old commas. This is not | |
1532 | the default. Normally, perltidy makes a best guess at list formatting, | |
1533 | and seldom uses old comma breakpoints. Usually this works well, | |
1534 | but consider: | |
1535 | ||
1536 | my @list = (1, | |
1537 | 1, 1, | |
1538 | 1, 2, 1, | |
1539 | 1, 3, 3, 1, | |
1540 | 1, 4, 6, 4, 1,); | |
1541 | ||
1542 | The default formatting will flatten this down to one line: | |
1543 | ||
1544 | # perltidy (default) | |
1545 | my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, ); | |
1546 | ||
1547 | which hides the structure. Using B<-boc>, plus additional flags | |
1548 | to retain the original style, yields | |
1549 | ||
1550 | # perltidy -boc -lp -pt=2 -vt=1 -vtc=1 | |
1551 | my @list = (1, | |
1552 | 1, 1, | |
1553 | 1, 2, 1, | |
1554 | 1, 3, 3, 1, | |
1555 | 1, 4, 6, 4, 1,); | |
1556 | ||
1557 | A disadvantage of this flag is that all tables in the file | |
1558 | must already be nicely formatted. | |
1559 | ||
1560 | =item B<-mft=n>, B<--maximum-fields-per-table=n> | |
1561 | ||
1562 | If the computed number of fields for any table exceeds B<n>, then it | |
1563 | will be reduced to B<n>. The default value for B<n> is a large number, | |
1564 | 40. While this value should probably be left unchanged as a general | |
1565 | rule, it might be used on a small section of code to force a list to | |
1566 | have a particular number of fields per line, and then either the B<-boc> | |
1567 | flag could be used to retain this formatting, or a single comment could | |
1568 | be introduced somewhere to freeze the formatting in future applications | |
1569 | of perltidy. | |
1570 | ||
1571 | # perltidy -mft=2 | |
1572 | @month_of_year = ( | |
1573 | 'Jan', 'Feb', | |
1574 | 'Mar', 'Apr', | |
1575 | 'May', 'Jun', | |
1576 | 'Jul', 'Aug', | |
1577 | 'Sep', 'Oct', | |
1578 | 'Nov', 'Dec' | |
1579 | ); | |
1580 | ||
1581 | =item B<-cab=n>, B<--comma-arrow-breakpoints=n> | |
1582 | ||
1583 | A comma which follows a comma arrow, '=>', requires special | |
1584 | consideration. In a long list, it is common to break at all such | |
1585 | commas. This parameter can be used to control how perltidy breaks at | |
1586 | these commas. (However, it will have no effect if old comma breaks are | |
1587 | being forced because B<-boc> is used). The possible values of B<n> are: | |
1588 | ||
1589 | n=0 break at all commas after => | |
1590 | n=1 stable: break at all commas after => unless this would break | |
1591 | an existing one-line container (default) | |
1592 | n=2 break at all commas after =>, but try to form the maximum | |
1593 | maximum one-line container lengths | |
1594 | n=3 do not treat commas after => specially at all | |
1595 | ||
1596 | For example, given the following single line, perltidy by default will | |
1597 | not add any line breaks because it would break the existing one-line | |
1598 | container: | |
1599 | ||
1600 | bless { B => $B, Root => $Root } => $package; | |
1601 | ||
1602 | Using B<-cab=0> will force a break after each comma-arrow item: | |
1603 | ||
1604 | # perltidy -cab=0: | |
1605 | bless { | |
1606 | B => $B, | |
1607 | Root => $Root | |
1608 | } => $package; | |
1609 | ||
1610 | If perltidy is subsequently run with this container broken, then by | |
1611 | default it will break after each '=>' because the container is now | |
1612 | broken. To reform a one-line container, the parameter B<-cab=2> would | |
1613 | be needed. | |
1614 | ||
1615 | The flag B<-cab=3> can be used to prevent these commas from being | |
1616 | treated specially. In this case, an item such as "01" => 31 is | |
1617 | treated as a single item in a table. The number of fields in this table | |
1618 | will be determined by the same rules that are used for any other table. | |
1619 | Here is an example. | |
1620 | ||
1621 | # perltidy -cab=3 | |
1622 | my %last_day = ( | |
1623 | "01" => 31, "02" => 29, "03" => 31, "04" => 30, | |
1624 | "05" => 31, "06" => 30, "07" => 31, "08" => 31, | |
1625 | "09" => 30, "10" => 31, "11" => 30, "12" => 31 | |
1626 | ); | |
1627 | ||
1628 | =back | |
1629 | ||
1630 | =head2 Retaining or Ignoring Existing Line Breaks | |
1631 | ||
1632 | Several additional parameters are available for controlling the extent | |
1633 | to which line breaks in the input script influence the output script. | |
1634 | In most cases, the default parameter values are set so that, if a choice | |
1635 | is possible, the output style follows the input style. For example, if | |
1636 | a short logical container is broken in the input script, then the | |
1637 | default behavior is for it to remain broken in the output script. | |
1638 | ||
1639 | Most of the parameters in this section would only be required for a | |
1640 | one-time conversion of a script from short container lengths to longer | |
1641 | container lengths. The opposite effect, of converting long container | |
1642 | lengths to shorter lengths, can be obtained by temporarily using a short | |
1643 | maximum line length. | |
1644 | ||
1645 | =over 4 | |
1646 | ||
1647 | =item B<-bol>, B<--break-at-old-logical-breakpoints> | |
1648 | ||
1649 | By default, if a logical expression is broken at a C<&&>, C<||>, C<and>, | |
1650 | or C<or>, then the container will remain broken. Also, breaks | |
1651 | at internal keywords C<if> and C<unless> will normally be retained. | |
1652 | To prevent this, and thus form longer lines, use B<-nbol>. | |
1653 | ||
1654 | =item B<-bok>, B<--break-at-old-keyword-breakpoints> | |
1655 | ||
1656 | By default, perltidy will retain a breakpoint before keywords which may | |
1657 | return lists, such as C<sort> and <map>. This allows chains of these | |
1658 | operators to be displayed one per line. Use B<-nbok> to prevent | |
1659 | retaining these breakpoints. | |
1660 | ||
1661 | =item B<-bot>, B<--break-at-old-trinary-breakpoints> | |
1662 | ||
1663 | By default, if a conditional (trinary) operator is broken at a C<:>, | |
1664 | then it will remain broken. To prevent this, and thereby | |
1665 | form longer lines, use B<-nbot>. | |
1666 | ||
1667 | =item B<-iob>, B<--ignore-old-breakpoints> | |
1668 | ||
1669 | Use this flag to tell perltidy to ignore existing line breaks to the | |
1670 | maximum extent possible. This will tend to produce the longest possible | |
1671 | containers, regardless of type, which do not exceed the line length | |
1672 | limit. | |
1673 | ||
1674 | =back | |
1675 | ||
1676 | =head2 Blank Line Control | |
1677 | ||
1678 | Blank lines can improve the readability of a script if they are carefully | |
1679 | placed. Perltidy has several commands for controlling the insertion, | |
1680 | retention, and removal of blank lines. | |
1681 | ||
1682 | =over 4 | |
1683 | ||
1684 | =item B<-bbc>, B<--blanks-before-comments> | |
1685 | ||
1686 | A blank line will be introduced before a full-line comment. This is the | |
1687 | default. Use B<-nbbc> or B<--noblanks-before-comments> to prevent | |
1688 | such blank lines from being introduced. | |
1689 | ||
1690 | =item B<-bbs>, B<--blanks-before-subs> | |
1691 | ||
1692 | A blank line will be introduced before a B<sub> definition, unless it is a | |
1693 | one-liner or preceded by a comment. A blank line will also be introduced | |
1694 | before a B<package> statement and a B<BEGIN> and B<END> block. This is the | |
1695 | default. The intention is to help display the structure of a program by | |
1696 | setting off certain key sections of code. This is negated with B<-nbbs> or | |
1697 | B<--noblanks-before-subs>. | |
1698 | ||
1699 | =item B<-bbb>, B<--blanks-before-blocks> | |
1700 | ||
1701 | A blank line will be introduced before blocks of coding delimited by | |
1702 | B<for>, B<foreach>, B<while>, B<until>, and B<if>, B<unless>, in the following | |
1703 | circumstances: | |
1704 | ||
1705 | =over 4 | |
1706 | ||
1707 | =item * | |
1708 | ||
1709 | The block is not preceded by a comment. | |
1710 | ||
1711 | =item * | |
1712 | ||
1713 | The block is not a one-line block. | |
1714 | ||
1715 | =item * | |
1716 | ||
1717 | The number of consecutive non-blank lines at the current indentation depth is at least B<-lbl> | |
1718 | (see next section). | |
1719 | ||
1720 | =back | |
1721 | ||
1722 | This is the default. The intention of this option is to introduce | |
1723 | some space within dense coding. | |
1724 | This is negated with B<-nbbb> or B<--noblanks-before-blocks>. | |
1725 | ||
1726 | =item B<-lbl=n> B<--long-block-line-count=n> | |
1727 | ||
1728 | This controls how often perltidy is allowed to add blank lines before | |
1729 | certain block types (see previous section). The default is 8. Entering | |
1730 | a value of B<0> is equivalent to entering a very large number. | |
1731 | ||
1732 | =item B<-mbl=n> B<--maximum-consecutive-blank-lines=n> | |
1733 | ||
1734 | This parameter specifies the maximum number of consecutive blank lines | |
1735 | in the output script. The default is n=1. If the input file has more | |
1736 | than n consecutive blank lines, the number will be reduced to n. | |
1737 | (This obviously does not apply to pod sections, here-documents, and quotes). | |
1738 | ||
1739 | =item B<-sob>, B<--swallow-optional-blank-lines> | |
1740 | ||
1741 | All blank lines not required by the above flags, B<-bbb>, B<-bbs>, and B<-bbc>, | |
1742 | will be deleted. (But essential blank lines above pod documents will be | |
1743 | retained). This is NOT the default. | |
1744 | ||
1745 | =item B<-nsob>, B<--noswallow-optional-blank-lines> | |
1746 | ||
1747 | Retain blank lines, including those which do not corresponding to flags | |
1748 | B<-bbb>, B<-bbs>, and B<-bbc>. This is the default. The number of | |
1749 | blanks retained is subject to the limit imposed by | |
1750 | B<--maximum-consecutive-blank-lines>, however. | |
1751 | ||
1752 | =back | |
1753 | ||
1754 | =head2 Styles | |
1755 | ||
1756 | A style refers to a convenient collection of existing parameters. | |
1757 | ||
1758 | =over 4 | |
1759 | ||
1760 | =item B<-gnu>, B<--gnu-style> | |
1761 | ||
1762 | B<-gnu> gives an approximation to the GNU Coding Standards (which do | |
1763 | not apply to perl) as they are sometimes implemented. At present, this | |
1764 | style overrides the default style with the following parameters: | |
1765 | ||
1766 | -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp | |
1767 | ||
1768 | =back | |
1769 | ||
1770 | =head2 Other Controls | |
1771 | ||
1772 | =over 4 | |
1773 | ||
1774 | =item Deleting selected text | |
1775 | ||
1776 | Perltidy can selectively delete comments and/or pod documentation. The | |
1777 | command B<-dac> or B<--delete-all-comments> will delete all comments | |
1778 | B<and> all pod documentation, leaving just code and any leading system | |
1779 | control lines. | |
1780 | ||
1781 | The command B<-dp> or B<--delete-pod> will remove all pod documentation | |
1782 | (but not comments). | |
1783 | ||
1784 | Two commands which remove comments (but not pod) are: B<-dbc> or | |
1785 | B<--delete-block-comments> and B<-dsc> or B<--delete-side-comments>. | |
1786 | (Hanging side comments will be deleted with block comments here.) | |
1787 | ||
1788 | The negatives of these commands also work, and are the defaults. When | |
1789 | block comments are deleted, any leading 'hash-bang' will be retained. | |
1790 | Also, if the B<-x> flag is used, any system commands before a leading | |
1791 | hash-bang will be retained (even if they are in the form of comments). | |
1792 | ||
1793 | =item Writing selected text to a file | |
1794 | ||
1795 | When perltidy writes a formatted text file, it has the ability to also | |
1796 | send selected text to a file with a F<.TEE> extension. This text can | |
1797 | include comments and pod documentation. | |
1798 | ||
1799 | The command B<-tac> or B<--tee-all-comments> will write all comments | |
1800 | B<and> all pod documentation. | |
1801 | ||
1802 | The command B<-tp> or B<--tee-pod> will write all pod documentation (but | |
1803 | not comments). | |
1804 | ||
1805 | The commands which write comments (but not pod) are: B<-tbc> or | |
1806 | B<--tee-block-comments> and B<-tsc> or B<--tee-side-comments>. | |
1807 | (Hanging side comments will be written with block comments here.) | |
1808 | ||
1809 | The negatives of these commands also work, and are the defaults. | |
1810 | ||
1811 | =item Using a F<.perltidyrc> command file | |
1812 | ||
1813 | If you use perltidy frequently, you probably won't be happy until you | |
1814 | create a F<.perltidyrc> file to avoid typing commonly-used parameters. | |
1815 | Perltidy will first look in your current directory for a command file | |
1816 | named F<.perltidyrc>. If it does not find one, it will continue looking | |
1817 | for one in other standard locations. | |
1818 | ||
1819 | These other locations are system-dependent, and may be displayed with | |
1820 | the command C<perltidy -dpro>. Under Unix systems, it will look for a | |
1821 | F<.perltidyrc> file in the home directory, and then for a system-wide | |
1822 | file F</usr/local/etc/perltidyrc>, and then it will look for | |
1823 | F</etc/perltidyrc>. Note that these last two system-wide files do not | |
1824 | have a leading dot. Further system-dependent information will be found | |
1825 | in the INSTALL file distributed with perltidy. | |
1826 | ||
1827 | This file is free format, and simply a list of parameters, just as they | |
1828 | would be entered on a command line. Any number of lines may be used, | |
1829 | with any number of parameters per line, although it may be easiest to | |
1830 | read with one parameter per line. Blank lines are ignored, and text | |
1831 | after a '#' is ignored to the end of a line. | |
1832 | ||
1833 | Here is an example of a F<.perltidyrc> file: | |
1834 | ||
1835 | # This is a simple of a .perltidyrc configuration file | |
1836 | # This implements a highly spaced style | |
1837 | -se # errors to standard error output | |
1838 | -w # show all warnings | |
1839 | -bl # braces on new lines | |
1840 | -pt=0 # parens not tight at all | |
1841 | -bt=0 # braces not tight | |
1842 | -sbt=0 # square brackets not tight | |
1843 | ||
1844 | The parameters in the F<.perltidyrc> file are installed first, so any | |
1845 | parameters given on the command line will have priority over them. | |
1846 | ||
1847 | To avoid confusion, perltidy ignores any command in the .perltidyrc | |
1848 | file which would cause some kind of dump and an exit. These are: | |
1849 | ||
1850 | -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss | |
1851 | ||
1852 | There are several options may be helpful in debugging a F<.perltidyrc> | |
1853 | file: | |
1854 | ||
1855 | =over 4 | |
1856 | ||
1857 | =item * | |
1858 | ||
1859 | A very helpful command is B<--dump-profile> or B<-dpro>. It writes a | |
1860 | list of all configuration filenames tested to standard output, and | |
1861 | if a file is found, it dumps the content to standard output before | |
1862 | exiting. So, to find out where perltidy looks for its configuration | |
1863 | files, and which one if any it selects, just enter | |
1864 | ||
1865 | perltidy -dpro | |
1866 | ||
1867 | =item * | |
1868 | ||
1869 | It may be simplest to develop and test configuration files with | |
1870 | alternative names, and invoke them with B<-pro=filename> on the command | |
1871 | line. Then rename the desired file to F<.perltidyrc> when finished. | |
1872 | ||
1873 | =item * | |
1874 | ||
1875 | The parameters in the F<.perltidyrc> file can be switched off with | |
1876 | the B<-npro> option. | |
1877 | ||
1878 | =item * | |
1879 | ||
1880 | The commands B<-dump-options>, B<-dump-defaults>, B<-dump-long-names>, | |
1881 | and B<-dump-short-names>, all described below, may all be helpful. | |
1882 | ||
1883 | =back | |
1884 | ||
1885 | =item Creating a new abbreviation | |
1886 | ||
1887 | A special notation is available for use in a F<.perltidyrc> file | |
1888 | for creating an abbreviation for a group | |
1889 | of options. This can be used to create a | |
1890 | shorthand for one or more styles which are frequently, but not always, | |
1891 | used. The notation is to group the options within curly braces which | |
1892 | are preceded by the name of the alias (without leading dashes), like this: | |
1893 | ||
1894 | newword { | |
1895 | -opt1 | |
1896 | -opt2 | |
1897 | } | |
1898 | ||
1899 | where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters | |
1900 | I<or other abbreviations>. The main syntax requirement is that | |
1901 | the new abbreviation must begin on a new line. | |
1902 | Space before and after the curly braces is optional. | |
1903 | For a | |
1904 | specific example, the following line | |
1905 | ||
1906 | airy {-bl -pt=0 -bt=0 -sbt=0} | |
1907 | ||
1908 | could be placed in a F<.perltidyrc> file, and then invoked at will with | |
1909 | ||
1910 | perltidy -airy somefile.pl | |
1911 | ||
1912 | (Either C<-airy> or C<--airy> may be used). | |
1913 | ||
1914 | =item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang> | |
1915 | ||
1916 | If your script has leading lines of system commands or other text which | |
1917 | are not valid perl code, and which are separated from the start of the | |
1918 | perl code by a "hash-bang" line, ( a line of the form C<#!...perl> ), | |
1919 | you must use the B<-x> flag to tell perltidy not to parse and format any | |
1920 | lines before the "hash-bang" line. This option also invokes perl with a | |
1921 | -x flag when checking the syntax. This option was originally added to | |
1922 | allow perltidy to parse interactive VMS scripts, but it should be used | |
1923 | for any script which is normally invoked with C<perl -x>. | |
1924 | ||
1925 | =item Making a file unreadable | |
1926 | ||
1927 | The goal of perltidy is to improve the readability of files, but there | |
1928 | are two commands which have the opposite effect, B<--mangle> and | |
1929 | B<--extrude>. They are actually | |
1930 | merely aliases for combinations of other parameters. Both of these | |
1931 | strip all possible whitespace, but leave comments and pod documents, | |
1932 | so that they are essentially reversible. The | |
1933 | difference between these is that B<--mangle> puts the fewest possible | |
1934 | line breaks in a script while B<--extrude> puts the maximum possible. | |
1935 | Note that these options do not provided any meaningful obfuscation, because | |
1936 | perltidy can be used to reformat the files. They were originally | |
1937 | developed to help test the tokenization logic of perltidy, but they | |
1938 | have other uses. | |
1939 | One use for B<--mangle> is the following: | |
1940 | ||
1941 | perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new | |
1942 | ||
1943 | This will form the maximum possible number of one-line blocks (see next | |
1944 | section), and can sometimes help clean up a badly formatted script. | |
1945 | ||
1946 | A similar technique can be used with B<--extrude> instead of B<--mangle> | |
1947 | to make the minimum number of one-line blocks. | |
1948 | ||
1949 | Another use for B<--mangle> is to combine it with B<-dac> to reduce | |
1950 | the file size of a perl script. | |
1951 | ||
1952 | =item One-line blocks | |
1953 | ||
1954 | There are a few points to note regarding one-line blocks. A one-line | |
1955 | block is something like this, | |
1956 | ||
1957 | if ($x > 0) { $y = 1 / $x } | |
1958 | ||
1959 | where the contents within the curly braces is short enough to fit | |
1960 | on a single line. | |
1961 | ||
1962 | With few exceptions, perltidy retains existing one-line blocks, if it | |
1963 | is possible within the line-length constraint, but it does not attempt | |
1964 | to form new ones. In other words, perltidy will try to follow the | |
1965 | one-line block style of the input file. | |
1966 | ||
1967 | If an existing one-line block is longer than the maximum line length, | |
1968 | however, it will be broken into multiple lines. When this happens, perltidy | |
1969 | checks for and adds any optional terminating semicolon (unless the B<-nasc> | |
1970 | option is used) if the block is a code block. | |
1971 | ||
1972 | The main exception is that perltidy will attempt to form new one-line | |
1973 | blocks following the keywords C<map>, C<eval>, and C<sort>, because | |
1974 | these code blocks are often small and most clearly displayed in a single | |
1975 | line. | |
1976 | ||
1977 | One-line block rules can conflict with the cuddled-else option. When | |
1978 | the cuddled-else option is used, perltidy retains existing one-line | |
1979 | blocks, even if they do not obey cuddled-else formatting. | |
1980 | ||
1981 | Occasionally, when one-line blocks get broken because they exceed the | |
1982 | available line length, the formatting will violate the requested brace style. | |
1983 | If this happens, reformatting the script a second time should correct | |
1984 | the problem. | |
1985 | ||
1986 | =item Debugging | |
1987 | ||
1988 | The following flags are available for debugging: | |
1989 | ||
1990 | B<--dump-defaults> or B<-ddf> will write the default option set to standard output and quit | |
1991 | ||
1992 | B<--dump-profile> or B<-dpro> will write the name of the current | |
1993 | configuration file and its contents to standard output and quit. | |
1994 | ||
1995 | B<--dump-options> or B<-dop> will write current option set to standard | |
1996 | output and quit. | |
1997 | ||
1998 | B<--dump-long-names> or B<-dln> will write all command line long names (passed | |
1999 | to Get_options) to standard output and quit. | |
2000 | ||
2001 | B<--dump-short-names> or B<-dsn> will write all command line short names | |
2002 | to standard output and quit. | |
2003 | ||
2004 | B<--dump-token-types> or B<-dtt> will write a list of all token types | |
2005 | to standard output and quit. | |
2006 | ||
2007 | B<--dump-want-left-space> or B<-dwls> will write the hash %want_left_space | |
2008 | to standard output and quit. See the section on controlling whitespace | |
2009 | around tokens. | |
2010 | ||
2011 | B<--dump-want-right-space> or B<-dwrs> will write the hash %want_right_space | |
2012 | to standard output and quit. See the section on controlling whitespace | |
2013 | around tokens. | |
2014 | ||
2015 | B<-DEBUG> will write a file with extension F<.DEBUG> for each input file | |
2016 | showing the tokenization of all lines of code. | |
2017 | ||
2018 | =item Working with MakeMaker, AutoLoader and SelfLoader | |
2019 | ||
2020 | The first $VERSION line of a file which might be eval'd by MakeMaker | |
2021 | is passed through unchanged except for indentation. | |
2022 | Use B<--nopass-version-line>, or B<-npvl>, to deactivate this feature. | |
2023 | ||
2024 | If the AutoLoader module is used, perltidy will continue formatting | |
2025 | code after seeing an __END__ line. | |
2026 | Use B<--nolook-for-autoloader>, or B<-nlal>, to deactivate this feature. | |
2027 | ||
2028 | Likewise, if the SelfLoader module is used, perltidy will continue formatting | |
2029 | code after seeing a __DATA__ line. | |
2030 | Use B<--nolook-for-selfloader>, or B<-nlsl>, to deactivate this feature. | |
2031 | ||
2032 | =item Working around problems with older version of Perl | |
2033 | ||
2034 | Perltidy contains a number of rules which help avoid known subtleties | |
2035 | and problems with older versions of perl, and these rules always | |
2036 | take priority over whatever formatting flags have been set. For example, | |
2037 | perltidy will usually avoid starting a new line with a bareword, because | |
2038 | this might cause problems if C<use strict> is active. | |
2039 | ||
2040 | There is no way to override these rules. | |
2041 | ||
2042 | =back | |
2043 | ||
2044 | =head1 HTML OPTIONS | |
2045 | ||
2046 | =over 4 | |
2047 | ||
2048 | =item The B<-html> master switch | |
2049 | ||
2050 | The flag B<-html> causes perltidy to write an html file with extension | |
2051 | F<.html>. So, for example, the following command | |
2052 | ||
2053 | perltidy -html somefile.pl | |
2054 | ||
2055 | will produce a syntax-colored html file named F<somefile.pl.html> | |
2056 | which may be viewed with a browser. | |
2057 | ||
2058 | B<Please Note>: In this case, perltidy does not do any formatting to the | |
2059 | input file, and it does not write a formatted file with extension | |
2060 | F<.tdy>. This means that two perltidy runs are required to create a | |
2061 | fully reformatted, html copy of a script. | |
2062 | ||
2063 | =item The B<-pre> flag for code snippets | |
2064 | ||
2065 | When the B<-pre> flag is given, only the pre-formatted section, within | |
2066 | the <PRE> and </PRE> tags, will be output. This simplifies inclusion | |
2067 | of the output in other files. The default is to output a complete | |
2068 | web page. | |
2069 | ||
2070 | =item The B<-nnn> flag for line numbering | |
2071 | ||
2072 | When the B<-nnn> flag is given, the output lines will be numbered. | |
2073 | ||
2074 | =item The B<-toc>, or B<--html-table-of-contents> flag | |
2075 | ||
2076 | By default, a table of contents to packages and subroutines will be | |
2077 | written at the start of html output. Use B<-ntoc> to prevent this. | |
2078 | This might be useful, for example, for a pod document which contains a | |
2079 | number of unrelated code snippets. This flag only influences the code | |
2080 | table of contents; it has no effect on any table of contents produced by | |
2081 | pod2html (see next item). | |
2082 | ||
2083 | =item The B<-pod>, or B<--pod2html> flag | |
2084 | ||
2085 | There are two options for formatting pod documentation. The default is | |
2086 | to pass the pod through the Pod::Html module (which forms the basis of | |
2087 | the pod2html utility). Any code sections are formatted by perltidy, and | |
2088 | the results then merged. Note: perltidy creates a temporary file when | |
2089 | Pod::Html is used; see L<"FILES">. Also, Pod::Html creates temporary | |
2090 | files for its cache. | |
2091 | ||
2092 | NOTE: Perltidy counts the number of C<=cut> lines, and either moves the | |
2093 | pod text to the top of the html file if there is one C<=cut>, or leaves | |
2094 | the pod text in its original order (interleaved with code) otherwise. | |
2095 | ||
2096 | Most of the flags accepted by pod2html may be included in the perltidy | |
2097 | command line, and they will be passed to pod2html. In some cases, | |
2098 | the flags have a prefix C<pod> to emphasize that they are for the | |
2099 | pod2html, and this prefix will be removed before they are passed to | |
2100 | pod2html. The flags which have the additional C<pod> prefix are: | |
2101 | ||
2102 | --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet | |
2103 | --[no]podverbose --podflush | |
2104 | ||
2105 | The flags which are unchanged from their use in pod2html are: | |
2106 | ||
2107 | --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s | |
2108 | --podpath=s --podroot=s | |
2109 | ||
2110 | where 's' is an appropriate character string. Not all of these flags are | |
2111 | available in older versions of Pod::Html. See your Pod::Html documentation for | |
2112 | more information. | |
2113 | ||
2114 | The alternative, indicated with B<-npod>, is not to use Pod::Html, but | |
2115 | rather to format pod text in italics (or whatever the stylesheet | |
2116 | indicates), without special html markup. This is useful, for example, | |
2117 | if pod is being used as an alternative way to write comments. | |
2118 | ||
2119 | =item The B<-frm>, or B<--frames> flag | |
2120 | ||
2121 | By default, a single html output file is produced. This can be changed | |
2122 | with the B<-frm> option, which creates a frame holding a table of | |
2123 | contents in the left panel and the source code in the right side. This | |
2124 | simplifies code browsing. Assume, for example, that the input file is | |
2125 | F<MyModule.pm>. Then, for default file extension choices, these three | |
2126 | files will be created: | |
2127 | ||
2128 | MyModule.pm.html - the frame | |
2129 | MyModule.pm.toc.html - the table of contents | |
2130 | MyModule.pm.src.html - the formatted source code | |
2131 | ||
2132 | Obviously this file naming scheme requires that output be directed to a real | |
2133 | file (as opposed to, say, standard output). If this is not the | |
2134 | case, or if the file extension is unknown, the B<-frm> option will be | |
2135 | ignored. | |
2136 | ||
2137 | =item The B<-text=s>, or B<--html-toc-extension> flag | |
2138 | ||
2139 | Use this flag to specify the extra file extension of the table of contents file | |
2140 | when html frames are used. The default is "toc". | |
2141 | See L<Specifying File Extensions>. | |
2142 | ||
2143 | =item The B<-sext=s>, or B<--html-src-extension> flag | |
2144 | ||
2145 | Use this flag to specify the extra file extension of the content file when html | |
2146 | frames are used. The default is "src". | |
2147 | See L<Specifying File Extensions>. | |
2148 | ||
2149 | =item The B<-hent>, or B<--html-entities> flag | |
2150 | ||
2151 | This flag controls the use of Html::Entities for html formatting. By | |
2152 | default, the module Html::Entities is used to encode special symbols. | |
2153 | This may not be the right thing for some browser/language | |
2154 | combinations. Use --nohtml-entities or -nhent to prevent this. | |
2155 | ||
2156 | =item Style Sheets | |
2157 | ||
2158 | Style sheets make it very convenient to control and adjust the | |
2159 | appearance of html pages. The default behavior is to write a page of | |
2160 | html with an embedded style sheet. | |
2161 | ||
2162 | An alternative to an embedded style sheet is to create a page with a | |
2163 | link to an external style sheet. This is indicated with the | |
2164 | B<-css=filename>, where the external style sheet is F<filename>. The | |
2165 | external style sheet F<filename> will be created if and only if it does | |
2166 | not exist. This option is useful for controlling multiple pages from a | |
2167 | single style sheet. | |
2168 | ||
2169 | To cause perltidy to write a style sheet to standard output and exit, | |
2170 | use the B<-ss>, or B<--stylesheet>, flag. This is useful if the style | |
2171 | sheet could not be written for some reason, such as if the B<-pre> flag | |
2172 | was used. Thus, for example, | |
2173 | ||
2174 | perltidy -html -ss >mystyle.css | |
2175 | ||
2176 | will write a style sheet with the default properties to file | |
2177 | F<mystyle.css>. | |
2178 | ||
2179 | The use of style sheets is encouraged, but a web page without a style | |
2180 | sheets can be created with the flag B<-nss>. Use this option if you | |
2181 | must to be sure that older browsers (roughly speaking, versions prior to | |
2182 | 4.0 of Netscape Navigator and Internet Explorer) can display the | |
2183 | syntax-coloring of the html files. | |
2184 | ||
2185 | =item Controlling HTML properties | |
2186 | ||
2187 | Note: It is usually more convenient to accept the default properties | |
2188 | and then edit the stylesheet which is produced. However, this section | |
2189 | shows how to control the properties with flags to perltidy. | |
2190 | ||
2191 | Syntax colors may be changed from their default values by flags of the either | |
2192 | the long form, B<-html-color-xxxxxx=n>, or more conveniently the short form, | |
2193 | B<-hcx=n>, where B<xxxxxx> is one of the following words, and B<x> is the | |
2194 | corresponding abbreviation: | |
2195 | ||
2196 | Token Type xxxxxx x | |
2197 | ---------- -------- -- | |
2198 | comment comment c | |
2199 | number numeric n | |
2200 | identifier identifier i | |
2201 | bareword, function bareword w | |
2202 | keyword keyword k | |
2203 | quite, pattern quote q | |
2204 | here doc text here-doc-text h | |
2205 | here doc target here-doc-target hh | |
2206 | punctuation punctuation pu | |
2207 | parentheses paren p | |
2208 | structural braces structure s | |
2209 | semicolon semicolon sc | |
2210 | colon colon co | |
2211 | comma comma cm | |
2212 | label label j | |
2213 | sub definition name subroutine m | |
2214 | pod text pod-text pd | |
2215 | ||
2216 | A default set of colors has been defined, but they may be changed by providing | |
2217 | values to any of the following parameters, where B<n> is either a 6 digit | |
2218 | hex RGB color value or an ascii name for a color, such as 'red'. | |
2219 | ||
2220 | To illustrate, the following command will produce an html | |
2221 | file F<somefile.pl.html> with "aqua" keywords: | |
2222 | ||
2223 | perltidy -html -hck=00ffff somefile.pl | |
2224 | ||
2225 | and this should be equivalent for most browsers: | |
2226 | ||
2227 | perltidy -html -hck=aqua somefile.pl | |
2228 | ||
2229 | Perltidy merely writes any non-hex names that it sees in the html file. | |
2230 | The following 16 color names are defined in the HTML 3.2 standard: | |
2231 | ||
2232 | black => 000000, | |
2233 | silver => c0c0c0, | |
2234 | gray => 808080, | |
2235 | white => ffffff, | |
2236 | maroon => 800000, | |
2237 | red => ff0000, | |
2238 | purple => 800080, | |
2239 | fuchsia => ff00ff, | |
2240 | green => 008000, | |
2241 | lime => 00ff00, | |
2242 | olive => 808000, | |
2243 | yellow => ffff00 | |
2244 | navy => 000080, | |
2245 | blue => 0000ff, | |
2246 | teal => 008080, | |
2247 | aqua => 00ffff, | |
2248 | ||
2249 | Many more names are supported in specific browsers, but it is safest | |
2250 | to use the hex codes for other colors. Helpful color tables can be | |
2251 | located with an internet search for "HTML color tables". | |
2252 | ||
2253 | Besides color, two other character attributes may be set: bold, and italics. | |
2254 | To set a token type to use bold, use the flag | |
2255 | B<-html-bold-xxxxxx> or B<-hbx>, where B<xxxxxx> or B<x> are the long | |
2256 | or short names from the above table. Conversely, to set a token type to | |
2257 | NOT use bold, use B<-nohtml-bold-xxxxxx> or B<-nhbx>. | |
2258 | ||
2259 | Likewise, to set a token type to use an italic font, use the flag | |
2260 | B<-html-italic-xxxxxx> or B<-hix>, where again B<xxxxxx> or B<x> are the | |
2261 | long or short names from the above table. And to set a token type to | |
2262 | NOT use italics, use B<-nohtml-italic-xxxxxx> or B<-nhix>. | |
2263 | ||
2264 | For example, to use bold braces and lime color, non-bold, italics keywords the | |
2265 | following command would be used: | |
2266 | ||
2267 | perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl | |
2268 | ||
2269 | The background color can be specified with B<-html-color-background=n>, | |
2270 | or B<-hcbg=n> for short, where n is a 6 character hex RGB value. The | |
2271 | default color of text is the value given to B<punctuation>, which is | |
2272 | black as a default. | |
2273 | ||
2274 | Here are some notes and hints: | |
2275 | ||
2276 | 1. If you find a preferred set of these parameters, you may want | |
2277 | to create a F<.perltidyrc> file containing them. See the perltidy man | |
2278 | page for an explanation. | |
2279 | ||
2280 | 2. Rather than specifying values for these parameters, it is probably | |
2281 | easier to accept the defaults and then edit a style sheet. The style | |
2282 | sheet contains comments which should make this easy. | |
2283 | ||
2284 | 3. The syntax-colored html files can be very large, so it may be best to | |
2285 | split large files into smaller pieces to improve download times. | |
2286 | ||
2287 | =back | |
2288 | ||
2289 | =head1 SOME COMMON INPUT CONVENTIONS | |
2290 | ||
2291 | =head2 Specifying Block Types | |
2292 | ||
2293 | Several parameters which refer to code block types may be customized by also | |
2294 | specifying an associated list of block types. The type of a block is the name | |
2295 | of the keyword which introduces that block, such as B<if>, B<else>, or B<sub>. | |
2296 | An exception is a labeled block, which has no keyword, and should be specified | |
2297 | with just a colon. | |
2298 | ||
2299 | For example, the following parameter specifies C<sub>, labels, C<BEGIN>, and | |
2300 | C<END> blocks: | |
2301 | ||
2302 | -cscl="sub : BEGIN END" | |
2303 | ||
2304 | (the meaning of the -cscl parameter is described above.) Note that | |
2305 | quotes are required around the list of block types because of the | |
2306 | spaces. | |
2307 | ||
2308 | =head2 Specifying File Extensions | |
2309 | ||
2310 | Several parameters allow default file extensions to be overridden. For | |
2311 | example, a backup file extension may be specified with B<-bext=ext>, | |
2312 | where B<ext> is some new extension. In order to provides the user some | |
2313 | flexibility, the following convention is used in all cases to decide if | |
2314 | a leading '.' should be used. If the extension C<ext> begins with | |
2315 | C<A-Z>, C<a-z>, or C<0-9>, then it will be appended to the filename with | |
2316 | an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it | |
2317 | will be appended directly. | |
2318 | ||
2319 | For example, suppose the file is F<somefile.pl>. For C<-bext=old>, a '.' is | |
2320 | added to give F<somefile.pl.old>. For C<-bext=.old>, no additional '.' is | |
2321 | added, so again the backup file is F<somefile.pl.old>. For C<-bext=~>, then no | |
2322 | dot is added, and the backup file will be F<somefile.pl~> . | |
2323 | ||
2324 | =head1 SWITCHES WHICH MAY BE NEGATED | |
2325 | ||
2326 | The following list shows all short parameter names which allow a prefix | |
2327 | 'n' to produce the negated form: | |
2328 | ||
2329 | D anl asc aws b bbb bbc bbs bli boc bok bol bot syn ce csc | |
2330 | dac dbc dcsc dnl dws dp dpro dsm dsc ddf dln dop dsn dtt dwls dwrs | |
2331 | f fll frm hsc html ibc icb icp iob isbc lp log lal x lsl ple pod bl | |
2332 | sbl okw ola oll ple pvl q opt sbc sfs ssc sts se st sob | |
2333 | t tac tbc toc tp tsc tqw w | |
2334 | ||
2335 | Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be | |
2336 | used. | |
2337 | ||
2338 | =head1 LIMITATIONS | |
2339 | ||
2340 | =over 4 | |
2341 | ||
2342 | =item Parsing Limitations | |
2343 | ||
2344 | Perltidy should work properly on most perl scripts. It does a lot of | |
2345 | self-checking, but still, it is possible that an error could be | |
2346 | introduced and go undetected. Therefore, it is essential to make | |
2347 | careful backups and to test reformatted scripts. | |
2348 | ||
2349 | The main current limitation is that perltidy does not scan modules | |
2350 | included with 'use' statements. This makes it necessary to guess the | |
2351 | context of any bare words introduced by such modules. Perltidy has good | |
2352 | guessing algorithms, but they are not infallible. When it must guess, | |
2353 | it leaves a message in the log file. | |
2354 | ||
2355 | If you encounter a bug, please report it. | |
2356 | ||
2357 | =item What perltidy does not parse and format | |
2358 | ||
2359 | Perltidy indents but does not reformat comments and C<qw> quotes. | |
2360 | Perltidy does not in any way modify the contents of here documents or | |
2361 | quoted text, even if they contain source code. (You could, however, | |
2362 | reformat them separately). Perltidy does not format 'format' sections | |
2363 | in any way. And, of course, it does not modify pod documents. | |
2364 | ||
2365 | =back | |
2366 | ||
2367 | =head1 FILES | |
2368 | ||
2369 | =over 4 | |
2370 | ||
2371 | =item Temporary files | |
2372 | ||
2373 | Under the -html option with the default --pod2html flag, a temporary file is | |
2374 | required to pass text to Pod::Html. Unix systems will try to use the POSIX | |
2375 | tmpnam() function. Otherwise the file F<perltidy.TMP> will be temporarily | |
2376 | created in the current working directory. | |
2377 | ||
2378 | =item Special files when standard input is used | |
2379 | ||
2380 | When standard input is used, the log file, if saved, is F<perltidy.LOG>, | |
2381 | and any errors are written to F<perltidy.ERR> unless the B<-se> flag is | |
2382 | set. These are saved in the current working directory. | |
2383 | ||
2384 | =item Files overwritten | |
2385 | ||
2386 | The following file extensions are used by perltidy, and files with these | |
2387 | extensions may be overwritten or deleted: F<.ERR>, F<.LOG>, F<.TEE>, | |
2388 | and/or F<.tdy>, F<.html>, and F<.bak>, depending on the run type and | |
2389 | settings. | |
2390 | ||
2391 | =item Files extensions limitations | |
2392 | ||
2393 | Perltidy does not operate on files for which the run could produce a file with | |
2394 | a duplicated file extension. These extensions include F<.LOG>, F<.ERR>, | |
2395 | F<.TEE>, and perhaps F<.tdy> and F<.bak>, depending on the run type. The | |
2396 | purpose of this rule is to prevent generating confusing filenames such as | |
2397 | F<somefile.tdy.tdy.tdy>. | |
2398 | ||
2399 | =back | |
2400 | ||
2401 | =head1 SEE ALSO | |
2402 | ||
2403 | perlstyle(1), Perl::Tidy(3) | |
2404 | ||
2405 | =head1 VERSION | |
2406 | ||
2407 | This man page documents perltidy version 20031021. | |
2408 | ||
2409 | =head1 CREDITS | |
2410 | ||
2411 | Michael Cartmell supplied code for adaptation to VMS and helped with | |
2412 | v-strings. | |
2413 | ||
2414 | Yves Orton supplied code for adaptation to the various versions | |
2415 | of Windows. | |
2416 | ||
2417 | Axel Rose supplied a patch for MacPerl. | |
2418 | ||
2419 | Hugh S. Myers designed and implemented the initial Perl::Tidy module interface. | |
2420 | ||
2421 | Many others have supplied key ideas, suggestions, and bug reports; | |
2422 | see the CHANGES file. | |
2423 | ||
2424 | =head1 AUTHOR | |
2425 | ||
2426 | Steve Hancock | |
2427 | email: perltidy at users.sourceforge.net | |
2428 | http://perltidy.sourceforge.net | |
2429 | ||
2430 | =head1 COPYRIGHT | |
2431 | ||
2432 | Copyright (c) 2000-2003 by Steve Hancock | |
2433 | ||
2434 | =head1 LICENSE | |
2435 | ||
2436 | This package is free software; you can redistribute it and/or modify it | |
2437 | under the terms of the "GNU General Public License". | |
2438 | ||
2439 | Please refer to the file "COPYING" for details. | |
2440 | ||
2441 | =head1 DISCLAIMER | |
2442 | ||
2443 | This package is distributed in the hope that it will be useful, | |
2444 | but WITHOUT ANY WARRANTY; without even the implied warranty of | |
2445 | MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. | |
2446 | ||
2447 | See the "GNU General Public License" for more details. |