1PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
2
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 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 A convenient aid to systematically defining a set of style parameters
24 can be found at http://perltidy.sourceforge.net/stylekey.html
25 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 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 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 perltidy *.pl
43 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 perltidy -b file1.pl file2.pl
50 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 perltidy -gnu somefile.pl
56 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 perltidy -i=3 somefile.pl
62 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 perltidy -i=3 -et=8 somefile.pl
70 Same as the previous example, except that leading whitespace will be
72 entabbed with one tab character per 8 spaces.
73 perltidy -ce -l=72 somefile.pl
75 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 perltidy -g somefile.pl
81 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 perltidy -html somefile.pl
87 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 perltidy -html -css=mystyle.css somefile.pl
93 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 perltidy -html -pre somefile.pl
100 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 perltidy -html -ss >mystyle.css
106 Write a style sheet to mystyle.css and exit.
108 perltidy -html -frm mymodule.pm
110 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 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 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 Options may not be bundled together. In other words, options -q and -g
135 may NOT be entered as -qg.
136 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 I/O control
143 The following parameters concern the files which are read and written.
145 -h, --help
147 Show summary of usage and exit.
148 -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 -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 perltidy somefile.pl -st >somefile.new.pl
163 This option may only be used if there is just a single input file.
165 The default is -nst or --nostandard-output.
166 -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 -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 -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 The path should end in a valid path separator character, but
187 perltidy will try to add one if it is missing.
188 For example
190 perltidy somefile.pl -opath=/tmp/
192 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
194 appear in whatever directory contains somefile.pl.
195 If the path contains spaces, it should be placed in quotes.
197 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 -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 A -b flag will be ignored if input is from standard input, or if
208 the -html flag is set.
209 -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 -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 -q, --quiet
222 Deactivate error messages and syntax checking (for running under an
223 editor).
224 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 :n1,n2!perltidy -q
230 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 -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 -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 Setting -g also causes the logfile to be saved, so it is not neces‐
250 sary to also include -log.
251 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 Setting a negative value of "n" is the same as not setting -g at
257 all.
258 -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 If you set the -npro flag, perltidy will not look for this file.
268 -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 perltidy -pro=testcfg
276 would cause file testcfg to be used instead of the default
278 .perltidyrc.
279 -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 -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 -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 -i=n, --indent-columns=n
301 Use n columns per indentation level (default n=4).
302 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 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 -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 -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 -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 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 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 -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 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 -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 Setting this flag is equivalent to setting --freeze-newlines and
369 --freeze-whitespace.
370 -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 -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 Code Indentation Control
387 -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 my $level = # -ci=2
393 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
394 The same example, with n=0, is a little harder to read:
396 my $level = # -ci=0
398 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
399 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 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 -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 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 # perltidy (default)
422 @month_of_year = (
423 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
424 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
425 );
426 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 # perltidy -lp
433 @month_of_year = (
434 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
435 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
436 );
437 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 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 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 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 -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 -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 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
470 section).
471 # perltidy -lp -cti=1
473 @month_of_year = (
474 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
475 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
476 );
477 # perltidy -lp -cti=2
479 @month_of_year = (
480 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
481 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
482 );
483 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 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 -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 -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 if ($task) {
506 yyy();
507 } # -icb
508 else {
509 zzz();
510 }
511 The default is not to do this, indicated by -nicb.
513 -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 -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 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 my $i;
533 LOOP: while ( $i = <FOTOS> ) {
534 chomp($i);
535 next unless $i;
536 fixit($i);
537 }
538 Use -nola to not outdent labels.
540 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 For example, using "perltidy -okw" on the previous example
551 gives:
552 my $i;
554 LOOP: while ( $i = <FOTOS> ) {
555 chomp($i);
556 next unless $i;
557 fixit($i);
558 }
559 The default is not to do this.
561 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 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 Whitespace Control
576 Whitespace refers to the blank space between variables, operators, and
578 other code tokens.
579 -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 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 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 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 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 Likewise, the parameter -sbt=n or --square-bracket-tightness=n con‐
608 trols the space within square brackets, as illustrated below.
609 $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 Curly braces which do not contain code blocks are controlled by the
615 parameter -bt=n or --brace-tightness=n.
616 $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 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 %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 -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 $i = 1 ; # -sts
635 $i = 1; # -nsts (default)
636 -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 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
644 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
645 -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 -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 -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 -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 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 -wls=s or --want-left-space=s,
679 -nwls=s or --nowant-left-space=s,
681 -wrs=s or --want-right-space=s,
683 -nwrs=s or --nowant-right-space=s.
685 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 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 -nwls="= + - / *" -nwrs="= + - / *"
697 (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 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
703 becomes this:
705 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
707 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 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 WARNING Be sure to put these tokens in quotes to avoid having them
721 misinterpreted by your command shell.
722 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 my local our and or eq ne if else elsif until unless
728 while for foreach return switch case given when
729 These defaults can be modified with two commands:
731 -sak=s or --space-after-keyword=s adds keywords.
733 -nsak=s or --nospace-after-keyword=s removes keywords.
735 where s is a list of keywords (in quotes if necessary). For exam‐
737 ple,
738 my ( $a, $b, $c ) = @_; # default
740 my( $a, $b, $c ) = @_; # -nsak="my local our"
741 To put a space after all keywords, see the next item.
743 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 -skp or --space-keyword-paren
751 You will probably also want to use the flag -sfp (next item) too.
753 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 -sfp or --space-function-paren
759 myfunc( $a, $b, $c ); # default
761 myfunc ( $a, $b, $c ); # -sfp
762 You will probably also want to use the flag -skp (previous item)
764 too.
765 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 -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 Comment Controls
777 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 -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 # this comment is indented (-ibc, default)
790 if ($task) { yyy(); }
791 The alternative is -nibc:
793 # this comment is not indented (-nibc)
795 if ($task) { yyy(); }
796 See also the next item, -isbc, as well as -sbc, for other ways to
798 have some indented and some outdented block comments.
799 -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 If both -ibc and -isbc are set, then -isbc takes priority.
805 -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 -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 -hsc, --hanging-side-comments
817 By default, perltidy tries to identify and align "hanging side com‐
818 ments", which are something like this:
819 my $IGNORE = 0; # This is a side comment
821 # This is a hanging side comment
822 # And so is this
823 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 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 sub message {
839 if ( !defined( $_[0] ) ) {
840 print("Hello, World\n");
841 }
842 else {
843 print( $_[0], "\n" );
844 }
845 }
846 And here is the result of processing with "perltidy -csc":
848 sub message {
850 if ( !defined( $_[0] ) ) {
851 print("Hello, World\n");
852 }
853 else {
854 print( $_[0], "\n" );
855 }
856 } ## end sub message
857 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 The command -dcsc (or --delete-closing-side-comments) reverses this
864 process and removes these comments.
865 Several commands are available to modify the behavior of these two
867 basic commands, -csc and -dcsc:
868 -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 # 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 Now the "if" and "else" blocks are commented. However, now
885 this has become very cluttered.
886 -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 -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 -cscl="sub : BEGIN END"
907 -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 -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 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 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 -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 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 Important Notes on Closing Side Comments:
950 * 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 * 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 * 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 * 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 * 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 * 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 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 -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 Comments so identified are treated as follows:
999 * If there is no leading space on the line, then the comment
1001 will not be indented, and otherwise it may be,
1002 * no new blank line will be inserted before such a comment,
1004 and
1005 * such a comment will never become a hanging side comment.
1007 For example, assuming @month_of_year is left-adjusted:
1009 @month_of_year = ( # -sbc (default)
1011 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1012 ## 'Dec', 'Nov'
1013 'Nov', 'Dec');
1014 Without this convention, the above code would become
1016 @month_of_year = ( # -nsbc
1018 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1019 ## 'Dec', 'Nov'
1021 'Nov', 'Dec'
1022 );
1023 which is not as clear. The default is to use -sbc. This may
1025 be deactivated with -nsbc.
1026 -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 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 -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 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 -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 The default is -nssc.
1063 -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 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 Skipping Selected Sections of Code
1076 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 -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 #<<< 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 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 -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 Some examples show how example strings become patterns:
1118 -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 -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 Line Break Control
1129 -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 -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 if ($task) {
1145 yyy();
1146 } else { # -ce
1147 zzz();
1148 }
1149 if ($task) {
1151 yyy();
1152 }
1153 else { # -nce (default)
1154 zzz();
1155 }
1156 -bl, --opening-brace-on-new-line
1158 Use the flag -bl to place the opening brace on a new line:
1159 if ( $input_file eq '-' ) # -bl
1161 {
1162 important_function();
1163 }
1164 This flag applies to all structural blocks, including sub's (unless
1166 the -sbl flag is set -- see next item).
1167 The default style, -nbl, places an opening brace on the same line
1169 as the keyword introducing it. For example,
1170 if ( $input_file eq '-' ) { # -nbl (default)
1172 -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 perltidy -sbl
1178 produces this result:
1180 sub message
1182 {
1183 if (!defined($_[0])) {
1184 print("Hello, World\n");
1185 }
1186 else {
1187 print($_[0], "\n");
1188 }
1189 }
1190 This flag is negated with -nsbl. If -sbl is not specified, the
1192 value of -bl is used.
1193 -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 For example,
1200 if ( $input_file eq '-' ) # -bli
1202 {
1203 important_function();
1204 }
1205 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 -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 -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 if ( $bigwasteofspace1 && $bigwasteofspace2
1222 ⎪⎪ $bigwasteofspace3 && $bigwasteofspace4 )
1223 {
1224 big_waste_of_time();
1225 }
1226 To force the opening brace to always be on the right, use the -bar
1228 flag. In this case, the above example becomes
1229 if ( $bigwasteofspace1 && $bigwasteofspace2
1231 ⎪⎪ $bigwasteofspace3 && $bigwasteofspace4 ) {
1232 big_waste_of_time();
1233 }
1234 A conflict occurs if both -bl and -bar are specified.
1236 -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 # default formatting
1242 push @{ $self->{$module}{$key} },
1243 {
1244 accno => $ref->{accno},
1245 description => $ref->{description}
1246 };
1247 # perltidy -otr
1249 push @{ $self->{$module}{$key} }, {
1250 accno => $ref->{accno},
1251 description => $ref->{description}
1252 };
1253 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 -opr or --opening-paren-right
1259 -ohbr or --opening-hash-brace-right
1260 -osbr or --opening-square-bracket-right
1261 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 * Opening tokens (except for block braces) are controlled by
1268 -vt=n, or --vertical-tightness=n, where
1269 -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 * You must also use the -lp flag when you use the -vt flag; the
1276 reason is explained below.
1277 * Closing tokens (except for block braces) are controlled by
1279 -vtc=n, or --vertical-tightness-closing=n, where
1280 -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 The rules for -vtc=1 are designed to maintain a reasonable bal‐
1288 ance between tightness and readability in complex lists.
1289 * Different controls may be applied to to different token types,
1291 and it is also possible to control block braces; see below.
1292 * 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 Here are some examples:
1301 # perltidy -lp -vt=0 -vtc=0
1303 %romanNumerals = (
1304 one => 'I',
1305 two => 'II',
1306 three => 'III',
1307 four => 'IV',
1308 );
1309 # perltidy -lp -vt=1 -vtc=0
1311 %romanNumerals = ( one => 'I',
1312 two => 'II',
1313 three => 'III',
1314 four => 'IV',
1315 );
1316 # perltidy -lp -vt=1 -vtc=1
1318 %romanNumerals = ( one => 'I',
1319 two => 'II',
1320 three => 'III',
1321 four => 'IV', );
1322 The difference between -vt=1 and -vt=2 is shown here:
1324 # perltidy -lp -vt=1
1326 $init->add(
1327 mysprintf( "(void)find_threadsv(%s);",
1328 cstring( $threadsv_names[ $op->targ ] )
1329 )
1330 );
1331 # perltidy -lp -vt=2
1333 $init->add( mysprintf( "(void)find_threadsv(%s);",
1334 cstring( $threadsv_names[ $op->targ ] )
1335 )
1336 );
1337 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 The tightest, and least readable, code is produced with both
1343 "-vt=2" and "-vtc=2":
1344 # perltidy -lp -vt=2 -vtc=2
1346 $init->add( mysprintf( "(void)find_threadsv(%s);",
1347 cstring( $threadsv_names[ $op->targ ] ) ) );
1348 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 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 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 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 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 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 -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 -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 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 # 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 # perltidy -bli -bbvt=1
1404 if ( open( FILE, "< $File" ) )
1405 { while ( $File = <FILE> )
1406 { $In .= $File;
1407 $count++;
1408 }
1409 close(FILE);
1410 }
1411 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 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 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 -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 For example:
1433 # default
1435 $opt_c = Text::CSV_XS->new(
1436 {
1437 binary => 1,
1438 sep_char => $opt_c,
1439 always_quote => 1,
1440 }
1441 );
1442 # -sot
1444 $opt_c = Text::CSV_XS->new( {
1445 binary => 1,
1446 sep_char => $opt_c,
1447 always_quote => 1,
1448 }
1449 );
1450 For detailed control of individual closing tokens the following
1452 controls can be used:
1453 -sop or --stack-opening-paren
1455 -sohb or --stack-opening-hash-brace
1456 -sosb or --stack-opening-square-bracket
1457 The flag -sot is a synonym for -sop -sohb -sosb.
1459 -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 For example:
1465 # default
1467 $opt_c = Text::CSV_XS->new(
1468 {
1469 binary => 1,
1470 sep_char => $opt_c,
1471 always_quote => 1,
1472 }
1473 );
1474 # -sct
1476 $opt_c = Text::CSV_XS->new(
1477 {
1478 binary => 1,
1479 sep_char => $opt_c,
1480 always_quote => 1,
1481 } );
1482 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 # -vtc=2
1492 $opt_c = Text::CSV_XS->new(
1493 {
1494 binary => 1,
1495 sep_char => $opt_c,
1496 always_quote => 1, } );
1497 For detailed control of the stacking of individual closing tokens
1499 the following controls can be used:
1500 -scp or --stack-closing-paren
1502 -schb or --stack-closing-hash-brace
1503 -scsb or --stack-closing-square-bracket
1504 The flag -sct is a synonym for -scp -schb -scsb.
1506 -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 -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 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 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 -wba=s or --want-break-after=s, and
1527 -wbb=s or --want-break-before=s.
1529 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 By default, perltidy breaks after these token types:
1537 % + - * / x != == >= <= =~ !~ < > ⎪ &
1538 = **= += *= &= <<= &&= -= /= ⎪= >>= ⎪⎪= //= .= %= ^= x=
1539 And perltidy breaks before these token types by default:
1541 . << >> -> && ⎪⎪ //
1542 To illustrate, to cause a break after a concatenation operator,
1544 '.', rather than before it, the command line would be
1545 -wba="."
1547 As another example, the following command would cause a break
1549 before math operators '+', '-', '/', and '*':
1550 -wbb="+ - / *"
1552 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 WARNING Be sure to put these tokens in quotes to avoid having them
1562 misinterpreted by your command shell.
1563 Controlling List Formatting
1565 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 -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 my @list = (1,
1578 1, 1,
1579 1, 2, 1,
1580 1, 3, 3, 1,
1581 1, 4, 6, 4, 1,);
1582 The default formatting will flatten this down to one line:
1584 # perltidy (default)
1586 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
1587 which hides the structure. Using -boc, plus additional flags to
1589 retain the original style, yields
1590 # 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 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 -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 # 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 -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 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 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 bless { B => $B, Root => $Root } => $package;
1641 Using -cab=0 will force a break after each comma-arrow item:
1643 # perltidy -cab=0:
1645 bless {
1646 B => $B,
1647 Root => $Root
1648 } => $package;
1649 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 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 # 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 Retaining or Ignoring Existing Line Breaks
1669 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 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 -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 -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 -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 -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 Blank Line Control
1708 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 -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 -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 -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 * The block is not preceded by a comment.
1732 * The block is not a one-line block.
1734 * The number of consecutive non-blank lines at the current inden‐
1736 tation depth is at least -lbl (see next section).
1737 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 -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 -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 -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 -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 Styles
1767 A style refers to a convenient collection of existing parameters.
1769 -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 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
1777 -pbp, --perl-best-practices
1779 -pbp is an abbreviation for the parameters in the book Perl Best
1780 Practices by Damian Conway:
1781 -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 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 Other Controls
1791 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 The command -dp or --delete-pod will remove all pod documentation
1799 (but not comments).
1800 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 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 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 The command -tac or --tee-all-comments will write all comments and
1817 all pod documentation.
1818 The command -tp or --tee-pod will write all pod documentation (but
1820 not comments).
1821 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 The negatives of these commands also work, and are the defaults.
1827 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 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 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 Here is an example of a .perltidyrc file:
1850 # 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 The parameters in the .perltidyrc file are installed first, so any
1861 parameters given on the command line will have priority over them.
1862 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 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
1867 There are several options may be helpful in debugging a .perltidyrc
1869 file:
1870 * 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 perltidy -dpro
1879 * 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 * The parameters in the .perltidyrc file can be switched off with
1886 the -npro option.
1887 * The commands --dump-options, --dump-defaults,
1889 --dump-long-names, and --dump-short-names, all described below,
1890 may all be helpful.
1891 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 newword {
1901 -opt1
1902 -opt2
1903 }
1904 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 airy {-bl -pt=0 -bt=0 -sbt=0}
1912 could be placed in a .perltidyrc file, and then invoked at will
1914 with
1915 perltidy -airy somefile.pl
1917 (Either "-airy" or "--airy" may be used).
1919 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 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 perltidy --mangle myfile.pl -st ⎪ perltidy -o myfile.pl.new
1946 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 A similar technique can be used with --extrude instead of --mangle
1952 to make the minimum number of one-line blocks.
1953 Another use for --mangle is to combine it with -dac to reduce the
1955 file size of a perl script.
1956 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 if ($x > 0) { $y = 1 / $x }
1962 where the contents within the curly braces is short enough to fit
1964 on a single line.
1965 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 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 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 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 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 Debugging
1992 The following flags are available for debugging:
1993 --dump-defaults or -ddf will write the default option set to stan‐
1995 dard output and quit
1996 --dump-profile or -dpro will write the name of the current config‐
1998 uration file and its contents to standard output and quit.
1999 --dump-options or -dop will write current option set to standard
2001 output and quit.
2002 --dump-long-names or -dln will write all command line long names
2004 (passed to Get_options) to standard output and quit.
2005 --dump-short-names or -dsn will write all command line short names
2007 to standard output and quit.
2008 --dump-token-types or -dtt will write a list of all token types to
2010 standard output and quit.
2011 --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 --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 -DEBUG will write a file with extension .DEBUG for each input file
2021 showing the tokenization of all lines of code.
2022 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 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 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 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 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 perltidy -html somefile.pl
2052 will produce a syntax-colored html file named somefile.pl.html
2054 which may be viewed with a browser.
2055 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 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 The -nnn flag for line numbering
2068 When the -nnn flag is given, the output lines will be numbered.
2069 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 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 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 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 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2099 --[no]podverbose --podflush
2100 The flags which are unchanged from their use in pod2html are:
2102 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2104 --podpath=s --podroot=s
2105 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 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 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 MyModule.pm.html - the frame
2124 MyModule.pm.toc.html - the table of contents
2125 MyModule.pm.src.html - the formatted source code
2126 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 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 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 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 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 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 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 perltidy -html -ss >mystyle.css
2166 will write a style sheet with the default properties to file
2168 mystyle.css.
2169 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 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 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 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 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 To illustrate, the following command will produce an html file
2212 somefile.pl.html with "aqua" keywords:
2213 perltidy -html -hck=00ffff somefile.pl
2215 and this should be equivalent for most browsers:
2217 perltidy -html -hck=aqua somefile.pl
2219 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 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 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 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 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 For example, to use bold braces and lime color, non-bold, italics
2257 keywords the following command would be used:
2258 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
2260 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 Here are some notes and hints:
2267 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 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 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 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 For example, the following parameter specifies "sub", labels, "BEGIN",
2290 and "END" blocks:
2291 -cscl="sub : BEGIN END"
2293 (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 Specifying File Extensions
2299 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 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 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 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 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 If you encounter a bug, please report it.
2342 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 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 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 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 Yves Orton supplied code for adaptation to the various versions of Win‐
2388 dows.
2389 Axel Rose supplied a patch for MacPerl.
2391 Hugh S. Myers designed and implemented the initial Perl::Tidy module
2393 interface.
2394 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 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 See the "GNU General Public License" for more details.
2418perl v5.8.8 2007-05-08 PERLTIDY(1)