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
29 recommendations in perlstyle(1), but it can be controlled in detail
30 with numerous input parameters, which are described in "FORMATTING
31 OPTIONS".
32 When the -html flag is given, the output is passed through an HTML
34 formatter which is described in "HTML OPTIONS".
35
37 perltidy somefile.pl
38 This will produce a file somefile.pl.tdy containing the script
40 reformatted using the default options, which approximate the style
41 suggested in perlstyle(1). The source file somefile.pl is unchanged.
42 perltidy *.pl
44 Execute perltidy on all .pl files in the current directory with the
46 default options. The output will be in files with an appended .tdy
47 extension. For any file with an error, there will be a file with
48 extension .ERR.
49 perltidy -b file1.pl file2.pl
51 Modify file1.pl and file2.pl in place, and backup the originals to
53 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
54 already exist, they will be overwritten.
55 perltidy -b -bext='/' file1.pl file2.pl
57 Same as the previous example except that the backup files file1.pl.bak
59 and file2.pl.bak will be deleted if there are no errors.
60 perltidy -gnu somefile.pl
62 Execute perltidy on file somefile.pl with a style which approximates
64 the GNU Coding Standards for C programs. The output will be
65 somefile.pl.tdy.
66 perltidy -i=3 somefile.pl
68 Execute perltidy on file somefile.pl, with 3 columns for each level of
70 indentation (-i=3) instead of the default 4 columns. There will not be
71 any tabs in the reformatted script, except for any which already exist
72 in comments, pod documents, quotes, and here documents. Output will be
73 somefile.pl.tdy.
74 perltidy -i=3 -et=8 somefile.pl
76 Same as the previous example, except that leading whitespace will be
78 entabbed with one tab character per 8 spaces.
79 perltidy -ce -l=72 somefile.pl
81 Execute perltidy on file somefile.pl with all defaults except use
83 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
84 instead of the default 80 columns.
85 perltidy -g somefile.pl
87 Execute perltidy on file somefile.pl and save a log file
89 somefile.pl.LOG which shows the nesting of braces, parentheses, and
90 square brackets at the start of every line.
91 perltidy -html somefile.pl
93 This will produce a file somefile.pl.html containing the script with
95 html markup. The output file will contain an embedded style sheet in
96 the <HEAD> section which may be edited to change the appearance.
97 perltidy -html -css=mystyle.css somefile.pl
99 This will produce a file somefile.pl.html containing the script with
101 html markup. This output file will contain a link to a separate style
102 sheet file mystyle.css. If the file mystyle.css does not exist, it
103 will be created. If it exists, it will not be overwritten.
104 perltidy -html -pre somefile.pl
106 Write an html snippet with only the PRE section to somefile.pl.html.
108 This is useful when code snippets are being formatted for inclusion in
109 a larger web page. No style sheet will be written in this case.
110 perltidy -html -ss >mystyle.css
112 Write a style sheet to mystyle.css and exit.
114 perltidy -html -frm mymodule.pm
116 Write html with a frame holding a table of contents and the source
118 code. The output files will be mymodule.pm.html (the frame),
119 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
120 (the source code).
121
123 The entire command line is scanned for options, and they are processed
124 before any files are processed. As a result, it does not matter
125 whether flags are before or after any filenames. However, the relative
126 order of parameters is important, with later parameters overriding the
127 values of earlier parameters.
128 For each parameter, there is a long name and a short name. The short
130 names are convenient for keyboard input, while the long names are self-
131 documenting and therefore useful in scripts. It is customary to use
132 two leading dashes for long names, but one may be used.
133 Most parameters which serve as on/off flags can be negated with a
135 leading "n" (for the short name) or a leading "no" or "no-" (for the
136 long name). For example, the flag to outdent long quotes is is -olq or
137 --outdent-long-quotes. The flag to skip this is -nolq or
138 --nooutdent-long-quotes or --no-outdent-long-quotes.
139 Options may not be bundled together. In other words, options -q and -g
141 may NOT be entered as -qg.
142 Option names may be terminated early as long as they are uniquely
144 identified. For example, instead of --dump-token-types, it would be
145 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
146 this command.
147 I/O control
149 The following parameters concern the files which are read and written.
150 -h, --help
152 Show summary of usage and exit.
153 -o=filename, --outfile=filename
155 Name of the output file (only if a single input file is being
156 processed). If no output file is specified, and output is not
157 redirected to the standard output, the output will go to
158 filename.tdy.
159 -st, --standard-output
161 Perltidy must be able to operate on an arbitrarily large number of
162 files in a single run, with each output being directed to a
163 different output file. Obviously this would conflict with
164 outputting to the single standard output device, so a special flag,
165 -st, is required to request outputting to the standard output. For
166 example,
167 perltidy somefile.pl -st >somefile.new.pl
169 This option may only be used if there is just a single input file.
171 The default is -nst or --nostandard-output.
172 -se, --standard-error-output
174 If perltidy detects an error when processing file somefile.pl, its
175 default behavior is to write error messages to file
176 somefile.pl.ERR. Use -se to cause all error messages to be sent to
177 the standard error output stream instead. This directive may be
178 negated with -nse. Thus, you may place -se in a .perltidyrc and
179 override it when desired with -nse on the command line.
180 -oext=ext, --output-file-extension=ext
182 Change the extension of the output file to be ext instead of the
183 default tdy (or html in case the --html option is used). See
184 "Specifying File Extensions".
185 -opath=path, --output-path=path
187 When perltidy creates a filename for an output file, by default it
188 merely appends an extension to the path and basename of the input
189 file. This parameter causes the path to be changed to path
190 instead.
191 The path should end in a valid path separator character, but
193 perltidy will try to add one if it is missing.
194 For example
196 perltidy somefile.pl -opath=/tmp/
198 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
200 appear in whatever directory contains somefile.pl.
201 If the path contains spaces, it should be placed in quotes.
203 This parameter will be ignored if output is being directed to
205 standard output, or if it is being specified explicitly with the
206 -o=s parameter.
207 -b, --backup-and-modify-in-place
209 Modify the input file or files in-place and save the original with
210 the extension .bak. Any existing .bak file will be deleted. See
211 next item for changing the default backup extension, and for
212 eliminating the backup file altogether.
213 A -b flag will be ignored if input is from standard input or goes
215 to standard output, or if the -html flag is set.
216 In particular, if you want to use both the -b flag and the -pbp
218 (--perl-best-practices) flag, then you must put a -nst flag after
219 the -pbp flag because it contains a -st flag as one of its
220 components, which means that output will go to the standard output
221 stream.
222 -bext=ext, --backup-file-extension=ext
224 This parameter serves two purposes: (1) to change the extension of
225 the backup file to be something other than the default .bak, and
226 (2) to indicate that no backup file should be saved.
227 To change the default extension to something other than .bak see
229 "Specifying File Extensions".
230 A backup file of the source is always written, but you can request
232 that it be deleted at the end of processing if there were no
233 errors. This is risky unless the source code is being maintained
234 with a source code control system.
235 To indicate that the backup should be deleted include one forward
237 slash, /, in the extension. If any text remains after the slash is
238 removed it will be used to define the backup file extension (which
239 is always created and only deleted if there were no errors).
240 Here are some examples:
242 Parameter Extension Backup File Treatment
244 <-bext=bak> F<.bak> Keep (same as the default behavior)
245 <-bext='/'> F<.bak> Delete if no errors
246 <-bext='/backup'> F<.backup> Delete if no errors
247 <-bext='original/'> F<.original> Delete if no errors
248 -w, --warning-output
250 Setting -w causes any non-critical warning messages to be reported
251 as errors. These include messages about possible pod problems,
252 possibly bad starting indentation level, and cautions about
253 indirect object usage. The default, -nw or --nowarning-output, is
254 not to include these warnings.
255 -q, --quiet
257 Deactivate error messages and syntax checking (for running under an
258 editor).
259 For example, if you use a vi-style editor, such as vim, you may
261 execute perltidy as a filter from within the editor using something
262 like
263 :n1,n2!perltidy -q
265 where "n1,n2" represents the selected text. Without the -q flag,
267 any error message may mess up your screen, so be prepared to use
268 your "undo" key.
269 -log, --logfile
271 Save the .LOG file, which has many useful diagnostics. Perltidy
272 always creates a .LOG file, but by default it is deleted unless a
273 program bug is suspected. Setting the -log flag forces the log
274 file to be saved.
275 -g=n, --logfile-gap=n
277 Set maximum interval between input code lines in the logfile. This
278 purpose of this flag is to assist in debugging nesting errors. The
279 value of "n" is optional. If you set the flag -g without the value
280 of "n", it will be taken to be 1, meaning that every line will be
281 written to the log file. This can be helpful if you are looking
282 for a brace, paren, or bracket nesting error.
283 Setting -g also causes the logfile to be saved, so it is not
285 necessary to also include -log.
286 If no -g flag is given, a value of 50 will be used, meaning that at
288 least every 50th line will be recorded in the logfile. This helps
289 prevent excessively long log files.
290 Setting a negative value of "n" is the same as not setting -g at
292 all.
293 -npro --noprofile
295 Ignore any .perltidyrc command file. Normally, perltidy looks
296 first in your current directory for a .perltidyrc file of
297 parameters. (The format is described below). If it finds one, it
298 applies those options to the initial default values, and then it
299 applies any that have been defined on the command line. If no
300 .perltidyrc file is found, it looks for one in your home directory.
301 If you set the -npro flag, perltidy will not look for this file.
303 -pro=filename or --profile=filename
305 To simplify testing and switching .perltidyrc files, this command
306 may be used to specify a configuration file which will override the
307 default name of .perltidyrc. There must not be a space on either
308 side of the '=' sign. For example, the line
309 perltidy -pro=testcfg
311 would cause file testcfg to be used instead of the default
313 .perltidyrc.
314 A pathname begins with three dots, e.g. ".../.perltidyrc",
316 indicates that the file should be searched for starting in the
317 current directory and working upwards. This makes it easier to have
318 multiple projects each with their own .perltidyrc in their root
319 directories.
320 -opt, --show-options
322 Write a list of all options used to the .LOG file. Please see
323 --dump-options for a simpler way to do this.
324 -f, --force-read-binary
326 Force perltidy to process binary files. To avoid producing
327 excessive error messages, perltidy skips files identified by the
328 system as non-text. However, valid perl scripts containing binary
329 data may sometimes be identified as non-text, and this flag forces
330 perltidy to process them.
331
333 Basic Options
334 --notidy
335 This flag disables all formatting and causes the input to be copied
336 unchanged to the output except for possible changes in line ending
337 characters and any pre- and post-filters. This can be useful in
338 conjunction with a hierarchical set of .perltidyrc files to avoid
339 unwanted code tidying. See also "Skipping Selected Sections of
340 Code" for a way to avoid tidying specific sections of code.
341 -i=n, --indent-columns=n
343 Use n columns per indentation level (default n=4).
344 -l=n, --maximum-line-length=n
346 The default maximum line length is n=80 characters. Perltidy will
347 try to find line break points to keep lines below this length.
348 However, long quotes and side comments may cause lines to exceed
349 this length. Setting -l=0 is equivalent to setting -l=(a large
350 number).
351 -vmll, --variable-maximum-line-length
353 A problem arises using a fixed maximum line length with very deeply
354 nested code and data structures because eventually the amount of
355 leading whitespace used for indicating indation takes up most or
356 all of the available line width, leaving little or no space for the
357 actual code or data. One solution is to use a vary long line
358 length. Another solution is to use the -vmll flag, which basically
359 tells perltidy to ignore leading whitespace when measuring the line
360 length.
361 To be precise, when the -vmll parameter is set, the maximum line
363 length of a line of code will be M+L*I, where
364 M is the value of --maximum-line-length=M (-l=M), default 80,
366 I is the value of --indent-columns=I (-i=I), default 4,
367 L is the indentation level of the line of code
368 When this flag is set, the choice of breakpoints for a block of
370 code should be essentially independent of its nesting depth.
371 However, the absolute line lengths, including leading whitespace,
372 can still be arbitrarily large. This problem can be avoided by
373 including the next parameter.
374 The default is not to do this (-nvmll).
376 -wc=n, --whitespace-cycle=n
378 This flag also addresses problems with very deeply nested code and
379 data structures. When the nesting depth exceeds the value n the
380 leading whitespace will be reduced and start at a depth of 1 again.
381 The result is that blocks of code will shift back to the left
382 rather than moving arbitrarily far to the right. This occurs
383 cyclically to any depth.
384 For example if one level of indentation equals 4 spaces (-i=4, the
386 default), and one uses -wc=15, then if the leading whitespace on a
387 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
388 spaces and continue increasing from there. If the whitespace never
389 exceeds this limit the formatting remains unchanged.
390 The combination of -vmll and -wc=n provides a solution to the
392 problem of displaying arbitrarily deep data structures and code in
393 a finite window, although -wc=n may of course be used without
394 -vmll.
395 The default is not to use this, which can also be indicated using
397 -wc=0.
398 tabs
400 Using tab characters will almost certainly lead to future
401 portability and maintenance problems, so the default and
402 recommendation is not to use them. For those who prefer tabs,
403 however, there are two different options.
404 Except for possibly introducing tab indentation characters, as
406 outlined below, perltidy does not introduce any tab characters into
407 your file, and it removes any tabs from the code (unless requested
408 not to do so with -fws). If you have any tabs in your comments,
409 quotes, or here-documents, they will remain.
410 -et=n, --entab-leading-whitespace
412 This flag causes each n initial space characters to be replaced
413 by one tab character. Note that the integer n is completely
414 independent of the integer specified for indentation parameter,
415 -i=n.
416 -t, --tabs
418 This flag causes one leading tab character to be inserted for
419 each level of indentation. Certain other features are
420 incompatible with this option, and if these options are also
421 given, then a warning message will be issued and this flag will
422 be unset. One example is the -lp option.
423 -dt=n, --default-tabsize=n
425 If the the first line of code passed to perltidy contains
426 leading tabs but no tab scheme is specified for the output
427 stream then perltidy must guess how many spaces correspond to
428 each leading tab. This number of spaces n corresponding to
429 each leading tab of the input stream may be specified with
430 -dt=n. The default is n=8.
431 This flag has no effect if a tab scheme is specified for the
433 output stream, because then the input stream is assumed to use
434 the same tab scheme and indentation spaces as for the output
435 stream (any other assumption would lead to unstable editing).
436 -syn, --check-syntax
438 This flag causes perltidy to run "perl -c -T" to check syntax of
439 input and output. (To change the flags passed to perl, see the
440 next item, -pscf). The results are written to the .LOG file, which
441 will be saved if an error is detected in the output script. The
442 output script is not checked if the input script has a syntax
443 error. Perltidy does its own checking, but this option employs
444 perl to get a "second opinion".
445 If perl reports errors in the input file, they will not be reported
447 in the error output unless the --warning-output flag is given.
448 The default is NOT to do this type of syntax checking (although
450 perltidy will still do as much self-checking as possible). The
451 reason is that it causes all code in BEGIN blocks to be executed,
452 for all modules being used, and this opens the door to security
453 issues and infinite loops when running perltidy.
454 -pscf=s, -perl-syntax-check-flags=s
456 When perl is invoked to check syntax, the normal flags are "-c -T".
457 In addition, if the -x flag is given to perltidy, then perl will
458 also be passed a -x flag. It should not normally be necessary to
459 change these flags, but it can be done with the -pscf=s flag. For
460 example, if the taint flag, "-T", is not wanted, the flag could be
461 set to be just -pscf=-c.
462 Perltidy will pass your string to perl with the exception that it
464 will add a -c and -x if appropriate. The .LOG file will show
465 exactly what flags were passed to perl.
466 -io, --indent-only
468 This flag is used to deactivate all formatting and line break
469 changes within non-blank lines of code. When it is in effect, the
470 only change to the script will be to the indentation and blank
471 lines. And any flags controlling whitespace and newlines will be
472 ignored. You might want to use this if you are perfectly happy
473 with your whitespace and line breaks, and merely want perltidy to
474 handle the indentation. (This also speeds up perltidy by well over
475 a factor of two, so it might be useful when perltidy is merely
476 being used to help find a brace error in a large script).
477 Setting this flag is equivalent to setting --freeze-newlines and
479 --freeze-whitespace.
480 If you also want to keep your existing blank lines exactly as they
482 are, you can add --freeze-blank-lines.
483 -ole=s, --output-line-ending=s
485 where s="win", "dos", "unix", or "mac". This flag tells perltidy
486 to output line endings for a specific system. Normally, perltidy
487 writes files with the line separator character of the host system.
488 The "win" and "dos" flags have an identical result.
489 -ple, --preserve-line-endings
491 This flag tells perltidy to write its output files with the same
492 line endings as the input file, if possible. It should work for
493 dos, unix, and mac line endings. It will only work if perltidy
494 input comes from a filename (rather than stdin, for example). If
495 perltidy has trouble determining the input file line ending, it
496 will revert to the default behavior of using the line ending of the
497 host system.
498 -it=n, --iterations=n
500 This flag causes perltidy to do n complete iterations. The reason
501 for this flag is that code beautification is an iterative process
502 and in some cases the output from perltidy can be different if it
503 is applied a second time. For most purposes the default of n=1
504 should be satisfactory. However n=2 can be useful when a major
505 style change is being made, or when code is being beautified on
506 check-in to a source code control system. It has been found to be
507 extremely rare for the output to change after 2 iterations. If a
508 value n is greater than 2 is input then a convergence test will be
509 used to stop the iterations as soon as possible, almost always
510 after 2 iterations. See the next item for a simplified iteration
511 control.
512 This flag has no effect when perltidy is used to generate html.
514 -conv, --converge
516 This flag is equivalent to -it=4 and is included to simplify
517 iteration control. For all practical purposes one either does or
518 does not want to be sure that the output is converged, and there is
519 no penalty to using a large iteration limit since perltidy will
520 check for convergence and stop iterating as soon as possible. The
521 default is -nconv (no convergence check). Using -conv will
522 approximately double run time since normally one extra iteration is
523 required to verify convergence.
524 Code Indentation Control
526 -ci=n, --continuation-indentation=n
527 Continuation indentation is extra indentation spaces applied when a
528 long line is broken. The default is n=2, illustrated here:
529 my $level = # -ci=2
531 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
532 The same example, with n=0, is a little harder to read:
534 my $level = # -ci=0
536 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
537 The value given to -ci is also used by some commands when a small
539 space is required. Examples are commands for outdenting labels,
540 -ola, and control keywords, -okw.
541 When default values are not used, it is suggested that the value n
543 given with -ci=n be no more than about one-half of the number of
544 spaces assigned to a full indentation level on the -i=n command.
545 -sil=n --starting-indentation-level=n
547 By default, perltidy examines the input file and tries to determine
548 the starting indentation level. While it is often zero, it may not
549 be zero for a code snippet being sent from an editing session.
550 To guess the starting indentation level perltidy simply assumes
552 that indentation scheme used to create the code snippet is the same
553 as is being used for the current perltidy process. This is the
554 only sensible guess that can be made. It should be correct if this
555 is true, but otherwise it probably won't. For example, if the
556 input script was written with -i=2 and the current peltidy flags
557 have -i=4, the wrong initial indentation will be guessed for a code
558 snippet which has non-zero initial indentation. Likewise, if an
559 entabbing scheme is used in the input script and not in the current
560 process then the guessed indentation will be wrong.
561 If the default method does not work correctly, or you want to
563 change the starting level, use -sil=n, to force the starting level
564 to be n.
565 List indentation using -lp, --line-up-parentheses
567 By default, perltidy indents lists with 4 spaces, or whatever value
568 is specified with -i=n. Here is a small list formatted in this
569 way:
570 # perltidy (default)
572 @month_of_year = (
573 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
574 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
575 );
576 Use the -lp flag to add extra indentation to cause the data to
578 begin past the opening parentheses of a sub call or list, or
579 opening square bracket of an anonymous array, or opening curly
580 brace of an anonymous hash. With this option, the above list would
581 become:
582 # perltidy -lp
584 @month_of_year = (
585 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
586 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
587 );
588 If the available line length (see -l=n ) does not permit this much
590 space, perltidy will use less. For alternate placement of the
591 closing paren, see the next section.
592 This option has no effect on code BLOCKS, such as if/then/else
594 blocks, which always use whatever is specified with -i=n. Also,
595 the existence of line breaks and/or block comments between the
596 opening and closing parens may cause perltidy to temporarily revert
597 to its default method.
598 Note: The -lp option may not be used together with the -t tabs
600 option. It may, however, be used with the -et=n tab method.
601 In addition, any parameter which significantly restricts the
603 ability of perltidy to choose newlines will conflict with -lp and
604 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
605 and -ndnl. The reason is that the -lp indentation style can
606 require the careful coordination of an arbitrary number of break
607 points in hierarchical lists, and these flags may prevent that.
608 -cti=n, --closing-token-indentation
610 The -cti=n flag controls the indentation of a line beginning with a
611 ")", "]", or a non-block "}". Such a line receives:
612 -cti = 0 no extra indentation (default)
614 -cti = 1 extra indentation such that the closing token
615 aligns with its opening token.
616 -cti = 2 one extra indentation level if the line looks like:
617 ); or ]; or };
618 -cti = 3 one extra indentation level always
619 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
621 section).
622 # perltidy -lp -cti=1
624 @month_of_year = (
625 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
626 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
627 );
628 # perltidy -lp -cti=2
630 @month_of_year = (
631 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
632 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
633 );
634 These flags are merely hints to the formatter and they may not
636 always be followed. In particular, if -lp is not being used, the
637 indentation for cti=1 is constrained to be no more than one
638 indentation level.
639 If desired, this control can be applied independently to each of
641 the closing container token types. In fact, -cti=n is merely an
642 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
643 --closing-paren-indentation controls )'s, -csbi or
644 --closing-square-bracket-indentation controls ]'s, -cbi or
645 --closing-brace-indentation controls non-block }'s.
646 -icp, --indent-closing-paren
648 The -icp flag is equivalent to -cti=2, described in the previous
649 section. The -nicp flag is equivalent -cti=0. They are included
650 for backwards compatibility.
651 -icb, --indent-closing-brace
653 The -icb option gives one extra level of indentation to a brace
654 which terminates a code block . For example,
655 if ($task) {
657 yyy();
658 } # -icb
659 else {
660 zzz();
661 }
662 The default is not to do this, indicated by -nicb.
664 -olq, --outdent-long-quotes
666 When -olq is set, lines which is a quoted string longer than the
667 value maximum-line-length will have their indentation removed to
668 make them more readable. This is the default. To prevent such
669 out-denting, use -nolq or --nooutdent-long-lines.
670 -oll, --outdent-long-lines
672 This command is equivalent to --outdent-long-quotes and
673 --outdent-long-comments, and it is included for compatibility with
674 previous versions of perltidy. The negation of this also works,
675 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
676 and -nolc.
677 Outdenting Labels: -ola, --outdent-labels
679 This command will cause labels to be outdented by 2 spaces (or
680 whatever -ci has been set to), if possible. This is the default.
681 For example:
682 my $i;
684 LOOP: while ( $i = <FOTOS> ) {
685 chomp($i);
686 next unless $i;
687 fixit($i);
688 }
689 Use -nola to not outdent labels.
691 Outdenting Keywords
693 -okw, --outdent-keywords
694 The command -okw will will cause certain leading control
695 keywords to be outdented by 2 spaces (or whatever -ci has been
696 set to), if possible. By default, these keywords are "redo",
697 "next", "last", "goto", and "return". The intention is to make
698 these control keywords easier to see. To change this list of
699 keywords being outdented, see the next section.
700 For example, using "perltidy -okw" on the previous example
702 gives:
703 my $i;
705 LOOP: while ( $i = <FOTOS> ) {
706 chomp($i);
707 next unless $i;
708 fixit($i);
709 }
710 The default is not to do this.
712 Specifying Outdented Keywords: -okwl=string,
714 --outdent-keyword-list=string
715 This command can be used to change the keywords which are
716 outdented with the -okw command. The parameter string is a
717 required list of perl keywords, which should be placed in
718 quotes if there are more than one. By itself, it does not
719 cause any outdenting to occur, so the -okw command is still
720 required.
721 For example, the commands "-okwl="next last redo goto" -okw"
723 will cause those four keywords to be outdented. It is probably
724 simplest to place any -okwl command in a .perltidyrc file.
725 Whitespace Control
727 Whitespace refers to the blank space between variables, operators, and
728 other code tokens.
729 -fws, --freeze-whitespace
731 This flag causes your original whitespace to remain unchanged, and
732 causes the rest of the whitespace commands in this section, the
733 Code Indentation section, and the Comment Control section to be
734 ignored.
735 Tightness of curly braces, parentheses, and square brackets.
737 Here the term "tightness" will mean the closeness with which pairs
738 of enclosing tokens, such as parentheses, contain the quantities
739 within. A numerical value of 0, 1, or 2 defines the tightness,
740 with 0 being least tight and 2 being most tight. Spaces within
741 containers are always symmetric, so if there is a space after a "("
742 then there will be a space before the corresponding ")".
743 The -pt=n or --paren-tightness=n parameter controls the space
745 within parens. The example below shows the effect of the three
746 possible values, 0, 1, and 2:
747 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
749 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
750 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
751 When n is 0, there is always a space to the right of a '(' and to
753 the left of a ')'. For n=2 there is never a space. For n=1, the
754 default, there is a space unless the quantity within the parens is
755 a single token, such as an identifier or quoted string.
756 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
758 controls the space within square brackets, as illustrated below.
759 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
761 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
762 $width = $col[$j + $k] - $col[$j]; # -sbt=2
763 Curly braces which do not contain code blocks are controlled by the
765 parameter -bt=n or --brace-tightness=n.
766 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
768 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
769 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
770 And finally, curly braces which contain blocks of code are
772 controlled by the parameter -bbt=n or --block-brace-tightness=n as
773 illustrated in the example below.
774 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
776 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
777 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
778 To simplify input in the case that all of the tightness flags have
780 the same value <n>, the parameter <-act=n> or
781 --all-containers-tightness=n is an abbreviation for the combination
782 <-pt=n -sbt=n -bt=n -bbt=n>.
783 -tso, --tight-secret-operators
785 The flag -tso causes certain perl token sequences (secret
786 operators) which might be considered to be a single operator to be
787 formatted "tightly" (without spaces). The operators currently
788 modified by this flag are:
789 0+ +0 ()x!! ~~<> ,=> =( )=
791 For example the sequence 0 +, which converts a string to a number,
793 would be formatted without a space: 0+ when the -tso flag is set.
794 This flag is off by default.
795 -sts, --space-terminal-semicolon
797 Some programmers prefer a space before all terminal semicolons.
798 The default is for no such space, and is indicated with -nsts or
799 --nospace-terminal-semicolon.
800 $i = 1 ; # -sts
802 $i = 1; # -nsts (default)
803 -sfs, --space-for-semicolon
805 Semicolons within for loops may sometimes be hard to see,
806 particularly when commas are also present. This option places
807 spaces on both sides of these special semicolons, and is the
808 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
809 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
811 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
812 -asc, --add-semicolons
814 Setting -asc allows perltidy to add any missing optional semicolon
815 at the end of a line which is followed by a closing curly brace on
816 the next line. This is the default, and may be deactivated with
817 -nasc or --noadd-semicolons.
818 -dsm, --delete-semicolons
820 Setting -dsm allows perltidy to delete extra semicolons which are
821 simply empty statements. This is the default, and may be
822 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
823 are not deleted, however, if they would promote a side comment to a
824 block comment).
825 -aws, --add-whitespace
827 Setting this option allows perltidy to add certain whitespace
828 improve code readability. This is the default. If you do not want
829 any whitespace added, but are willing to have some whitespace
830 deleted, use -naws. (Use -fws to leave whitespace completely
831 unchanged).
832 -dws, --delete-old-whitespace
834 Setting this option allows perltidy to remove some old whitespace
835 between characters, if necessary. This is the default. If you do
836 not want any old whitespace removed, use -ndws or
837 --nodelete-old-whitespace.
838 Detailed whitespace controls around tokens
840 For those who want more detailed control over the whitespace around
841 tokens, there are four parameters which can directly modify the
842 default whitespace rules built into perltidy for any token. They
843 are:
844 -wls=s or --want-left-space=s,
846 -nwls=s or --nowant-left-space=s,
848 -wrs=s or --want-right-space=s,
850 -nwrs=s or --nowant-right-space=s.
852 These parameters are each followed by a quoted string, s,
854 containing a list of token types. No more than one of each of
855 these parameters should be specified, because repeating a command-
856 line parameter always overwrites the previous one before perltidy
857 ever sees it.
858 To illustrate how these are used, suppose it is desired that there
860 be no space on either side of the token types = + - / *. The
861 following two parameters would specify this desire:
862 -nwls="= + - / *" -nwrs="= + - / *"
864 (Note that the token types are in quotes, and that they are
866 separated by spaces). With these modified whitespace rules, the
867 following line of math:
868 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
870 becomes this:
872 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
874 These parameters should be considered to be hints to perltidy
876 rather than fixed rules, because perltidy must try to resolve
877 conflicts that arise between them and all of the other rules that
878 it uses. One conflict that can arise is if, between two tokens,
879 the left token wants a space and the right one doesn't. In this
880 case, the token not wanting a space takes priority.
881 It is necessary to have a list of all token types in order to
883 create this type of input. Such a list can be obtained by the
884 command --dump-token-types. Also try the -D flag on a short
885 snippet of code and look at the .DEBUG file to see the
886 tokenization.
887 WARNING Be sure to put these tokens in quotes to avoid having them
889 misinterpreted by your command shell.
890 Space between specific keywords and opening paren
892 When an opening paren follows a Perl keyword, no space is
893 introduced after the keyword, unless it is (by default) one of
894 these:
895 my local our and or eq ne if else elsif until unless
897 while for foreach return switch case given when
898 These defaults can be modified with two commands:
900 -sak=s or --space-after-keyword=s adds keywords.
902 -nsak=s or --nospace-after-keyword=s removes keywords.
904 where s is a list of keywords (in quotes if necessary). For
906 example,
907 my ( $a, $b, $c ) = @_; # default
909 my( $a, $b, $c ) = @_; # -nsak="my local our"
910 The abbreviation -nsak='*' is equivalent to including all of the
912 keywords in the above list.
913 When both -nsak=s and -sak=s commands are included, the -nsak=s
915 command is executed first. For example, to have space after only
916 the keywords (my, local, our) you could use -nsak="*" -sak="my
917 local our".
918 To put a space after all keywords, see the next item.
920 Space between all keywords and opening parens
922 When an opening paren follows a function or keyword, no space is
923 introduced after the keyword except for the keywords noted in the
924 previous item. To always put a space between a function or keyword
925 and its opening paren, use the command:
926 -skp or --space-keyword-paren
928 You will probably also want to use the flag -sfp (next item) too.
930 Space between all function names and opening parens
932 When an opening paren follows a function the default is not to
933 introduce a space. To cause a space to be introduced use:
934 -sfp or --space-function-paren
936 myfunc( $a, $b, $c ); # default
938 myfunc ( $a, $b, $c ); # -sfp
939 You will probably also want to use the flag -skp (previous item)
941 too.
942 Trimming whitespace around "qw" quotes
944 -tqw or --trim-qw provide the default behavior of trimming spaces
945 around multi-line "qw" quotes and indenting them appropriately.
946 -ntqw or --notrim-qw cause leading and trailing whitespace around
948 multi-line "qw" quotes to be left unchanged. This option will not
949 normally be necessary, but was added for testing purposes, because
950 in some versions of perl, trimming "qw" quotes changes the syntax
951 tree.
952 Comment Controls
954 Perltidy has a number of ways to control the appearance of both block
955 comments and side comments. The term block comment here refers to a
956 full-line comment, whereas side comment will refer to a comment which
957 appears on a line to the right of some code.
958 -ibc, --indent-block-comments
960 Block comments normally look best when they are indented to the
961 same level as the code which follows them. This is the default
962 behavior, but you may use -nibc to keep block comments left-
963 justified. Here is an example:
964 # this comment is indented (-ibc, default)
966 if ($task) { yyy(); }
967 The alternative is -nibc:
969 # this comment is not indented (-nibc)
971 if ($task) { yyy(); }
972 See also the next item, -isbc, as well as -sbc, for other ways to
974 have some indented and some outdented block comments.
975 -isbc, --indent-spaced-block-comments
977 If there is no leading space on the line, then the comment will not
978 be indented, and otherwise it may be.
979 If both -ibc and -isbc are set, then -isbc takes priority.
981 -olc, --outdent-long-comments
983 When -olc is set, lines which are full-line (block) comments longer
984 than the value maximum-line-length will have their indentation
985 removed. This is the default; use -nolc to prevent outdenting.
986 -msc=n, --minimum-space-to-comment=n
988 Side comments look best when lined up several spaces to the right
989 of code. Perltidy will try to keep comments at least n spaces to
990 the right. The default is n=4 spaces.
991 -fpsc=n, --fixed-position-side-comment=n
993 This parameter tells perltidy to line up side comments in column
994 number n whenever possible. The default, n=0, is not do do this.
995 -iscl, --ignore-side-comment-lengths
997 This parameter causes perltidy to ignore the length of side
998 comments when setting line breaks. The default, -niscl, is to
999 include the length of side comments when breaking lines to stay
1000 within the length prescribed by the -l=n maximum line length
1001 parameter. For example, the following long single line would
1002 remain intact with -l=80 and -iscl:
1003 perltidy -l=80 -iscl
1005 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1006 whereas without the -iscl flag the line will be broken:
1008 perltidy -l=80
1010 $vmsfile =~ s/;[\d\-]*$//
1011 ; # Clip off version number; we can use a newer version as well
1012 -hsc, --hanging-side-comments
1014 By default, perltidy tries to identify and align "hanging side
1015 comments", which are something like this:
1016 my $IGNORE = 0; # This is a side comment
1018 # This is a hanging side comment
1019 # And so is this
1020 A comment is considered to be a hanging side comment if (1) it
1022 immediately follows a line with a side comment, or another hanging
1023 side comment, and (2) there is some leading whitespace on the line.
1024 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1025 If block comments are preceded by a blank line, or have no leading
1026 whitespace, they will not be mistaken as hanging side comments.
1027 Closing Side Comments
1029 A closing side comment is a special comment which perltidy can
1030 automatically create and place after the closing brace of a code
1031 block. They can be useful for code maintenance and debugging. The
1032 command -csc (or --closing-side-comments) adds or updates closing
1033 side comments. For example, here is a small code snippet
1034 sub message {
1036 if ( !defined( $_[0] ) ) {
1037 print("Hello, World\n");
1038 }
1039 else {
1040 print( $_[0], "\n" );
1041 }
1042 }
1043 And here is the result of processing with "perltidy -csc":
1045 sub message {
1047 if ( !defined( $_[0] ) ) {
1048 print("Hello, World\n");
1049 }
1050 else {
1051 print( $_[0], "\n" );
1052 }
1053 } ## end sub message
1054 A closing side comment was added for "sub message" in this case,
1056 but not for the "if" and "else" blocks, because they were below the
1057 6 line cutoff limit for adding closing side comments. This limit
1058 may be changed with the -csci command, described below.
1059 The command -dcsc (or --delete-closing-side-comments) reverses this
1061 process and removes these comments.
1062 Several commands are available to modify the behavior of these two
1064 basic commands, -csc and -dcsc:
1065 -csci=n, or --closing-side-comment-interval=n
1067 where "n" is the minimum number of lines that a block must have
1068 in order for a closing side comment to be added. The default
1069 value is "n=6". To illustrate:
1070 # perltidy -csci=2 -csc
1072 sub message {
1073 if ( !defined( $_[0] ) ) {
1074 print("Hello, World\n");
1075 } ## end if ( !defined( $_[0] ))
1076 else {
1077 print( $_[0], "\n" );
1078 } ## end else [ if ( !defined( $_[0] ))
1079 } ## end sub message
1080 Now the "if" and "else" blocks are commented. However, now
1082 this has become very cluttered.
1083 -cscp=string, or --closing-side-comment-prefix=string
1085 where string is the prefix used before the name of the block
1086 type. The default prefix, shown above, is "## end". This
1087 string will be added to closing side comments, and it will also
1088 be used to recognize them in order to update, delete, and
1089 format them. Any comment identified as a closing side comment
1090 will be placed just a single space to the right of its closing
1091 brace.
1092 -cscl=string, or --closing-side-comment-list-string
1094 where "string" is a list of block types to be tagged with
1095 closing side comments. By default, all code block types
1096 preceded by a keyword or label (such as "if", "sub", and so on)
1097 will be tagged. The -cscl command changes the default list to
1098 be any selected block types; see "Specifying Block Types". For
1099 example, the following command requests that only "sub"'s,
1100 labels, "BEGIN", and "END" blocks be affected by any -csc or
1101 -dcsc operation:
1102 -cscl="sub : BEGIN END"
1104 -csct=n, or --closing-side-comment-maximum-text=n
1106 The text appended to certain block types, such as an "if"
1107 block, is whatever lies between the keyword introducing the
1108 block, such as "if", and the opening brace. Since this might
1109 be too much text for a side comment, there needs to be a limit,
1110 and that is the purpose of this parameter. The default value
1111 is "n=20", meaning that no additional tokens will be appended
1112 to this text after its length reaches 20 characters. Omitted
1113 text is indicated with "...". (Tokens, including sub names,
1114 are never truncated, however, so actual lengths may exceed
1115 this). To illustrate, in the above example, the appended text
1116 of the first block is " ( !defined( $_[0] )...". The existing
1117 limit of "n=20" caused this text to be truncated, as indicated
1118 by the "...". See the next flag for additional control of the
1119 abbreviated text.
1120 -cscb, or --closing-side-comments-balanced
1122 As discussed in the previous item, when the closing-side-
1123 comment-maximum-text limit is exceeded the comment text must be
1124 truncated. Older versions of perltidy terminated with three
1125 dots, and this can still be achieved with -ncscb:
1126 perltidy -csc -ncscb
1128 } ## end foreach my $foo (sort { $b cmp $a ...
1129 However this causes a problem with editors editors which cannot
1131 recognize comments or are not configured to do so because they
1132 cannot "bounce" around in the text correctly. The -cscb flag
1133 has been added to help them by appending appropriate balancing
1134 structure:
1135 perltidy -csc -cscb
1137 } ## end foreach my $foo (sort { $b cmp $a ... })
1138 The default is -cscb.
1140 -csce=n, or --closing-side-comment-else-flag=n
1142 The default, n=0, places the text of the opening "if" statement
1143 after any terminal "else".
1144 If n=2 is used, then each "elsif" is also given the text of the
1146 opening "if" statement. Also, an "else" will include the text
1147 of a preceding "elsif" statement. Note that this may result
1148 some long closing side comments.
1149 If n=1 is used, the results will be the same as n=2 whenever
1151 the resulting line length is less than the maximum allowed.
1152 =item -cscb, or --closing-side-comments-balanced
1153 When using closing-side-comments, and the closing-side-comment-
1155 maximum-text limit is exceeded, then the comment text must be
1156 abbreviated. It is terminated with three dots if the -cscb
1157 flag is negated:
1158 perltidy -csc -ncscb
1160 } ## end foreach my $foo (sort { $b cmp $a ...
1161 This causes a problem with older editors which do not recognize
1163 comments because they cannot "bounce" around in the text
1164 correctly. The -cscb flag tries to help them by appending
1165 appropriate terminal balancing structures:
1166 perltidy -csc -cscb
1168 } ## end foreach my $foo (sort { $b cmp $a ... })
1169 The default is -cscb.
1171 -cscw, or --closing-side-comment-warnings
1173 This parameter is intended to help make the initial transition
1174 to the use of closing side comments. It causes two things to
1175 happen if a closing side comment replaces an existing,
1176 different closing side comment: first, an error message will
1177 be issued, and second, the original side comment will be placed
1178 alone on a new specially marked comment line for later
1179 attention.
1180 The intent is to avoid clobbering existing hand-written side
1182 comments which happen to match the pattern of closing side
1183 comments. This flag should only be needed on the first run with
1184 -csc.
1185 Important Notes on Closing Side Comments:
1187 · Closing side comments are only placed on lines terminated with
1189 a closing brace. Certain closing styles, such as the use of
1190 cuddled elses (-ce), preclude the generation of some closing
1191 side comments.
1192 · Please note that adding or deleting of closing side comments
1194 takes place only through the commands -csc or -dcsc. The other
1195 commands, if used, merely modify the behavior of these two
1196 commands.
1197 · It is recommended that the -cscw flag be used along with -csc
1199 on the first use of perltidy on a given file. This will
1200 prevent loss of any existing side comment data which happens to
1201 have the csc prefix.
1202 · Once you use -csc, you should continue to use it so that any
1204 closing side comments remain correct as code changes.
1205 Otherwise, these comments will become incorrect as the code is
1206 updated.
1207 · If you edit the closing side comments generated by perltidy,
1209 you must also change the prefix to be different from the
1210 closing side comment prefix. Otherwise, your edits will be
1211 lost when you rerun perltidy with -csc. For example, you
1212 could simply change "## end" to be "## End", since the test is
1213 case sensitive. You may also want to use the -ssc flag to keep
1214 these modified closing side comments spaced the same as actual
1215 closing side comments.
1216 · Temporarily generating closing side comments is a useful
1218 technique for exploring and/or debugging a perl script,
1219 especially one written by someone else. You can always remove
1220 them with -dcsc.
1221 Static Block Comments
1223 Static block comments are block comments with a special leading
1224 pattern, "##" by default, which will be treated slightly
1225 differently from other block comments. They effectively behave as
1226 if they had glue along their left and top edges, because they stick
1227 to the left edge and previous line when there is no blank spaces in
1228 those places. This option is particularly useful for controlling
1229 how commented code is displayed.
1230 -sbc, --static-block-comments
1232 When -sbc is used, a block comment with a special leading
1233 pattern, "##" by default, will be treated specially.
1234 Comments so identified are treated as follows:
1236 · If there is no leading space on the line, then the comment
1238 will not be indented, and otherwise it may be,
1239 · no new blank line will be inserted before such a comment,
1241 and
1242 · such a comment will never become a hanging side comment.
1244 For example, assuming @month_of_year is left-adjusted:
1246 @month_of_year = ( # -sbc (default)
1248 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1249 ## 'Dec', 'Nov'
1250 'Nov', 'Dec');
1251 Without this convention, the above code would become
1253 @month_of_year = ( # -nsbc
1255 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1256 ## 'Dec', 'Nov'
1258 'Nov', 'Dec'
1259 );
1260 which is not as clear. The default is to use -sbc. This may
1262 be deactivated with -nsbc.
1263 -sbcp=string, --static-block-comment-prefix=string
1265 This parameter defines the prefix used to identify static block
1266 comments when the -sbc parameter is set. The default prefix is
1267 "##", corresponding to "-sbcp=##". The prefix is actually part
1268 of a perl pattern used to match lines and it must either begin
1269 with "#" or "^#". In the first case a prefix ^\s* will be
1270 added to match any leading whitespace, while in the second case
1271 the pattern will match only comments with no leading
1272 whitespace. For example, to identify all comments as static
1273 block comments, one would use "-sbcp=#". To identify all left-
1274 adjusted comments as static block comments, use "-sbcp='^#'".
1275 Please note that -sbcp merely defines the pattern used to
1277 identify static block comments; it will not be used unless the
1278 switch -sbc is set. Also, please be aware that since this
1279 string is used in a perl regular expression which identifies
1280 these comments, it must enable a valid regular expression to be
1281 formed.
1282 A pattern which can be useful is:
1284 -sbcp=^#{2,}[^\s#]
1286 This pattern requires a static block comment to have at least
1288 one character which is neither a # nor a space. It allows a
1289 line containing only '#' characters to be rejected as a static
1290 block comment. Such lines are often used at the start and end
1291 of header information in subroutines and should not be
1292 separated from the intervening comments, which typically begin
1293 with just a single '#'.
1294 -osbc, --outdent-static-block-comments
1296 The command -osbc will will cause static block comments to be
1297 outdented by 2 spaces (or whatever -ci=n has been set to), if
1298 possible.
1299 Static Side Comments
1301 Static side comments are side comments with a special leading
1302 pattern. This option can be useful for controlling how commented
1303 code is displayed when it is a side comment.
1304 -ssc, --static-side-comments
1306 When -ssc is used, a side comment with a static leading
1307 pattern, which is "##" by default, will be be spaced only a
1308 single space from previous character, and it will not be
1309 vertically aligned with other side comments.
1310 The default is -nssc.
1312 -sscp=string, --static-side-comment-prefix=string
1314 This parameter defines the prefix used to identify static side
1315 comments when the -ssc parameter is set. The default prefix is
1316 "##", corresponding to "-sscp=##".
1317 Please note that -sscp merely defines the pattern used to
1319 identify static side comments; it will not be used unless the
1320 switch -ssc is set. Also, note that this string is used in a
1321 perl regular expression which identifies these comments, so it
1322 must enable a valid regular expression to be formed.
1323 Skipping Selected Sections of Code
1325 Selected lines of code may be passed verbatim to the output without any
1326 formatting. This feature is enabled by default but can be disabled
1327 with the --noformat-skipping or -nfs flag. It should be used sparingly
1328 to avoid littering code with markers, but it might be helpful for
1329 working around occasional problems. For example it might be useful for
1330 keeping the indentation of old commented code unchanged, keeping
1331 indentation of long blocks of aligned comments unchanged, keeping
1332 certain list formatting unchanged, or working around a glitch in
1333 perltidy.
1334 -fs, --format-skipping
1336 This flag, which is enabled by default, causes any code between
1337 special beginning and ending comment markers to be passed to the
1338 output without formatting. The default beginning marker is #<<<
1339 and the default ending marker is #>>> but they may be changed (see
1340 next items below). Additional text may appear on these special
1341 comment lines provided that it is separated from the marker by at
1342 least one space. For example
1343 #<<< do not let perltidy touch this
1345 my @list = (1,
1346 1, 1,
1347 1, 2, 1,
1348 1, 3, 3, 1,
1349 1, 4, 6, 4, 1,);
1350 #>>>
1351 The comment markers may be placed at any location that a block
1353 comment may appear. If they do not appear to be working, use the
1354 -log flag and examine the .LOG file. Use -nfs to disable this
1355 feature.
1356 -fsb=string, --format-skipping-begin=string
1358 The -fsb=string parameter may be used to change the beginning
1359 marker for format skipping. The default is equivalent to
1360 -fsb='#<<<'. The string that you enter must begin with a # and
1361 should be in quotes as necessary to get past the command shell of
1362 your system. It is actually the leading text of a pattern that is
1363 constructed by appending a '\s', so you must also include
1364 backslashes for characters to be taken literally rather than as
1365 patterns.
1366 Some examples show how example strings become patterns:
1368 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1370 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1371 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1372 -fse=string, --format-skipping-end=string
1374 The -fsb=string is the corresponding parameter used to change the
1375 ending marker for format skipping. The default is equivalent to
1376 -fse='#<<<'.
1377 Line Break Control
1379 The parameters in this section control breaks after non-blank lines of
1380 code. Blank lines are controlled separately by parameters in the
1381 section "Blank Line Control".
1382 -fnl, --freeze-newlines
1384 If you do not want any changes to the line breaks within lines of
1385 code in your script, set -fnl, and they will remain fixed, and the
1386 rest of the commands in this section and sections "Controlling List
1387 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1388 want to use -noll with this.
1389 Note: If you also want to keep your blank lines exactly as they
1391 are, you can use the -fbl flag which is described in the section
1392 "Blank Line Control".
1393 -ce, --cuddled-else
1395 Enable the "cuddled else" style, in which "else" and "elsif" are
1396 follow immediately after the curly brace closing the previous
1397 block. The default is not to use cuddled elses, and is indicated
1398 with the flag -nce or --nocuddled-else. Here is a comparison of
1399 the alternatives:
1400 if ($task) {
1402 yyy();
1403 } else { # -ce
1404 zzz();
1405 }
1406 if ($task) {
1408 yyy();
1409 }
1410 else { # -nce (default)
1411 zzz();
1412 }
1413 -bl, --opening-brace-on-new-line
1415 Use the flag -bl to place the opening brace on a new line:
1416 if ( $input_file eq '-' ) # -bl
1418 {
1419 important_function();
1420 }
1421 This flag applies to all structural blocks, including named sub's
1423 (unless the -sbl flag is set -- see next item).
1424 The default style, -nbl, places an opening brace on the same line
1426 as the keyword introducing it. For example,
1427 if ( $input_file eq '-' ) { # -nbl (default)
1429 -sbl, --opening-sub-brace-on-new-line
1431 The flag -sbl can be used to override the value of -bl for the
1432 opening braces of named sub's. For example,
1433 perltidy -sbl
1435 produces this result:
1437 sub message
1439 {
1440 if (!defined($_[0])) {
1441 print("Hello, World\n");
1442 }
1443 else {
1444 print($_[0], "\n");
1445 }
1446 }
1447 This flag is negated with -nsbl. If -sbl is not specified, the
1449 value of -bl is used.
1450 -asbl, --opening-anonymous-sub-brace-on-new-line
1452 The flag -asbl is like the -sbl flag except that it applies to
1453 anonymous sub's instead of named subs. For example
1454 perltidy -asbl
1456 produces this result:
1458 $a = sub
1460 {
1461 if ( !defined( $_[0] ) ) {
1462 print("Hello, World\n");
1463 }
1464 else {
1465 print( $_[0], "\n" );
1466 }
1467 };
1468 This flag is negated with -nasbl, and the default is -nasbl.
1470 -bli, --brace-left-and-indent
1472 The flag -bli is the same as -bl but in addition it causes one unit
1473 of continuation indentation ( see -ci ) to be placed before an
1474 opening and closing block braces.
1475 For example,
1477 if ( $input_file eq '-' ) # -bli
1479 {
1480 important_function();
1481 }
1482 By default, this extra indentation occurs for blocks of type: if,
1484 elsif, else, unless, for, foreach, sub, while, until, and also with
1485 a preceding label. The next item shows how to change this.
1486 -blil=s, --brace-left-and-indent-list=s
1488 Use this parameter to change the types of block braces for which
1489 the -bli flag applies; see "Specifying Block Types". For example,
1490 -blil='if elsif else' would apply it to only "if/elsif/else"
1491 blocks.
1492 -bar, --opening-brace-always-on-right
1494 The default style, -nbl places the opening code block brace on a
1495 new line if it does not fit on the same line as the opening
1496 keyword, like this:
1497 if ( $bigwasteofspace1 && $bigwasteofspace2
1499 || $bigwasteofspace3 && $bigwasteofspace4 )
1500 {
1501 big_waste_of_time();
1502 }
1503 To force the opening brace to always be on the right, use the -bar
1505 flag. In this case, the above example becomes
1506 if ( $bigwasteofspace1 && $bigwasteofspace2
1508 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1509 big_waste_of_time();
1510 }
1511 A conflict occurs if both -bl and -bar are specified.
1513 -otr, --opening-token-right and related flags
1515 The -otr flag is a hint that perltidy should not place a break
1516 between a comma and an opening token. For example:
1517 # default formatting
1519 push @{ $self->{$module}{$key} },
1520 {
1521 accno => $ref->{accno},
1522 description => $ref->{description}
1523 };
1524 # perltidy -otr
1526 push @{ $self->{$module}{$key} }, {
1527 accno => $ref->{accno},
1528 description => $ref->{description}
1529 };
1530 The flag -otr is actually an abbreviation for three other flags
1532 which can be used to control parens, hash braces, and square
1533 brackets separately if desired:
1534 -opr or --opening-paren-right
1536 -ohbr or --opening-hash-brace-right
1537 -osbr or --opening-square-bracket-right
1538 Vertical tightness of non-block curly braces, parentheses, and square
1540 brackets.
1541 These parameters control what shall be called vertical tightness.
1542 Here are the main points:
1543 · Opening tokens (except for block braces) are controlled by
1545 -vt=n, or --vertical-tightness=n, where
1546 -vt=0 always break a line after opening token (default).
1548 -vt=1 do not break unless this would produce more than one
1549 step in indentation in a line.
1550 -vt=2 never break a line after opening token
1551 · You must also use the -lp flag when you use the -vt flag; the
1553 reason is explained below.
1554 · Closing tokens (except for block braces) are controlled by
1556 -vtc=n, or --vertical-tightness-closing=n, where
1557 -vtc=0 always break a line before a closing token (default),
1559 -vtc=1 do not break before a closing token which is followed
1560 by a semicolon or another closing token, and is not in
1561 a list environment.
1562 -vtc=2 never break before a closing token.
1563 The rules for -vtc=1 are designed to maintain a reasonable
1565 balance between tightness and readability in complex lists.
1566 · Different controls may be applied to to different token types,
1568 and it is also possible to control block braces; see below.
1569 · Finally, please note that these vertical tightness flags are
1571 merely hints to the formatter, and it cannot always follow
1572 them. Things which make it difficult or impossible include
1573 comments, blank lines, blocks of code within a list, and
1574 possibly the lack of the -lp parameter. Also, these flags may
1575 be ignored for very small lists (2 or 3 lines in length).
1576 Here are some examples:
1578 # perltidy -lp -vt=0 -vtc=0
1580 %romanNumerals = (
1581 one => 'I',
1582 two => 'II',
1583 three => 'III',
1584 four => 'IV',
1585 );
1586 # perltidy -lp -vt=1 -vtc=0
1588 %romanNumerals = ( one => 'I',
1589 two => 'II',
1590 three => 'III',
1591 four => 'IV',
1592 );
1593 # perltidy -lp -vt=1 -vtc=1
1595 %romanNumerals = ( one => 'I',
1596 two => 'II',
1597 three => 'III',
1598 four => 'IV', );
1599 The difference between -vt=1 and -vt=2 is shown here:
1601 # perltidy -lp -vt=1
1603 $init->add(
1604 mysprintf( "(void)find_threadsv(%s);",
1605 cstring( $threadsv_names[ $op->targ ] )
1606 )
1607 );
1608 # perltidy -lp -vt=2
1610 $init->add( mysprintf( "(void)find_threadsv(%s);",
1611 cstring( $threadsv_names[ $op->targ ] )
1612 )
1613 );
1614 With -vt=1, the line ending in "add(" does not combine with the
1616 next line because the next line is not balanced. This can help
1617 with readability, but -vt=2 can be used to ignore this rule.
1618 The tightest, and least readable, code is produced with both
1620 "-vt=2" and "-vtc=2":
1621 # perltidy -lp -vt=2 -vtc=2
1623 $init->add( mysprintf( "(void)find_threadsv(%s);",
1624 cstring( $threadsv_names[ $op->targ ] ) ) );
1625 Notice how the code in all of these examples collapses vertically
1627 as -vt increases, but the indentation remains unchanged. This is
1628 because perltidy implements the -vt parameter by first formatting
1629 as if -vt=0, and then simply overwriting one output line on top of
1630 the next, if possible, to achieve the desired vertical tightness.
1631 The -lp indentation style has been designed to allow this vertical
1632 collapse to occur, which is why it is required for the -vt
1633 parameter.
1634 The -vt=n and -vtc=n parameters apply to each type of container
1636 token. If desired, vertical tightness controls can be applied
1637 independently to each of the closing container token types.
1638 The parameters for controlling parentheses are -pvt=n or
1640 --paren-vertical-tightness=n, and -pcvt=n or
1641 --paren-vertical-tightness-closing=n.
1642 Likewise, the parameters for square brackets are -sbvt=n or
1644 --square-bracket-vertical-tightness=n, and -sbcvt=n or
1645 --square-bracket-vertical-tightness-closing=n.
1646 Finally, the parameters for controlling non-code block braces are
1648 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1649 --brace-vertical-tightness-closing=n.
1650 In fact, the parameter -vt=n is actually just an abbreviation for
1652 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1653 -pvtc=n -bvtc=n sbvtc=n.
1654 -bbvt=n or --block-brace-vertical-tightness=n
1656 The -bbvt=n flag is just like the -vt=n flag but applies to opening
1657 code block braces.
1658 -bbvt=0 break after opening block brace (default).
1660 -bbvt=1 do not break unless this would produce more than one
1661 step in indentation in a line.
1662 -bbvt=2 do not break after opening block brace.
1663 It is necessary to also use either -bl or -bli for this to work,
1665 because, as with other vertical tightness controls, it is
1666 implemented by simply overwriting a line ending with an opening
1667 block brace with the subsequent line. For example:
1668 # perltidy -bli -bbvt=0
1670 if ( open( FILE, "< $File" ) )
1671 {
1672 while ( $File = <FILE> )
1673 {
1674 $In .= $File;
1675 $count++;
1676 }
1677 close(FILE);
1678 }
1679 # perltidy -bli -bbvt=1
1681 if ( open( FILE, "< $File" ) )
1682 { while ( $File = <FILE> )
1683 { $In .= $File;
1684 $count++;
1685 }
1686 close(FILE);
1687 }
1688 By default this applies to blocks associated with keywords if,
1690 elsif, else, unless, for, foreach, sub, while, until, and also with
1691 a preceding label. This can be changed with the parameter
1692 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
1693 where string is a space-separated list of block types. For more
1694 information on the possible values of this string, see "Specifying
1695 Block Types"
1696 For example, if we want to just apply this style to "if", "elsif",
1698 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
1699 elsif else'".
1700 There is no vertical tightness control for closing block braces;
1702 with one exception they they will be placed on separate lines. The
1703 exception is that a cascade of closing block braces may be stacked
1704 on a single line. See -scbb.
1705 -sot, --stack-opening-tokens and related flags
1707 The -sot flag tells perltidy to "stack" opening tokens when
1708 possible to avoid lines with isolated opening tokens.
1709 For example:
1711 # default
1713 $opt_c = Text::CSV_XS->new(
1714 {
1715 binary => 1,
1716 sep_char => $opt_c,
1717 always_quote => 1,
1718 }
1719 );
1720 # -sot
1722 $opt_c = Text::CSV_XS->new( {
1723 binary => 1,
1724 sep_char => $opt_c,
1725 always_quote => 1,
1726 }
1727 );
1728 For detailed control of individual closing tokens the following
1730 controls can be used:
1731 -sop or --stack-opening-paren
1733 -sohb or --stack-opening-hash-brace
1734 -sosb or --stack-opening-square-bracket
1735 -sobb or --stack-opening-block-brace
1736 The flag -sot is an abbreviation for -sop -sohb -sosb.
1738 The flag -sobb is a abbreviation for -bbvt=2 -bbvtl='*'. This will
1740 case a cascade of opening block braces to appear on a single line,
1741 although this an uncommon occurrence except in test scripts.
1742 -sct, --stack-closing-tokens and related flags
1744 The -sct flag tells perltidy to "stack" closing tokens when
1745 possible to avoid lines with isolated closing tokens.
1746 For example:
1748 # default
1750 $opt_c = Text::CSV_XS->new(
1751 {
1752 binary => 1,
1753 sep_char => $opt_c,
1754 always_quote => 1,
1755 }
1756 );
1757 # -sct
1759 $opt_c = Text::CSV_XS->new(
1760 {
1761 binary => 1,
1762 sep_char => $opt_c,
1763 always_quote => 1,
1764 } );
1765 The -sct flag is somewhat similar to the -vtc flags, and in some
1767 cases it can give a similar result. The difference is that the
1768 -vtc flags try to avoid lines with leading opening tokens by
1769 "hiding" them at the end of a previous line, whereas the -sct flag
1770 merely tries to reduce the number of lines with isolated closing
1771 tokens by stacking them but does not try to hide them. For
1772 example:
1773 # -vtc=2
1775 $opt_c = Text::CSV_XS->new(
1776 {
1777 binary => 1,
1778 sep_char => $opt_c,
1779 always_quote => 1, } );
1780 For detailed control of the stacking of individual closing tokens
1782 the following controls can be used:
1783 -scp or --stack-closing-paren
1785 -schb or --stack-closing-hash-brace
1786 -scsb or --stack-closing-square-bracket
1787 -scbb or --stack-closing-block-brace
1788 The flag -sct is an abbreviation for stacking the non-block closing
1790 tokens, -scp -schb -scsb.
1791 Stacking of closing block braces, -scbb, causes a cascade of
1793 isolated closing block braces to be combined into a single line as
1794 in the following example:
1795 # -scbb:
1797 for $w1 (@w1) {
1798 for $w2 (@w2) {
1799 for $w3 (@w3) {
1800 for $w4 (@w4) {
1801 push( @lines, "$w1 $w2 $w3 $w4\n" );
1802 } } } }
1803 To simplify input even further for the case in which both opening
1805 and closing non-block containers are stacked, the flag -sac or
1806 --stack-all-containers is an abbreviation for -sot -sot.
1807 -dnl, --delete-old-newlines
1809 By default, perltidy first deletes all old line break locations,
1810 and then it looks for good break points to match the desired line
1811 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
1812 retain all old line break points.
1813 -anl, --add-newlines
1815 By default, perltidy will add line breaks when necessary to create
1816 continuations of long lines and to improve the script appearance.
1817 Use -nanl or --noadd-newlines to prevent any new line breaks.
1818 This flag does not prevent perltidy from eliminating existing line
1820 breaks; see --freeze-newlines to completely prevent changes to line
1821 break points.
1822 Controlling whether perltidy breaks before or after operators
1824 Four command line parameters provide some control over whether a
1825 line break should be before or after specific token types. Two
1826 parameters give detailed control:
1827 -wba=s or --want-break-after=s, and
1829 -wbb=s or --want-break-before=s.
1831 These parameters are each followed by a quoted string, s,
1833 containing a list of token types (separated only by spaces). No
1834 more than one of each of these parameters should be specified,
1835 because repeating a command-line parameter always overwrites the
1836 previous one before perltidy ever sees it.
1837 By default, perltidy breaks after these token types:
1839 % + - * / x != == >= <= =~ !~ < > | &
1840 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1841 And perltidy breaks before these token types by default:
1843 . << >> -> && || //
1844 To illustrate, to cause a break after a concatenation operator,
1846 '.', rather than before it, the command line would be
1847 -wba="."
1849 As another example, the following command would cause a break
1851 before math operators '+', '-', '/', and '*':
1852 -wbb="+ - / *"
1854 These commands should work well for most of the token types that
1856 perltidy uses (use --dump-token-types for a list). Also try the -D
1857 flag on a short snippet of code and look at the .DEBUG file to see
1858 the tokenization. However, for a few token types there may be
1859 conflicts with hardwired logic which cause unexpected results. One
1860 example is curly braces, which should be controlled with the
1861 parameter bl provided for that purpose.
1862 WARNING Be sure to put these tokens in quotes to avoid having them
1864 misinterpreted by your command shell.
1865 Two additional parameters are available which, though they provide
1867 no further capability, can simplify input are:
1868 -baao or --break-after-all-operators,
1870 -bbao or --break-before-all-operators.
1872 The -baao sets the default to be to break after all of the
1874 following operators:
1875 % + - * / x != == >= <= =~ !~ < > | &
1877 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
1878 . : ? && || and or err xor
1879 and the -bbao flag sets the default to break before all of these
1881 operators. These can be used to define an initial break preference
1882 which can be fine-tuned with the -wba and -wbb flags. For example,
1883 to break before all operators except an = one could use --bbao
1884 -wba='=' rather than listing every single perl operator except = on
1885 a -wbb flag.
1886 Controlling List Formatting
1888 Perltidy attempts to place comma-separated arrays of values in tables
1889 which look good. Its default algorithms usually work well, and they
1890 have been improving with each release, but several parameters are
1891 available to control list formatting.
1892 -boc, --break-at-old-comma-breakpoints
1894 This flag tells perltidy to try to break at all old commas. This
1895 is not the default. Normally, perltidy makes a best guess at list
1896 formatting, and seldom uses old comma breakpoints. Usually this
1897 works well, but consider:
1898 my @list = (1,
1900 1, 1,
1901 1, 2, 1,
1902 1, 3, 3, 1,
1903 1, 4, 6, 4, 1,);
1904 The default formatting will flatten this down to one line:
1906 # perltidy (default)
1908 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
1909 which hides the structure. Using -boc, plus additional flags to
1911 retain the original style, yields
1912 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
1914 my @list = (1,
1915 1, 1,
1916 1, 2, 1,
1917 1, 3, 3, 1,
1918 1, 4, 6, 4, 1,);
1919 A disadvantage of this flag is that all tables in the file must
1921 already be nicely formatted. For another possibility see the -fs
1922 flag in "Skipping Selected Sections of Code".
1923 -mft=n, --maximum-fields-per-table=n
1925 If the computed number of fields for any table exceeds n, then it
1926 will be reduced to n. The default value for n is a large number,
1927 40. While this value should probably be left unchanged as a
1928 general rule, it might be used on a small section of code to force
1929 a list to have a particular number of fields per line, and then
1930 either the -boc flag could be used to retain this formatting, or a
1931 single comment could be introduced somewhere to freeze the
1932 formatting in future applications of perltidy.
1933 # perltidy -mft=2
1935 @month_of_year = (
1936 'Jan', 'Feb',
1937 'Mar', 'Apr',
1938 'May', 'Jun',
1939 'Jul', 'Aug',
1940 'Sep', 'Oct',
1941 'Nov', 'Dec'
1942 );
1943 -cab=n, --comma-arrow-breakpoints=n
1945 A comma which follows a comma arrow, '=>', is given special
1946 consideration. In a long list, it is common to break at all such
1947 commas. This parameter can be used to control how perltidy breaks
1948 at these commas. (However, it will have no effect if old comma
1949 breaks are being forced because -boc is used). The possible values
1950 of n are:
1951 n=0 break at all commas after =>
1953 n=1 stable: break at all commas after => if container is open,
1954 EXCEPT FOR one-line containers
1955 n=2 break at all commas after =>, BUT try to form the maximum
1956 maximum one-line container lengths
1957 n=3 do not treat commas after => specially at all
1958 n=4 break everything: like n=0 but ALSO break a short container with
1959 a => not followed by a comma when -vt=0 is used
1960 n=5 stable: like n=1 but ALSO break at open one-line containers when
1961 -vt=0 is used (default)
1962 For example, given the following single line, perltidy by default
1964 will not add any line breaks because it would break the existing
1965 one-line container:
1966 bless { B => $B, Root => $Root } => $package;
1968 Using -cab=0 will force a break after each comma-arrow item:
1970 # perltidy -cab=0:
1972 bless {
1973 B => $B,
1974 Root => $Root
1975 } => $package;
1976 If perltidy is subsequently run with this container broken, then by
1978 default it will break after each '=>' because the container is now
1979 broken. To reform a one-line container, the parameter -cab=2 could
1980 be used.
1981 The flag -cab=3 can be used to prevent these commas from being
1983 treated specially. In this case, an item such as "01" => 31 is
1984 treated as a single item in a table. The number of fields in this
1985 table will be determined by the same rules that are used for any
1986 other table. Here is an example.
1987 # perltidy -cab=3
1989 my %last_day = (
1990 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
1991 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
1992 "09" => 30, "10" => 31, "11" => 30, "12" => 31
1993 );
1994 Retaining or Ignoring Existing Line Breaks
1996 Several additional parameters are available for controlling the extent
1997 to which line breaks in the input script influence the output script.
1998 In most cases, the default parameter values are set so that, if a
1999 choice is possible, the output style follows the input style. For
2000 example, if a short logical container is broken in the input script,
2001 then the default behavior is for it to remain broken in the output
2002 script.
2003 Most of the parameters in this section would only be required for a
2005 one-time conversion of a script from short container lengths to longer
2006 container lengths. The opposite effect, of converting long container
2007 lengths to shorter lengths, can be obtained by temporarily using a
2008 short maximum line length.
2009 -bol, --break-at-old-logical-breakpoints
2011 By default, if a logical expression is broken at a "&&", "||",
2012 "and", or "or", then the container will remain broken. Also,
2013 breaks at internal keywords "if" and "unless" will normally be
2014 retained. To prevent this, and thus form longer lines, use -nbol.
2015 -bok, --break-at-old-keyword-breakpoints
2017 By default, perltidy will retain a breakpoint before keywords which
2018 may return lists, such as "sort" and <map>. This allows chains of
2019 these operators to be displayed one per line. Use -nbok to prevent
2020 retaining these breakpoints.
2021 -bot, --break-at-old-ternary-breakpoints
2023 By default, if a conditional (ternary) operator is broken at a ":",
2024 then it will remain broken. To prevent this, and thereby form
2025 longer lines, use -nbot.
2026 -boa, --break-at-old-attribute-breakpoints
2028 By default, if an attribute list is broken at a ":" in the source
2029 file, then it will remain broken. For example, given the following
2030 code, the line breaks at the ':'s will be retained:
2031 my @field
2033 : field
2034 : Default(1)
2035 : Get('Name' => 'foo') : Set('Name');
2036 If the attributes are on a single line in the source code then they
2038 will remain on a single line if possible.
2039 To prevent this, and thereby always form longer lines, use -nboa.
2041 -iob, --ignore-old-breakpoints
2043 Use this flag to tell perltidy to ignore existing line breaks to
2044 the maximum extent possible. This will tend to produce the longest
2045 possible containers, regardless of type, which do not exceed the
2046 line length limit.
2047 -kis, --keep-interior-semicolons
2049 Use the -kis flag to prevent breaking at a semicolon if there was
2050 no break there in the input file. Normally perltidy places a
2051 newline after each semicolon which terminates a statement unless
2052 several statements are contained within a one-line brace block. To
2053 illustrate, consider the following input lines:
2054 dbmclose(%verb_delim); undef %verb_delim;
2056 dbmclose(%expanded); undef %expanded;
2057 The default is to break after each statement, giving
2059 dbmclose(%verb_delim);
2061 undef %verb_delim;
2062 dbmclose(%expanded);
2063 undef %expanded;
2064 With perltidy -kis the multiple statements are retained:
2066 dbmclose(%verb_delim); undef %verb_delim;
2068 dbmclose(%expanded); undef %expanded;
2069 The statements are still subject to the specified value of maximum-
2071 line-length and will be broken if this maximum is exceeed.
2072 Blank Line Control
2074 Blank lines can improve the readability of a script if they are
2075 carefully placed. Perltidy has several commands for controlling the
2076 insertion, retention, and removal of blank lines.
2077 -fbl, --freeze-blank-lines
2079 Set -fbl if you want to the blank lines in your script to remain
2080 exactly as they are. The rest of the parameters in this section
2081 may then be ignored. (Note: setting the -fbl flag is equivalent to
2082 setting -mbl=0 and -kbl=2).
2083 -bbc, --blanks-before-comments
2085 A blank line will be introduced before a full-line comment. This
2086 is the default. Use -nbbc or --noblanks-before-comments to
2087 prevent such blank lines from being introduced.
2088 -blbs=n, --blank-lines-before-subs=n
2090 The parameter -blbs=n requests that least n blank lines precede a
2091 sub definition which does not follow a comment and which is more
2092 than one-line long. The default is <-blbs=1>. BEGIN and END
2093 blocks are included.
2094 The requested number of blanks statement will be inserted
2096 regardless of of the value of --maximum-consecutive-blank-lines=n
2097 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
2098 output.
2099 This parameter interacts with the value k of the parameter
2101 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
2102 1. If -mbl=0 then no blanks will be output. This allows all blanks
2104 to be suppressed with a single parameter. Otherwise,
2105 2. If the number of old blank lines in the script is less than n
2107 then additional blanks will be inserted to make the total n
2108 regardless of the value of -mbl=k.
2109 3. If the number of old blank lines in the script equals or exceeds
2111 n then this parameter has no effect, however the total will not
2112 exceed value specified on the -mbl=k flag.
2113 -blbp=n, --blank-lines-before-packages=n
2115 The parameter -blbp=n requests that least n blank lines precede a
2116 package which does not follow a comment. The default is <-blbp=1>.
2117 This parameter interacts with the value k of the parameter
2119 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
2120 described for the previous item -blbs=n.
2121 -bbs, --blanks-before-subs
2123 For compatibility with previous versions, -bbs or
2124 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
2125 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
2127 and -blbs=0.
2128 -bbb, --blanks-before-blocks
2130 A blank line will be introduced before blocks of coding delimited
2131 by for, foreach, while, until, and if, unless, in the following
2132 circumstances:
2133 · The block is not preceded by a comment.
2135 · The block is not a one-line block.
2137 · The number of consecutive non-blank lines at the current
2139 indentation depth is at least -lbl (see next section).
2140 This is the default. The intention of this option is to introduce
2142 some space within dense coding. This is negated with -nbbb or
2143 --noblanks-before-blocks.
2144 -lbl=n --long-block-line-count=n
2146 This controls how often perltidy is allowed to add blank lines
2147 before certain block types (see previous section). The default is
2148 8. Entering a value of 0 is equivalent to entering a very large
2149 number.
2150 -mbl=n --maximum-consecutive-blank-lines=n
2152 This parameter specifies the maximum number of consecutive blank
2153 lines which will be output within code sections of a script. The
2154 default is n=1. If the input file has more than n consecutive
2155 blank lines, the number will be reduced to n except as noted above
2156 for the -blbp and -blbs parameters. If n=0 then no blank lines
2157 will be output (unless all old blank lines are retained with the
2158 -kbl=2 flag of the next section).
2159 This flag obviously does not apply to pod sections, here-documents,
2161 and quotes.
2162 -kbl=n, --keep-old-blank-lines=n
2164 The -kbl=n flag gives you control over how your existing blank
2165 lines are treated.
2166 The possible values of n are:
2168 n=0 ignore all old blank lines
2170 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
2171 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
2172 The default is n=1.
2174 -sob, --swallow-optional-blank-lines
2176 This is equivalent to kbl=0 and is included for compatibility with
2177 previous versions.
2178 -nsob, --noswallow-optional-blank-lines
2180 This is equivalent to kbl=1 and is included for compatibility with
2181 previous versions.
2182 Styles
2184 A style refers to a convenient collection of existing parameters.
2185 -gnu, --gnu-style
2187 -gnu gives an approximation to the GNU Coding Standards (which do
2188 not apply to perl) as they are sometimes implemented. At present,
2189 this style overrides the default style with the following
2190 parameters:
2191 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
2193 -pbp, --perl-best-practices
2195 -pbp is an abbreviation for the parameters in the book Perl Best
2196 Practices by Damian Conway:
2197 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
2199 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
2200 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
2201 Please note that this parameter set includes -st and -se flags,
2203 which make perltidy act as a filter on one file only. These can be
2204 overridden by placing -nst and/or -nse after the -pbp parameter.
2205 Also note that the value of continuation indentation, -ci=4, is
2207 equal to the value of the full indentation, -i=4. In some complex
2208 statements perltidy will produce nicer results with -ci=2. This can
2209 be implemented by including -ci=2 after the -pbp parameter. For
2210 example,
2211 # perltidy -pbp
2213 $self->{_text} = (
2214 !$section ? ''
2215 : $type eq 'item' ? "the $section entry"
2216 : "the section on $section"
2217 )
2218 . (
2219 $page
2220 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2221 : ' elsewhere in this document'
2222 );
2223 # perltidy -pbp -ci=2
2225 $self->{_text} = (
2226 !$section ? ''
2227 : $type eq 'item' ? "the $section entry"
2228 : "the section on $section"
2229 )
2230 . (
2231 $page
2232 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2233 : ' elsewhere in this document'
2234 );
2235 Other Controls
2237 Deleting selected text
2238 Perltidy can selectively delete comments and/or pod documentation.
2239 The command -dac or --delete-all-comments will delete all comments
2240 and all pod documentation, leaving just code and any leading system
2241 control lines.
2242 The command -dp or --delete-pod will remove all pod documentation
2244 (but not comments).
2245 Two commands which remove comments (but not pod) are: -dbc or
2247 --delete-block-comments and -dsc or --delete-side-comments.
2248 (Hanging side comments will be deleted with block comments here.)
2249 The negatives of these commands also work, and are the defaults.
2251 When block comments are deleted, any leading 'hash-bang' will be
2252 retained. Also, if the -x flag is used, any system commands before
2253 a leading hash-bang will be retained (even if they are in the form
2254 of comments).
2255 Writing selected text to a file
2257 When perltidy writes a formatted text file, it has the ability to
2258 also send selected text to a file with a .TEE extension. This text
2259 can include comments and pod documentation.
2260 The command -tac or --tee-all-comments will write all comments and
2262 all pod documentation.
2263 The command -tp or --tee-pod will write all pod documentation (but
2265 not comments).
2266 The commands which write comments (but not pod) are: -tbc or
2268 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
2269 side comments will be written with block comments here.)
2270 The negatives of these commands also work, and are the defaults.
2272 Using a .perltidyrc command file
2274 If you use perltidy frequently, you probably won't be happy until
2275 you create a .perltidyrc file to avoid typing commonly-used
2276 parameters. Perltidy will first look in your current directory for
2277 a command file named .perltidyrc. If it does not find one, it will
2278 continue looking for one in other standard locations.
2279 These other locations are system-dependent, and may be displayed
2281 with the command "perltidy -dpro". Under Unix systems, it will
2282 first look for an environment variable PERLTIDY. Then it will look
2283 for a .perltidyrc file in the home directory, and then for a
2284 system-wide file /usr/local/etc/perltidyrc, and then it will look
2285 for /etc/perltidyrc. Note that these last two system-wide files do
2286 not have a leading dot. Further system-dependent information will
2287 be found in the INSTALL file distributed with perltidy.
2288 Under Windows, perltidy will also search for a configuration file
2290 named perltidy.ini since Windows does not allow files with a
2291 leading period (.). Use "perltidy -dpro" to see the possbile
2292 locations for your system. An example might be C:\Documents and
2293 Settings\All Users\perltidy.ini.
2294 Another option is the use of the PERLTIDY environment variable.
2296 The method for setting environment variables depends upon the
2297 version of Windows that you are using. Instructions for Windows 95
2298 and later versions can be found here:
2299 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
2301 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
2303 be placed in either the user section or the system section. The
2304 later makes the configuration file common to all users on the
2305 machine. Be sure to enter the full path of the configuration file
2306 in the value of the environment variable. Ex.
2307 PERLTIDY=C:\Documents and Settings\perltidy.ini
2308 The configuation file is free format, and simply a list of
2310 parameters, just as they would be entered on a command line. Any
2311 number of lines may be used, with any number of parameters per
2312 line, although it may be easiest to read with one parameter per
2313 line. Comment text begins with a #, and there must also be a space
2314 before the # for side comments. It is a good idea to put complex
2315 parameters in either single or double quotes.
2316 Here is an example of a .perltidyrc file:
2318 # This is a simple of a .perltidyrc configuration file
2320 # This implements a highly spaced style
2321 -se # errors to standard error output
2322 -w # show all warnings
2323 -bl # braces on new lines
2324 -pt=0 # parens not tight at all
2325 -bt=0 # braces not tight
2326 -sbt=0 # square brackets not tight
2327 The parameters in the .perltidyrc file are installed first, so any
2329 parameters given on the command line will have priority over them.
2330 To avoid confusion, perltidy ignores any command in the .perltidyrc
2332 file which would cause some kind of dump and an exit. These are:
2333 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
2335 There are several options may be helpful in debugging a .perltidyrc
2337 file:
2338 · A very helpful command is --dump-profile or -dpro. It writes a
2340 list of all configuration filenames tested to standard output,
2341 and if a file is found, it dumps the content to standard output
2342 before exiting. So, to find out where perltidy looks for its
2343 configuration files, and which one if any it selects, just
2344 enter
2345 perltidy -dpro
2347 · It may be simplest to develop and test configuration files with
2349 alternative names, and invoke them with -pro=filename on the
2350 command line. Then rename the desired file to .perltidyrc when
2351 finished.
2352 · The parameters in the .perltidyrc file can be switched off with
2354 the -npro option.
2355 · The commands --dump-options, --dump-defaults,
2357 --dump-long-names, and --dump-short-names, all described below,
2358 may all be helpful.
2359 Creating a new abbreviation
2361 A special notation is available for use in a .perltidyrc file for
2362 creating an abbreviation for a group of options. This can be used
2363 to create a shorthand for one or more styles which are frequently,
2364 but not always, used. The notation is to group the options within
2365 curly braces which are preceded by the name of the alias (without
2366 leading dashes), like this:
2367 newword {
2369 -opt1
2370 -opt2
2371 }
2372 where newword is the abbreviation, and opt1, etc, are existing
2374 parameters or other abbreviations. The main syntax requirement is
2375 that the new abbreviation must begin on a new line. Space before
2376 and after the curly braces is optional. For a specific example,
2377 the following line
2378 airy {-bl -pt=0 -bt=0 -sbt=0}
2380 could be placed in a .perltidyrc file, and then invoked at will
2382 with
2383 perltidy -airy somefile.pl
2385 (Either "-airy" or "--airy" may be used).
2387 Skipping leading non-perl commands with -x or --look-for-hash-bang
2389 If your script has leading lines of system commands or other text
2390 which are not valid perl code, and which are separated from the
2391 start of the perl code by a "hash-bang" line, ( a line of the form
2392 "#!...perl" ), you must use the -x flag to tell perltidy not to
2393 parse and format any lines before the "hash-bang" line. This
2394 option also invokes perl with a -x flag when checking the syntax.
2395 This option was originally added to allow perltidy to parse
2396 interactive VMS scripts, but it should be used for any script which
2397 is normally invoked with "perl -x".
2398 Making a file unreadable
2400 The goal of perltidy is to improve the readability of files, but
2401 there are two commands which have the opposite effect, --mangle and
2402 --extrude. They are actually merely aliases for combinations of
2403 other parameters. Both of these strip all possible whitespace, but
2404 leave comments and pod documents, so that they are essentially
2405 reversible. The difference between these is that --mangle puts the
2406 fewest possible line breaks in a script while --extrude puts the
2407 maximum possible. Note that these options do not provided any
2408 meaningful obfuscation, because perltidy can be used to reformat
2409 the files. They were originally developed to help test the
2410 tokenization logic of perltidy, but they have other uses. One use
2411 for --mangle is the following:
2412 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
2414 This will form the maximum possible number of one-line blocks (see
2416 next section), and can sometimes help clean up a badly formatted
2417 script.
2418 A similar technique can be used with --extrude instead of --mangle
2420 to make the minimum number of one-line blocks.
2421 Another use for --mangle is to combine it with -dac to reduce the
2423 file size of a perl script.
2424 One-line blocks
2426 There are a few points to note regarding one-line blocks. A one-
2427 line block is something like this,
2428 if ($x > 0) { $y = 1 / $x }
2430 where the contents within the curly braces is short enough to fit
2432 on a single line.
2433 With few exceptions, perltidy retains existing one-line blocks, if
2435 it is possible within the line-length constraint, but it does not
2436 attempt to form new ones. In other words, perltidy will try to
2437 follow the one-line block style of the input file.
2438 If an existing one-line block is longer than the maximum line
2440 length, however, it will be broken into multiple lines. When this
2441 happens, perltidy checks for and adds any optional terminating
2442 semicolon (unless the -nasc option is used) if the block is a code
2443 block.
2444 The main exception is that perltidy will attempt to form new one-
2446 line blocks following the keywords "map", "eval", and "sort",
2447 because these code blocks are often small and most clearly
2448 displayed in a single line.
2449 One-line block rules can conflict with the cuddled-else option.
2451 When the cuddled-else option is used, perltidy retains existing
2452 one-line blocks, even if they do not obey cuddled-else formatting.
2453 Occasionally, when one-line blocks get broken because they exceed
2455 the available line length, the formatting will violate the
2456 requested brace style. If this happens, reformatting the script a
2457 second time should correct the problem.
2458 Debugging
2460 The following flags are available for debugging:
2461 --dump-defaults or -ddf will write the default option set to
2463 standard output and quit
2464 --dump-profile or -dpro will write the name of the current
2466 configuration file and its contents to standard output and quit.
2467 --dump-options or -dop will write current option set to standard
2469 output and quit.
2470 --dump-long-names or -dln will write all command line long names
2472 (passed to Get_options) to standard output and quit.
2473 --dump-short-names or -dsn will write all command line short names
2475 to standard output and quit.
2476 --dump-token-types or -dtt will write a list of all token types to
2478 standard output and quit.
2479 --dump-want-left-space or -dwls will write the hash
2481 %want_left_space to standard output and quit. See the section on
2482 controlling whitespace around tokens.
2483 --dump-want-right-space or -dwrs will write the hash
2485 %want_right_space to standard output and quit. See the section on
2486 controlling whitespace around tokens.
2487 --no-memoize or -nmem will turn of memoizing. Memoization can
2489 reduce run time when running perltidy repeatedly in a single
2490 process. It is on by default but can be deactivated for testing
2491 with -nmem.
2492 -DEBUG will write a file with extension .DEBUG for each input file
2494 showing the tokenization of all lines of code.
2495 Working with MakeMaker, AutoLoader and SelfLoader
2497 The first $VERSION line of a file which might be eval'd by
2498 MakeMaker is passed through unchanged except for indentation. Use
2499 --nopass-version-line, or -npvl, to deactivate this feature.
2500 If the AutoLoader module is used, perltidy will continue formatting
2502 code after seeing an __END__ line. Use --nolook-for-autoloader, or
2503 -nlal, to deactivate this feature.
2504 Likewise, if the SelfLoader module is used, perltidy will continue
2506 formatting code after seeing a __DATA__ line. Use
2507 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
2508 Working around problems with older version of Perl
2510 Perltidy contains a number of rules which help avoid known
2511 subtleties and problems with older versions of perl, and these
2512 rules always take priority over whatever formatting flags have been
2513 set. For example, perltidy will usually avoid starting a new line
2514 with a bareword, because this might cause problems if "use strict"
2515 is active.
2516 There is no way to override these rules.
2518
2520 The -html master switch
2521 The flag -html causes perltidy to write an html file with extension
2522 .html. So, for example, the following command
2523 perltidy -html somefile.pl
2525 will produce a syntax-colored html file named somefile.pl.html
2527 which may be viewed with a browser.
2528 Please Note: In this case, perltidy does not do any formatting to
2530 the input file, and it does not write a formatted file with
2531 extension .tdy. This means that two perltidy runs are required to
2532 create a fully reformatted, html copy of a script.
2533 The -pre flag for code snippets
2535 When the -pre flag is given, only the pre-formatted section, within
2536 the <PRE> and </PRE> tags, will be output. This simplifies
2537 inclusion of the output in other files. The default is to output a
2538 complete web page.
2539 The -nnn flag for line numbering
2541 When the -nnn flag is given, the output lines will be numbered.
2542 The -toc, or --html-table-of-contents flag
2544 By default, a table of contents to packages and subroutines will be
2545 written at the start of html output. Use -ntoc to prevent this.
2546 This might be useful, for example, for a pod document which
2547 contains a number of unrelated code snippets. This flag only
2548 influences the code table of contents; it has no effect on any
2549 table of contents produced by pod2html (see next item).
2550 The -pod, or --pod2html flag
2552 There are two options for formatting pod documentation. The
2553 default is to pass the pod through the Pod::Html module (which
2554 forms the basis of the pod2html utility). Any code sections are
2555 formatted by perltidy, and the results then merged. Note: perltidy
2556 creates a temporary file when Pod::Html is used; see "FILES".
2557 Also, Pod::Html creates temporary files for its cache.
2558 NOTE: Perltidy counts the number of "=cut" lines, and either moves
2560 the pod text to the top of the html file if there is one "=cut", or
2561 leaves the pod text in its original order (interleaved with code)
2562 otherwise.
2563 Most of the flags accepted by pod2html may be included in the
2565 perltidy command line, and they will be passed to pod2html. In
2566 some cases, the flags have a prefix "pod" to emphasize that they
2567 are for the pod2html, and this prefix will be removed before they
2568 are passed to pod2html. The flags which have the additional "pod"
2569 prefix are:
2570 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2572 --[no]podverbose --podflush
2573 The flags which are unchanged from their use in pod2html are:
2575 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2577 --podpath=s --podroot=s
2578 where 's' is an appropriate character string. Not all of these
2580 flags are available in older versions of Pod::Html. See your
2581 Pod::Html documentation for more information.
2582 The alternative, indicated with -npod, is not to use Pod::Html, but
2584 rather to format pod text in italics (or whatever the stylesheet
2585 indicates), without special html markup. This is useful, for
2586 example, if pod is being used as an alternative way to write
2587 comments.
2588 The -frm, or --frames flag
2590 By default, a single html output file is produced. This can be
2591 changed with the -frm option, which creates a frame holding a table
2592 of contents in the left panel and the source code in the right
2593 side. This simplifies code browsing. Assume, for example, that the
2594 input file is MyModule.pm. Then, for default file extension
2595 choices, these three files will be created:
2596 MyModule.pm.html - the frame
2598 MyModule.pm.toc.html - the table of contents
2599 MyModule.pm.src.html - the formatted source code
2600 Obviously this file naming scheme requires that output be directed
2602 to a real file (as opposed to, say, standard output). If this is
2603 not the case, or if the file extension is unknown, the -frm option
2604 will be ignored.
2605 The -text=s, or --html-toc-extension flag
2607 Use this flag to specify the extra file extension of the table of
2608 contents file when html frames are used. The default is "toc".
2609 See "Specifying File Extensions".
2610 The -sext=s, or --html-src-extension flag
2612 Use this flag to specify the extra file extension of the content
2613 file when html frames are used. The default is "src". See
2614 "Specifying File Extensions".
2615 The -hent, or --html-entities flag
2617 This flag controls the use of Html::Entities for html formatting.
2618 By default, the module Html::Entities is used to encode special
2619 symbols. This may not be the right thing for some browser/language
2620 combinations. Use --nohtml-entities or -nhent to prevent this.
2621 Style Sheets
2623 Style sheets make it very convenient to control and adjust the
2624 appearance of html pages. The default behavior is to write a page
2625 of html with an embedded style sheet.
2626 An alternative to an embedded style sheet is to create a page with
2628 a link to an external style sheet. This is indicated with the
2629 -css=filename, where the external style sheet is filename. The
2630 external style sheet filename will be created if and only if it
2631 does not exist. This option is useful for controlling multiple
2632 pages from a single style sheet.
2633 To cause perltidy to write a style sheet to standard output and
2635 exit, use the -ss, or --stylesheet, flag. This is useful if the
2636 style sheet could not be written for some reason, such as if the
2637 -pre flag was used. Thus, for example,
2638 perltidy -html -ss >mystyle.css
2640 will write a style sheet with the default properties to file
2642 mystyle.css.
2643 The use of style sheets is encouraged, but a web page without a
2645 style sheets can be created with the flag -nss. Use this option if
2646 you must to be sure that older browsers (roughly speaking, versions
2647 prior to 4.0 of Netscape Navigator and Internet Explorer) can
2648 display the syntax-coloring of the html files.
2649 Controlling HTML properties
2651 Note: It is usually more convenient to accept the default
2652 properties and then edit the stylesheet which is produced.
2653 However, this section shows how to control the properties with
2654 flags to perltidy.
2655 Syntax colors may be changed from their default values by flags of
2657 the either the long form, -html-color-xxxxxx=n, or more
2658 conveniently the short form, -hcx=n, where xxxxxx is one of the
2659 following words, and x is the corresponding abbreviation:
2660 Token Type xxxxxx x
2662 ---------- -------- --
2663 comment comment c
2664 number numeric n
2665 identifier identifier i
2666 bareword, function bareword w
2667 keyword keyword k
2668 quite, pattern quote q
2669 here doc text here-doc-text h
2670 here doc target here-doc-target hh
2671 punctuation punctuation pu
2672 parentheses paren p
2673 structural braces structure s
2674 semicolon semicolon sc
2675 colon colon co
2676 comma comma cm
2677 label label j
2678 sub definition name subroutine m
2679 pod text pod-text pd
2680 A default set of colors has been defined, but they may be changed
2682 by providing values to any of the following parameters, where n is
2683 either a 6 digit hex RGB color value or an ascii name for a color,
2684 such as 'red'.
2685 To illustrate, the following command will produce an html file
2687 somefile.pl.html with "aqua" keywords:
2688 perltidy -html -hck=00ffff somefile.pl
2690 and this should be equivalent for most browsers:
2692 perltidy -html -hck=aqua somefile.pl
2694 Perltidy merely writes any non-hex names that it sees in the html
2696 file. The following 16 color names are defined in the HTML 3.2
2697 standard:
2698 black => 000000,
2700 silver => c0c0c0,
2701 gray => 808080,
2702 white => ffffff,
2703 maroon => 800000,
2704 red => ff0000,
2705 purple => 800080,
2706 fuchsia => ff00ff,
2707 green => 008000,
2708 lime => 00ff00,
2709 olive => 808000,
2710 yellow => ffff00
2711 navy => 000080,
2712 blue => 0000ff,
2713 teal => 008080,
2714 aqua => 00ffff,
2715 Many more names are supported in specific browsers, but it is
2717 safest to use the hex codes for other colors. Helpful color tables
2718 can be located with an internet search for "HTML color tables".
2719 Besides color, two other character attributes may be set: bold, and
2721 italics. To set a token type to use bold, use the flag
2722 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
2723 names from the above table. Conversely, to set a token type to NOT
2724 use bold, use --nohtml-bold-xxxxxx or -nhbx.
2725 Likewise, to set a token type to use an italic font, use the flag
2727 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
2728 or short names from the above table. And to set a token type to
2729 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
2730 For example, to use bold braces and lime color, non-bold, italics
2732 keywords the following command would be used:
2733 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
2735 The background color can be specified with
2737 --html-color-background=n, or -hcbg=n for short, where n is a 6
2738 character hex RGB value. The default color of text is the value
2739 given to punctuation, which is black as a default.
2740 Here are some notes and hints:
2742 1. If you find a preferred set of these parameters, you may want to
2744 create a .perltidyrc file containing them. See the perltidy man
2745 page for an explanation.
2746 2. Rather than specifying values for these parameters, it is
2748 probably easier to accept the defaults and then edit a style sheet.
2749 The style sheet contains comments which should make this easy.
2750 3. The syntax-colored html files can be very large, so it may be
2752 best to split large files into smaller pieces to improve download
2753 times.
2754
2756 Specifying Block Types
2757 Several parameters which refer to code block types may be customized by
2758 also specifying an associated list of block types. The type of a block
2759 is the name of the keyword which introduces that block, such as if,
2760 else, or sub. An exception is a labeled block, which has no keyword,
2761 and should be specified with just a colon. To specify all blocks use
2762 '*'.
2763 For example, the following parameter specifies "sub", labels, "BEGIN",
2765 and "END" blocks:
2766 -cscl="sub : BEGIN END"
2768 (the meaning of the -cscl parameter is described above.) Note that
2770 quotes are required around the list of block types because of the
2771 spaces. For another example, the following list specifies all block
2772 types for vertical tightness:
2773 -bbvtl='*'
2775 Specifying File Extensions
2777 Several parameters allow default file extensions to be overridden. For
2778 example, a backup file extension may be specified with -bext=ext, where
2779 ext is some new extension. In order to provides the user some
2780 flexibility, the following convention is used in all cases to decide if
2781 a leading '.' should be used. If the extension "ext" begins with
2782 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
2783 an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it
2784 will be appended directly.
2785 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
2787 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
2788 is added, so again the backup file is somefile.pl.old. For "-bext=~",
2789 then no dot is added, and the backup file will be somefile.pl~ .
2790
2792 The following list shows all short parameter names which allow a prefix
2793 'n' to produce the negated form:
2794 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
2796 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
2797 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
2798 lp lsl ohbr okw ola oll opr opt osbr otr ple ple pod pvl q
2799 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
2800 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
2801 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
2803 may be used.
2804
2806 Parsing Limitations
2807 Perltidy should work properly on most perl scripts. It does a lot
2808 of self-checking, but still, it is possible that an error could be
2809 introduced and go undetected. Therefore, it is essential to make
2810 careful backups and to test reformatted scripts.
2811 The main current limitation is that perltidy does not scan modules
2813 included with 'use' statements. This makes it necessary to guess
2814 the context of any bare words introduced by such modules. Perltidy
2815 has good guessing algorithms, but they are not infallible. When it
2816 must guess, it leaves a message in the log file.
2817 If you encounter a bug, please report it.
2819 What perltidy does not parse and format
2821 Perltidy indents but does not reformat comments and "qw" quotes.
2822 Perltidy does not in any way modify the contents of here documents
2823 or quoted text, even if they contain source code. (You could,
2824 however, reformat them separately). Perltidy does not format
2825 'format' sections in any way. And, of course, it does not modify
2826 pod documents.
2827
2829 Temporary files
2830 Under the -html option with the default --pod2html flag, a
2831 temporary file is required to pass text to Pod::Html. Unix systems
2832 will try to use the POSIX tmpnam() function. Otherwise the file
2833 perltidy.TMP will be temporarily created in the current working
2834 directory.
2835 Special files when standard input is used
2837 When standard input is used, the log file, if saved, is
2838 perltidy.LOG, and any errors are written to perltidy.ERR unless the
2839 -se flag is set. These are saved in the current working directory.
2840 Files overwritten
2842 The following file extensions are used by perltidy, and files with
2843 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
2844 and/or .tdy, .html, and .bak, depending on the run type and
2845 settings.
2846 Files extensions limitations
2848 Perltidy does not operate on files for which the run could produce
2849 a file with a duplicated file extension. These extensions include
2850 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
2851 type. The purpose of this rule is to prevent generating confusing
2852 filenames such as somefile.tdy.tdy.tdy.
2853
2855 perlstyle(1), Perl::Tidy(3)
2856
2858 This man page documents perltidy version 20121207.
2859
2861 Michael Cartmell supplied code for adaptation to VMS and helped with
2862 v-strings.
2863 Yves Orton supplied code for adaptation to the various versions of
2865 Windows.
2866 Axel Rose supplied a patch for MacPerl.
2868 Hugh S. Myers designed and implemented the initial Perl::Tidy module
2870 interface.
2871 Many others have supplied key ideas, suggestions, and bug reports; see
2873 the CHANGES file.
2874
2876 Steve Hancock
2877 email: perltidy at users.sourceforge.net
2878 http://perltidy.sourceforge.net
2879
2881 Copyright (c) 2000-2012 by Steve Hancock
2882
2884 This package is free software; you can redistribute it and/or modify it
2885 under the terms of the "GNU General Public License".
2886 Please refer to the file "COPYING" for details.
2888
2890 This package is distributed in the hope that it will be useful, but
2891 WITHOUT ANY WARRANTY; without even the implied warranty of
2892 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2893 See the "GNU General Public License" for more details.
2895perl v5.16.3 2012-12-09 PERLTIDY(1)