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 -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 (see -st), the output will go to
158 filename.tdy. [Note: - does not redirect to standard output. Use
159 -st instead.]
160 -st, --standard-output
162 Perltidy must be able to operate on an arbitrarily large number of
163 files in a single run, with each output being directed to a
164 different output file. Obviously this would conflict with
165 outputting to the single standard output device, so a special flag,
166 -st, is required to request outputting to the standard output. For
167 example,
168 perltidy somefile.pl -st >somefile.new.pl
170 This option may only be used if there is just a single input file.
172 The default is -nst or --nostandard-output.
173 -se, --standard-error-output
175 If perltidy detects an error when processing file somefile.pl, its
176 default behavior is to write error messages to file
177 somefile.pl.ERR. Use -se to cause all error messages to be sent to
178 the standard error output stream instead. This directive may be
179 negated with -nse. Thus, you may place -se in a .perltidyrc and
180 override it when desired with -nse on the command line.
181 -oext=ext, --output-file-extension=ext
183 Change the extension of the output file to be ext instead of the
184 default tdy (or html in case the --html option is used). See
185 "Specifying File Extensions".
186 -opath=path, --output-path=path
188 When perltidy creates a filename for an output file, by default it
189 merely appends an extension to the path and basename of the input
190 file. This parameter causes the path to be changed to path
191 instead.
192 The path should end in a valid path separator character, but
194 perltidy will try to add one if it is missing.
195 For example
197 perltidy somefile.pl -opath=/tmp/
199 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
201 appear in whatever directory contains somefile.pl.
202 If the path contains spaces, it should be placed in quotes.
204 This parameter will be ignored if output is being directed to
206 standard output, or if it is being specified explicitly with the
207 -o=s parameter.
208 -b, --backup-and-modify-in-place
210 Modify the input file or files in-place and save the original with
211 the extension .bak. Any existing .bak file will be deleted. See
212 next item for changing the default backup extension, and for
213 eliminating the backup file altogether.
214 A -b flag will be ignored if input is from standard input or goes
216 to standard output, or if the -html flag is set.
217 In particular, if you want to use both the -b flag and the -pbp
219 (--perl-best-practices) flag, then you must put a -nst flag after
220 the -pbp flag because it contains a -st flag as one of its
221 components, which means that output will go to the standard output
222 stream.
223 -bext=ext, --backup-file-extension=ext
225 This parameter serves two purposes: (1) to change the extension of
226 the backup file to be something other than the default .bak, and
227 (2) to indicate that no backup file should be saved.
228 To change the default extension to something other than .bak see
230 "Specifying File Extensions".
231 A backup file of the source is always written, but you can request
233 that it be deleted at the end of processing if there were no
234 errors. This is risky unless the source code is being maintained
235 with a source code control system.
236 To indicate that the backup should be deleted include one forward
238 slash, /, in the extension. If any text remains after the slash is
239 removed it will be used to define the backup file extension (which
240 is always created and only deleted if there were no errors).
241 Here are some examples:
243 Parameter Extension Backup File Treatment
245 <-bext=bak> F<.bak> Keep (same as the default behavior)
246 <-bext='/'> F<.bak> Delete if no errors
247 <-bext='/backup'> F<.backup> Delete if no errors
248 <-bext='original/'> F<.original> Delete if no errors
249 -w, --warning-output
251 Setting -w causes any non-critical warning messages to be reported
252 as errors. These include messages about possible pod problems,
253 possibly bad starting indentation level, and cautions about
254 indirect object usage. The default, -nw or --nowarning-output, is
255 not to include these warnings.
256 -q, --quiet
258 Deactivate error messages and syntax checking (for running under an
259 editor).
260 For example, if you use a vi-style editor, such as vim, you may
262 execute perltidy as a filter from within the editor using something
263 like
264 :n1,n2!perltidy -q
266 where "n1,n2" represents the selected text. Without the -q flag,
268 any error message may mess up your screen, so be prepared to use
269 your "undo" key.
270 -log, --logfile
272 Save the .LOG file, which has many useful diagnostics. Perltidy
273 always creates a .LOG file, but by default it is deleted unless a
274 program bug is suspected. Setting the -log flag forces the log
275 file to be saved.
276 -g=n, --logfile-gap=n
278 Set maximum interval between input code lines in the logfile. This
279 purpose of this flag is to assist in debugging nesting errors. The
280 value of "n" is optional. If you set the flag -g without the value
281 of "n", it will be taken to be 1, meaning that every line will be
282 written to the log file. This can be helpful if you are looking
283 for a brace, paren, or bracket nesting error.
284 Setting -g also causes the logfile to be saved, so it is not
286 necessary to also include -log.
287 If no -g flag is given, a value of 50 will be used, meaning that at
289 least every 50th line will be recorded in the logfile. This helps
290 prevent excessively long log files.
291 Setting a negative value of "n" is the same as not setting -g at
293 all.
294 -npro --noprofile
296 Ignore any .perltidyrc command file. Normally, perltidy looks
297 first in your current directory for a .perltidyrc file of
298 parameters. (The format is described below). If it finds one, it
299 applies those options to the initial default values, and then it
300 applies any that have been defined on the command line. If no
301 .perltidyrc file is found, it looks for one in your home directory.
302 If you set the -npro flag, perltidy will not look for this file.
304 -pro=filename or --profile=filename
306 To simplify testing and switching .perltidyrc files, this command
307 may be used to specify a configuration file which will override the
308 default name of .perltidyrc. There must not be a space on either
309 side of the '=' sign. For example, the line
310 perltidy -pro=testcfg
312 would cause file testcfg to be used instead of the default
314 .perltidyrc.
315 A pathname begins with three dots, e.g. ".../.perltidyrc",
317 indicates that the file should be searched for starting in the
318 current directory and working upwards. This makes it easier to have
319 multiple projects each with their own .perltidyrc in their root
320 directories.
321 -opt, --show-options
323 Write a list of all options used to the .LOG file. Please see
324 --dump-options for a simpler way to do this.
325 -f, --force-read-binary
327 Force perltidy to process binary files. To avoid producing
328 excessive error messages, perltidy skips files identified by the
329 system as non-text. However, valid perl scripts containing binary
330 data may sometimes be identified as non-text, and this flag forces
331 perltidy to process them.
332 -ast, --assert-tidy
334 This flag asserts that the input and output code streams are
335 identical, or in other words that the input code is already 'tidy'
336 according to the formatting parameters. If this is not the case,
337 an error message noting this is produced. This error message will
338 cause the process to return a non-zero exit code. The test for
339 this is made by comparing an MD5 hash value for the input and
340 output code streams. This flag has no other effect on the
341 functioning of perltidy. This might be useful for certain code
342 maintenance operations.
343 -asu, --assert-untidy
345 This flag asserts that the input and output code streams are
346 different, or in other words that the input code is 'untidy'
347 according to the formatting parameters. If this is not the case,
348 an error message noting this is produced. This flag has no other
349 effect on the functioning of perltidy.
350
352 Basic Options
353 --notidy
354 This flag disables all formatting and causes the input to be copied
355 unchanged to the output except for possible changes in line ending
356 characters and any pre- and post-filters. This can be useful in
357 conjunction with a hierarchical set of .perltidyrc files to avoid
358 unwanted code tidying. See also "Skipping Selected Sections of
359 Code" for a way to avoid tidying specific sections of code.
360 -i=n, --indent-columns=n
362 Use n columns per indentation level (default n=4).
363 -l=n, --maximum-line-length=n
365 The default maximum line length is n=80 characters. Perltidy will
366 try to find line break points to keep lines below this length.
367 However, long quotes and side comments may cause lines to exceed
368 this length. Setting -l=0 is equivalent to setting -l=(a large
369 number).
370 -vmll, --variable-maximum-line-length
372 A problem arises using a fixed maximum line length with very deeply
373 nested code and data structures because eventually the amount of
374 leading whitespace used for indicating indentation takes up most or
375 all of the available line width, leaving little or no space for the
376 actual code or data. One solution is to use a vary long line
377 length. Another solution is to use the -vmll flag, which basically
378 tells perltidy to ignore leading whitespace when measuring the line
379 length.
380 To be precise, when the -vmll parameter is set, the maximum line
382 length of a line of code will be M+L*I, where
383 M is the value of --maximum-line-length=M (-l=M), default 80,
385 I is the value of --indent-columns=I (-i=I), default 4,
386 L is the indentation level of the line of code
387 When this flag is set, the choice of breakpoints for a block of
389 code should be essentially independent of its nesting depth.
390 However, the absolute line lengths, including leading whitespace,
391 can still be arbitrarily large. This problem can be avoided by
392 including the next parameter.
393 The default is not to do this (-nvmll).
395 -wc=n, --whitespace-cycle=n
397 This flag also addresses problems with very deeply nested code and
398 data structures. When the nesting depth exceeds the value n the
399 leading whitespace will be reduced and start at a depth of 1 again.
400 The result is that blocks of code will shift back to the left
401 rather than moving arbitrarily far to the right. This occurs
402 cyclically to any depth.
403 For example if one level of indentation equals 4 spaces (-i=4, the
405 default), and one uses -wc=15, then if the leading whitespace on a
406 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
407 spaces and continue increasing from there. If the whitespace never
408 exceeds this limit the formatting remains unchanged.
409 The combination of -vmll and -wc=n provides a solution to the
411 problem of displaying arbitrarily deep data structures and code in
412 a finite window, although -wc=n may of course be used without
413 -vmll.
414 The default is not to use this, which can also be indicated using
416 -wc=0.
417 tabs
419 Using tab characters will almost certainly lead to future
420 portability and maintenance problems, so the default and
421 recommendation is not to use them. For those who prefer tabs,
422 however, there are two different options.
423 Except for possibly introducing tab indentation characters, as
425 outlined below, perltidy does not introduce any tab characters into
426 your file, and it removes any tabs from the code (unless requested
427 not to do so with -fws). If you have any tabs in your comments,
428 quotes, or here-documents, they will remain.
429 -et=n, --entab-leading-whitespace
431 This flag causes each n initial space characters to be replaced
432 by one tab character. Note that the integer n is completely
433 independent of the integer specified for indentation parameter,
434 -i=n.
435 -t, --tabs
437 This flag causes one leading tab character to be inserted for
438 each level of indentation. Certain other features are
439 incompatible with this option, and if these options are also
440 given, then a warning message will be issued and this flag will
441 be unset. One example is the -lp option.
442 -dt=n, --default-tabsize=n
444 If the first line of code passed to perltidy contains leading
445 tabs but no tab scheme is specified for the output stream then
446 perltidy must guess how many spaces correspond to each leading
447 tab. This number of spaces n corresponding to each leading tab
448 of the input stream may be specified with -dt=n. The default
449 is n=8.
450 This flag has no effect if a tab scheme is specified for the
452 output stream, because then the input stream is assumed to use
453 the same tab scheme and indentation spaces as for the output
454 stream (any other assumption would lead to unstable editing).
455 -syn, --check-syntax
457 This flag is now ignored for safety, but the following
458 documentation has been retained for reference.
459 This flag causes perltidy to run "perl -c -T" to check syntax of
461 input and output. (To change the flags passed to perl, see the
462 next item, -pscf). The results are written to the .LOG file, which
463 will be saved if an error is detected in the output script. The
464 output script is not checked if the input script has a syntax
465 error. Perltidy does its own checking, but this option employs
466 perl to get a "second opinion".
467 If perl reports errors in the input file, they will not be reported
469 in the error output unless the --warning-output flag is given.
470 The default is NOT to do this type of syntax checking (although
472 perltidy will still do as much self-checking as possible). The
473 reason is that it causes all code in BEGIN blocks to be executed,
474 for all modules being used, and this opens the door to security
475 issues and infinite loops when running perltidy.
476 -pscf=s, -perl-syntax-check-flags=s
478 When perl is invoked to check syntax, the normal flags are "-c -T".
479 In addition, if the -x flag is given to perltidy, then perl will
480 also be passed a -x flag. It should not normally be necessary to
481 change these flags, but it can be done with the -pscf=s flag. For
482 example, if the taint flag, "-T", is not wanted, the flag could be
483 set to be just -pscf=-c.
484 Perltidy will pass your string to perl with the exception that it
486 will add a -c and -x if appropriate. The .LOG file will show
487 exactly what flags were passed to perl.
488 -xs, --extended-syntax
490 A problem with formatting Perl code is that some modules can
491 introduce new syntax. This flag allows perltidy to handle certain
492 common extensions to the standard syntax without complaint.
493 For example, without this flag a structure such as the following
495 would generate a syntax error and the braces would not be balanced:
496 method deposit( Num $amount) {
498 $self->balance( $self->balance + $amount );
499 }
500 This flag is enabled by default but it can be deactivated with
502 -nxs. Probably the only reason to deactivate this flag is to
503 generate more diagnostic messages when debugging a script.
504 -io, --indent-only
506 This flag is used to deactivate all whitespace and line break
507 changes within non-blank lines of code. When it is in effect, the
508 only change to the script will be to the indentation and to the
509 number of blank lines. And any flags controlling whitespace and
510 newlines will be ignored. You might want to use this if you are
511 perfectly happy with your whitespace and line breaks, and merely
512 want perltidy to handle the indentation. (This also speeds up
513 perltidy by well over a factor of two, so it might be useful when
514 perltidy is merely being used to help find a brace error in a large
515 script).
516 Setting this flag is equivalent to setting --freeze-newlines and
518 --freeze-whitespace.
519 If you also want to keep your existing blank lines exactly as they
521 are, you can add --freeze-blank-lines.
522 With this option perltidy is still free to modify the indenting
524 (and outdenting) of code and comments as it normally would. If you
525 also want to prevent long comment lines from being outdented, you
526 can add either -noll or -l=0.
527 Setting this flag will prevent perltidy from doing any special
529 operations on closing side comments. You may still delete all side
530 comments however when this flag is in effect.
531 -enc=s, --character-encoding=s
533 where s=none or utf8. This flag tells perltidy the character
534 encoding of both the input and output character streams. The value
535 utf8 causes the stream to be read and written as UTF-8. The value
536 none causes the stream to be processed without special encoding
537 assumptions. At present there is no automatic detection of
538 character encoding (even if there is a 'use utf8' statement in your
539 code) so this flag must be set for streams encoded in UTF-8.
540 Incorrectly setting this parameter can cause data corruption, so
541 please carefully check the output.
542 The default is none.
544 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8. So
546 to process a file named file.pl which is encoded in UTF-8 you can
547 use:
548 perltidy -utf8 file.pl
550 -ole=s, --output-line-ending=s
552 where s="win", "dos", "unix", or "mac". This flag tells perltidy
553 to output line endings for a specific system. Normally, perltidy
554 writes files with the line separator character of the host system.
555 The "win" and "dos" flags have an identical result.
556 -ple, --preserve-line-endings
558 This flag tells perltidy to write its output files with the same
559 line endings as the input file, if possible. It should work for
560 dos, unix, and mac line endings. It will only work if perltidy
561 input comes from a filename (rather than stdin, for example). If
562 perltidy has trouble determining the input file line ending, it
563 will revert to the default behavior of using the line ending of the
564 host system.
565 -it=n, --iterations=n
567 This flag causes perltidy to do n complete iterations. The reason
568 for this flag is that code beautification is an iterative process
569 and in some cases the output from perltidy can be different if it
570 is applied a second time. For most purposes the default of n=1
571 should be satisfactory. However n=2 can be useful when a major
572 style change is being made, or when code is being beautified on
573 check-in to a source code control system. It has been found to be
574 extremely rare for the output to change after 2 iterations. If a
575 value n is greater than 2 is input then a convergence test will be
576 used to stop the iterations as soon as possible, almost always
577 after 2 iterations. See the next item for a simplified iteration
578 control.
579 This flag has no effect when perltidy is used to generate html.
581 -conv, --converge
583 This flag is equivalent to -it=4 and is included to simplify
584 iteration control. For all practical purposes one either does or
585 does not want to be sure that the output is converged, and there is
586 no penalty to using a large iteration limit since perltidy will
587 check for convergence and stop iterating as soon as possible. The
588 default is -nconv (no convergence check). Using -conv will
589 approximately double run time since normally one extra iteration is
590 required to verify convergence.
591 Code Indentation Control
593 -ci=n, --continuation-indentation=n
594 Continuation indentation is extra indentation spaces applied when a
595 long line is broken. The default is n=2, illustrated here:
596 my $level = # -ci=2
598 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
599 The same example, with n=0, is a little harder to read:
601 my $level = # -ci=0
603 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
604 The value given to -ci is also used by some commands when a small
606 space is required. Examples are commands for outdenting labels,
607 -ola, and control keywords, -okw.
608 When default values are not used, it is suggested that the value n
610 given with -ci=n be no more than about one-half of the number of
611 spaces assigned to a full indentation level on the -i=n command.
612 -sil=n --starting-indentation-level=n
614 By default, perltidy examines the input file and tries to determine
615 the starting indentation level. While it is often zero, it may not
616 be zero for a code snippet being sent from an editing session.
617 To guess the starting indentation level perltidy simply assumes
619 that indentation scheme used to create the code snippet is the same
620 as is being used for the current perltidy process. This is the
621 only sensible guess that can be made. It should be correct if this
622 is true, but otherwise it probably won't. For example, if the
623 input script was written with -i=2 and the current peltidy flags
624 have -i=4, the wrong initial indentation will be guessed for a code
625 snippet which has non-zero initial indentation. Likewise, if an
626 entabbing scheme is used in the input script and not in the current
627 process then the guessed indentation will be wrong.
628 If the default method does not work correctly, or you want to
630 change the starting level, use -sil=n, to force the starting level
631 to be n.
632 List indentation using -lp, --line-up-parentheses
634 By default, perltidy indents lists with 4 spaces, or whatever value
635 is specified with -i=n. Here is a small list formatted in this
636 way:
637 # perltidy (default)
639 @month_of_year = (
640 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
641 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
642 );
643 Use the -lp flag to add extra indentation to cause the data to
645 begin past the opening parentheses of a sub call or list, or
646 opening square bracket of an anonymous array, or opening curly
647 brace of an anonymous hash. With this option, the above list would
648 become:
649 # perltidy -lp
651 @month_of_year = (
652 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
653 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
654 );
655 If the available line length (see -l=n ) does not permit this much
657 space, perltidy will use less. For alternate placement of the
658 closing paren, see the next section.
659 This option has no effect on code BLOCKS, such as if/then/else
661 blocks, which always use whatever is specified with -i=n. Also,
662 the existence of line breaks and/or block comments between the
663 opening and closing parens may cause perltidy to temporarily revert
664 to its default method.
665 Note: The -lp option may not be used together with the -t tabs
667 option. It may, however, be used with the -et=n tab method.
668 In addition, any parameter which significantly restricts the
670 ability of perltidy to choose newlines will conflict with -lp and
671 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
672 and -ndnl. The reason is that the -lp indentation style can
673 require the careful coordination of an arbitrary number of break
674 points in hierarchical lists, and these flags may prevent that.
675 -cti=n, --closing-token-indentation
677 The -cti=n flag controls the indentation of a line beginning with a
678 ")", "]", or a non-block "}". Such a line receives:
679 -cti = 0 no extra indentation (default)
681 -cti = 1 extra indentation such that the closing token
682 aligns with its opening token.
683 -cti = 2 one extra indentation level if the line looks like:
684 ); or ]; or };
685 -cti = 3 one extra indentation level always
686 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
688 section).
689 # perltidy -lp -cti=1
691 @month_of_year = (
692 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
693 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
694 );
695 # perltidy -lp -cti=2
697 @month_of_year = (
698 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
699 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
700 );
701 These flags are merely hints to the formatter and they may not
703 always be followed. In particular, if -lp is not being used, the
704 indentation for cti=1 is constrained to be no more than one
705 indentation level.
706 If desired, this control can be applied independently to each of
708 the closing container token types. In fact, -cti=n is merely an
709 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
710 --closing-paren-indentation controls )'s, -csbi or
711 --closing-square-bracket-indentation controls ]'s, -cbi or
712 --closing-brace-indentation controls non-block }'s.
713 -icp, --indent-closing-paren
715 The -icp flag is equivalent to -cti=2, described in the previous
716 section. The -nicp flag is equivalent -cti=0. They are included
717 for backwards compatibility.
718 -icb, --indent-closing-brace
720 The -icb option gives one extra level of indentation to a brace
721 which terminates a code block . For example,
722 if ($task) {
724 yyy();
725 } # -icb
726 else {
727 zzz();
728 }
729 The default is not to do this, indicated by -nicb.
731 -olq, --outdent-long-quotes
733 When -olq is set, lines which is a quoted string longer than the
734 value maximum-line-length will have their indentation removed to
735 make them more readable. This is the default. To prevent such
736 out-denting, use -nolq or --nooutdent-long-lines.
737 -oll, --outdent-long-lines
739 This command is equivalent to --outdent-long-quotes and
740 --outdent-long-comments, and it is included for compatibility with
741 previous versions of perltidy. The negation of this also works,
742 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
743 and -nolc.
744 Outdenting Labels: -ola, --outdent-labels
746 This command will cause labels to be outdented by 2 spaces (or
747 whatever -ci has been set to), if possible. This is the default.
748 For example:
749 my $i;
751 LOOP: while ( $i = <FOTOS> ) {
752 chomp($i);
753 next unless $i;
754 fixit($i);
755 }
756 Use -nola to not outdent labels.
758 Outdenting Keywords
760 -okw, --outdent-keywords
761 The command -okw will cause certain leading control keywords to
762 be outdented by 2 spaces (or whatever -ci has been set to), if
763 possible. By default, these keywords are "redo", "next",
764 "last", "goto", and "return". The intention is to make these
765 control keywords easier to see. To change this list of
766 keywords being outdented, see the next section.
767 For example, using "perltidy -okw" on the previous example
769 gives:
770 my $i;
772 LOOP: while ( $i = <FOTOS> ) {
773 chomp($i);
774 next unless $i;
775 fixit($i);
776 }
777 The default is not to do this.
779 Specifying Outdented Keywords: -okwl=string,
781 --outdent-keyword-list=string
782 This command can be used to change the keywords which are
783 outdented with the -okw command. The parameter string is a
784 required list of perl keywords, which should be placed in
785 quotes if there are more than one. By itself, it does not
786 cause any outdenting to occur, so the -okw command is still
787 required.
788 For example, the commands "-okwl="next last redo goto" -okw"
790 will cause those four keywords to be outdented. It is probably
791 simplest to place any -okwl command in a .perltidyrc file.
792 Whitespace Control
794 Whitespace refers to the blank space between variables, operators, and
795 other code tokens.
796 -fws, --freeze-whitespace
798 This flag causes your original whitespace to remain unchanged, and
799 causes the rest of the whitespace commands in this section, the
800 Code Indentation section, and the Comment Control section to be
801 ignored.
802 Tightness of curly braces, parentheses, and square brackets.
804 Here the term "tightness" will mean the closeness with which pairs
805 of enclosing tokens, such as parentheses, contain the quantities
806 within. A numerical value of 0, 1, or 2 defines the tightness,
807 with 0 being least tight and 2 being most tight. Spaces within
808 containers are always symmetric, so if there is a space after a "("
809 then there will be a space before the corresponding ")".
810 The -pt=n or --paren-tightness=n parameter controls the space
812 within parens. The example below shows the effect of the three
813 possible values, 0, 1, and 2:
814 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
816 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
817 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
818 When n is 0, there is always a space to the right of a '(' and to
820 the left of a ')'. For n=2 there is never a space. For n=1, the
821 default, there is a space unless the quantity within the parens is
822 a single token, such as an identifier or quoted string.
823 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
825 controls the space within square brackets, as illustrated below.
826 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
828 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
829 $width = $col[$j + $k] - $col[$j]; # -sbt=2
830 Curly braces which do not contain code blocks are controlled by the
832 parameter -bt=n or --brace-tightness=n.
833 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
835 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
836 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
837 And finally, curly braces which contain blocks of code are
839 controlled by the parameter -bbt=n or --block-brace-tightness=n as
840 illustrated in the example below.
841 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
843 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
844 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
845 To simplify input in the case that all of the tightness flags have
847 the same value <n>, the parameter <-act=n> or
848 --all-containers-tightness=n is an abbreviation for the combination
849 <-pt=n -sbt=n -bt=n -bbt=n>.
850 -tso, --tight-secret-operators
852 The flag -tso causes certain perl token sequences (secret
853 operators) which might be considered to be a single operator to be
854 formatted "tightly" (without spaces). The operators currently
855 modified by this flag are:
856 0+ +0 ()x!! ~~<> ,=> =( )=
858 For example the sequence 0 +, which converts a string to a number,
860 would be formatted without a space: 0+ when the -tso flag is set.
861 This flag is off by default.
862 -sts, --space-terminal-semicolon
864 Some programmers prefer a space before all terminal semicolons.
865 The default is for no such space, and is indicated with -nsts or
866 --nospace-terminal-semicolon.
867 $i = 1 ; # -sts
869 $i = 1; # -nsts (default)
870 -sfs, --space-for-semicolon
872 Semicolons within for loops may sometimes be hard to see,
873 particularly when commas are also present. This option places
874 spaces on both sides of these special semicolons, and is the
875 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
876 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
878 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
879 -asc, --add-semicolons
881 Setting -asc allows perltidy to add any missing optional semicolon
882 at the end of a line which is followed by a closing curly brace on
883 the next line. This is the default, and may be deactivated with
884 -nasc or --noadd-semicolons.
885 -dsm, --delete-semicolons
887 Setting -dsm allows perltidy to delete extra semicolons which are
888 simply empty statements. This is the default, and may be
889 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
890 are not deleted, however, if they would promote a side comment to a
891 block comment).
892 -aws, --add-whitespace
894 Setting this option allows perltidy to add certain whitespace
895 improve code readability. This is the default. If you do not want
896 any whitespace added, but are willing to have some whitespace
897 deleted, use -naws. (Use -fws to leave whitespace completely
898 unchanged).
899 -dws, --delete-old-whitespace
901 Setting this option allows perltidy to remove some old whitespace
902 between characters, if necessary. This is the default. If you do
903 not want any old whitespace removed, use -ndws or
904 --nodelete-old-whitespace.
905 Detailed whitespace controls around tokens
907 For those who want more detailed control over the whitespace around
908 tokens, there are four parameters which can directly modify the
909 default whitespace rules built into perltidy for any token. They
910 are:
911 -wls=s or --want-left-space=s,
913 -nwls=s or --nowant-left-space=s,
915 -wrs=s or --want-right-space=s,
917 -nwrs=s or --nowant-right-space=s.
919 These parameters are each followed by a quoted string, s,
921 containing a list of token types. No more than one of each of
922 these parameters should be specified, because repeating a command-
923 line parameter always overwrites the previous one before perltidy
924 ever sees it.
925 To illustrate how these are used, suppose it is desired that there
927 be no space on either side of the token types = + - / *. The
928 following two parameters would specify this desire:
929 -nwls="= + - / *" -nwrs="= + - / *"
931 (Note that the token types are in quotes, and that they are
933 separated by spaces). With these modified whitespace rules, the
934 following line of math:
935 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
937 becomes this:
939 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
941 These parameters should be considered to be hints to perltidy
943 rather than fixed rules, because perltidy must try to resolve
944 conflicts that arise between them and all of the other rules that
945 it uses. One conflict that can arise is if, between two tokens,
946 the left token wants a space and the right one doesn't. In this
947 case, the token not wanting a space takes priority.
948 It is necessary to have a list of all token types in order to
950 create this type of input. Such a list can be obtained by the
951 command --dump-token-types. Also try the -D flag on a short
952 snippet of code and look at the .DEBUG file to see the
953 tokenization.
954 WARNING Be sure to put these tokens in quotes to avoid having them
956 misinterpreted by your command shell.
957 Space between specific keywords and opening paren
959 When an opening paren follows a Perl keyword, no space is
960 introduced after the keyword, unless it is (by default) one of
961 these:
962 my local our and or eq ne if else elsif until unless
964 while for foreach return switch case given when
965 These defaults can be modified with two commands:
967 -sak=s or --space-after-keyword=s adds keywords.
969 -nsak=s or --nospace-after-keyword=s removes keywords.
971 where s is a list of keywords (in quotes if necessary). For
973 example,
974 my ( $a, $b, $c ) = @_; # default
976 my( $a, $b, $c ) = @_; # -nsak="my local our"
977 The abbreviation -nsak='*' is equivalent to including all of the
979 keywords in the above list.
980 When both -nsak=s and -sak=s commands are included, the -nsak=s
982 command is executed first. For example, to have space after only
983 the keywords (my, local, our) you could use -nsak="*" -sak="my
984 local our".
985 To put a space after all keywords, see the next item.
987 Space between all keywords and opening parens
989 When an opening paren follows a function or keyword, no space is
990 introduced after the keyword except for the keywords noted in the
991 previous item. To always put a space between a function or keyword
992 and its opening paren, use the command:
993 -skp or --space-keyword-paren
995 You will probably also want to use the flag -sfp (next item) too.
997 Space between all function names and opening parens
999 When an opening paren follows a function the default is not to
1000 introduce a space. To cause a space to be introduced use:
1001 -sfp or --space-function-paren
1003 myfunc( $a, $b, $c ); # default
1005 myfunc ( $a, $b, $c ); # -sfp
1006 You will probably also want to use the flag -skp (previous item)
1008 too.
1009 Trimming whitespace around "qw" quotes
1011 -tqw or --trim-qw provide the default behavior of trimming spaces
1012 around multi-line "qw" quotes and indenting them appropriately.
1013 -ntqw or --notrim-qw cause leading and trailing whitespace around
1015 multi-line "qw" quotes to be left unchanged. This option will not
1016 normally be necessary, but was added for testing purposes, because
1017 in some versions of perl, trimming "qw" quotes changes the syntax
1018 tree.
1019 -sbq=n or --space-backslash-quote=n
1021 Lines like
1022 $str1=\"string1";
1024 $str2=\'string2';
1025 can confuse syntax highlighters unless a space is included between
1027 the backslash and the single or double quotation mark.
1028 This can be controlled with the value of n as follows:
1030 -sbq=0 means no space between the backslash and quote
1032 -sbq=1 means follow the example of the source code
1033 -sbq=2 means always put a space between the backslash and quote
1034 The default is -sbq=1, meaning that a space will be used 0if there
1036 is one in the source code.
1037 Trimming trailing whitespace from lines of POD
1039 -trp or --trim-pod will remove trailing whitespace from lines of
1040 POD. The default is not to do this.
1041 Comment Controls
1043 Perltidy has a number of ways to control the appearance of both block
1044 comments and side comments. The term block comment here refers to a
1045 full-line comment, whereas side comment will refer to a comment which
1046 appears on a line to the right of some code.
1047 -ibc, --indent-block-comments
1049 Block comments normally look best when they are indented to the
1050 same level as the code which follows them. This is the default
1051 behavior, but you may use -nibc to keep block comments left-
1052 justified. Here is an example:
1053 # this comment is indented (-ibc, default)
1055 if ($task) { yyy(); }
1056 The alternative is -nibc:
1058 # this comment is not indented (-nibc)
1060 if ($task) { yyy(); }
1061 See also the next item, -isbc, as well as -sbc, for other ways to
1063 have some indented and some outdented block comments.
1064 -isbc, --indent-spaced-block-comments
1066 If there is no leading space on the line, then the comment will not
1067 be indented, and otherwise it may be.
1068 If both -ibc and -isbc are set, then -isbc takes priority.
1070 -olc, --outdent-long-comments
1072 When -olc is set, lines which are full-line (block) comments longer
1073 than the value maximum-line-length will have their indentation
1074 removed. This is the default; use -nolc to prevent outdenting.
1075 -msc=n, --minimum-space-to-comment=n
1077 Side comments look best when lined up several spaces to the right
1078 of code. Perltidy will try to keep comments at least n spaces to
1079 the right. The default is n=4 spaces.
1080 -fpsc=n, --fixed-position-side-comment=n
1082 This parameter tells perltidy to line up side comments in column
1083 number n whenever possible. The default, n=0, will not do this.
1084 -iscl, --ignore-side-comment-lengths
1086 This parameter causes perltidy to ignore the length of side
1087 comments when setting line breaks. The default, -niscl, is to
1088 include the length of side comments when breaking lines to stay
1089 within the length prescribed by the -l=n maximum line length
1090 parameter. For example, the following long single line would
1091 remain intact with -l=80 and -iscl:
1092 perltidy -l=80 -iscl
1094 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1095 whereas without the -iscl flag the line will be broken:
1097 perltidy -l=80
1099 $vmsfile =~ s/;[\d\-]*$//
1100 ; # Clip off version number; we can use a newer version as well
1101 -hsc, --hanging-side-comments
1103 By default, perltidy tries to identify and align "hanging side
1104 comments", which are something like this:
1105 my $IGNORE = 0; # This is a side comment
1107 # This is a hanging side comment
1108 # And so is this
1109 A comment is considered to be a hanging side comment if (1) it
1111 immediately follows a line with a side comment, or another hanging
1112 side comment, and (2) there is some leading whitespace on the line.
1113 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1114 If block comments are preceded by a blank line, or have no leading
1115 whitespace, they will not be mistaken as hanging side comments.
1116 Closing Side Comments
1118 A closing side comment is a special comment which perltidy can
1119 automatically create and place after the closing brace of a code
1120 block. They can be useful for code maintenance and debugging. The
1121 command -csc (or --closing-side-comments) adds or updates closing
1122 side comments. For example, here is a small code snippet
1123 sub message {
1125 if ( !defined( $_[0] ) ) {
1126 print("Hello, World\n");
1127 }
1128 else {
1129 print( $_[0], "\n" );
1130 }
1131 }
1132 And here is the result of processing with "perltidy -csc":
1134 sub message {
1136 if ( !defined( $_[0] ) ) {
1137 print("Hello, World\n");
1138 }
1139 else {
1140 print( $_[0], "\n" );
1141 }
1142 } ## end sub message
1143 A closing side comment was added for "sub message" in this case,
1145 but not for the "if" and "else" blocks, because they were below the
1146 6 line cutoff limit for adding closing side comments. This limit
1147 may be changed with the -csci command, described below.
1148 The command -dcsc (or --delete-closing-side-comments) reverses this
1150 process and removes these comments.
1151 Several commands are available to modify the behavior of these two
1153 basic commands, -csc and -dcsc:
1154 -csci=n, or --closing-side-comment-interval=n
1156 where "n" is the minimum number of lines that a block must have
1157 in order for a closing side comment to be added. The default
1158 value is "n=6". To illustrate:
1159 # perltidy -csci=2 -csc
1161 sub message {
1162 if ( !defined( $_[0] ) ) {
1163 print("Hello, World\n");
1164 } ## end if ( !defined( $_[0] ))
1165 else {
1166 print( $_[0], "\n" );
1167 } ## end else [ if ( !defined( $_[0] ))
1168 } ## end sub message
1169 Now the "if" and "else" blocks are commented. However, now
1171 this has become very cluttered.
1172 -cscp=string, or --closing-side-comment-prefix=string
1174 where string is the prefix used before the name of the block
1175 type. The default prefix, shown above, is "## end". This
1176 string will be added to closing side comments, and it will also
1177 be used to recognize them in order to update, delete, and
1178 format them. Any comment identified as a closing side comment
1179 will be placed just a single space to the right of its closing
1180 brace.
1181 -cscl=string, or --closing-side-comment-list
1183 where "string" is a list of block types to be tagged with
1184 closing side comments. By default, all code block types
1185 preceded by a keyword or label (such as "if", "sub", and so on)
1186 will be tagged. The -cscl command changes the default list to
1187 be any selected block types; see "Specifying Block Types". For
1188 example, the following command requests that only "sub"'s,
1189 labels, "BEGIN", and "END" blocks be affected by any -csc or
1190 -dcsc operation:
1191 -cscl="sub : BEGIN END"
1193 -csct=n, or --closing-side-comment-maximum-text=n
1195 The text appended to certain block types, such as an "if"
1196 block, is whatever lies between the keyword introducing the
1197 block, such as "if", and the opening brace. Since this might
1198 be too much text for a side comment, there needs to be a limit,
1199 and that is the purpose of this parameter. The default value
1200 is "n=20", meaning that no additional tokens will be appended
1201 to this text after its length reaches 20 characters. Omitted
1202 text is indicated with "...". (Tokens, including sub names,
1203 are never truncated, however, so actual lengths may exceed
1204 this). To illustrate, in the above example, the appended text
1205 of the first block is " ( !defined( $_[0] )...". The existing
1206 limit of "n=20" caused this text to be truncated, as indicated
1207 by the "...". See the next flag for additional control of the
1208 abbreviated text.
1209 -cscb, or --closing-side-comments-balanced
1211 As discussed in the previous item, when the closing-side-
1212 comment-maximum-text limit is exceeded the comment text must be
1213 truncated. Older versions of perltidy terminated with three
1214 dots, and this can still be achieved with -ncscb:
1215 perltidy -csc -ncscb
1217 } ## end foreach my $foo (sort { $b cmp $a ...
1218 However this causes a problem with editors which cannot
1220 recognize comments or are not configured to do so because they
1221 cannot "bounce" around in the text correctly. The -cscb flag
1222 has been added to help them by appending appropriate balancing
1223 structure:
1224 perltidy -csc -cscb
1226 } ## end foreach my $foo (sort { $b cmp $a ... })
1227 The default is -cscb.
1229 -csce=n, or --closing-side-comment-else-flag=n
1231 The default, n=0, places the text of the opening "if" statement
1232 after any terminal "else".
1233 If n=2 is used, then each "elsif" is also given the text of the
1235 opening "if" statement. Also, an "else" will include the text
1236 of a preceding "elsif" statement. Note that this may result
1237 some long closing side comments.
1238 If n=1 is used, the results will be the same as n=2 whenever
1240 the resulting line length is less than the maximum allowed.
1241 -cscb, or --closing-side-comments-balanced
1243 When using closing-side-comments, and the closing-side-comment-
1244 maximum-text limit is exceeded, then the comment text must be
1245 abbreviated. It is terminated with three dots if the -cscb
1246 flag is negated:
1247 perltidy -csc -ncscb
1249 } ## end foreach my $foo (sort { $b cmp $a ...
1250 This causes a problem with older editors which do not recognize
1252 comments because they cannot "bounce" around in the text
1253 correctly. The -cscb flag tries to help them by appending
1254 appropriate terminal balancing structures:
1255 perltidy -csc -cscb
1257 } ## end foreach my $foo (sort { $b cmp $a ... })
1258 The default is -cscb.
1260 -cscw, or --closing-side-comment-warnings
1262 This parameter is intended to help make the initial transition
1263 to the use of closing side comments. It causes two things to
1264 happen if a closing side comment replaces an existing,
1265 different closing side comment: first, an error message will
1266 be issued, and second, the original side comment will be placed
1267 alone on a new specially marked comment line for later
1268 attention.
1269 The intent is to avoid clobbering existing hand-written side
1271 comments which happen to match the pattern of closing side
1272 comments. This flag should only be needed on the first run with
1273 -csc.
1274 Important Notes on Closing Side Comments:
1276 · Closing side comments are only placed on lines terminated with
1278 a closing brace. Certain closing styles, such as the use of
1279 cuddled elses (-ce), preclude the generation of some closing
1280 side comments.
1281 · Please note that adding or deleting of closing side comments
1283 takes place only through the commands -csc or -dcsc. The other
1284 commands, if used, merely modify the behavior of these two
1285 commands.
1286 · It is recommended that the -cscw flag be used along with -csc
1288 on the first use of perltidy on a given file. This will
1289 prevent loss of any existing side comment data which happens to
1290 have the csc prefix.
1291 · Once you use -csc, you should continue to use it so that any
1293 closing side comments remain correct as code changes.
1294 Otherwise, these comments will become incorrect as the code is
1295 updated.
1296 · If you edit the closing side comments generated by perltidy,
1298 you must also change the prefix to be different from the
1299 closing side comment prefix. Otherwise, your edits will be
1300 lost when you rerun perltidy with -csc. For example, you
1301 could simply change "## end" to be "## End", since the test is
1302 case sensitive. You may also want to use the -ssc flag to keep
1303 these modified closing side comments spaced the same as actual
1304 closing side comments.
1305 · Temporarily generating closing side comments is a useful
1307 technique for exploring and/or debugging a perl script,
1308 especially one written by someone else. You can always remove
1309 them with -dcsc.
1310 Static Block Comments
1312 Static block comments are block comments with a special leading
1313 pattern, "##" by default, which will be treated slightly
1314 differently from other block comments. They effectively behave as
1315 if they had glue along their left and top edges, because they stick
1316 to the left edge and previous line when there is no blank spaces in
1317 those places. This option is particularly useful for controlling
1318 how commented code is displayed.
1319 -sbc, --static-block-comments
1321 When -sbc is used, a block comment with a special leading
1322 pattern, "##" by default, will be treated specially.
1323 Comments so identified are treated as follows:
1325 · If there is no leading space on the line, then the comment
1327 will not be indented, and otherwise it may be,
1328 · no new blank line will be inserted before such a comment,
1330 and
1331 · such a comment will never become a hanging side comment.
1333 For example, assuming @month_of_year is left-adjusted:
1335 @month_of_year = ( # -sbc (default)
1337 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1338 ## 'Dec', 'Nov'
1339 'Nov', 'Dec');
1340 Without this convention, the above code would become
1342 @month_of_year = ( # -nsbc
1344 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1345 ## 'Dec', 'Nov'
1347 'Nov', 'Dec'
1348 );
1349 which is not as clear. The default is to use -sbc. This may
1351 be deactivated with -nsbc.
1352 -sbcp=string, --static-block-comment-prefix=string
1354 This parameter defines the prefix used to identify static block
1355 comments when the -sbc parameter is set. The default prefix is
1356 "##", corresponding to "-sbcp=##". The prefix is actually part
1357 of a perl pattern used to match lines and it must either begin
1358 with "#" or "^#". In the first case a prefix ^\s* will be
1359 added to match any leading whitespace, while in the second case
1360 the pattern will match only comments with no leading
1361 whitespace. For example, to identify all comments as static
1362 block comments, one would use "-sbcp=#". To identify all left-
1363 adjusted comments as static block comments, use "-sbcp='^#'".
1364 Please note that -sbcp merely defines the pattern used to
1366 identify static block comments; it will not be used unless the
1367 switch -sbc is set. Also, please be aware that since this
1368 string is used in a perl regular expression which identifies
1369 these comments, it must enable a valid regular expression to be
1370 formed.
1371 A pattern which can be useful is:
1373 -sbcp=^#{2,}[^\s#]
1375 This pattern requires a static block comment to have at least
1377 one character which is neither a # nor a space. It allows a
1378 line containing only '#' characters to be rejected as a static
1379 block comment. Such lines are often used at the start and end
1380 of header information in subroutines and should not be
1381 separated from the intervening comments, which typically begin
1382 with just a single '#'.
1383 -osbc, --outdent-static-block-comments
1385 The command -osbc will cause static block comments to be
1386 outdented by 2 spaces (or whatever -ci=n has been set to), if
1387 possible.
1388 Static Side Comments
1390 Static side comments are side comments with a special leading
1391 pattern. This option can be useful for controlling how commented
1392 code is displayed when it is a side comment.
1393 -ssc, --static-side-comments
1395 When -ssc is used, a side comment with a static leading
1396 pattern, which is "##" by default, will be spaced only a single
1397 space from previous character, and it will not be vertically
1398 aligned with other side comments.
1399 The default is -nssc.
1401 -sscp=string, --static-side-comment-prefix=string
1403 This parameter defines the prefix used to identify static side
1404 comments when the -ssc parameter is set. The default prefix is
1405 "##", corresponding to "-sscp=##".
1406 Please note that -sscp merely defines the pattern used to
1408 identify static side comments; it will not be used unless the
1409 switch -ssc is set. Also, note that this string is used in a
1410 perl regular expression which identifies these comments, so it
1411 must enable a valid regular expression to be formed.
1412 Skipping Selected Sections of Code
1414 Selected lines of code may be passed verbatim to the output without any
1415 formatting. This feature is enabled by default but can be disabled
1416 with the --noformat-skipping or -nfs flag. It should be used sparingly
1417 to avoid littering code with markers, but it might be helpful for
1418 working around occasional problems. For example it might be useful for
1419 keeping the indentation of old commented code unchanged, keeping
1420 indentation of long blocks of aligned comments unchanged, keeping
1421 certain list formatting unchanged, or working around a glitch in
1422 perltidy.
1423 -fs, --format-skipping
1425 This flag, which is enabled by default, causes any code between
1426 special beginning and ending comment markers to be passed to the
1427 output without formatting. The default beginning marker is #<<<
1428 and the default ending marker is #>>> but they may be changed (see
1429 next items below). Additional text may appear on these special
1430 comment lines provided that it is separated from the marker by at
1431 least one space. For example
1432 #<<< do not let perltidy touch this
1434 my @list = (1,
1435 1, 1,
1436 1, 2, 1,
1437 1, 3, 3, 1,
1438 1, 4, 6, 4, 1,);
1439 #>>>
1440 The comment markers may be placed at any location that a block
1442 comment may appear. If they do not appear to be working, use the
1443 -log flag and examine the .LOG file. Use -nfs to disable this
1444 feature.
1445 -fsb=string, --format-skipping-begin=string
1447 The -fsb=string parameter may be used to change the beginning
1448 marker for format skipping. The default is equivalent to
1449 -fsb='#<<<'. The string that you enter must begin with a # and
1450 should be in quotes as necessary to get past the command shell of
1451 your system. It is actually the leading text of a pattern that is
1452 constructed by appending a '\s', so you must also include
1453 backslashes for characters to be taken literally rather than as
1454 patterns.
1455 Some examples show how example strings become patterns:
1457 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1459 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1460 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1461 -fse=string, --format-skipping-end=string
1463 The -fsb=string is the corresponding parameter used to change the
1464 ending marker for format skipping. The default is equivalent to
1465 -fse='#<<<'.
1466 Line Break Control
1468 The parameters in this section control breaks after non-blank lines of
1469 code. Blank lines are controlled separately by parameters in the
1470 section "Blank Line Control".
1471 -fnl, --freeze-newlines
1473 If you do not want any changes to the line breaks within lines of
1474 code in your script, set -fnl, and they will remain fixed, and the
1475 rest of the commands in this section and sections "Controlling List
1476 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1477 want to use -noll with this.
1478 Note: If you also want to keep your blank lines exactly as they
1480 are, you can use the -fbl flag which is described in the section
1481 "Blank Line Control".
1482 -ce, --cuddled-else
1484 Enable the "cuddled else" style, in which "else" and "elsif" are
1485 follow immediately after the curly brace closing the previous
1486 block. The default is not to use cuddled elses, and is indicated
1487 with the flag -nce or --nocuddled-else. Here is a comparison of
1488 the alternatives:
1489 # -ce
1491 if ($task) {
1492 yyy();
1493 } else {
1494 zzz();
1495 }
1496 # -nce (default)
1498 if ($task) {
1499 yyy();
1500 }
1501 else {
1502 zzz();
1503 }
1504 In this example the keyword else is placed on the same line which
1506 begins with the preceding closing block brace and is followed by
1507 its own opening block brace on the same line. Other keywords and
1508 function names which are formatted with this "cuddled" style are
1509 elsif, continue, catch, finally.
1510 Other block types can be formatted by specifying their names on a
1512 separate parameter -cbl, described in a later section.
1513 Cuddling between a pair of code blocks requires that the closing
1515 brace of the first block start a new line. If this block is
1516 entirely on one line in the input file, it is necessary to decide
1517 if it should be broken to allow cuddling. This decision is
1518 controlled by the flag -cbo=n discussed below. The default and
1519 recommended value of -cbo=1 bases this decision on the first block
1520 in the chain. If it spans multiple lines then cuddling is made and
1521 continues along the chain, regardless of the sizes of subsequent
1522 blocks. Otherwise, short lines remain intact.
1523 So for example, the -ce flag would not have any effect if the above
1525 snippet is rewritten as
1526 if ($task) { yyy() }
1528 else { zzz() }
1529 If the first block spans multiple lines, then cuddling can be done
1531 and will continue for the subsequent blocks in the chain, as
1532 illustrated in the previous snippet.
1533 If there are blank lines between cuddled blocks they will be
1535 eliminated. If there are comments after the closing brace where
1536 cuddling would occur then cuddling will be prevented. If this
1537 occurs, cuddling will restart later in the chain if possible.
1538 -cb, --cuddled-blocks
1540 This flag is equivalent to -ce.
1541 -cbl, --cuddled-block-list
1543 The built-in default cuddled block types are else, elsif, continue,
1544 catch, finally.
1545 Additional block types to which the -cuddled-blocks style applies
1547 can be defined by this parameter. This parameter is a character
1548 string, giving a list of block types separated by commas or spaces.
1549 For example, to cuddle code blocks of type sort, map and grep, in
1550 addition to the default types, the string could be set to
1551 -cbl="sort map grep"
1553 or equivalently
1555 -cbl=sort,map,grep
1557 Note however that these particular block types are typically short
1559 so there might not be much opportunity for the cuddled format
1560 style.
1561 Using commas avoids the need to protect spaces with quotes.
1563 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
1565 can be used to view the hash of values that are generated by this
1566 flag.
1567 Finally, note that the -cbl flag by itself merely specifies which
1569 blocks are formatted with the cuddled format. It has no effect
1570 unless this formatting style is activated with -ce.
1571 -cblx, --cuddled-block-list-exclusive
1573 When cuddled else formatting is selected with -ce, setting this
1574 flag causes perltidy to ignore its built-in defaults and rely
1575 exclusively on the block types specified on the -cbl flag described
1576 in the previous section. For example, to avoid using cuddled catch
1577 and finally, which among in the defaults, the following set of
1578 parameters could be used:
1579 perltidy -ce -cbl='else elsif continue' -cblx
1581 -cbo=n, --cuddled-break-option=n
1583 Cuddled formatting is only possible between a pair of code blocks
1584 if the closing brace of the first block starts a new line. If a
1585 block is encountered which is entirely on a single line, and
1586 cuddled formatting is selected, it is necessary to make a decision
1587 as to whether or not to "break" the block, meaning to cause it to
1588 span multiple lines. This parameter controls that decision. The
1589 options are:
1590 cbo=0 Never force a short block to break.
1592 cbo=1 If the first of a pair of blocks is broken in the input file,
1593 then break the second [DEFAULT].
1594 cbo=2 Break open all blocks for maximal cuddled formatting.
1595 The default and recommended value is cbo=1. With this value, if
1597 the starting block of a chain spans multiple lines, then a cascade
1598 of breaks will occur for remaining blocks causing the entire chain
1599 to be cuddled.
1600 The option cbo=0 can produce erratic cuddling if there are numerous
1602 one-line blocks.
1603 The option cbo=2 produces maximal cuddling but will not allow any
1605 short blocks.
1606 -bl, --opening-brace-on-new-line
1608 Use the flag -bl to place the opening brace on a new line:
1609 if ( $input_file eq '-' ) # -bl
1611 {
1612 important_function();
1613 }
1614 This flag applies to all structural blocks, including named sub's
1616 (unless the -sbl flag is set -- see next item).
1617 The default style, -nbl, places an opening brace on the same line
1619 as the keyword introducing it. For example,
1620 if ( $input_file eq '-' ) { # -nbl (default)
1622 -sbl, --opening-sub-brace-on-new-line
1624 The flag -sbl can be used to override the value of -bl for the
1625 opening braces of named sub's. For example,
1626 perltidy -sbl
1628 produces this result:
1630 sub message
1632 {
1633 if (!defined($_[0])) {
1634 print("Hello, World\n");
1635 }
1636 else {
1637 print($_[0], "\n");
1638 }
1639 }
1640 This flag is negated with -nsbl. If -sbl is not specified, the
1642 value of -bl is used.
1643 -asbl, --opening-anonymous-sub-brace-on-new-line
1645 The flag -asbl is like the -sbl flag except that it applies to
1646 anonymous sub's instead of named subs. For example
1647 perltidy -asbl
1649 produces this result:
1651 $a = sub
1653 {
1654 if ( !defined( $_[0] ) ) {
1655 print("Hello, World\n");
1656 }
1657 else {
1658 print( $_[0], "\n" );
1659 }
1660 };
1661 This flag is negated with -nasbl, and the default is -nasbl.
1663 -bli, --brace-left-and-indent
1665 The flag -bli is the same as -bl but in addition it causes one unit
1666 of continuation indentation ( see -ci ) to be placed before an
1667 opening and closing block braces.
1668 For example,
1670 if ( $input_file eq '-' ) # -bli
1672 {
1673 important_function();
1674 }
1675 By default, this extra indentation occurs for blocks of type: if,
1677 elsif, else, unless, for, foreach, sub, while, until, and also with
1678 a preceding label. The next item shows how to change this.
1679 -blil=s, --brace-left-and-indent-list=s
1681 Use this parameter to change the types of block braces for which
1682 the -bli flag applies; see "Specifying Block Types". For example,
1683 -blil='if elsif else' would apply it to only "if/elsif/else"
1684 blocks.
1685 -bar, --opening-brace-always-on-right
1687 The default style, -nbl places the opening code block brace on a
1688 new line if it does not fit on the same line as the opening
1689 keyword, like this:
1690 if ( $bigwasteofspace1 && $bigwasteofspace2
1692 || $bigwasteofspace3 && $bigwasteofspace4 )
1693 {
1694 big_waste_of_time();
1695 }
1696 To force the opening brace to always be on the right, use the -bar
1698 flag. In this case, the above example becomes
1699 if ( $bigwasteofspace1 && $bigwasteofspace2
1701 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1702 big_waste_of_time();
1703 }
1704 A conflict occurs if both -bl and -bar are specified.
1706 -otr, --opening-token-right and related flags
1708 The -otr flag is a hint that perltidy should not place a break
1709 between a comma and an opening token. For example:
1710 # default formatting
1712 push @{ $self->{$module}{$key} },
1713 {
1714 accno => $ref->{accno},
1715 description => $ref->{description}
1716 };
1717 # perltidy -otr
1719 push @{ $self->{$module}{$key} }, {
1720 accno => $ref->{accno},
1721 description => $ref->{description}
1722 };
1723 The flag -otr is actually an abbreviation for three other flags
1725 which can be used to control parens, hash braces, and square
1726 brackets separately if desired:
1727 -opr or --opening-paren-right
1729 -ohbr or --opening-hash-brace-right
1730 -osbr or --opening-square-bracket-right
1731 -wn, --weld-nested-containers
1733 The -wn flag causes closely nested pairs of opening and closing
1734 container symbols (curly braces, brackets, or parens) to be
1735 "welded" together, meaning that they are treated as if combined
1736 into a single unit, with the indentation of the innermost code
1737 reduced to be as if there were just a single container symbol.
1738 For example:
1740 # default formatting
1742 do {
1743 {
1744 next if $x == $y;
1745 }
1746 } until $x++ > $z;
1747 # perltidy -wn
1749 do { {
1750 next if $x == $y;
1751 } } until $x++ > $z;
1752 When this flag is set perltidy makes a preliminary pass through the
1754 file and identifies all nested pairs of containers. To qualify as
1755 a nested pair, the closing container symbols must be immediately
1756 adjacent. The opening symbols must either be adjacent, or, if the
1757 outer opening symbol is an opening paren, they may be separated by
1758 any single non-container symbol or something that looks like a
1759 function evaluation.
1760 Any container symbol may serve as both the inner container of one
1762 pair and as the outer container of an adjacent pair. Consequently,
1763 any number of adjacent opening or closing symbols may join together
1764 in weld. For example, here are three levels of wrapped function
1765 calls:
1766 # default formatting
1768 my (@date_time) = Localtime(
1769 Date_to_Time(
1770 Add_Delta_DHMS(
1771 $year, $month, $day, $hour, $minute, $second,
1772 '0', $offset, '0', '0'
1773 )
1774 )
1775 );
1776 # perltidy -wn
1778 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
1779 $year, $month, $day, $hour, $minute, $second,
1780 '0', $offset, '0', '0'
1781 ) ) );
1782 Notice how the indentation of the inner lines are reduced by two
1784 levels in this case. This example also shows the typical result of
1785 this formatting, namely it is a sandwich consisting of an initial
1786 opening layer, a central section of any complexity forming the
1787 "meat" of the sandwich, and a final closing layer. This
1788 predictable structure helps keep the compacted structure readable.
1789 The inner sandwich layer is required to be at least one line thick.
1791 If this cannot be achieved, welding does not occur. This
1792 constraint can cause formatting to take a couple of iterations to
1793 stabilize when it is first applied to a script. The -conv flag can
1794 be used to insure that the final format is achieved in a single
1795 run.
1796 Here is an example illustrating a welded container within a welded
1798 containers:
1799 # default formatting
1801 $x->badd(
1802 bmul(
1803 $class->new(
1804 abs(
1805 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1806 )
1807 ),
1808 $m
1809 )
1810 );
1811 # perltidy -wn
1813 $x->badd( bmul(
1814 $class->new( abs(
1815 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1816 ) ),
1817 $m
1818 ) );
1819 This format option is quite general but there are some limitations.
1821 One limitation is that any line length limit still applies and can
1823 cause long welded sections to be broken into multiple lines.
1824 Another limitation is that an opening symbol which delimits quoted
1826 text cannot be included in a welded pair. This is because quote
1827 delimiters are treated specially in perltidy.
1828 Finally, the stacking of containers defined by this flag have
1830 priority over any other container stacking flags. This is because
1831 any welding is done first.
1832 Vertical tightness of non-block curly braces, parentheses, and square
1834 brackets.
1835 These parameters control what shall be called vertical tightness.
1836 Here are the main points:
1837 · Opening tokens (except for block braces) are controlled by
1839 -vt=n, or --vertical-tightness=n, where
1840 -vt=0 always break a line after opening token (default).
1842 -vt=1 do not break unless this would produce more than one
1843 step in indentation in a line.
1844 -vt=2 never break a line after opening token
1845 · You must also use the -lp flag when you use the -vt flag; the
1847 reason is explained below.
1848 · Closing tokens (except for block braces) are controlled by
1850 -vtc=n, or --vertical-tightness-closing=n, where
1851 -vtc=0 always break a line before a closing token (default),
1853 -vtc=1 do not break before a closing token which is followed
1854 by a semicolon or another closing token, and is not in
1855 a list environment.
1856 -vtc=2 never break before a closing token.
1857 The rules for -vtc=1 are designed to maintain a reasonable
1859 balance between tightness and readability in complex lists.
1860 · Different controls may be applied to different token types, and
1862 it is also possible to control block braces; see below.
1863 · Finally, please note that these vertical tightness flags are
1865 merely hints to the formatter, and it cannot always follow
1866 them. Things which make it difficult or impossible include
1867 comments, blank lines, blocks of code within a list, and
1868 possibly the lack of the -lp parameter. Also, these flags may
1869 be ignored for very small lists (2 or 3 lines in length).
1870 Here are some examples:
1872 # perltidy -lp -vt=0 -vtc=0
1874 %romanNumerals = (
1875 one => 'I',
1876 two => 'II',
1877 three => 'III',
1878 four => 'IV',
1879 );
1880 # perltidy -lp -vt=1 -vtc=0
1882 %romanNumerals = ( one => 'I',
1883 two => 'II',
1884 three => 'III',
1885 four => 'IV',
1886 );
1887 # perltidy -lp -vt=1 -vtc=1
1889 %romanNumerals = ( one => 'I',
1890 two => 'II',
1891 three => 'III',
1892 four => 'IV', );
1893 The difference between -vt=1 and -vt=2 is shown here:
1895 # perltidy -lp -vt=1
1897 $init->add(
1898 mysprintf( "(void)find_threadsv(%s);",
1899 cstring( $threadsv_names[ $op->targ ] )
1900 )
1901 );
1902 # perltidy -lp -vt=2
1904 $init->add( mysprintf( "(void)find_threadsv(%s);",
1905 cstring( $threadsv_names[ $op->targ ] )
1906 )
1907 );
1908 With -vt=1, the line ending in "add(" does not combine with the
1910 next line because the next line is not balanced. This can help
1911 with readability, but -vt=2 can be used to ignore this rule.
1912 The tightest, and least readable, code is produced with both
1914 "-vt=2" and "-vtc=2":
1915 # perltidy -lp -vt=2 -vtc=2
1917 $init->add( mysprintf( "(void)find_threadsv(%s);",
1918 cstring( $threadsv_names[ $op->targ ] ) ) );
1919 Notice how the code in all of these examples collapses vertically
1921 as -vt increases, but the indentation remains unchanged. This is
1922 because perltidy implements the -vt parameter by first formatting
1923 as if -vt=0, and then simply overwriting one output line on top of
1924 the next, if possible, to achieve the desired vertical tightness.
1925 The -lp indentation style has been designed to allow this vertical
1926 collapse to occur, which is why it is required for the -vt
1927 parameter.
1928 The -vt=n and -vtc=n parameters apply to each type of container
1930 token. If desired, vertical tightness controls can be applied
1931 independently to each of the closing container token types.
1932 The parameters for controlling parentheses are -pvt=n or
1934 --paren-vertical-tightness=n, and -pcvt=n or
1935 --paren-vertical-tightness-closing=n.
1936 Likewise, the parameters for square brackets are -sbvt=n or
1938 --square-bracket-vertical-tightness=n, and -sbcvt=n or
1939 --square-bracket-vertical-tightness-closing=n.
1940 Finally, the parameters for controlling non-code block braces are
1942 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
1943 --brace-vertical-tightness-closing=n.
1944 In fact, the parameter -vt=n is actually just an abbreviation for
1946 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
1947 -pvtc=n -bvtc=n sbvtc=n.
1948 -bbvt=n or --block-brace-vertical-tightness=n
1950 The -bbvt=n flag is just like the -vt=n flag but applies to opening
1951 code block braces.
1952 -bbvt=0 break after opening block brace (default).
1954 -bbvt=1 do not break unless this would produce more than one
1955 step in indentation in a line.
1956 -bbvt=2 do not break after opening block brace.
1957 It is necessary to also use either -bl or -bli for this to work,
1959 because, as with other vertical tightness controls, it is
1960 implemented by simply overwriting a line ending with an opening
1961 block brace with the subsequent line. For example:
1962 # perltidy -bli -bbvt=0
1964 if ( open( FILE, "< $File" ) )
1965 {
1966 while ( $File = <FILE> )
1967 {
1968 $In .= $File;
1969 $count++;
1970 }
1971 close(FILE);
1972 }
1973 # perltidy -bli -bbvt=1
1975 if ( open( FILE, "< $File" ) )
1976 { while ( $File = <FILE> )
1977 { $In .= $File;
1978 $count++;
1979 }
1980 close(FILE);
1981 }
1982 By default this applies to blocks associated with keywords if,
1984 elsif, else, unless, for, foreach, sub, while, until, and also with
1985 a preceding label. This can be changed with the parameter
1986 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
1987 where string is a space-separated list of block types. For more
1988 information on the possible values of this string, see "Specifying
1989 Block Types"
1990 For example, if we want to just apply this style to "if", "elsif",
1992 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
1993 elsif else'".
1994 There is no vertical tightness control for closing block braces;
1996 with one exception they will be placed on separate lines. The
1997 exception is that a cascade of closing block braces may be stacked
1998 on a single line. See -scbb.
1999 -sot, --stack-opening-tokens and related flags
2001 The -sot flag tells perltidy to "stack" opening tokens when
2002 possible to avoid lines with isolated opening tokens.
2003 For example:
2005 # default
2007 $opt_c = Text::CSV_XS->new(
2008 {
2009 binary => 1,
2010 sep_char => $opt_c,
2011 always_quote => 1,
2012 }
2013 );
2014 # -sot
2016 $opt_c = Text::CSV_XS->new( {
2017 binary => 1,
2018 sep_char => $opt_c,
2019 always_quote => 1,
2020 }
2021 );
2022 For detailed control of individual closing tokens the following
2024 controls can be used:
2025 -sop or --stack-opening-paren
2027 -sohb or --stack-opening-hash-brace
2028 -sosb or --stack-opening-square-bracket
2029 -sobb or --stack-opening-block-brace
2030 The flag -sot is an abbreviation for -sop -sohb -sosb.
2032 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
2034 will case a cascade of opening block braces to appear on a single
2035 line, although this an uncommon occurrence except in test scripts.
2036 -sct, --stack-closing-tokens and related flags
2038 The -sct flag tells perltidy to "stack" closing tokens when
2039 possible to avoid lines with isolated closing tokens.
2040 For example:
2042 # default
2044 $opt_c = Text::CSV_XS->new(
2045 {
2046 binary => 1,
2047 sep_char => $opt_c,
2048 always_quote => 1,
2049 }
2050 );
2051 # -sct
2053 $opt_c = Text::CSV_XS->new(
2054 {
2055 binary => 1,
2056 sep_char => $opt_c,
2057 always_quote => 1,
2058 } );
2059 The -sct flag is somewhat similar to the -vtc flags, and in some
2061 cases it can give a similar result. The difference is that the
2062 -vtc flags try to avoid lines with leading opening tokens by
2063 "hiding" them at the end of a previous line, whereas the -sct flag
2064 merely tries to reduce the number of lines with isolated closing
2065 tokens by stacking them but does not try to hide them. For
2066 example:
2067 # -vtc=2
2069 $opt_c = Text::CSV_XS->new(
2070 {
2071 binary => 1,
2072 sep_char => $opt_c,
2073 always_quote => 1, } );
2074 For detailed control of the stacking of individual closing tokens
2076 the following controls can be used:
2077 -scp or --stack-closing-paren
2079 -schb or --stack-closing-hash-brace
2080 -scsb or --stack-closing-square-bracket
2081 -scbb or --stack-closing-block-brace
2082 The flag -sct is an abbreviation for stacking the non-block closing
2084 tokens, -scp -schb -scsb.
2085 Stacking of closing block braces, -scbb, causes a cascade of
2087 isolated closing block braces to be combined into a single line as
2088 in the following example:
2089 # -scbb:
2091 for $w1 (@w1) {
2092 for $w2 (@w2) {
2093 for $w3 (@w3) {
2094 for $w4 (@w4) {
2095 push( @lines, "$w1 $w2 $w3 $w4\n" );
2096 } } } }
2097 To simplify input even further for the case in which both opening
2099 and closing non-block containers are stacked, the flag -sac or
2100 --stack-all-containers is an abbreviation for -sot -sot.
2101 -dnl, --delete-old-newlines
2103 By default, perltidy first deletes all old line break locations,
2104 and then it looks for good break points to match the desired line
2105 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2106 retain all old line break points.
2107 -anl, --add-newlines
2109 By default, perltidy will add line breaks when necessary to create
2110 continuations of long lines and to improve the script appearance.
2111 Use -nanl or --noadd-newlines to prevent any new line breaks.
2112 This flag does not prevent perltidy from eliminating existing line
2114 breaks; see --freeze-newlines to completely prevent changes to line
2115 break points.
2116 Controlling whether perltidy breaks before or after operators
2118 Four command line parameters provide some control over whether a
2119 line break should be before or after specific token types. Two
2120 parameters give detailed control:
2121 -wba=s or --want-break-after=s, and
2123 -wbb=s or --want-break-before=s.
2125 These parameters are each followed by a quoted string, s,
2127 containing a list of token types (separated only by spaces). No
2128 more than one of each of these parameters should be specified,
2129 because repeating a command-line parameter always overwrites the
2130 previous one before perltidy ever sees it.
2131 By default, perltidy breaks after these token types:
2133 % + - * / x != == >= <= =~ !~ < > | &
2134 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2135 And perltidy breaks before these token types by default:
2137 . << >> -> && || //
2138 To illustrate, to cause a break after a concatenation operator,
2140 '.', rather than before it, the command line would be
2141 -wba="."
2143 As another example, the following command would cause a break
2145 before math operators '+', '-', '/', and '*':
2146 -wbb="+ - / *"
2148 These commands should work well for most of the token types that
2150 perltidy uses (use --dump-token-types for a list). Also try the -D
2151 flag on a short snippet of code and look at the .DEBUG file to see
2152 the tokenization. However, for a few token types there may be
2153 conflicts with hardwired logic which cause unexpected results. One
2154 example is curly braces, which should be controlled with the
2155 parameter bl provided for that purpose.
2156 WARNING Be sure to put these tokens in quotes to avoid having them
2158 misinterpreted by your command shell.
2159 Two additional parameters are available which, though they provide
2161 no further capability, can simplify input are:
2162 -baao or --break-after-all-operators,
2164 -bbao or --break-before-all-operators.
2166 The -baao sets the default to be to break after all of the
2168 following operators:
2169 % + - * / x != == >= <= =~ !~ < > | &
2171 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2172 . : ? && || and or err xor
2173 and the -bbao flag sets the default to break before all of these
2175 operators. These can be used to define an initial break preference
2176 which can be fine-tuned with the -wba and -wbb flags. For example,
2177 to break before all operators except an = one could use --bbao
2178 -wba='=' rather than listing every single perl operator except = on
2179 a -wbb flag.
2180 Controlling List Formatting
2182 Perltidy attempts to place comma-separated arrays of values in tables
2183 which look good. Its default algorithms usually work well, and they
2184 have been improving with each release, but several parameters are
2185 available to control list formatting.
2186 -boc, --break-at-old-comma-breakpoints
2188 This flag tells perltidy to try to break at all old commas. This
2189 is not the default. Normally, perltidy makes a best guess at list
2190 formatting, and seldom uses old comma breakpoints. Usually this
2191 works well, but consider:
2192 my @list = (1,
2194 1, 1,
2195 1, 2, 1,
2196 1, 3, 3, 1,
2197 1, 4, 6, 4, 1,);
2198 The default formatting will flatten this down to one line:
2200 # perltidy (default)
2202 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2203 which hides the structure. Using -boc, plus additional flags to
2205 retain the original style, yields
2206 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2208 my @list = (1,
2209 1, 1,
2210 1, 2, 1,
2211 1, 3, 3, 1,
2212 1, 4, 6, 4, 1,);
2213 A disadvantage of this flag is that all tables in the file must
2215 already be nicely formatted. For another possibility see the -fs
2216 flag in "Skipping Selected Sections of Code".
2217 -mft=n, --maximum-fields-per-table=n
2219 If the computed number of fields for any table exceeds n, then it
2220 will be reduced to n. The default value for n is a large number,
2221 40. While this value should probably be left unchanged as a
2222 general rule, it might be used on a small section of code to force
2223 a list to have a particular number of fields per line, and then
2224 either the -boc flag could be used to retain this formatting, or a
2225 single comment could be introduced somewhere to freeze the
2226 formatting in future applications of perltidy.
2227 # perltidy -mft=2
2229 @month_of_year = (
2230 'Jan', 'Feb',
2231 'Mar', 'Apr',
2232 'May', 'Jun',
2233 'Jul', 'Aug',
2234 'Sep', 'Oct',
2235 'Nov', 'Dec'
2236 );
2237 -cab=n, --comma-arrow-breakpoints=n
2239 A comma which follows a comma arrow, '=>', is given special
2240 consideration. In a long list, it is common to break at all such
2241 commas. This parameter can be used to control how perltidy breaks
2242 at these commas. (However, it will have no effect if old comma
2243 breaks are being forced because -boc is used). The possible values
2244 of n are:
2245 n=0 break at all commas after =>
2247 n=1 stable: break at all commas after => if container is open,
2248 EXCEPT FOR one-line containers
2249 n=2 break at all commas after =>, BUT try to form the maximum
2250 maximum one-line container lengths
2251 n=3 do not treat commas after => specially at all
2252 n=4 break everything: like n=0 but ALSO break a short container with
2253 a => not followed by a comma when -vt=0 is used
2254 n=5 stable: like n=1 but ALSO break at open one-line containers when
2255 -vt=0 is used (default)
2256 For example, given the following single line, perltidy by default
2258 will not add any line breaks because it would break the existing
2259 one-line container:
2260 bless { B => $B, Root => $Root } => $package;
2262 Using -cab=0 will force a break after each comma-arrow item:
2264 # perltidy -cab=0:
2266 bless {
2267 B => $B,
2268 Root => $Root
2269 } => $package;
2270 If perltidy is subsequently run with this container broken, then by
2272 default it will break after each '=>' because the container is now
2273 broken. To reform a one-line container, the parameter -cab=2 could
2274 be used.
2275 The flag -cab=3 can be used to prevent these commas from being
2277 treated specially. In this case, an item such as "01" => 31 is
2278 treated as a single item in a table. The number of fields in this
2279 table will be determined by the same rules that are used for any
2280 other table. Here is an example.
2281 # perltidy -cab=3
2283 my %last_day = (
2284 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
2285 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
2286 "09" => 30, "10" => 31, "11" => 30, "12" => 31
2287 );
2288 Retaining or Ignoring Existing Line Breaks
2290 Several additional parameters are available for controlling the extent
2291 to which line breaks in the input script influence the output script.
2292 In most cases, the default parameter values are set so that, if a
2293 choice is possible, the output style follows the input style. For
2294 example, if a short logical container is broken in the input script,
2295 then the default behavior is for it to remain broken in the output
2296 script.
2297 Most of the parameters in this section would only be required for a
2299 one-time conversion of a script from short container lengths to longer
2300 container lengths. The opposite effect, of converting long container
2301 lengths to shorter lengths, can be obtained by temporarily using a
2302 short maximum line length.
2303 -bol, --break-at-old-logical-breakpoints
2305 By default, if a logical expression is broken at a "&&", "||",
2306 "and", or "or", then the container will remain broken. Also,
2307 breaks at internal keywords "if" and "unless" will normally be
2308 retained. To prevent this, and thus form longer lines, use -nbol.
2309 -bom, --break-at-old-method-breakpoints
2311 By default, a method call arrow "->" is considered a candidate for
2312 a breakpoint, but method chains will fill to the line width before
2313 a break is considered. With -bom, breaks before the arrow are
2314 preserved, so if you have preformatted a method chain:
2315 my $q = $rs
2317 ->related_resultset('CDs')
2318 ->related_resultset('Tracks')
2319 ->search({
2320 'track.id' => {-ident => 'none_search.id'},
2321 })->as_query;
2322 It will keep these breaks, rather than become this:
2324 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
2326 'track.id' => {-ident => 'none_search.id'},
2327 })->as_query;
2328 This flag will also look for and keep a 'cuddled' style of calls,
2330 in which lines begin with a closing paren followed by a call arrow,
2331 as in this example:
2332 my $q = $rs->related_resultset(
2334 'CDs'
2335 )->related_resultset(
2336 'Tracks'
2337 )->search( {
2338 'track.id' => { -ident => 'none_search.id' },
2339 } )->as_query;
2340 You may want to include the -weld-nested-containers flag in this
2342 case to keep nested braces and parens together, as in the last
2343 line.
2344 -bok, --break-at-old-keyword-breakpoints
2346 By default, perltidy will retain a breakpoint before keywords which
2347 may return lists, such as "sort" and <map>. This allows chains of
2348 these operators to be displayed one per line. Use -nbok to prevent
2349 retaining these breakpoints.
2350 -bot, --break-at-old-ternary-breakpoints
2352 By default, if a conditional (ternary) operator is broken at a ":",
2353 then it will remain broken. To prevent this, and thereby form
2354 longer lines, use -nbot.
2355 -boa, --break-at-old-attribute-breakpoints
2357 By default, if an attribute list is broken at a ":" in the source
2358 file, then it will remain broken. For example, given the following
2359 code, the line breaks at the ':'s will be retained:
2360 my @field
2362 : field
2363 : Default(1)
2364 : Get('Name' => 'foo') : Set('Name');
2365 If the attributes are on a single line in the source code then they
2367 will remain on a single line if possible.
2368 To prevent this, and thereby always form longer lines, use -nboa.
2370 -iob, --ignore-old-breakpoints
2372 Use this flag to tell perltidy to ignore existing line breaks to
2373 the maximum extent possible. This will tend to produce the longest
2374 possible containers, regardless of type, which do not exceed the
2375 line length limit.
2376 -kis, --keep-interior-semicolons
2378 Use the -kis flag to prevent breaking at a semicolon if there was
2379 no break there in the input file. Normally perltidy places a
2380 newline after each semicolon which terminates a statement unless
2381 several statements are contained within a one-line brace block. To
2382 illustrate, consider the following input lines:
2383 dbmclose(%verb_delim); undef %verb_delim;
2385 dbmclose(%expanded); undef %expanded;
2386 The default is to break after each statement, giving
2388 dbmclose(%verb_delim);
2390 undef %verb_delim;
2391 dbmclose(%expanded);
2392 undef %expanded;
2393 With perltidy -kis the multiple statements are retained:
2395 dbmclose(%verb_delim); undef %verb_delim;
2397 dbmclose(%expanded); undef %expanded;
2398 The statements are still subject to the specified value of maximum-
2400 line-length and will be broken if this maximum is exceeded.
2401 Blank Line Control
2403 Blank lines can improve the readability of a script if they are
2404 carefully placed. Perltidy has several commands for controlling the
2405 insertion, retention, and removal of blank lines.
2406 -fbl, --freeze-blank-lines
2408 Set -fbl if you want to the blank lines in your script to remain
2409 exactly as they are. The rest of the parameters in this section
2410 may then be ignored. (Note: setting the -fbl flag is equivalent to
2411 setting -mbl=0 and -kbl=2).
2412 -bbc, --blanks-before-comments
2414 A blank line will be introduced before a full-line comment. This
2415 is the default. Use -nbbc or --noblanks-before-comments to
2416 prevent such blank lines from being introduced.
2417 -blbs=n, --blank-lines-before-subs=n
2419 The parameter -blbs=n requests that least n blank lines precede a
2420 sub definition which does not follow a comment and which is more
2421 than one-line long. The default is <-blbs=1>. BEGIN and END
2422 blocks are included.
2423 The requested number of blanks statement will be inserted
2425 regardless of the value of --maximum-consecutive-blank-lines=n
2426 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
2427 output.
2428 This parameter interacts with the value k of the parameter
2430 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
2431 1. If -mbl=0 then no blanks will be output. This allows all blanks
2433 to be suppressed with a single parameter. Otherwise,
2434 2. If the number of old blank lines in the script is less than n
2436 then additional blanks will be inserted to make the total n
2437 regardless of the value of -mbl=k.
2438 3. If the number of old blank lines in the script equals or exceeds
2440 n then this parameter has no effect, however the total will not
2441 exceed value specified on the -mbl=k flag.
2442 -blbp=n, --blank-lines-before-packages=n
2444 The parameter -blbp=n requests that least n blank lines precede a
2445 package which does not follow a comment. The default is -blbp=1.
2446 This parameter interacts with the value k of the parameter
2448 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
2449 described for the previous item -blbs=n.
2450 -bbs, --blanks-before-subs
2452 For compatibility with previous versions, -bbs or
2453 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
2454 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
2456 and -blbs=0.
2457 -bbb, --blanks-before-blocks
2459 A blank line will be introduced before blocks of coding delimited
2460 by for, foreach, while, until, and if, unless, in the following
2461 circumstances:
2462 · The block is not preceded by a comment.
2464 · The block is not a one-line block.
2466 · The number of consecutive non-blank lines at the current
2468 indentation depth is at least -lbl (see next section).
2469 This is the default. The intention of this option is to introduce
2471 some space within dense coding. This is negated with -nbbb or
2472 --noblanks-before-blocks.
2473 -lbl=n --long-block-line-count=n
2475 This controls how often perltidy is allowed to add blank lines
2476 before certain block types (see previous section). The default is
2477 8. Entering a value of 0 is equivalent to entering a very large
2478 number.
2479 -blao=i or --blank-lines-after-opening-block=i
2481 This control places a minimum of i blank lines after a line which
2482 ends with an opening block brace of a specified type. By default,
2483 this only applies to the block of a named sub, but this can be
2484 changed (see -blaol below). The default is not to do this (i=0).
2485 Please see the note below on using the -blao and -blbc options.
2487 -blbc=i or --blank-lines-before-closing-block=i
2489 This control places a minimum of i blank lines before a line which
2490 begins with a closing block brace of a specified type. By default,
2491 this only applies to the block of a named sub, but this can be
2492 changed (see -blbcl below). The default is not to do this (i=0).
2493 -blaol=s or --blank-lines-after-opening-block-list=s
2495 The parameter s is a list of block type keywords to which the flag
2496 -blao should apply. The section "Specifying Block Types" explains
2497 how to list block types.
2498 -blbcl=s or --blank-lines-before-closing-block-list=s
2500 This parameter is a list of block type keywords to which the flag
2501 -blbc should apply. The section "Specifying Block Types" explains
2502 how to list block types.
2503 Note on using the -blao and -blbc options.
2505 These blank line controls introduce a certain minimum number of
2506 blank lines in the text, but the final number of blank lines may be
2507 greater, depending on values of the other blank line controls and
2508 the number of old blank lines. A consequence is that introducing
2509 blank lines with these and other controls cannot be exactly undone,
2510 so some experimentation with these controls is recommended before
2511 using them.
2512 For example, suppose that for some reason we decide to introduce
2514 one blank space at the beginning and ending of all blocks. We
2515 could do this using
2516 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
2518 Now suppose the script continues to be developed, but at some later
2520 date we decide we don't want these spaces after all. we might
2521 expect that running with the flags -blao=0 and -blbc=0 will undo
2522 them. However, by default perltidy retains single blank lines, so
2523 the blank lines remain.
2524 We can easily fix this by telling perltidy to ignore old blank
2526 lines by including the added parameter -kbl=0 and rerunning. Then
2527 the unwanted blank lines will be gone. However, this will cause
2528 all old blank lines to be ignored, perhaps even some that were
2529 added by hand to improve formatting. So please be cautious when
2530 using these parameters.
2531 -mbl=n --maximum-consecutive-blank-lines=n
2533 This parameter specifies the maximum number of consecutive blank
2534 lines which will be output within code sections of a script. The
2535 default is n=1. If the input file has more than n consecutive
2536 blank lines, the number will be reduced to n except as noted above
2537 for the -blbp and -blbs parameters. If n=0 then no blank lines
2538 will be output (unless all old blank lines are retained with the
2539 -kbl=2 flag of the next section).
2540 This flag obviously does not apply to pod sections, here-documents,
2542 and quotes.
2543 -kbl=n, --keep-old-blank-lines=n
2545 The -kbl=n flag gives you control over how your existing blank
2546 lines are treated.
2547 The possible values of n are:
2549 n=0 ignore all old blank lines
2551 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
2552 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
2553 The default is n=1.
2555 -sob, --swallow-optional-blank-lines
2557 This is equivalent to kbl=0 and is included for compatibility with
2558 previous versions.
2559 -nsob, --noswallow-optional-blank-lines
2561 This is equivalent to kbl=1 and is included for compatibility with
2562 previous versions.
2563 Controls for blank lines around lines of consecutive keywords
2565 The parameters in this section provide some control over the placement
2567 of blank lines within and around groups of statements beginning with
2568 selected keywords. These blank lines are called here keyword group
2569 blanks, and all of the parameters begin with --keyword-group-blanks*,
2570 or -kgb* for short. The default settings do not employ these controls
2571 but they can be enabled with the following parameters:
2572 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
2574 keywords
2575 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
2577 keywords required to form a group.
2578 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
2580 leading blank
2581 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
2583 trailing blank
2584 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
2586 between subgroups
2587 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
2589 blank lines between keywords
2590 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
2592 of times this logic is applied
2593 In addition, the following abbreviations are available to for
2595 simplified usage:
2596 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
2598 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
2600 Before describing the meaning of the parameters in detail let us look
2602 at an example which is formatted with default parameter settings.
2603 print "Entering test 2\n";
2605 use Test;
2606 use Encode qw(from_to encode decode
2607 encode_utf8 decode_utf8
2608 find_encoding is_utf8);
2609 use charnames qw(greek);
2610 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2611 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2612 my @source = qw(ascii iso8859-1 cp1250);
2613 my @destiny = qw(cp1047 cp37 posix-bc);
2614 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2615 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2616 return unless ($str);
2617 using perltidy -kgb gives:
2619 print "Entering test 2\n";
2621 <----------this blank controlled by -kgbb
2622 use Test;
2623 use Encode qw(from_to encode decode
2624 encode_utf8 decode_utf8
2625 find_encoding is_utf8);
2626 use charnames qw(greek);
2627 <---------this blank controlled by -kgbi
2628 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2629 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2630 my @source = qw(ascii iso8859-1 cp1250);
2631 my @destiny = qw(cp1047 cp37 posix-bc);
2632 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2633 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2634 <----------this blank controlled by -kgba
2635 return unless ($str);
2636 Blank lines have been introduced around the my and use sequences. What
2638 happened is that the default keyword list includes my and use but not
2639 print and return. So a continuous sequence of nine my and use
2640 statements was located. This number exceeds the default threshold of
2641 five, so blanks were placed before and after the entire group. Then,
2642 since there was also a subsequence of six my lines, a blank line was
2643 introduced to separate them.
2644 Finer control over blank placement can be achieved by using the
2646 individual parameters rather than the -kgb flag. The individual
2647 controls are as follows.
2648 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
2650 defines the set of keywords which will be formed into groups. The
2651 string is a space separated list of keywords. The default set is
2652 s="use require local our my", but any list of keywords may be used.
2653 Comment lines may also be included in a keyword group, even though they
2654 are not keywords. To include ordinary block comments, include the
2655 symbol BC. To include static block comments (which normally begin with
2656 '##'), include the symbol SBC.
2657 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
2659 describing the number of consecutive keyword statements forming a
2660 group. If s is an integer then it is the minimum number required for a
2661 group. A maximum value may also be given with the format s=min.max,
2662 where min is the minimum number and max is the maximum number, and the
2663 min and max values are separated by one or more dots. No groups will
2664 be found if the maximum is less than the minimum. The maximum is
2665 unlimited if not given. The default is s=5. Some examples:
2666 s min max number for group
2668 3 3 unlimited 3 or more
2669 1.1 1 1 1
2670 1..3 1 3 1 to 3
2671 1.0 1 0 (no match)
2672 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
2674 should appear before the first line of the group, as follows:
2675 n=0 => (delete) an existing blank line will be removed
2677 n=1 => (stable) no change to the input file is made [DEFAULT]
2678 n=2 => (insert) a blank line is introduced if possible
2679 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
2681 blank should appear after the last line of the group, using the same
2682 scheme (0=delete, 1=stable, 2=insert).
2683 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
2685 lines between the first and last statement of the entire group. If
2686 there is a continuous run of a single statement type with more than the
2687 minimum threshold number (as specified with -kgbs=s) then this switch
2688 causes a blank line be inserted between this subgroup and the others.
2689 In the example above this happened between the use and my statements.
2690 -kgbd or --keyword-group-blanks-delete controls the deletion of any
2692 blank lines that exist in the the group when it is first scanned. When
2693 statements are initially scanned, any existing blank lines are included
2694 in the collection. Any such orignial blank lines will be deleted
2695 before any other insertions are made when the parameter -kgbd is set.
2696 The default is not to do this, -nkgbd.
2697 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
2699 maximum number of times this logic will be applied to any file. The
2700 special value n=0 is the same as n=infinity which means it will be
2701 applied to an entire script [Default]. A value n=1 could be used to
2702 make it apply just one time for example. This might be useful for
2703 adjusting just the use statements in the top part of a module for
2704 example.
2705 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
2707 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
2708 set of default values.
2709 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
2711 This flag turns off keyword group blank lines and is the default
2712 setting.
2713 Here are a few notes about the functioning of this technique.
2715 · These parameters are probably more useful as part of a major code
2717 reformatting operation rather than as a routine formatting
2718 operation.
2719 In particular, note that deleting old blank lines with -kgbd is an
2721 irreversible operation so it should be applied with care. Existing
2722 blank lines may be serving an important role in controlling
2723 vertical alignment.
2724 · Conflicts which arise among these kgb* parameters and other blank
2726 line controls are generally resolved by producing the maximum
2727 number of blank lines implied by any parameter.
2728 For example, if the flags --freeze-blank-lines, or
2730 --keep-old-blank-lines=2, are set, then they have priority over any
2731 blank line deletion implied by the -kgb flags of this section, so
2732 no blank lines will be deleted.
2733 For another example, if a keyword group ends at a sub and the flag
2735 kgba=0 requests no blank line there, but we also have
2736 --blank-lines-before-subs=2, then two blank lines will still be
2737 introduced before the sub.
2738 · The introduction of blank lines does not occur if it would conflict
2740 with other input controls or code validity. For example, a blank
2741 line will not be placed within a here-doc or within a section of
2742 code marked with format skipping comments. And in general, a blank
2743 line will only be introduced at the end of a group if the next
2744 statement is a line of code.
2745 · The count which is used to determine the group size is not the
2747 number of lines but rather the total number of keywords which are
2748 found. Individual statements with a certain leading keyword may
2749 continue on multiple lines, but if any of these lines is nested
2750 more than one level deep then that group will be ended.
2751 · The search for groups of lines with similar leading keywords is
2753 based on the input source, not the final formatted source.
2754 Consequently, if the source code is badly formatted, it would be
2755 best to make a first formatting pass without these options.
2756 Styles
2758 A style refers to a convenient collection of existing parameters.
2759 -gnu, --gnu-style
2761 -gnu gives an approximation to the GNU Coding Standards (which do
2762 not apply to perl) as they are sometimes implemented. At present,
2763 this style overrides the default style with the following
2764 parameters:
2765 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
2767 -pbp, --perl-best-practices
2769 -pbp is an abbreviation for the parameters in the book Perl Best
2770 Practices by Damian Conway:
2771 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
2773 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
2774 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
2775 Please note that this parameter set includes -st and -se flags,
2777 which make perltidy act as a filter on one file only. These can be
2778 overridden by placing -nst and/or -nse after the -pbp parameter.
2779 Also note that the value of continuation indentation, -ci=4, is
2781 equal to the value of the full indentation, -i=4. In some complex
2782 statements perltidy will produce nicer results with -ci=2. This can
2783 be implemented by including -ci=2 after the -pbp parameter. For
2784 example,
2785 # perltidy -pbp
2787 $self->{_text} = (
2788 !$section ? ''
2789 : $type eq 'item' ? "the $section entry"
2790 : "the section on $section"
2791 )
2792 . (
2793 $page
2794 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2795 : ' elsewhere in this document'
2796 );
2797 # perltidy -pbp -ci=2
2799 $self->{_text} = (
2800 !$section ? ''
2801 : $type eq 'item' ? "the $section entry"
2802 : "the section on $section"
2803 )
2804 . (
2805 $page
2806 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2807 : ' elsewhere in this document'
2808 );
2809 One-line blocks
2811 There are a few points to note regarding one-line blocks. A one-
2812 line block is something like this,
2813 if ($x > 0) { $y = 1 / $x }
2815 where the contents within the curly braces is short enough to fit
2817 on a single line.
2818 With few exceptions, perltidy retains existing one-line blocks, if
2820 it is possible within the line-length constraint, but it does not
2821 attempt to form new ones. In other words, perltidy will try to
2822 follow the one-line block style of the input file.
2823 If an existing one-line block is longer than the maximum line
2825 length, however, it will be broken into multiple lines. When this
2826 happens, perltidy checks for and adds any optional terminating
2827 semicolon (unless the -nasc option is used) if the block is a code
2828 block.
2829 The main exception is that perltidy will attempt to form new one-
2831 line blocks following the keywords "map", "eval", and "sort",
2832 because these code blocks are often small and most clearly
2833 displayed in a single line.
2834 One-line block rules can conflict with the cuddled-else option.
2836 When the cuddled-else option is used, perltidy retains existing
2837 one-line blocks, even if they do not obey cuddled-else formatting.
2838 Occasionally, when one-line blocks get broken because they exceed
2840 the available line length, the formatting will violate the
2841 requested brace style. If this happens, reformatting the script a
2842 second time should correct the problem.
2843 Sometimes it might be desirable to convert a script to have one-
2845 line blocks whenever possible. Although there is currently no flag
2846 for this, a simple workaround is to execute perltidy twice, once
2847 with the flag -noadd-newlines and then once again with normal
2848 parameters, like this:
2849 cat infile | perltidy -nanl | perltidy >outfile
2851 When executed on this snippet
2853 if ( $? == -1 ) {
2855 die "failed to execute: $!\n";
2856 }
2857 if ( $? == -1 ) {
2858 print "Had enough.\n";
2859 die "failed to execute: $!\n";
2860 }
2861 the result is
2863 if ( $? == -1 ) { die "failed to execute: $!\n"; }
2865 if ( $? == -1 ) {
2866 print "Had enough.\n";
2867 die "failed to execute: $!\n";
2868 }
2869 This shows that blocks with a single statement become one-line
2871 blocks.
2872 -olbs=n, --one-line-block-semicolons=n
2874 This flag controls the placement of semicolons at the end of one-
2875 line blocks. Semicolons are optional before a closing block brace,
2876 and frequently they are omitted at the end of a one-line block
2877 containing just a single statement. By default, perltidy follows
2878 the input file regarding these semicolons, but this behavior can be
2879 controlled by this flag. The values of n are:
2880 n=0 remove terminal semicolons in one-line blocks having a single statement
2882 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
2883 n=2 add terminal semicolons in all one-line blocks
2884 Note that the n=2 option has no effect if adding semicolons is
2886 prohibited with the -nasc flag. Also not that while n=2 adds
2887 missing semicolons to all one-line blocks, regardless of
2888 complexity, the n=0 option only removes ending semicolons which
2889 terminate one-line blocks containing just one semicolon. So these
2890 two options are not exact inverses.
2891 Controlling Vertical Alignment
2893 Vertical alignment refers to lining up certain symbols in list of
2894 consecutive similar lines to improve readability. For example, the
2895 "fat commas" are aligned in the following statement:
2896 $data = $pkg->new(
2898 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
2899 PeerPort => $port[4] * 256 + $port[5],
2900 Proto => 'tcp'
2901 );
2902 The only explicit control on vertical alignment is to turn it off using
2904 -novalign, a flag mainly intended for debugging. However, vertical
2905 alignment can be forced to stop and restart by selectively introducing
2906 blank lines. For example, a blank has been inserted in the following
2907 code to keep somewhat similar things aligned.
2908 %option_range = (
2910 'format' => [ 'tidy', 'html', 'user' ],
2911 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
2912 'character-encoding' => [ 'none', 'utf8' ],
2913 'block-brace-tightness' => [ 0, 2 ],
2915 'brace-tightness' => [ 0, 2 ],
2916 'paren-tightness' => [ 0, 2 ],
2917 'square-bracket-tightness' => [ 0, 2 ],
2918 );
2919 Other Controls
2921 Deleting selected text
2922 Perltidy can selectively delete comments and/or pod documentation.
2923 The command -dac or --delete-all-comments will delete all comments
2924 and all pod documentation, leaving just code and any leading system
2925 control lines.
2926 The command -dp or --delete-pod will remove all pod documentation
2928 (but not comments).
2929 Two commands which remove comments (but not pod) are: -dbc or
2931 --delete-block-comments and -dsc or --delete-side-comments.
2932 (Hanging side comments will be deleted with block comments here.)
2933 The negatives of these commands also work, and are the defaults.
2935 When block comments are deleted, any leading 'hash-bang' will be
2936 retained. Also, if the -x flag is used, any system commands before
2937 a leading hash-bang will be retained (even if they are in the form
2938 of comments).
2939 Writing selected text to a file
2941 When perltidy writes a formatted text file, it has the ability to
2942 also send selected text to a file with a .TEE extension. This text
2943 can include comments and pod documentation.
2944 The command -tac or --tee-all-comments will write all comments and
2946 all pod documentation.
2947 The command -tp or --tee-pod will write all pod documentation (but
2949 not comments).
2950 The commands which write comments (but not pod) are: -tbc or
2952 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
2953 side comments will be written with block comments here.)
2954 The negatives of these commands also work, and are the defaults.
2956 Using a .perltidyrc command file
2958 If you use perltidy frequently, you probably won't be happy until
2959 you create a .perltidyrc file to avoid typing commonly-used
2960 parameters. Perltidy will first look in your current directory for
2961 a command file named .perltidyrc. If it does not find one, it will
2962 continue looking for one in other standard locations.
2963 These other locations are system-dependent, and may be displayed
2965 with the command "perltidy -dpro". Under Unix systems, it will
2966 first look for an environment variable PERLTIDY. Then it will look
2967 for a .perltidyrc file in the home directory, and then for a
2968 system-wide file /usr/local/etc/perltidyrc, and then it will look
2969 for /etc/perltidyrc. Note that these last two system-wide files do
2970 not have a leading dot. Further system-dependent information will
2971 be found in the INSTALL file distributed with perltidy.
2972 Under Windows, perltidy will also search for a configuration file
2974 named perltidy.ini since Windows does not allow files with a
2975 leading period (.). Use "perltidy -dpro" to see the possible
2976 locations for your system. An example might be C:\Documents and
2977 Settings\All Users\perltidy.ini.
2978 Another option is the use of the PERLTIDY environment variable.
2980 The method for setting environment variables depends upon the
2981 version of Windows that you are using. Instructions for Windows 95
2982 and later versions can be found here:
2983 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
2985 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
2987 be placed in either the user section or the system section. The
2988 later makes the configuration file common to all users on the
2989 machine. Be sure to enter the full path of the configuration file
2990 in the value of the environment variable. Ex.
2991 PERLTIDY=C:\Documents and Settings\perltidy.ini
2992 The configuration file is free format, and simply a list of
2994 parameters, just as they would be entered on a command line. Any
2995 number of lines may be used, with any number of parameters per
2996 line, although it may be easiest to read with one parameter per
2997 line. Comment text begins with a #, and there must also be a space
2998 before the # for side comments. It is a good idea to put complex
2999 parameters in either single or double quotes.
3000 Here is an example of a .perltidyrc file:
3002 # This is a simple of a .perltidyrc configuration file
3004 # This implements a highly spaced style
3005 -se # errors to standard error output
3006 -w # show all warnings
3007 -bl # braces on new lines
3008 -pt=0 # parens not tight at all
3009 -bt=0 # braces not tight
3010 -sbt=0 # square brackets not tight
3011 The parameters in the .perltidyrc file are installed first, so any
3013 parameters given on the command line will have priority over them.
3014 To avoid confusion, perltidy ignores any command in the .perltidyrc
3016 file which would cause some kind of dump and an exit. These are:
3017 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3019 There are several options may be helpful in debugging a .perltidyrc
3021 file:
3022 · A very helpful command is --dump-profile or -dpro. It writes a
3024 list of all configuration filenames tested to standard output,
3025 and if a file is found, it dumps the content to standard output
3026 before exiting. So, to find out where perltidy looks for its
3027 configuration files, and which one if any it selects, just
3028 enter
3029 perltidy -dpro
3031 · It may be simplest to develop and test configuration files with
3033 alternative names, and invoke them with -pro=filename on the
3034 command line. Then rename the desired file to .perltidyrc when
3035 finished.
3036 · The parameters in the .perltidyrc file can be switched off with
3038 the -npro option.
3039 · The commands --dump-options, --dump-defaults,
3041 --dump-long-names, and --dump-short-names, all described below,
3042 may all be helpful.
3043 Creating a new abbreviation
3045 A special notation is available for use in a .perltidyrc file for
3046 creating an abbreviation for a group of options. This can be used
3047 to create a shorthand for one or more styles which are frequently,
3048 but not always, used. The notation is to group the options within
3049 curly braces which are preceded by the name of the alias (without
3050 leading dashes), like this:
3051 newword {
3053 -opt1
3054 -opt2
3055 }
3056 where newword is the abbreviation, and opt1, etc, are existing
3058 parameters or other abbreviations. The main syntax requirement is
3059 that the new abbreviation along with its opening curly brace must
3060 begin on a new line. Space before and after the curly braces is
3061 optional. For a specific example, the following line
3062 airy {-bl -pt=0 -bt=0 -sbt=0}
3064 could be placed in a .perltidyrc file, and then invoked at will
3066 with
3067 perltidy -airy somefile.pl
3069 (Either "-airy" or "--airy" may be used).
3071 Skipping leading non-perl commands with -x or --look-for-hash-bang
3073 If your script has leading lines of system commands or other text
3074 which are not valid perl code, and which are separated from the
3075 start of the perl code by a "hash-bang" line, ( a line of the form
3076 "#!...perl" ), you must use the -x flag to tell perltidy not to
3077 parse and format any lines before the "hash-bang" line. This
3078 option also invokes perl with a -x flag when checking the syntax.
3079 This option was originally added to allow perltidy to parse
3080 interactive VMS scripts, but it should be used for any script which
3081 is normally invoked with "perl -x".
3082 Making a file unreadable
3084 The goal of perltidy is to improve the readability of files, but
3085 there are two commands which have the opposite effect, --mangle and
3086 --extrude. They are actually merely aliases for combinations of
3087 other parameters. Both of these strip all possible whitespace, but
3088 leave comments and pod documents, so that they are essentially
3089 reversible. The difference between these is that --mangle puts the
3090 fewest possible line breaks in a script while --extrude puts the
3091 maximum possible. Note that these options do not provided any
3092 meaningful obfuscation, because perltidy can be used to reformat
3093 the files. They were originally developed to help test the
3094 tokenization logic of perltidy, but they have other uses. One use
3095 for --mangle is the following:
3096 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
3098 This will form the maximum possible number of one-line blocks (see
3100 next section), and can sometimes help clean up a badly formatted
3101 script.
3102 A similar technique can be used with --extrude instead of --mangle
3104 to make the minimum number of one-line blocks.
3105 Another use for --mangle is to combine it with -dac to reduce the
3107 file size of a perl script.
3108 Debugging
3110 The following flags are available for debugging:
3111 --dump-cuddled-block-list or -dcbl will dump to standard output the
3113 internal hash of cuddled block types created by a
3114 -cuddled-block-list input string.
3115 --dump-defaults or -ddf will write the default option set to
3117 standard output and quit
3118 --dump-profile or -dpro will write the name of the current
3120 configuration file and its contents to standard output and quit.
3121 --dump-options or -dop will write current option set to standard
3123 output and quit.
3124 --dump-long-names or -dln will write all command line long names
3126 (passed to Get_options) to standard output and quit.
3127 --dump-short-names or -dsn will write all command line short names
3129 to standard output and quit.
3130 --dump-token-types or -dtt will write a list of all token types to
3132 standard output and quit.
3133 --dump-want-left-space or -dwls will write the hash
3135 %want_left_space to standard output and quit. See the section on
3136 controlling whitespace around tokens.
3137 --dump-want-right-space or -dwrs will write the hash
3139 %want_right_space to standard output and quit. See the section on
3140 controlling whitespace around tokens.
3141 --no-memoize or -nmem will turn of memoizing. Memoization can
3143 reduce run time when running perltidy repeatedly in a single
3144 process. It is on by default but can be deactivated for testing
3145 with -nmem.
3146 --no-timestamp or -nts will eliminate any time stamps in output
3148 files to prevent differences in dates from causing test
3149 installation scripts to fail. There are just a couple of places
3150 where timestamps normally occur. One is in the headers of html
3151 files, and another is when the -cscw option is selected. The
3152 default is to allow timestamps (--timestamp or -ts).
3153 --file-size-order or -fso will cause files to be processed in order
3155 of increasing size, when multiple files are being processed. This
3156 is useful during program development, when large numbers of files
3157 with varying sizes are processed, because it can reduce virtual
3158 memory usage.
3159 -DEBUG will write a file with extension .DEBUG for each input file
3161 showing the tokenization of all lines of code.
3162 Working with MakeMaker, AutoLoader and SelfLoader
3164 The first $VERSION line of a file which might be eval'd by
3165 MakeMaker is passed through unchanged except for indentation. Use
3166 --nopass-version-line, or -npvl, to deactivate this feature.
3167 If the AutoLoader module is used, perltidy will continue formatting
3169 code after seeing an __END__ line. Use --nolook-for-autoloader, or
3170 -nlal, to deactivate this feature.
3171 Likewise, if the SelfLoader module is used, perltidy will continue
3173 formatting code after seeing a __DATA__ line. Use
3174 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
3175 Working around problems with older version of Perl
3177 Perltidy contains a number of rules which help avoid known
3178 subtleties and problems with older versions of perl, and these
3179 rules always take priority over whatever formatting flags have been
3180 set. For example, perltidy will usually avoid starting a new line
3181 with a bareword, because this might cause problems if "use strict"
3182 is active.
3183 There is no way to override these rules.
3185
3187 The -html master switch
3188 The flag -html causes perltidy to write an html file with extension
3189 .html. So, for example, the following command
3190 perltidy -html somefile.pl
3192 will produce a syntax-colored html file named somefile.pl.html
3194 which may be viewed with a browser.
3195 Please Note: In this case, perltidy does not do any formatting to
3197 the input file, and it does not write a formatted file with
3198 extension .tdy. This means that two perltidy runs are required to
3199 create a fully reformatted, html copy of a script.
3200 The -pre flag for code snippets
3202 When the -pre flag is given, only the pre-formatted section, within
3203 the <PRE> and </PRE> tags, will be output. This simplifies
3204 inclusion of the output in other files. The default is to output a
3205 complete web page.
3206 The -nnn flag for line numbering
3208 When the -nnn flag is given, the output lines will be numbered.
3209 The -toc, or --html-table-of-contents flag
3211 By default, a table of contents to packages and subroutines will be
3212 written at the start of html output. Use -ntoc to prevent this.
3213 This might be useful, for example, for a pod document which
3214 contains a number of unrelated code snippets. This flag only
3215 influences the code table of contents; it has no effect on any
3216 table of contents produced by pod2html (see next item).
3217 The -pod, or --pod2html flag
3219 There are two options for formatting pod documentation. The
3220 default is to pass the pod through the Pod::Html module (which
3221 forms the basis of the pod2html utility). Any code sections are
3222 formatted by perltidy, and the results then merged. Note: perltidy
3223 creates a temporary file when Pod::Html is used; see "FILES".
3224 Also, Pod::Html creates temporary files for its cache.
3225 NOTE: Perltidy counts the number of "=cut" lines, and either moves
3227 the pod text to the top of the html file if there is one "=cut", or
3228 leaves the pod text in its original order (interleaved with code)
3229 otherwise.
3230 Most of the flags accepted by pod2html may be included in the
3232 perltidy command line, and they will be passed to pod2html. In
3233 some cases, the flags have a prefix "pod" to emphasize that they
3234 are for the pod2html, and this prefix will be removed before they
3235 are passed to pod2html. The flags which have the additional "pod"
3236 prefix are:
3237 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
3239 --[no]podverbose --podflush
3240 The flags which are unchanged from their use in pod2html are:
3242 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
3244 --podpath=s --podroot=s
3245 where 's' is an appropriate character string. Not all of these
3247 flags are available in older versions of Pod::Html. See your
3248 Pod::Html documentation for more information.
3249 The alternative, indicated with -npod, is not to use Pod::Html, but
3251 rather to format pod text in italics (or whatever the stylesheet
3252 indicates), without special html markup. This is useful, for
3253 example, if pod is being used as an alternative way to write
3254 comments.
3255 The -frm, or --frames flag
3257 By default, a single html output file is produced. This can be
3258 changed with the -frm option, which creates a frame holding a table
3259 of contents in the left panel and the source code in the right
3260 side. This simplifies code browsing. Assume, for example, that the
3261 input file is MyModule.pm. Then, for default file extension
3262 choices, these three files will be created:
3263 MyModule.pm.html - the frame
3265 MyModule.pm.toc.html - the table of contents
3266 MyModule.pm.src.html - the formatted source code
3267 Obviously this file naming scheme requires that output be directed
3269 to a real file (as opposed to, say, standard output). If this is
3270 not the case, or if the file extension is unknown, the -frm option
3271 will be ignored.
3272 The -text=s, or --html-toc-extension flag
3274 Use this flag to specify the extra file extension of the table of
3275 contents file when html frames are used. The default is "toc".
3276 See "Specifying File Extensions".
3277 The -sext=s, or --html-src-extension flag
3279 Use this flag to specify the extra file extension of the content
3280 file when html frames are used. The default is "src". See
3281 "Specifying File Extensions".
3282 The -hent, or --html-entities flag
3284 This flag controls the use of Html::Entities for html formatting.
3285 By default, the module Html::Entities is used to encode special
3286 symbols. This may not be the right thing for some browser/language
3287 combinations. Use --nohtml-entities or -nhent to prevent this.
3288 Style Sheets
3290 Style sheets make it very convenient to control and adjust the
3291 appearance of html pages. The default behavior is to write a page
3292 of html with an embedded style sheet.
3293 An alternative to an embedded style sheet is to create a page with
3295 a link to an external style sheet. This is indicated with the
3296 -css=filename, where the external style sheet is filename. The
3297 external style sheet filename will be created if and only if it
3298 does not exist. This option is useful for controlling multiple
3299 pages from a single style sheet.
3300 To cause perltidy to write a style sheet to standard output and
3302 exit, use the -ss, or --stylesheet, flag. This is useful if the
3303 style sheet could not be written for some reason, such as if the
3304 -pre flag was used. Thus, for example,
3305 perltidy -html -ss >mystyle.css
3307 will write a style sheet with the default properties to file
3309 mystyle.css.
3310 The use of style sheets is encouraged, but a web page without a
3312 style sheets can be created with the flag -nss. Use this option if
3313 you must to be sure that older browsers (roughly speaking, versions
3314 prior to 4.0 of Netscape Navigator and Internet Explorer) can
3315 display the syntax-coloring of the html files.
3316 Controlling HTML properties
3318 Note: It is usually more convenient to accept the default
3319 properties and then edit the stylesheet which is produced.
3320 However, this section shows how to control the properties with
3321 flags to perltidy.
3322 Syntax colors may be changed from their default values by flags of
3324 the either the long form, -html-color-xxxxxx=n, or more
3325 conveniently the short form, -hcx=n, where xxxxxx is one of the
3326 following words, and x is the corresponding abbreviation:
3327 Token Type xxxxxx x
3329 ---------- -------- --
3330 comment comment c
3331 number numeric n
3332 identifier identifier i
3333 bareword, function bareword w
3334 keyword keyword k
3335 quite, pattern quote q
3336 here doc text here-doc-text h
3337 here doc target here-doc-target hh
3338 punctuation punctuation pu
3339 parentheses paren p
3340 structural braces structure s
3341 semicolon semicolon sc
3342 colon colon co
3343 comma comma cm
3344 label label j
3345 sub definition name subroutine m
3346 pod text pod-text pd
3347 A default set of colors has been defined, but they may be changed
3349 by providing values to any of the following parameters, where n is
3350 either a 6 digit hex RGB color value or an ascii name for a color,
3351 such as 'red'.
3352 To illustrate, the following command will produce an html file
3354 somefile.pl.html with "aqua" keywords:
3355 perltidy -html -hck=00ffff somefile.pl
3357 and this should be equivalent for most browsers:
3359 perltidy -html -hck=aqua somefile.pl
3361 Perltidy merely writes any non-hex names that it sees in the html
3363 file. The following 16 color names are defined in the HTML 3.2
3364 standard:
3365 black => 000000,
3367 silver => c0c0c0,
3368 gray => 808080,
3369 white => ffffff,
3370 maroon => 800000,
3371 red => ff0000,
3372 purple => 800080,
3373 fuchsia => ff00ff,
3374 green => 008000,
3375 lime => 00ff00,
3376 olive => 808000,
3377 yellow => ffff00
3378 navy => 000080,
3379 blue => 0000ff,
3380 teal => 008080,
3381 aqua => 00ffff,
3382 Many more names are supported in specific browsers, but it is
3384 safest to use the hex codes for other colors. Helpful color tables
3385 can be located with an internet search for "HTML color tables".
3386 Besides color, two other character attributes may be set: bold, and
3388 italics. To set a token type to use bold, use the flag
3389 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
3390 names from the above table. Conversely, to set a token type to NOT
3391 use bold, use --nohtml-bold-xxxxxx or -nhbx.
3392 Likewise, to set a token type to use an italic font, use the flag
3394 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
3395 or short names from the above table. And to set a token type to
3396 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
3397 For example, to use bold braces and lime color, non-bold, italics
3399 keywords the following command would be used:
3400 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
3402 The background color can be specified with
3404 --html-color-background=n, or -hcbg=n for short, where n is a 6
3405 character hex RGB value. The default color of text is the value
3406 given to punctuation, which is black as a default.
3407 Here are some notes and hints:
3409 1. If you find a preferred set of these parameters, you may want to
3411 create a .perltidyrc file containing them. See the perltidy man
3412 page for an explanation.
3413 2. Rather than specifying values for these parameters, it is
3415 probably easier to accept the defaults and then edit a style sheet.
3416 The style sheet contains comments which should make this easy.
3417 3. The syntax-colored html files can be very large, so it may be
3419 best to split large files into smaller pieces to improve download
3420 times.
3421
3423 Specifying Block Types
3424 Several parameters which refer to code block types may be customized by
3425 also specifying an associated list of block types. The type of a block
3426 is the name of the keyword which introduces that block, such as if,
3427 else, or sub. An exception is a labeled block, which has no keyword,
3428 and should be specified with just a colon. To specify all blocks use
3429 '*'.
3430 The keyword sub indicates a named sub. For anonymous subs, use the
3432 special keyword asub.
3433 For example, the following parameter specifies "sub", labels, "BEGIN",
3435 and "END" blocks:
3436 -cscl="sub : BEGIN END"
3438 (the meaning of the -cscl parameter is described above.) Note that
3440 quotes are required around the list of block types because of the
3441 spaces. For another example, the following list specifies all block
3442 types for vertical tightness:
3443 -bbvtl='*'
3445 Specifying File Extensions
3447 Several parameters allow default file extensions to be overridden. For
3448 example, a backup file extension may be specified with -bext=ext, where
3449 ext is some new extension. In order to provides the user some
3450 flexibility, the following convention is used in all cases to decide if
3451 a leading '.' should be used. If the extension "ext" begins with
3452 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
3453 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
3454 will be appended directly.
3455 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
3457 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
3458 is added, so again the backup file is somefile.pl.old. For "-bext=~",
3459 then no dot is added, and the backup file will be somefile.pl~ .
3460
3462 The following list shows all short parameter names which allow a prefix
3463 'n' to produce the negated form:
3464 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
3466 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
3467 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
3468 lp lsl ohbr okw ola oll opr opt osbr otr ple pod pvl q
3469 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
3470 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
3471 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
3473 may be used.
3474
3476 Parsing Limitations
3477 Perltidy should work properly on most perl scripts. It does a lot
3478 of self-checking, but still, it is possible that an error could be
3479 introduced and go undetected. Therefore, it is essential to make
3480 careful backups and to test reformatted scripts.
3481 The main current limitation is that perltidy does not scan modules
3483 included with 'use' statements. This makes it necessary to guess
3484 the context of any bare words introduced by such modules. Perltidy
3485 has good guessing algorithms, but they are not infallible. When it
3486 must guess, it leaves a message in the log file.
3487 If you encounter a bug, please report it.
3489 What perltidy does not parse and format
3491 Perltidy indents but does not reformat comments and "qw" quotes.
3492 Perltidy does not in any way modify the contents of here documents
3493 or quoted text, even if they contain source code. (You could,
3494 however, reformat them separately). Perltidy does not format
3495 'format' sections in any way. And, of course, it does not modify
3496 pod documents.
3497
3499 Temporary files
3500 Under the -html option with the default --pod2html flag, a
3501 temporary file is required to pass text to Pod::Html. Unix systems
3502 will try to use the POSIX tmpnam() function. Otherwise the file
3503 perltidy.TMP will be temporarily created in the current working
3504 directory.
3505 Special files when standard input is used
3507 When standard input is used, the log file, if saved, is
3508 perltidy.LOG, and any errors are written to perltidy.ERR unless the
3509 -se flag is set. These are saved in the current working directory.
3510 Files overwritten
3512 The following file extensions are used by perltidy, and files with
3513 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
3514 and/or .tdy, .html, and .bak, depending on the run type and
3515 settings.
3516 Files extensions limitations
3518 Perltidy does not operate on files for which the run could produce
3519 a file with a duplicated file extension. These extensions include
3520 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
3521 type. The purpose of this rule is to prevent generating confusing
3522 filenames such as somefile.tdy.tdy.tdy.
3523
3525 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
3526 status of the result.
3527 A exit value of 0 indicates that perltidy ran to completion with no
3529 error messages.
3530 A non-zero exit value indicates some kind of problem was detected.
3532 An exit value of 1 indicates that perltidy terminated prematurely,
3534 usually due to some kind of errors in the input parameters. This can
3535 happen for example if a parameter is misspelled or given an invalid
3536 value. Error messages in the standard error output will indicate the
3537 cause of any problem. If perltidy terminates prematurely then no
3538 output files will be produced.
3539 An exit value of 2 indicates that perltidy was able to run to
3541 completion but there there are (1) warning messages in the standard
3542 error output related to parameter errors or problems and/or (2) warning
3543 messages in the perltidy error file(s) relating to possible syntax
3544 errors in one or more of the source script(s) being tidied. When
3545 multiple files are being processed, an error detected in any single
3546 file will produce this type of exit condition.
3547
3549 perlstyle(1), Perl::Tidy(3)
3550
3552 This man page documents perltidy version 20190915
3553
3555 A list of current bugs and issues can be found at the CPAN site
3556 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
3557 To report a new bug or problem, use the link on this page.
3559 The source code repository is at
3561 <https://github.com/perltidy/perltidy>.
3562
3564 Copyright (c) 2000-2018 by Steve Hancock
3565
3567 This package is free software; you can redistribute it and/or modify it
3568 under the terms of the "GNU General Public License".
3569 Please refer to the file "COPYING" for details.
3571
3573 This package is distributed in the hope that it will be useful, but
3574 WITHOUT ANY WARRANTY; without even the implied warranty of
3575 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
3576 See the "GNU General Public License" for more details.
3578perl v5.30.0 2019-09-15 PERLTIDY(1)