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