6 my $arg_string = undef;
8 # give Macs a chance to provide command line parameters
11 MacPerl::Ask( 'Please enter @ARGV (-h for help)',
12 defined $ARGV[0] ? "\"$ARGV[0]\"" : "" );
15 Perl::Tidy::perltidy(argv => $arg_string);
21 perltidy - a perl script indenter and reformatter
25 perltidy [ options ] file1 file2 file3 ...
26 (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
27 perltidy [ options ] file1 -o outfile
28 perltidy [ options ] file1 -st >outfile
29 perltidy [ options ] <infile >outfile
33 Perltidy reads a perl script and writes an indented, reformatted script.
35 Many users will find enough information in L<"EXAMPLES"> to get
36 started. New users may benefit from the short tutorial
38 http://perltidy.sourceforge.net/tutorial.html
40 A convenient aid to systematically defining a set of style parameters
42 http://perltidy.sourceforge.net/stylekey.html
44 Perltidy can produce output on either of two modes, depending on the
45 existence of an B<-html> flag. Without this flag, the output is passed
46 through a formatter. The default formatting tries to follow the
47 recommendations in perlstyle(1), but it can be controlled in detail with
48 numerous input parameters, which are described in L<"FORMATTING
51 When the B<-html> flag is given, the output is passed through an HTML
52 formatter which is described in L<"HTML OPTIONS">.
58 This will produce a file F<somefile.pl.tdy> containing the script reformatted
59 using the default options, which approximate the style suggested in
60 perlstyle(1). Perltidy never changes the input file.
64 Execute perltidy on all F<.pl> files in the current directory with the
65 default options. The output will be in files with an appended F<.tdy>
66 extension. For any file with an error, there will be a file with extension
69 perltidy -b file1.pl file2.pl
71 Modify F<file1.pl> and F<file1.pl> in place, and backup the originals to
72 F<file1.pl.bak> and F<file2.pl.bak>. If F<file1.pl.bak> and/or F<file2.pl.bak>
73 already exist, they will be overwritten.
75 perltidy -gnu somefile.pl
77 Execute perltidy on file F<somefile.pl> with a style which approximates the
78 GNU Coding Standards for C programs. The output will be F<somefile.pl.tdy>.
80 perltidy -i=3 somefile.pl
82 Execute perltidy on file F<somefile.pl>, with 3 columns for each level of
83 indentation (B<-i=3>) instead of the default 4 columns. There will not be any
84 tabs in the reformatted script, except for any which already exist in comments,
85 pod documents, quotes, and here documents. Output will be F<somefile.pl.tdy>.
87 perltidy -i=3 -et=8 somefile.pl
89 Same as the previous example, except that leading whitespace will
90 be entabbed with one tab character per 8 spaces.
92 perltidy -ce -l=72 somefile.pl
94 Execute perltidy on file F<somefile.pl> with all defaults except use "cuddled
95 elses" (B<-ce>) and a maximum line length of 72 columns (B<-l=72>) instead of
96 the default 80 columns.
98 perltidy -g somefile.pl
100 Execute perltidy on file F<somefile.pl> and save a log file F<somefile.pl.LOG>
101 which shows the nesting of braces, parentheses, and square brackets at
102 the start of every line.
104 perltidy -html somefile.pl
106 This will produce a file F<somefile.pl.html> containing the script with
107 html markup. The output file will contain an embedded style sheet in
108 the <HEAD> section which may be edited to change the appearance.
110 perltidy -html -css=mystyle.css somefile.pl
112 This will produce a file F<somefile.pl.html> containing the script with
113 html markup. This output file will contain a link to a separate style
114 sheet file F<mystyle.css>. If the file F<mystyle.css> does not exist,
115 it will be created. If it exists, it will not be overwritten.
117 perltidy -html -pre somefile.pl
119 Write an html snippet with only the PRE section to F<somefile.pl.html>.
120 This is useful when code snippets are being formatted for inclusion in a
121 larger web page. No style sheet will be written in this case.
123 perltidy -html -ss >mystyle.css
125 Write a style sheet to F<mystyle.css> and exit.
127 perltidy -html -frm mymodule.pm
129 Write html with a frame holding a table of contents and the source code. The
130 output files will be F<mymodule.pm.html> (the frame), F<mymodule.pm.toc.html>
131 (the table of contents), and F<mymodule.pm.src.html> (the source code).
133 =head1 OPTIONS - OVERVIEW
135 The entire command line is scanned for options, and they are processed
136 before any files are processed. As a result, it does not matter
137 whether flags are before or after any filenames. However, the relative
138 order of parameters is important, with later parameters overriding the
139 values of earlier parameters.
141 For each parameter, there is a long name and a short name. The short
142 names are convenient for keyboard input, while the long names are
143 self-documenting and therefore useful in scripts. It is customary to
144 use two leading dashes for long names, but one may be used.
146 Most parameters which serve as on/off flags can be negated with a
147 leading "n" (for the short name) or a leading "no" or "no-" (for the
148 long name). For example, the flag to outdent long quotes is is B<-olq>
149 or B<--outdent-long-quotes>. The flag to skip this is B<-nolq>
150 or B<--nooutdent-long-quotes> or B<--no-outdent-long-quotes>.
152 Options may not be bundled together. In other words, options B<-q> and
153 B<-g> may NOT be entered as B<-qg>.
155 Option names may be terminated early as long as they are uniquely identified.
156 For example, instead of B<-dump-token-types>, it would be sufficient to enter
157 B<-dump-tok>, or even B<-dump-t>, to uniquely identify this command.
161 The following parameters concern the files which are read and written.
165 =item B<-h>, B<--help>
167 Show summary of usage and exit.
169 =item B<-o>=filename, B<--outfile>=filename
171 Name of the output file (only if a single input file is being
172 processed). If no output file is specified, and output is not
173 redirected to the standard output (see B<-st>), the output will go to
174 F<filename.tdy>. [Note: - does not redirect to standard output. Use
177 =item B<-st>, B<--standard-output>
179 Perltidy must be able to operate on an arbitrarily large number of files
180 in a single run, with each output being directed to a different output
181 file. Obviously this would conflict with outputting to the single
182 standard output device, so a special flag, B<-st>, is required to
183 request outputting to the standard output. For example,
185 perltidy somefile.pl -st >somefile.new.pl
187 This option may only be used if there is just a single input file.
188 The default is B<-nst> or B<-nostandard-output>.
190 =item B<-se>, B<--standard-error-output>
192 If perltidy detects an error when processing file F<somefile.pl>, its
193 default behavior is to write error messages to file F<somefile.pl.ERR>.
194 Use B<-se> to cause all error messages to be sent to the standard error
195 output stream instead. This directive may be negated with B<-nse>.
196 Thus, you may place B<-se> in a F<.perltidyrc> and override it when
197 desired with B<-nse> on the command line.
199 =item B<-oext>=ext, B<--output-file-extension>=ext
201 Change the extension of the output file to be F<ext> instead of the
202 default F<tdy> (or F<html> in case the -B<-html> option is used).
203 See L<Specifying File Extensions>.
205 =item B<-opath>=path, B<--output-path>=path
207 When perltidy creates a filename for an output file, by default it merely
208 appends an extension to the path and basename of the input file. This
209 parameter causes the path to be changed to F<path> instead.
211 The path should end in a valid path separator character, but perltidy will try
212 to add one if it is missing.
216 perltidy somefile.pl -opath=/tmp/
218 will produce F</tmp/somefile.pl.tdy>. Otherwise, F<somefile.pl.tdy> will
219 appear in whatever directory contains F<somefile.pl>.
221 If the path contains spaces, it should be placed in quotes.
223 This parameter will be ignored if output is being directed to standard output,
224 or if it is being specified explicitly with the B<-o=s> parameter.
226 =item B<-b>, B<--backup-and-modify-in-place>
228 Modify the input file or files in-place and save the original with the
229 extension F<.bak>. Any existing F<.bak> file will be deleted. See next item
230 for changing the default backup extension.
232 A B<-b> flag will be ignored if input is from standard input, or
233 if the B<-html> flag is set.
235 =item B<-bext>=ext, B<--backup-file-extension>=ext
237 Change the extension of the backup file to be something other than the
238 default F<.bak>. See L<Specifying File Extensions>.
240 =item B<-w>, B<--warning-output>
242 Setting B<-w> causes any non-critical warning
243 messages to be reported as errors. These include messages
244 about possible pod problems, possibly bad starting indentation level,
245 and cautions about indirect object usage. The default, B<-nw> or
246 B<--nowarning-output>, is not to include these warnings.
248 =item B<-q>, B<--quiet>
250 Deactivate error messages and syntax checking (for running under
253 For example, if you use a vi-style editor, such as vim, you may execute
254 perltidy as a filter from within the editor using something like
258 where C<n1,n2> represents the selected text. Without the B<-q> flag,
259 any error message may mess up your screen, so be prepared to use your
262 =item B<-log>, B<--logfile>
264 Save the F<.LOG> file, which has many useful diagnostics. Perltidy always
265 creates a F<.LOG> file, but by default it is deleted unless a program bug is
266 suspected. Setting the B<-log> flag forces the log file to be saved.
268 =item B<-g=n>, B<--logfile-gap=n>
270 Set maximum interval between input code lines in the logfile. This purpose of
271 this flag is to assist in debugging nesting errors. The value of C<n> is
272 optional. If you set the flag B<-g> without the value of C<n>, it will be
273 taken to be 1, meaning that every line will be written to the log file. This
274 can be helpful if you are looking for a brace, paren, or bracket nesting error.
276 Setting B<-g> also causes the logfile to be saved, so it is not necessary to
277 also include B<-log>.
279 If no B<-g> flag is given, a value of 50 will be used, meaning that at least
280 every 50th line will be recorded in the logfile. This helps prevent
281 excessively long log files.
283 Setting a negative value of C<n> is the same as not setting B<-g> at all.
285 =item B<-npro> B<--noprofile>
287 Ignore any F<.perltidyrc> command file. Normally, perltidy looks first in
288 your current directory for a F<.perltidyrc> file of parameters. (The format
289 is described below). If it finds one, it applies those options to the
290 initial default values, and then it applies any that have been defined
291 on the command line. If no F<.perltidyrc> file is found, it looks for one
292 in your home directory.
294 If you set the B<-npro> flag, perltidy will not look for this file.
296 =item B<-pro=filename> or B<--profile=filename>
298 To simplify testing and switching .perltidyrc files, this command may be
299 used to specify a configuration file which will override the default
300 name of .perltidyrc. There must not be a space on either side of the
301 '=' sign. For example, the line
303 perltidy -pro=testcfg
305 would cause file F<testcfg> to be used instead of the
306 default F<.perltidyrc>.
308 =item B<-opt>, B<--show-options>
310 Write a list of all options used to the F<.LOG> file.
311 Please see B<--dump-options> for a simpler way to do this.
313 =item B<-f>, B<--force-read-binary>
315 Force perltidy to process binary files. To avoid producing excessive
316 error messages, perltidy skips files identified by the system as non-text.
317 However, valid perl scripts containing binary data may sometimes be identified
318 as non-text, and this flag forces perltidy to process them.
322 =head1 FORMATTING OPTIONS
328 =item B<-l=n>, B<--maximum-line-length=n>
330 The default maximum line length is n=80 characters. Perltidy will try
331 to find line break points to keep lines below this length. However, long
332 quotes and side comments may cause lines to exceed this length.
333 Setting B<-l=0> is equivalent to setting B<-l=(a large number)>.
335 =item B<-i=n>, B<--indent-columns=n>
337 Use n columns per indentation level (default n=4).
341 Using tab characters will almost certainly lead to future portability
342 and maintenance problems, so the default and recommendation is not to
343 use them. For those who prefer tabs, however, there are two different
346 Except for possibly introducing tab indentation characters, as outlined
347 below, perltidy does not introduce any tab characters into your file,
348 and it removes any tabs from the code (unless requested not to do so
349 with B<-fws>). If you have any tabs in your comments, quotes, or
350 here-documents, they will remain.
354 =item B<-et=n>, B<--entab-leading-whitespace>
356 This flag causes each B<n> initial space characters to be replaced by
357 one tab character. Note that the integer B<n> is completely independent
358 of the integer specified for indentation parameter, B<-i=n>.
360 =item B<-t>, B<--tabs>
362 This flag causes one leading tab character to be inserted for each level
363 of indentation. Certain other features are incompatible with this
364 option, and if these options are also given, then a warning message will
365 be issued and this flag will be unset. One example is the B<-lp>
370 =item B<-syn>, B<--check-syntax>
372 This flag causes perltidy to run C<perl -c -T> to check syntax of input
373 and output. (To change the flags passed to perl, see the next
374 item, B<-pscf>). The results are written to the F<.LOG> file, which
375 will be saved if an error is detected in the output script. The output
376 script is not checked if the input script has a syntax error. Perltidy
377 does its own checking, but this option employs perl to get a "second
380 If perl reports errors in the input file, they will not be reported in
381 the error output unless the B<-warning-output> flag is given.
383 The default is B<not> to do this type of syntax checking (although
384 perltidy will still do as much self-checking as possible). The reason
385 is that it causes all code in BEGIN blocks to be executed, for all
386 modules being used, and this opens the door to security issues and
387 infinite loops when running perltidy.
389 =item B<-pscf=s>, B<-perl-syntax-check-flags=s>
391 When perl is invoked to check syntax, the normal flags are C<-c -T>. In
392 addition, if the B<-x> flag is given to perltidy, then perl will also be
393 passed a B<-x> flag. It should not normally be necessary to change
394 these flags, but it can be done with the B<-pscf=s> flag. For example,
395 if the taint flag, C<-T>, is not wanted, the flag could be set to be just
398 Perltidy will pass your string to perl with the exception that it will
399 add a B<-c> and B<-x> if appropriate. The F<.LOG> file will show
400 exactly what flags were passed to perl.
402 =item B<-io>, B<--indent-only>
404 This flag is used to deactivate all formatting and line break changes.
405 When it is in effect, the only change to the script will be indentation.
406 And any flags controlling whitespace and newlines will be ignored. You
407 might want to use this if you are perfectly happy with your whitespace
408 and line breaks, and merely want perltidy to handle the indentation.
409 (This also speeds up perltidy by well over a factor of two, so it might be
410 useful when perltidy is merely being used to help find a brace error in
413 Setting this flag is equivalent to setting B<--freeze-newlines> and
414 B<--freeze-whitespace>.
416 =item B<-ole=s>, B<--output-line-ending=s>
418 where s=C<win>, C<dos>, C<unix>, or C<mac>. This flag tells perltidy
419 to output line endings for a specific system. Normally,
420 perltidy writes files with the line separator character of the host
421 system. The C<win> and C<dos> flags have an identical result.
422 B<NOTE>: This only works under unix-like systems and is ignored under
425 =item B<-ple>, B<--preserve-line-endings>
427 This flag tells perltidy to write its output files with the same line
428 endings as the input file, if possible. It should work for
429 B<dos>, B<unix>, and B<mac> line endings. It will only work if perltidy
430 input comes from a filename (rather than stdin, for example). If
431 perltidy has trouble determining the input file line ending, it will
432 revert to the default behavior of using the line ending of the host system.
433 B<NOTE>: This only works under unix-like systems and is ignored under
438 =head2 Code Indentation Control
442 =item B<-ci=n>, B<--continuation-indentation=n>
444 Continuation indentation is extra indentation spaces applied when
445 a long line is broken. The default is n=2, illustrated here:
448 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
450 The same example, with n=0, is a little harder to read:
453 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
455 The value given to B<-ci> is also used by some commands when a small
456 space is required. Examples are commands for outdenting labels,
457 B<-ola>, and control keywords, B<-okw>.
459 When default values are not used, it is suggested that the value B<n>
460 given with B<-ci=n> be no more than about one-half of the number of
461 spaces assigned to a full indentation level on the B<-i=n> command.
463 =item B<-sil=n> B<--starting-indentation-level=n>
465 By default, perltidy examines the input file and tries to determine the
466 starting indentation level. While it is often zero, it may not be
467 zero for a code snippet being sent from an editing session. If the
468 default method does not work correctly, or you want to change the
469 starting level, use B<-sil=n>, to force the starting level to be n.
471 =item List indentation using B<-lp>, B<--line-up-parentheses>
473 By default, perltidy indents lists with 4 spaces, or whatever value
474 is specified with B<-i=n>. Here is a small list formatted in this way:
478 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
479 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
482 Use the B<-lp> flag to add extra indentation to cause the data to begin
483 past the opening parentheses of a sub call or list, or opening square
484 bracket of an anonymous array, or opening curly brace of an anonymous
485 hash. With this option, the above list would become:
489 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
490 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
493 If the available line length (see B<-l=n> ) does not permit this much
494 space, perltidy will use less. For alternate placement of the
495 closing paren, see the next section.
497 This option has no effect on code BLOCKS, such as if/then/else blocks,
498 which always use whatever is specified with B<-i=n>. Also, the
499 existence of line breaks and/or block comments between the opening and
500 closing parens may cause perltidy to temporarily revert to its default
503 Note: The B<-lp> option may not be used together with the B<-t> tabs option.
504 It may, however, be used with the B<-et=n> tab method.
506 In addition, any parameter which significantly restricts the ability of
507 perltidy to choose newlines will conflict with B<-lp> and will cause
508 B<-lp> to be deactivated. These include B<-io>, B<-fnl>, B<-nanl>, and
509 B<-ndnl>. The reason is that the B<-lp> indentation style can require
510 the careful coordination of an arbitrary number of break points in
511 hierarchical lists, and these flags may prevent that.
513 =item B<-cti=n>, B<--closing-token-indentation>
515 The B<-cti=n> flag controls the indentation of a line beginning with
516 a C<)>, C<]>, or a non-block C<}>. Such a line receives:
518 -cti = 0 no extra indentation (default)
519 -cti = 1 extra indentation such that the closing token
520 aligns with its opening token.
521 -cti = 2 one extra indentation level if the line looks like:
524 The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous
527 # perltidy -lp -cti=1
529 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
530 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
533 # perltidy -lp -cti=2
535 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
536 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
539 These flags are merely hints to the formatter and they may not always be
540 followed. In particular, if -lp is not being used, the indentation for
541 B<cti=1> is constrained to be no more than one indentation level.
543 If desired, this control can be applied independently to each of the
544 closing container token types. In fact, B<-cti=n> is merely an
545 abbreviation for B<-cpi=n -csbi=n -cbi=n>, where:
546 B<-cpi> or B<-closing-paren-indentation> controls B<)>'s,
547 B<-csbi> or B<-closing-square-bracket-indentation> controls B<]>'s,
548 B<-cbi> or B<-closing-brace-indentation> controls non-block B<}>'s.
550 =item B<-icp>, B<--indent-closing-paren>
552 The B<-icp> flag is equivalent to
553 B<-cti=2>, described in the previous section. The B<-nicp> flag is
554 equivalent B<-cti=0>. They are included for backwards compatability.
556 =item B<-icb>, B<--indent-closing-brace>
558 The B<-icb> option leaves a brace which terminates a code block
559 indented with the same indentation as the previous line. For example,
568 The default is not to do this, indicated by B<-nicb>.
570 =item B<-olq>, B<--outdent-long-quotes>
572 When B<-olq> is set, lines which is a quoted string longer than the
573 value B<maximum-line-length> will have their indentation removed to make
574 them more readable. This is the default. To prevent such out-denting,
575 use B<-nolq> or B<--nooutdent-long-lines>.
577 =item B<-oll>, B<--outdent-long-lines>
579 This command is equivalent to B<--outdent-long-quotes> and
580 B<--outdent-long-comments>, and it is included for compatibility with previous
581 versions of perltidy. The negation of this also works, B<-noll> or
582 B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>.
584 =item Outdenting Labels: B<-ola>, B<--outdent-labels>
586 This command will cause labels to be outdented by 2 spaces (or whatever B<-ci>
587 has been set to), if possible. This is the default. For example:
590 LOOP: while ( $i = <FOTOS> ) {
596 Use B<-nola> to not outdent labels.
598 =item Outdenting Keywords
602 =item B<-okw>, B<--outdent-keywords>
604 The command B<-okw> will will cause certain leading control keywords to
605 be outdented by 2 spaces (or whatever B<-ci> has been set to), if
606 possible. By default, these keywords are C<redo>, C<next>, C<last>,
607 C<goto>, and C<return>. The intention is to make these control keywords
608 easier to see. To change this list of keywords being outdented, see
611 For example, using C<perltidy -okw> on the previous example gives:
614 LOOP: while ( $i = <FOTOS> ) {
620 The default is not to do this.
622 =item Specifying Outdented Keywords: B<-okwl=string>, B<--outdent-keyword-list=string>
624 This command can be used to change the keywords which are outdented with
625 the B<-okw> command. The parameter B<string> is a required list of perl
626 keywords, which should be placed in quotes if there are more than one.
627 By itself, it does not cause any outdenting to occur, so the B<-okw>
628 command is still required.
630 For example, the commands C<-okwl="next last redo goto" -okw> will cause
631 those four keywords to be outdented. It is probably simplest to place
632 any B<-okwl> command in a F<.perltidyrc> file.
638 =head2 Whitespace Control
640 Whitespace refers to the blank space between variables, operators,
641 and other code tokens.
645 =item B<-fws>, B<--freeze-whitespace>
647 This flag causes your original whitespace to remain unchanged, and
648 causes the rest of the whitespace commands in this section, the
649 Code Indentation section, and
650 the Comment Control section to be ignored.
652 =item Tightness of curly braces, parentheses, and square brackets.
654 Here the term "tightness" will mean the closeness with which
655 pairs of enclosing tokens, such as parentheses, contain the quantities
656 within. A numerical value of 0, 1, or 2 defines the tightness, with
657 0 being least tight and 2 being most tight. Spaces within containers
658 are always symmetric, so if there is a space after a C<(> then there
659 will be a space before the corresponding C<)>.
661 The B<-pt=n> or B<--paren-tightness=n> parameter controls the space within
662 parens. The example below shows the effect of the three possible
665 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
666 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
667 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
669 When n is 0, there is always a space to the right of a '(' and to the left
670 of a ')'. For n=2 there is never a space. For n=1, the default, there
671 is a space unless the quantity within the parens is a single token, such
672 as an identifier or quoted string.
674 Likewise, the parameter B<-sbt=n> or B<--square-bracket-tightness=n>
675 controls the space within square brackets, as illustrated below.
677 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
678 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
679 $width = $col[$j + $k] - $col[$j]; # -sbt=2
681 Curly braces which do not contain code blocks are controlled by
682 the parameter B<-bt=n> or B<--brace-tightness=n>.
684 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
685 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
686 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
688 And finally, curly braces which contain blocks of code are controlled by the
689 parameter B<-bbt=n> or B<--block-brace-tightness=n> as illustrated in the
692 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
693 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
694 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
696 =item B<-sts>, B<--space-terminal-semicolon>
698 Some programmers prefer a space before all terminal semicolons. The
699 default is for no such space, and is indicated with B<-nsts> or
700 B<--nospace-terminal-semicolon>.
703 $i = 1; # -nsts (default)
705 =item B<-sfs>, B<--space-for-semicolon>
707 Semicolons within B<for> loops may sometimes be hard to see,
708 particularly when commas are also present. This option places spaces on
709 both sides of these special semicolons, and is the default. Use
710 B<-nsfs> or B<--nospace-for-semicolon> to deactivate it.
712 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
713 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
715 =item B<-asc>, B<--add-semicolons>
717 Setting B<-asc> allows perltidy to add any missing optional semicolon at the end
718 of a line which is followed by a closing curly brace on the next line. This
719 is the default, and may be deactivated with B<-nasc> or B<--noadd-semicolons>.
721 =item B<-dsm>, B<--delete-semicolons>
723 Setting B<-dsm> allows perltidy to delete extra semicolons which are
724 simply empty statements. This is the default, and may be deactivated
725 with B<-ndsm> or B<--nodelete-semicolons>. (Such semicolons are not
726 deleted, however, if they would promote a side comment to a block
729 =item B<-aws>, B<--add-whitespace>
731 Setting this option allows perltidy to add certain whitespace improve
732 code readability. This is the default. If you do not want any
733 whitespace added, but are willing to have some whitespace deleted, use
734 B<-naws>. (Use B<-fws> to leave whitespace completely unchanged).
736 =item B<-dws>, B<--delete-old-whitespace>
738 Setting this option allows perltidy to remove some old whitespace
739 between characters, if necessary. This is the default. If you
740 do not want any old whitespace removed, use B<-ndws> or
741 B<--nodelete-old-whitespace>.
743 =item Detailed whitespace controls around tokens
745 For those who want more detailed control over the whitespace around
746 tokens, there are four parameters which can directly modify the default
747 whitespace rules built into perltidy for any token. They are:
749 B<-wls=s> or B<--want-left-space=s>,
751 B<-nwls=s> or B<--nowant-left-space=s>,
753 B<-wrs=s> or B<--want-right-space=s>,
755 B<-nwrs=s> or B<--nowant-right-space=s>.
757 These parameters are each followed by a quoted string, B<s>, containing a
758 list of token types. No more than one of each of these parameters
759 should be specified, because repeating a command-line parameter
760 always overwrites the previous one before perltidy ever sees it.
762 To illustrate how these are used, suppose it is desired that there be no
763 space on either side of the token types B<= + - / *>. The following two
764 parameters would specify this desire:
766 -nwls="= + - / *" -nwrs="= + - / *"
768 (Note that the token types are in quotes, and that they are separated by
769 spaces). With these modified whitespace rules, the following line of math:
771 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
775 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
777 These parameters should be considered to be hints to perltidy rather
778 than fixed rules, because perltidy must try to resolve conflicts that
779 arise between them and all of the other rules that it uses. One
780 conflict that can arise is if, between two tokens, the left token wants
781 a space and the right one doesn't. In this case, the token not wanting
782 a space takes priority.
784 It is necessary to have a list of all token types in order to create
785 this type of input. Such a list can be obtained by the command
786 B<-dump-token-types>.
788 =item Space between keyword and opening paren
790 When an opening paren follows a keyword, no space is introduced after the
791 keyword, unless it is (by default) one of these:
793 my local our and or eq ne if else elsif until unless
794 while for foreach return switch case given when
796 These defaults can be modified with two commands:
798 B<-sak=s> or B<--space-after-keyword=s> adds keywords.
800 B<-nsak=s> or B<--nospace-after-keyword=s> removes keywords.
802 where B<s> is a list of keywords (in quotes if necessary). For example,
804 my ( $a, $b, $c ) = @_; # default
805 my( $a, $b, $c ) = @_; # -nsak="my local our"
807 =item Trimming whitespace around C<qw> quotes
809 B<-tqw> or B<--trim-qw> provide the default behavior of trimming
810 spaces around multi-line C<qw> quotes and indenting them appropriately.
812 B<-ntqw> or B<--notrim-qw> cause leading and trailing whitespace around
813 multi-line C<qw> quotes to be left unchanged. This option will not
814 normally be necessary, but was added for testing purposes, because in
815 some versions of perl, trimming C<qw> quotes changes the syntax tree.
819 =head2 Comment Controls
821 Perltidy has a number of ways to control the appearance of both block comments
822 and side comments. The term B<block comment> here refers to a full-line
823 comment, whereas B<side comment> will refer to a comment which appears on a
824 line to the right of some code.
828 =item B<-ibc>, B<--indent-block-comments>
830 Block comments normally look best when they are indented to the same
831 level as the code which follows them. This is the default behavior, but
832 you may use B<-nibc> to keep block comments left-justified. Here is an
835 # this comment is indented (-ibc, default)
836 if ($task) { yyy(); }
838 The alternative is B<-nibc>:
840 # this comment is not indented (-nibc)
841 if ($task) { yyy(); }
843 See also the next item, B<-isbc>, as well as B<-sbc>, for other ways to
844 have some indented and some outdented block comments.
846 =item B<-isbc>, B<--indent-spaced-block-comments>
848 If there is no leading space on the line, then the comment will not be
849 indented, and otherwise it may be.
851 If both B<-ibc> and B<-isbc> are set, then B<-isbc> takes priority.
853 =item B<-olc>, B<--outdent-long-comments>
855 When B<-olc> is set, lines which are full-line (block) comments longer
856 than the value B<maximum-line-length> will have their indentation
857 removed. The default is not to do this.
859 =item B<-msc=n>, B<--minimum-space-to-comment=n>
861 Side comments look best when lined up several spaces to the right of
862 code. Perltidy will try to keep comments at least n spaces to the
863 right. The default is n=4 spaces.
865 =item B<-hsc>, B<--hanging-side-comments>
867 By default, perltidy tries to identify and align "hanging side
868 comments", which are something like this:
870 my $IGNORE = 0; # This is a side comment
871 # This is a hanging side comment
874 A comment is considered to be a hanging side comment if (1) it immediately
875 follows a line with a side comment, or another hanging side comment, and
876 (2) there is some leading whitespace on the line.
877 To deactivate this feature, use B<-nhsc> or B<--nohanging-side-comments>.
878 If block comments are preceded by a blank line, or have no leading
879 whitespace, they will not be mistaken as hanging side comments.
881 =item Closing Side Comments
883 A closing side comment is a special comment which perltidy can
884 automatically create and place after the closing brace of a code block.
885 They can be useful for code maintenance and debugging. The command
886 B<-csc> (or B<-closing-side-comments>) adds or updates closing side
887 comments. For example, here is a small code snippet
890 if ( !defined( $_[0] ) ) {
891 print("Hello, World\n");
894 print( $_[0], "\n" );
898 And here is the result of processing with C<perltidy -csc>:
901 if ( !defined( $_[0] ) ) {
902 print("Hello, World\n");
905 print( $_[0], "\n" );
909 A closing side comment was added for C<sub message> in this case, but not
910 for the C<if> and C<else> blocks, because they were below the 6 line
911 cutoff limit for adding closing side comments. This limit may be
912 changed with the B<-csci> command, described below.
914 The command B<-dcsc> (or B<--delete-closing-side-comments>) reverses this
915 process and removes these comments.
917 Several commands are available to modify the behavior of these two basic
918 commands, B<-csc> and B<-dcsc>:
922 =item B<-csci=n>, or B<-closing-side-comment-interval=n>
924 where C<n> is the minimum number of lines that a block must have in
925 order for a closing side comment to be added. The default value is
926 C<n=6>. To illustrate:
928 # perltidy -csci=2 -csc
930 if ( !defined( $_[0] ) ) {
931 print("Hello, World\n");
932 } ## end if ( !defined( $_[0] ))
934 print( $_[0], "\n" );
935 } ## end else [ if ( !defined( $_[0] ))
938 Now the C<if> and C<else> blocks are commented. However, now this has
939 become very cluttered.
941 =item B<-cscp=string>, or B<-closing-side-comment-prefix=string>
943 where string is the prefix used before the name of the block type. The
944 default prefix, shown above, is C<## end>. This string will be added to
945 closing side comments, and it will also be used to recognize them in
946 order to update, delete, and format them. Any comment identified as a
947 closing side comment will be placed just a single space to the right of
950 =item B<-cscl=string>, or B<-closing-side-comment-list-string>
952 where C<string> is a list of block types to be tagged with closing side
953 comments. By default, all code block types preceded by a keyword or
954 label (such as C<if>, C<sub>, and so on) will be tagged. The B<-cscl>
955 command changes the default list to be any selected block types; see
956 L<Specifying Block Types>.
957 For example, the following command
958 requests that only C<sub>'s, labels, C<BEGIN>, and C<END> blocks be
959 affected by any B<-csc> or B<-dcsc> operation:
961 -cscl="sub : BEGIN END"
963 =item B<-csct=n>, or B<-closing-side-comment-maximum-text=n>
965 The text appended to certain block types, such as an C<if> block, is
966 whatever lies between the keyword introducing the block, such as C<if>,
967 and the opening brace. Since this might be too much text for a side
968 comment, there needs to be a limit, and that is the purpose of this
969 parameter. The default value is C<n=20>, meaning that no additional
970 tokens will be appended to this text after its length reaches 20
971 characters. Omitted text is indicated with C<...>. (Tokens, including
972 sub names, are never truncated, however, so actual lengths may exceed
973 this). To illustrate, in the above example, the appended text of the
974 first block is C< ( !defined( $_[0] )...>. The existing limit of
975 C<n=20> caused this text to be truncated, as indicated by the C<...>.
977 =item B<-csce=n>, or B<-closing-side-comment-else-flag=n>
979 The default, B<n=0>, places the text of the opening C<if> statement after any
982 If B<n=2> is used, then each C<elsif> is also given the text of the opening
983 C<if> statement. Also, an C<else> will include the text of a preceding
984 C<elsif> statement. Note that this may result some long closing
987 If B<n=1> is used, the results will be the same as B<n=2> whenever the
988 resulting line length is less than the maximum allowed.
990 =item B<-cscw>, or B<-closing-side-comment-warnings>
992 This parameter is intended to help make the initial transition to the use of
993 closing side comments.
995 things to happen if a closing side comment replaces an existing, different
996 closing side comment: first, an error message will be issued, and second, the
997 original side comment will be placed alone on a new specially marked comment
998 line for later attention.
1000 The intent is to avoid clobbering existing hand-written side comments
1001 which happen to match the pattern of closing side comments. This flag
1002 should only be needed on the first run with B<-csc>.
1006 B<Important Notes on Closing Side Comments:>
1012 Closing side comments are only placed on lines terminated with a closing
1013 brace. Certain closing styles, such as the use of cuddled elses
1014 (B<-ce>), preclude the generation of some closing side comments.
1018 Please note that adding or deleting of closing side comments takes
1019 place only through the commands B<-csc> or B<-dcsc>. The other commands,
1020 if used, merely modify the behavior of these two commands.
1024 It is recommended that the B<-cscw> flag be used along with B<-csc> on
1025 the first use of perltidy on a given file. This will prevent loss of
1026 any existing side comment data which happens to have the csc prefix.
1030 Once you use B<-csc>, you should continue to use it so that any
1031 closing side comments remain correct as code changes. Otherwise, these
1032 comments will become incorrect as the code is updated.
1036 If you edit the closing side comments generated by perltidy, you must also
1037 change the prefix to be different from the closing side comment prefix.
1038 Otherwise, your edits will be lost when you rerun perltidy with B<-csc>. For
1039 example, you could simply change C<## end> to be C<## End>, since the test is
1040 case sensitive. You may also want to use the B<-ssc> flag to keep these
1041 modified closing side comments spaced the same as actual closing side comments.
1045 Temporarily generating closing side comments is a useful technique for
1046 exploring and/or debugging a perl script, especially one written by someone
1047 else. You can always remove them with B<-dcsc>.
1051 =item Static Block Comments
1053 Static block comments are block comments with a special leading pattern,
1054 C<##> by default, which will be treated slightly differently from other
1055 block comments. They effectively behave as if they had glue along their
1056 left and top edges, because they stick to the left edge and previous line
1057 when there is no blank spaces in those places. This option is
1058 particularly useful for controlling how commented code is displayed.
1062 =item B<-sbc>, B<--static-block-comments>
1064 When B<-sbc> is used, a block comment with a special leading pattern, C<##> by
1065 default, will be treated specially.
1067 Comments so identified are treated as follows:
1073 If there is no leading space on the line, then the comment will not
1074 be indented, and otherwise it may be,
1078 no new blank line will be
1079 inserted before such a comment, and
1083 such a comment will never become
1084 a hanging side comment.
1088 For example, assuming C<@month_of_year> is
1091 @month_of_year = ( # -sbc (default)
1092 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1096 Without this convention, the above code would become
1098 @month_of_year = ( # -nsbc
1099 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1105 which is not as clear.
1106 The default is to use B<-sbc>. This may be deactivated with B<-nsbc>.
1108 =item B<-sbcp=string>, B<--static-block-comment-prefix=string>
1110 This parameter defines the prefix used to identify static block comments
1111 when the B<-sbc> parameter is set. The default prefix is C<##>,
1112 corresponding to C<-sbcp=##>. The first character must be a C<#>
1113 symbol, since this must only match comments. As a simple example, to
1114 identify all comments as static block comments, one would use C<-sbcp=#>.
1116 Please note that B<-sbcp> merely defines the pattern used to identify static
1117 block comments; it will not be used unless the switch B<-sbc> is set. Also,
1118 please be aware that this string is used in a perl regular expression which
1119 identifies these comments, so it must enable a valid regular expression to be
1122 =item B<-osbc>, B<--outdent-static-block-comments>
1124 The command B<-osbc> will will cause static block comments to be outdented by 2
1125 spaces (or whatever B<-ci=n> has been set to), if possible.
1129 =item Static Side Comments
1131 Static side comments are side comments with a special leading pattern.
1132 This option can be useful for controlling how commented code is displayed
1133 when it is a side comment.
1137 =item B<-ssc>, B<--static-side-comments>
1139 When B<-ssc> is used, a side comment with a static leading pattern, which is
1140 C<##> by default, will be be spaced only a single space from previous
1141 character, and it will not be vertically aligned with other side comments.
1143 The default is B<-nssc>.
1145 =item B<-sscp=string>, B<--static-side-comment-prefix=string>
1147 This parameter defines the prefix used to identify static side comments
1148 when the B<-ssc> parameter is set. The default prefix is C<##>,
1149 corresponding to C<-sscp=##>.
1151 Please note that B<-sscp> merely defines the pattern used to identify
1152 static side comments; it will not be used unless the switch B<-ssc> is
1153 set. Also, note that this string is used in a perl regular expression
1154 which identifies these comments, so it must enable a valid regular
1155 expression to be formed.
1162 =head2 Line Break Control
1166 =item B<-fnl>, B<--freeze-newlines>
1168 If you do not want any changes to the line breaks in your script, set
1169 B<-fnl>, and they will remain fixed, and the rest of the commands in
1170 this section and sections
1171 L<Controlling List Formatting>,
1172 L<Retaining or Ignoring Existing Line Breaks>, and
1173 L<Blank Line Control> will be ignored. You may want to use B<-noll>
1176 =item B<-ce>, B<--cuddled-else>
1178 Enable the "cuddled else" style, in which C<else> and C<elsif> are
1179 follow immediately after the curly brace closing the previous block.
1180 The default is not to use cuddled elses, and is indicated with the flag
1181 B<-nce> or B<--nocuddled-else>. Here is a comparison of the
1193 else { # -nce (default)
1197 =item B<-bl>, B<--opening-brace-on-new-line>
1199 Use the flag B<-bl> to place the opening brace on a new line:
1201 if ( $input_file eq '-' ) # -bl
1203 important_function();
1206 This flag applies to all structural blocks, including sub's (unless
1207 the B<-sbl> flag is set -- see next item).
1209 The default style, B<-nbl>, places an opening brace on the same line as
1210 the keyword introducing it. For example,
1212 if ( $input_file eq '-' ) { # -nbl (default)
1214 =item B<-sbl>, B<--opening-sub-brace-on-new-line>
1216 The flag B<-sbl> can be used to override the value of B<-bl> for
1217 opening sub braces. For example,
1221 produces this result:
1225 if (!defined($_[0])) {
1226 print("Hello, World\n");
1233 This flag is negated with B<-nsbl>. If B<-sbl> is not specified,
1234 the value of B<-bl> is used.
1236 =item B<-bli>, B<--brace-left-and-indent>
1238 The flag B<-bli> is the same as B<-bl> but in addition it causes one
1239 unit of continuation indentation ( see B<-ci> ) to be placed before
1240 an opening and closing block braces.
1244 if ( $input_file eq '-' ) # -bli
1246 important_function();
1249 By default, this extra indentation occurs for blocks of type:
1250 B<if>, B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>,
1251 B<while>, B<until>, and also with a preceding label. The next item
1252 shows how to change this.
1254 =item B<-blil=s>, B<--brace-left-and-indent-list=s>
1256 Use this parameter to change the types of block braces for which the
1257 B<-bli> flag applies; see L<Specifying Block Types>. For example,
1258 B<-blil='if elsif else'> would apply it to only C<if/elsif/else> blocks.
1260 =item B<-bar>, B<--opening-brace-always-on-right>
1262 The default style, B<-nbl> places the opening brace on a new
1263 line if it does not fit on the same line as the opening keyword, like
1266 if ( $bigwasteofspace1 && $bigwasteofspace2
1267 || $bigwasteofspace3 && $bigwasteofspace4 )
1269 big_waste_of_time();
1272 To force the opening brace to always be on the right, use the B<-bar>
1273 flag. In this case, the above example becomes
1275 if ( $bigwasteofspace1 && $bigwasteofspace2
1276 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1277 big_waste_of_time();
1280 A conflict occurs if both B<-bl> and B<-bar> are specified.
1282 =item Vertical tightness of non-block curly braces, parentheses, and square brackets.
1284 These parameters control what shall be called vertical tightness. Here are the
1291 Opening tokens (except for block braces) are controlled by B<-vt=n>, or
1292 B<--vertical-tightness=n>, where
1294 -vt=0 always break a line after opening token (default).
1295 -vt=1 do not break unless this would produce more than one
1296 step in indentation in a line.
1297 -vt=2 never break a line after opening token
1301 You must also use the B<-lp> flag when you use the B<-vt> flag; the
1302 reason is explained below.
1306 Closing tokens (except for block braces) are controlled by B<-vtc=n>, or
1307 B<--vertical-tightness-closing=n>, where
1309 -vtc=0 always break a line before a closing token (default),
1310 -vtc=1 do not break before a closing token which is followed
1311 by a semicolon or another closing token, and is not in
1313 -vtc=2 never break before a closing token.
1315 The rules for B<-vtc=1> are designed to maintain a reasonable balance
1316 between tightness and readability in complex lists.
1320 Different controls may be applied to to different token types,
1321 and it is also possible to control block braces; see below.
1325 Finally, please note that these vertical tightness flags are merely
1326 hints to the formatter, and it cannot always follow them. Things which
1327 make it difficult or impossible include comments, blank lines, blocks of
1328 code within a list, and possibly the lack of the B<-lp> parameter.
1329 Also, these flags may be ignored for very small lists (2 or 3 lines in
1334 Here are some examples:
1336 # perltidy -lp -vt=0 -vtc=0
1344 # perltidy -lp -vt=1 -vtc=0
1345 %romanNumerals = ( one => 'I',
1351 # perltidy -lp -vt=1 -vtc=1
1352 %romanNumerals = ( one => 'I',
1357 The difference between B<-vt=1> and B<-vt=2> is shown here:
1359 # perltidy -lp -vt=1
1361 mysprintf( "(void)find_threadsv(%s);",
1362 cstring( $threadsv_names[ $op->targ ] )
1366 # perltidy -lp -vt=2
1367 $init->add( mysprintf( "(void)find_threadsv(%s);",
1368 cstring( $threadsv_names[ $op->targ ] )
1372 With B<-vt=1>, the line ending in C<add(> does not combine with the next
1373 line because the next line is not balanced. This can help with
1374 readability, but B<-vt=2> can be used to ignore this rule.
1376 The tightest, and least readable, code is produced with both C<-vt=2> and
1379 # perltidy -lp -vt=2 -vtc=2
1380 $init->add( mysprintf( "(void)find_threadsv(%s);",
1381 cstring( $threadsv_names[ $op->targ ] ) ) );
1383 Notice how the code in all of these examples collapses vertically as
1384 B<-vt> increases, but the indentation remains unchanged. This is
1385 because perltidy implements the B<-vt> parameter by first formatting as
1386 if B<-vt=0>, and then simply overwriting one output line on top of the
1387 next, if possible, to achieve the desired vertical tightness. The
1388 B<-lp> indentation style has been designed to allow this vertical
1389 collapse to occur, which is why it is required for the B<-vt> parameter.
1391 The B<-vt=n> and B<-vtc=n> parameters apply to each type of container
1392 token. If desired, vertical tightness controls can be applied
1393 independently to each of the closing container token types.
1395 The parameters for controlling parentheses are B<-pvt=n> or
1396 B<--paren-vertical-tightness=n>, and B<-pcvt=n> or
1397 B<--paren-vertical-tightness-closing=n>.
1399 Likewise, the parameters for square brackets are B<-sbvt=n> or
1400 B<--square-bracket-vertical-tightness=n>, and B<-sbcvt=n> or
1401 B<--square-bracket-vertical-tightness-closing=n>.
1403 Finally, the parameters for controlling non-code block braces are
1404 B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bcvt=n> or
1405 B<--brace-vertical-tightness-closing=n>.
1407 In fact, the parameter B<-vt=n> is actually just an abbreviation for
1408 B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation
1409 for B<-pvtc=n -bvtc=n sbvtc=n>.
1411 =item B<-bbvt=n> or B<--block-brace-vertical-tightness=n>
1413 The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies
1414 to opening code block braces.
1416 -bbvt=0 break after opening block brace (default).
1417 -bbvt=1 do not break unless this would produce more than one
1418 step in indentation in a line.
1419 -bbvt=2 do not break after opening block brace.
1421 It is necessary to also use either B<-bl> or B<-bli> for this to work,
1422 because, as with other vertical tightness controls, it is implemented by
1423 simply overwriting a line ending with an opening block brace with the
1424 subsequent line. For example:
1426 # perltidy -bli -bbvt=0
1427 if ( open( FILE, "< $File" ) )
1429 while ( $File = <FILE> )
1437 # perltidy -bli -bbvt=1
1438 if ( open( FILE, "< $File" ) )
1439 { while ( $File = <FILE> )
1446 By default this applies to blocks associated with keywords B<if>,
1447 B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>, B<while>,
1448 B<until>, and also with a preceding label. This can be changed with
1449 the parameter B<-bbvtl=string>, or
1450 B<--block-brace-vertical-tightness-list=string>, where B<string> is a
1451 space-separated list of block types. For more information on the
1452 possible values of this string, see L<Specifying Block Types>
1454 For example, if we want to just apply this style to C<if>,
1455 C<elsif>, and C<else> blocks, we could use
1456 C<perltidy -bli -bbvt -bbvtl='if elsif else'>.
1458 There is no vertical tightness control for closing block braces; with
1459 the exception of one-line blocks, they will normally remain on a
1462 =item B<-dnl>, B<--delete-old-newlines>
1464 By default, perltidy first deletes all old line break locations, and then it
1465 looks for good break points to match the desired line length. Use B<-ndnl>
1466 or B<--nodelete-old-newlines> to force perltidy to retain all old line break
1469 =item B<-anl>, B<--add-newlines>
1471 By default, perltidy will add line breaks when necessary to create
1472 continuations of long lines and to improve the script appearance. Use
1473 B<-nanl> or B<-noadd-newlines> to prevent any new line breaks.
1475 This flag does not prevent perltidy from eliminating existing line
1476 breaks; see B<-freeze-newlines> to completely prevent changes to line
1479 =item Controlling whether perltidy breaks before or after operators
1481 Two command line parameters provide some control over whether
1482 a line break should be before or after specific token types.
1484 B<-wba=s> or B<--want-break-after=s>, and
1486 B<-wbb=s> or B<--want-break-before=s>.
1488 These parameters are each followed by a quoted string, B<s>, containing
1489 a list of token types (separated only by spaces). No more than one of each
1490 of these parameters should be specified, because repeating a
1491 command-line parameter always overwrites the previous one before
1492 perltidy ever sees it.
1494 By default, perltidy breaks B<after> these token types:
1495 % + - * / x != == >= <= =~ !~ < > | & >= <
1496 = **= += *= &= <<= &&= -= /= |= >>= ||= .= %= ^= x=
1498 And perltidy breaks B<before> these token types by default:
1501 To illustrate, to cause a break after a concatenation operator, C<'.'>,
1502 rather than before it, the command line would be
1506 As another example, the following command would cause a break before
1507 math operators C<'+'>, C<'-'>, C<'/'>, and C<'*'>:
1511 These commands should work well for most of the token types that
1512 perltidy uses (use B<--dump-token-types> for a list). However, for a
1513 few token types there may be conflicts with hardwired logic which cause
1514 unexpected results. One example is curly braces, which should be
1515 controlled with the parameter B<bl> provided for that purpose.
1519 =head2 Controlling List Formatting
1521 Perltidy attempts to place comma-separated arrays of values in tables
1522 which look good. Its default algorithms usually work well, and they
1523 have been improving with each release, but several parameters are
1524 available to control list formatting.
1528 =item B<-boc>, B<--break-at-old-comma-breakpoints>
1530 This flag tells perltidy to try to break at all old commas. This is not
1531 the default. Normally, perltidy makes a best guess at list formatting,
1532 and seldom uses old comma breakpoints. Usually this works well,
1541 The default formatting will flatten this down to one line:
1543 # perltidy (default)
1544 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
1546 which hides the structure. Using B<-boc>, plus additional flags
1547 to retain the original style, yields
1549 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
1556 A disadvantage of this flag is that all tables in the file
1557 must already be nicely formatted.
1559 =item B<-mft=n>, B<--maximum-fields-per-table=n>
1561 If the computed number of fields for any table exceeds B<n>, then it
1562 will be reduced to B<n>. The default value for B<n> is a large number,
1563 40. While this value should probably be left unchanged as a general
1564 rule, it might be used on a small section of code to force a list to
1565 have a particular number of fields per line, and then either the B<-boc>
1566 flag could be used to retain this formatting, or a single comment could
1567 be introduced somewhere to freeze the formatting in future applications
1580 =item B<-cab=n>, B<--comma-arrow-breakpoints=n>
1582 A comma which follows a comma arrow, '=>', requires special
1583 consideration. In a long list, it is common to break at all such
1584 commas. This parameter can be used to control how perltidy breaks at
1585 these commas. (However, it will have no effect if old comma breaks are
1586 being forced because B<-boc> is used). The possible values of B<n> are:
1588 n=0 break at all commas after =>
1589 n=1 stable: break at all commas after => unless this would break
1590 an existing one-line container (default)
1591 n=2 break at all commas after =>, but try to form the maximum
1592 maximum one-line container lengths
1593 n=3 do not treat commas after => specially at all
1595 For example, given the following single line, perltidy by default will
1596 not add any line breaks because it would break the existing one-line
1599 bless { B => $B, Root => $Root } => $package;
1601 Using B<-cab=0> will force a break after each comma-arrow item:
1609 If perltidy is subsequently run with this container broken, then by
1610 default it will break after each '=>' because the container is now
1611 broken. To reform a one-line container, the parameter B<-cab=2> would
1614 The flag B<-cab=3> can be used to prevent these commas from being
1615 treated specially. In this case, an item such as "01" => 31 is
1616 treated as a single item in a table. The number of fields in this table
1617 will be determined by the same rules that are used for any other table.
1622 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
1623 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
1624 "09" => 30, "10" => 31, "11" => 30, "12" => 31
1629 =head2 Retaining or Ignoring Existing Line Breaks
1631 Several additional parameters are available for controlling the extent
1632 to which line breaks in the input script influence the output script.
1633 In most cases, the default parameter values are set so that, if a choice
1634 is possible, the output style follows the input style. For example, if
1635 a short logical container is broken in the input script, then the
1636 default behavior is for it to remain broken in the output script.
1638 Most of the parameters in this section would only be required for a
1639 one-time conversion of a script from short container lengths to longer
1640 container lengths. The opposite effect, of converting long container
1641 lengths to shorter lengths, can be obtained by temporarily using a short
1642 maximum line length.
1646 =item B<-bol>, B<--break-at-old-logical-breakpoints>
1648 By default, if a logical expression is broken at a C<&&>, C<||>, C<and>,
1649 or C<or>, then the container will remain broken. Also, breaks
1650 at internal keywords C<if> and C<unless> will normally be retained.
1651 To prevent this, and thus form longer lines, use B<-nbol>.
1653 =item B<-bok>, B<--break-at-old-keyword-breakpoints>
1655 By default, perltidy will retain a breakpoint before keywords which may
1656 return lists, such as C<sort> and <map>. This allows chains of these
1657 operators to be displayed one per line. Use B<-nbok> to prevent
1658 retaining these breakpoints.
1660 =item B<-bot>, B<--break-at-old-trinary-breakpoints>
1662 By default, if a conditional (trinary) operator is broken at a C<:>,
1663 then it will remain broken. To prevent this, and thereby
1664 form longer lines, use B<-nbot>.
1666 =item B<-iob>, B<--ignore-old-breakpoints>
1668 Use this flag to tell perltidy to ignore existing line breaks to the
1669 maximum extent possible. This will tend to produce the longest possible
1670 containers, regardless of type, which do not exceed the line length
1675 =head2 Blank Line Control
1677 Blank lines can improve the readability of a script if they are carefully
1678 placed. Perltidy has several commands for controlling the insertion,
1679 retention, and removal of blank lines.
1683 =item B<-bbc>, B<--blanks-before-comments>
1685 A blank line will be introduced before a full-line comment. This is the
1686 default. Use B<-nbbc> or B<--noblanks-before-comments> to prevent
1687 such blank lines from being introduced.
1689 =item B<-bbs>, B<--blanks-before-subs>
1691 A blank line will be introduced before a B<sub> definition, unless it is a
1692 one-liner or preceded by a comment. A blank line will also be introduced
1693 before a B<package> statement and a B<BEGIN> and B<END> block. This is the
1694 default. The intention is to help display the structure of a program by
1695 setting off certain key sections of code. This is negated with B<-nbbs> or
1696 B<--noblanks-before-subs>.
1698 =item B<-bbb>, B<--blanks-before-blocks>
1700 A blank line will be introduced before blocks of coding delimited by
1701 B<for>, B<foreach>, B<while>, B<until>, and B<if>, B<unless>, in the following
1708 The block is not preceded by a comment.
1712 The block is not a one-line block.
1716 The number of consecutive non-blank lines at the current indentation depth is at least B<-lbl>
1721 This is the default. The intention of this option is to introduce
1722 some space within dense coding.
1723 This is negated with B<-nbbb> or B<--noblanks-before-blocks>.
1725 =item B<-lbl=n> B<--long-block-line-count=n>
1727 This controls how often perltidy is allowed to add blank lines before
1728 certain block types (see previous section). The default is 8. Entering
1729 a value of B<0> is equivalent to entering a very large number.
1731 =item B<-mbl=n> B<--maximum-consecutive-blank-lines=n>
1733 This parameter specifies the maximum number of consecutive blank lines
1734 in the output script. The default is n=1. If the input file has more
1735 than n consecutive blank lines, the number will be reduced to n.
1736 (This obviously does not apply to pod sections, here-documents, and quotes).
1738 =item B<-sob>, B<--swallow-optional-blank-lines>
1740 All blank lines not required by the above flags, B<-bbb>, B<-bbs>, and B<-bbc>,
1741 will be deleted. (But essential blank lines above pod documents will be
1742 retained). This is NOT the default.
1744 =item B<-nsob>, B<--noswallow-optional-blank-lines>
1746 Retain blank lines, including those which do not corresponding to flags
1747 B<-bbb>, B<-bbs>, and B<-bbc>. This is the default. The number of
1748 blanks retained is subject to the limit imposed by
1749 B<--maximum-consecutive-blank-lines>, however.
1755 A style refers to a convenient collection of existing parameters.
1759 =item B<-gnu>, B<--gnu-style>
1761 B<-gnu> gives an approximation to the GNU Coding Standards (which do
1762 not apply to perl) as they are sometimes implemented. At present, this
1763 style overrides the default style with the following parameters:
1765 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
1769 =head2 Other Controls
1773 =item Deleting selected text
1775 Perltidy can selectively delete comments and/or pod documentation. The
1776 command B<-dac> or B<--delete-all-comments> will delete all comments
1777 B<and> all pod documentation, leaving just code and any leading system
1780 The command B<-dp> or B<--delete-pod> will remove all pod documentation
1783 Two commands which remove comments (but not pod) are: B<-dbc> or
1784 B<--delete-block-comments> and B<-dsc> or B<--delete-side-comments>.
1785 (Hanging side comments will be deleted with block comments here.)
1787 The negatives of these commands also work, and are the defaults. When
1788 block comments are deleted, any leading 'hash-bang' will be retained.
1789 Also, if the B<-x> flag is used, any system commands before a leading
1790 hash-bang will be retained (even if they are in the form of comments).
1792 =item Writing selected text to a file
1794 When perltidy writes a formatted text file, it has the ability to also
1795 send selected text to a file with a F<.TEE> extension. This text can
1796 include comments and pod documentation.
1798 The command B<-tac> or B<--tee-all-comments> will write all comments
1799 B<and> all pod documentation.
1801 The command B<-tp> or B<--tee-pod> will write all pod documentation (but
1804 The commands which write comments (but not pod) are: B<-tbc> or
1805 B<--tee-block-comments> and B<-tsc> or B<--tee-side-comments>.
1806 (Hanging side comments will be written with block comments here.)
1808 The negatives of these commands also work, and are the defaults.
1810 =item Using a F<.perltidyrc> command file
1812 If you use perltidy frequently, you probably won't be happy until you
1813 create a F<.perltidyrc> file to avoid typing commonly-used parameters.
1814 Perltidy will first look in your current directory for a command file
1815 named F<.perltidyrc>. If it does not find one, it will continue looking
1816 for one in other standard locations.
1818 These other locations are system-dependent, and may be displayed with
1819 the command C<perltidy -dpro>. Under Unix systems, it will look for a
1820 F<.perltidyrc> file in the home directory, and then for a system-wide
1821 file F</usr/local/etc/perltidyrc>, and then it will look for
1822 F</etc/perltidyrc>. Note that these last two system-wide files do not
1823 have a leading dot. Further system-dependent information will be found
1824 in the INSTALL file distributed with perltidy.
1826 This file is free format, and simply a list of parameters, just as they
1827 would be entered on a command line. Any number of lines may be used,
1828 with any number of parameters per line, although it may be easiest to
1829 read with one parameter per line. Blank lines are ignored, and text
1830 after a '#' is ignored to the end of a line.
1832 Here is an example of a F<.perltidyrc> file:
1834 # This is a simple of a .perltidyrc configuration file
1835 # This implements a highly spaced style
1836 -se # errors to standard error output
1837 -w # show all warnings
1838 -bl # braces on new lines
1839 -pt=0 # parens not tight at all
1840 -bt=0 # braces not tight
1841 -sbt=0 # square brackets not tight
1843 The parameters in the F<.perltidyrc> file are installed first, so any
1844 parameters given on the command line will have priority over them.
1846 To avoid confusion, perltidy ignores any command in the .perltidyrc
1847 file which would cause some kind of dump and an exit. These are:
1849 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
1851 There are several options may be helpful in debugging a F<.perltidyrc>
1858 A very helpful command is B<--dump-profile> or B<-dpro>. It writes a
1859 list of all configuration filenames tested to standard output, and
1860 if a file is found, it dumps the content to standard output before
1861 exiting. So, to find out where perltidy looks for its configuration
1862 files, and which one if any it selects, just enter
1868 It may be simplest to develop and test configuration files with
1869 alternative names, and invoke them with B<-pro=filename> on the command
1870 line. Then rename the desired file to F<.perltidyrc> when finished.
1874 The parameters in the F<.perltidyrc> file can be switched off with
1875 the B<-npro> option.
1879 The commands B<-dump-options>, B<-dump-defaults>, B<-dump-long-names>,
1880 and B<-dump-short-names>, all described below, may all be helpful.
1884 =item Creating a new abbreviation
1886 A special notation is available for use in a F<.perltidyrc> file
1887 for creating an abbreviation for a group
1888 of options. This can be used to create a
1889 shorthand for one or more styles which are frequently, but not always,
1890 used. The notation is to group the options within curly braces which
1891 are preceded by the name of the alias (without leading dashes), like this:
1898 where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters
1899 I<or other abbreviations>. The main syntax requirement is that
1900 the new abbreviation must begin on a new line.
1901 Space before and after the curly braces is optional.
1903 specific example, the following line
1905 airy {-bl -pt=0 -bt=0 -sbt=0}
1907 could be placed in a F<.perltidyrc> file, and then invoked at will with
1909 perltidy -airy somefile.pl
1911 (Either C<-airy> or C<--airy> may be used).
1913 =item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang>
1915 If your script has leading lines of system commands or other text which
1916 are not valid perl code, and which are separated from the start of the
1917 perl code by a "hash-bang" line, ( a line of the form C<#!...perl> ),
1918 you must use the B<-x> flag to tell perltidy not to parse and format any
1919 lines before the "hash-bang" line. This option also invokes perl with a
1920 -x flag when checking the syntax. This option was originally added to
1921 allow perltidy to parse interactive VMS scripts, but it should be used
1922 for any script which is normally invoked with C<perl -x>.
1924 =item Making a file unreadable
1926 The goal of perltidy is to improve the readability of files, but there
1927 are two commands which have the opposite effect, B<--mangle> and
1928 B<--extrude>. They are actually
1929 merely aliases for combinations of other parameters. Both of these
1930 strip all possible whitespace, but leave comments and pod documents,
1931 so that they are essentially reversible. The
1932 difference between these is that B<--mangle> puts the fewest possible
1933 line breaks in a script while B<--extrude> puts the maximum possible.
1934 Note that these options do not provided any meaningful obfuscation, because
1935 perltidy can be used to reformat the files. They were originally
1936 developed to help test the tokenization logic of perltidy, but they
1938 One use for B<--mangle> is the following:
1940 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
1942 This will form the maximum possible number of one-line blocks (see next
1943 section), and can sometimes help clean up a badly formatted script.
1945 A similar technique can be used with B<--extrude> instead of B<--mangle>
1946 to make the minimum number of one-line blocks.
1948 Another use for B<--mangle> is to combine it with B<-dac> to reduce
1949 the file size of a perl script.
1951 =item One-line blocks
1953 There are a few points to note regarding one-line blocks. A one-line
1954 block is something like this,
1956 if ($x > 0) { $y = 1 / $x }
1958 where the contents within the curly braces is short enough to fit
1961 With few exceptions, perltidy retains existing one-line blocks, if it
1962 is possible within the line-length constraint, but it does not attempt
1963 to form new ones. In other words, perltidy will try to follow the
1964 one-line block style of the input file.
1966 If an existing one-line block is longer than the maximum line length,
1967 however, it will be broken into multiple lines. When this happens, perltidy
1968 checks for and adds any optional terminating semicolon (unless the B<-nasc>
1969 option is used) if the block is a code block.
1971 The main exception is that perltidy will attempt to form new one-line
1972 blocks following the keywords C<map>, C<eval>, and C<sort>, because
1973 these code blocks are often small and most clearly displayed in a single
1976 One-line block rules can conflict with the cuddled-else option. When
1977 the cuddled-else option is used, perltidy retains existing one-line
1978 blocks, even if they do not obey cuddled-else formatting.
1980 Occasionally, when one-line blocks get broken because they exceed the
1981 available line length, the formatting will violate the requested brace style.
1982 If this happens, reformatting the script a second time should correct
1987 The following flags are available for debugging:
1989 B<--dump-defaults> or B<-ddf> will write the default option set to standard output and quit
1991 B<--dump-profile> or B<-dpro> will write the name of the current
1992 configuration file and its contents to standard output and quit.
1994 B<--dump-options> or B<-dop> will write current option set to standard
1997 B<--dump-long-names> or B<-dln> will write all command line long names (passed
1998 to Get_options) to standard output and quit.
2000 B<--dump-short-names> or B<-dsn> will write all command line short names
2001 to standard output and quit.
2003 B<--dump-token-types> or B<-dtt> will write a list of all token types
2004 to standard output and quit.
2006 B<--dump-want-left-space> or B<-dwls> will write the hash %want_left_space
2007 to standard output and quit. See the section on controlling whitespace
2010 B<--dump-want-right-space> or B<-dwrs> will write the hash %want_right_space
2011 to standard output and quit. See the section on controlling whitespace
2014 B<-DEBUG> will write a file with extension F<.DEBUG> for each input file
2015 showing the tokenization of all lines of code.
2017 =item Working with MakeMaker, AutoLoader and SelfLoader
2019 The first $VERSION line of a file which might be eval'd by MakeMaker
2020 is passed through unchanged except for indentation.
2021 Use B<--nopass-version-line>, or B<-npvl>, to deactivate this feature.
2023 If the AutoLoader module is used, perltidy will continue formatting
2024 code after seeing an __END__ line.
2025 Use B<--nolook-for-autoloader>, or B<-nlal>, to deactivate this feature.
2027 Likewise, if the SelfLoader module is used, perltidy will continue formatting
2028 code after seeing a __DATA__ line.
2029 Use B<--nolook-for-selfloader>, or B<-nlsl>, to deactivate this feature.
2031 =item Working around problems with older version of Perl
2033 Perltidy contains a number of rules which help avoid known subtleties
2034 and problems with older versions of perl, and these rules always
2035 take priority over whatever formatting flags have been set. For example,
2036 perltidy will usually avoid starting a new line with a bareword, because
2037 this might cause problems if C<use strict> is active.
2039 There is no way to override these rules.
2047 =item The B<-html> master switch
2049 The flag B<-html> causes perltidy to write an html file with extension
2050 F<.html>. So, for example, the following command
2052 perltidy -html somefile.pl
2054 will produce a syntax-colored html file named F<somefile.pl.html>
2055 which may be viewed with a browser.
2057 B<Please Note>: In this case, perltidy does not do any formatting to the
2058 input file, and it does not write a formatted file with extension
2059 F<.tdy>. This means that two perltidy runs are required to create a
2060 fully reformatted, html copy of a script.
2062 =item The B<-pre> flag for code snippets
2064 When the B<-pre> flag is given, only the pre-formatted section, within
2065 the <PRE> and </PRE> tags, will be output. This simplifies inclusion
2066 of the output in other files. The default is to output a complete
2069 =item The B<-nnn> flag for line numbering
2071 When the B<-nnn> flag is given, the output lines will be numbered.
2073 =item The B<-toc>, or B<--html-table-of-contents> flag
2075 By default, a table of contents to packages and subroutines will be
2076 written at the start of html output. Use B<-ntoc> to prevent this.
2077 This might be useful, for example, for a pod document which contains a
2078 number of unrelated code snippets. This flag only influences the code
2079 table of contents; it has no effect on any table of contents produced by
2080 pod2html (see next item).
2082 =item The B<-pod>, or B<--pod2html> flag
2084 There are two options for formatting pod documentation. The default is
2085 to pass the pod through the Pod::Html module (which forms the basis of
2086 the pod2html utility). Any code sections are formatted by perltidy, and
2087 the results then merged. Note: perltidy creates a temporary file when
2088 Pod::Html is used; see L<"FILES">. Also, Pod::Html creates temporary
2089 files for its cache.
2091 NOTE: Perltidy counts the number of C<=cut> lines, and either moves the
2092 pod text to the top of the html file if there is one C<=cut>, or leaves
2093 the pod text in its original order (interleaved with code) otherwise.
2095 Most of the flags accepted by pod2html may be included in the perltidy
2096 command line, and they will be passed to pod2html. In some cases,
2097 the flags have a prefix C<pod> to emphasize that they are for the
2098 pod2html, and this prefix will be removed before they are passed to
2099 pod2html. The flags which have the additional C<pod> prefix are:
2101 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
2102 --[no]podverbose --podflush
2104 The flags which are unchanged from their use in pod2html are:
2106 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
2107 --podpath=s --podroot=s
2109 where 's' is an appropriate character string. Not all of these flags are
2110 available in older versions of Pod::Html. See your Pod::Html documentation for
2113 The alternative, indicated with B<-npod>, is not to use Pod::Html, but
2114 rather to format pod text in italics (or whatever the stylesheet
2115 indicates), without special html markup. This is useful, for example,
2116 if pod is being used as an alternative way to write comments.
2118 =item The B<-frm>, or B<--frames> flag
2120 By default, a single html output file is produced. This can be changed
2121 with the B<-frm> option, which creates a frame holding a table of
2122 contents in the left panel and the source code in the right side. This
2123 simplifies code browsing. Assume, for example, that the input file is
2124 F<MyModule.pm>. Then, for default file extension choices, these three
2125 files will be created:
2127 MyModule.pm.html - the frame
2128 MyModule.pm.toc.html - the table of contents
2129 MyModule.pm.src.html - the formatted source code
2131 Obviously this file naming scheme requires that output be directed to a real
2132 file (as opposed to, say, standard output). If this is not the
2133 case, or if the file extension is unknown, the B<-frm> option will be
2136 =item The B<-text=s>, or B<--html-toc-extension> flag
2138 Use this flag to specify the extra file extension of the table of contents file
2139 when html frames are used. The default is "toc".
2140 See L<Specifying File Extensions>.
2142 =item The B<-sext=s>, or B<--html-src-extension> flag
2144 Use this flag to specify the extra file extension of the content file when html
2145 frames are used. The default is "src".
2146 See L<Specifying File Extensions>.
2148 =item The B<-hent>, or B<--html-entities> flag
2150 This flag controls the use of Html::Entities for html formatting. By
2151 default, the module Html::Entities is used to encode special symbols.
2152 This may not be the right thing for some browser/language
2153 combinations. Use --nohtml-entities or -nhent to prevent this.
2157 Style sheets make it very convenient to control and adjust the
2158 appearance of html pages. The default behavior is to write a page of
2159 html with an embedded style sheet.
2161 An alternative to an embedded style sheet is to create a page with a
2162 link to an external style sheet. This is indicated with the
2163 B<-css=filename>, where the external style sheet is F<filename>. The
2164 external style sheet F<filename> will be created if and only if it does
2165 not exist. This option is useful for controlling multiple pages from a
2168 To cause perltidy to write a style sheet to standard output and exit,
2169 use the B<-ss>, or B<--stylesheet>, flag. This is useful if the style
2170 sheet could not be written for some reason, such as if the B<-pre> flag
2171 was used. Thus, for example,
2173 perltidy -html -ss >mystyle.css
2175 will write a style sheet with the default properties to file
2178 The use of style sheets is encouraged, but a web page without a style
2179 sheets can be created with the flag B<-nss>. Use this option if you
2180 must to be sure that older browsers (roughly speaking, versions prior to
2181 4.0 of Netscape Navigator and Internet Explorer) can display the
2182 syntax-coloring of the html files.
2184 =item Controlling HTML properties
2186 Note: It is usually more convenient to accept the default properties
2187 and then edit the stylesheet which is produced. However, this section
2188 shows how to control the properties with flags to perltidy.
2190 Syntax colors may be changed from their default values by flags of the either
2191 the long form, B<-html-color-xxxxxx=n>, or more conveniently the short form,
2192 B<-hcx=n>, where B<xxxxxx> is one of the following words, and B<x> is the
2193 corresponding abbreviation:
2196 ---------- -------- --
2199 identifier identifier i
2200 bareword, function bareword w
2202 quite, pattern quote q
2203 here doc text here-doc-text h
2204 here doc target here-doc-target hh
2205 punctuation punctuation pu
2207 structural braces structure s
2208 semicolon semicolon sc
2212 sub definition name subroutine m
2213 pod text pod-text pd
2215 A default set of colors has been defined, but they may be changed by providing
2216 values to any of the following parameters, where B<n> is either a 6 digit
2217 hex RGB color value or an ascii name for a color, such as 'red'.
2219 To illustrate, the following command will produce an html
2220 file F<somefile.pl.html> with "aqua" keywords:
2222 perltidy -html -hck=00ffff somefile.pl
2224 and this should be equivalent for most browsers:
2226 perltidy -html -hck=aqua somefile.pl
2228 Perltidy merely writes any non-hex names that it sees in the html file.
2229 The following 16 color names are defined in the HTML 3.2 standard:
2248 Many more names are supported in specific browsers, but it is safest
2249 to use the hex codes for other colors. Helpful color tables can be
2250 located with an internet search for "HTML color tables".
2252 Besides color, two other character attributes may be set: bold, and italics.
2253 To set a token type to use bold, use the flag
2254 B<-html-bold-xxxxxx> or B<-hbx>, where B<xxxxxx> or B<x> are the long
2255 or short names from the above table. Conversely, to set a token type to
2256 NOT use bold, use B<-nohtml-bold-xxxxxx> or B<-nhbx>.
2258 Likewise, to set a token type to use an italic font, use the flag
2259 B<-html-italic-xxxxxx> or B<-hix>, where again B<xxxxxx> or B<x> are the
2260 long or short names from the above table. And to set a token type to
2261 NOT use italics, use B<-nohtml-italic-xxxxxx> or B<-nhix>.
2263 For example, to use bold braces and lime color, non-bold, italics keywords the
2264 following command would be used:
2266 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
2268 The background color can be specified with B<-html-color-background=n>,
2269 or B<-hcbg=n> for short, where n is a 6 character hex RGB value. The
2270 default color of text is the value given to B<punctuation>, which is
2273 Here are some notes and hints:
2275 1. If you find a preferred set of these parameters, you may want
2276 to create a F<.perltidyrc> file containing them. See the perltidy man
2277 page for an explanation.
2279 2. Rather than specifying values for these parameters, it is probably
2280 easier to accept the defaults and then edit a style sheet. The style
2281 sheet contains comments which should make this easy.
2283 3. The syntax-colored html files can be very large, so it may be best to
2284 split large files into smaller pieces to improve download times.
2288 =head1 SOME COMMON INPUT CONVENTIONS
2290 =head2 Specifying Block Types
2292 Several parameters which refer to code block types may be customized by also
2293 specifying an associated list of block types. The type of a block is the name
2294 of the keyword which introduces that block, such as B<if>, B<else>, or B<sub>.
2295 An exception is a labeled block, which has no keyword, and should be specified
2298 For example, the following parameter specifies C<sub>, labels, C<BEGIN>, and
2301 -cscl="sub : BEGIN END"
2303 (the meaning of the -cscl parameter is described above.) Note that
2304 quotes are required around the list of block types because of the
2307 =head2 Specifying File Extensions
2309 Several parameters allow default file extensions to be overridden. For
2310 example, a backup file extension may be specified with B<-bext=ext>,
2311 where B<ext> is some new extension. In order to provides the user some
2312 flexibility, the following convention is used in all cases to decide if
2313 a leading '.' should be used. If the extension C<ext> begins with
2314 C<A-Z>, C<a-z>, or C<0-9>, then it will be appended to the filename with
2315 an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it
2316 will be appended directly.
2318 For example, suppose the file is F<somefile.pl>. For C<-bext=old>, a '.' is
2319 added to give F<somefile.pl.old>. For C<-bext=.old>, no additional '.' is
2320 added, so again the backup file is F<somefile.pl.old>. For C<-bext=~>, then no
2321 dot is added, and the backup file will be F<somefile.pl~> .
2323 =head1 SWITCHES WHICH MAY BE NEGATED
2325 The following list shows all short parameter names which allow a prefix
2326 'n' to produce the negated form:
2328 D anl asc aws b bbb bbc bbs bli boc bok bol bot syn ce csc
2329 dac dbc dcsc dnl dws dp dpro dsm dsc ddf dln dop dsn dtt dwls dwrs
2330 f fll frm hsc html ibc icb icp iob isbc lp log lal x lsl ple pod bl
2331 sbl okw ola oll ple pvl q opt sbc sfs ssc sts se st sob
2332 t tac tbc toc tp tsc tqw w
2334 Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be
2341 =item Parsing Limitations
2343 Perltidy should work properly on most perl scripts. It does a lot of
2344 self-checking, but still, it is possible that an error could be
2345 introduced and go undetected. Therefore, it is essential to make
2346 careful backups and to test reformatted scripts.
2348 The main current limitation is that perltidy does not scan modules
2349 included with 'use' statements. This makes it necessary to guess the
2350 context of any bare words introduced by such modules. Perltidy has good
2351 guessing algorithms, but they are not infallible. When it must guess,
2352 it leaves a message in the log file.
2354 If you encounter a bug, please report it.
2356 =item What perltidy does not parse and format
2358 Perltidy indents but does not reformat comments and C<qw> quotes.
2359 Perltidy does not in any way modify the contents of here documents or
2360 quoted text, even if they contain source code. (You could, however,
2361 reformat them separately). Perltidy does not format 'format' sections
2362 in any way. And, of course, it does not modify pod documents.
2370 =item Temporary files
2372 Under the -html option with the default --pod2html flag, a temporary file is
2373 required to pass text to Pod::Html. Unix systems will try to use the POSIX
2374 tmpnam() function. Otherwise the file F<perltidy.TMP> will be temporarily
2375 created in the current working directory.
2377 =item Special files when standard input is used
2379 When standard input is used, the log file, if saved, is F<perltidy.LOG>,
2380 and any errors are written to F<perltidy.ERR> unless the B<-se> flag is
2381 set. These are saved in the current working directory.
2383 =item Files overwritten
2385 The following file extensions are used by perltidy, and files with these
2386 extensions may be overwritten or deleted: F<.ERR>, F<.LOG>, F<.TEE>,
2387 and/or F<.tdy>, F<.html>, and F<.bak>, depending on the run type and
2390 =item Files extensions limitations
2392 Perltidy does not operate on files for which the run could produce a file with
2393 a duplicated file extension. These extensions include F<.LOG>, F<.ERR>,
2394 F<.TEE>, and perhaps F<.tdy> and F<.bak>, depending on the run type. The
2395 purpose of this rule is to prevent generating confusing filenames such as
2396 F<somefile.tdy.tdy.tdy>.
2402 perlstyle(1), Perl::Tidy(3)
2406 This man page documents perltidy version 20031021.
2410 Michael Cartmell supplied code for adaptation to VMS and helped with
2413 Yves Orton supplied code for adaptation to the various versions
2416 Axel Rose supplied a patch for MacPerl.
2418 Hugh S. Myers designed and implemented the initial Perl::Tidy module interface.
2420 Many others have supplied key ideas, suggestions, and bug reports;
2421 see the CHANGES file.
2426 email: perltidy at users.sourceforge.net
2427 http://perltidy.sourceforge.net
2431 Copyright (c) 2000-2003 by Steve Hancock
2435 This package is free software; you can redistribute it and/or modify it
2436 under the terms of the "GNU General Public License".
2438 Please refer to the file "COPYING" for details.
2442 This package is distributed in the hope that it will be useful,
2443 but WITHOUT ANY WARRANTY; without even the implied warranty of
2444 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
2446 See the "GNU General Public License" for more details.
projects / perltidy.git / blob