6 my $arg_string = undef;
8 # give Macs a chance to provide command line parameters
10 $arg_string = MacPerl::Ask(
11 'Please enter @ARGV (-h for help)',
12 defined $ARGV[0] ? "\"$ARGV[0]\"" : ""
16 Perl::Tidy::perltidy( argv => $arg_string );
22 perltidy - a perl script indenter and reformatter
26 perltidy [ options ] file1 file2 file3 ...
27 (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
28 perltidy [ options ] file1 -o outfile
29 perltidy [ options ] file1 -st >outfile
30 perltidy [ options ] <infile >outfile
34 Perltidy reads a perl script and writes an indented, reformatted script.
36 Many users will find enough information in L<"EXAMPLES"> to get
37 started. New users may benefit from the short tutorial
39 http://perltidy.sourceforge.net/tutorial.html
41 A convenient aid to systematically defining a set of style parameters
43 http://perltidy.sourceforge.net/stylekey.html
45 Perltidy can produce output on either of two modes, depending on the
46 existence of an B<-html> flag. Without this flag, the output is passed
47 through a formatter. The default formatting tries to follow the
48 recommendations in perlstyle(1), but it can be controlled in detail with
49 numerous input parameters, which are described in L<"FORMATTING
52 When the B<-html> flag is given, the output is passed through an HTML
53 formatter which is described in L<"HTML OPTIONS">.
59 This will produce a file F<somefile.pl.tdy> containing the script reformatted
60 using the default options, which approximate the style suggested in
61 perlstyle(1). The source file F<somefile.pl> is unchanged.
65 Execute perltidy on all F<.pl> files in the current directory with the
66 default options. The output will be in files with an appended F<.tdy>
67 extension. For any file with an error, there will be a file with extension
70 perltidy -b file1.pl file2.pl
72 Modify F<file1.pl> and F<file2.pl> in place, and backup the originals to
73 F<file1.pl.bak> and F<file2.pl.bak>. If F<file1.pl.bak> and/or F<file2.pl.bak>
74 already exist, they will be overwritten.
76 perltidy -b -bext='/' file1.pl file2.pl
78 Same as the previous example except that the backup files F<file1.pl.bak> and F<file2.pl.bak> will be deleted if there are no errors.
80 perltidy -gnu somefile.pl
82 Execute perltidy on file F<somefile.pl> with a style which approximates the
83 GNU Coding Standards for C programs. The output will be F<somefile.pl.tdy>.
85 perltidy -i=3 somefile.pl
87 Execute perltidy on file F<somefile.pl>, with 3 columns for each level of
88 indentation (B<-i=3>) instead of the default 4 columns. There will not be any
89 tabs in the reformatted script, except for any which already exist in comments,
90 pod documents, quotes, and here documents. Output will be F<somefile.pl.tdy>.
92 perltidy -i=3 -et=8 somefile.pl
94 Same as the previous example, except that leading whitespace will
95 be entabbed with one tab character per 8 spaces.
97 perltidy -ce -l=72 somefile.pl
99 Execute perltidy on file F<somefile.pl> with all defaults except use "cuddled
100 elses" (B<-ce>) and a maximum line length of 72 columns (B<-l=72>) instead of
101 the default 80 columns.
103 perltidy -g somefile.pl
105 Execute perltidy on file F<somefile.pl> and save a log file F<somefile.pl.LOG>
106 which shows the nesting of braces, parentheses, and square brackets at
107 the start of every line.
109 perltidy -html somefile.pl
111 This will produce a file F<somefile.pl.html> containing the script with
112 html markup. The output file will contain an embedded style sheet in
113 the <HEAD> section which may be edited to change the appearance.
115 perltidy -html -css=mystyle.css somefile.pl
117 This will produce a file F<somefile.pl.html> containing the script with
118 html markup. This output file will contain a link to a separate style
119 sheet file F<mystyle.css>. If the file F<mystyle.css> does not exist,
120 it will be created. If it exists, it will not be overwritten.
122 perltidy -html -pre somefile.pl
124 Write an html snippet with only the PRE section to F<somefile.pl.html>.
125 This is useful when code snippets are being formatted for inclusion in a
126 larger web page. No style sheet will be written in this case.
128 perltidy -html -ss >mystyle.css
130 Write a style sheet to F<mystyle.css> and exit.
132 perltidy -html -frm mymodule.pm
134 Write html with a frame holding a table of contents and the source code. The
135 output files will be F<mymodule.pm.html> (the frame), F<mymodule.pm.toc.html>
136 (the table of contents), and F<mymodule.pm.src.html> (the source code).
138 =head1 OPTIONS - OVERVIEW
140 The entire command line is scanned for options, and they are processed
141 before any files are processed. As a result, it does not matter
142 whether flags are before or after any filenames. However, the relative
143 order of parameters is important, with later parameters overriding the
144 values of earlier parameters.
146 For each parameter, there is a long name and a short name. The short
147 names are convenient for keyboard input, while the long names are
148 self-documenting and therefore useful in scripts. It is customary to
149 use two leading dashes for long names, but one may be used.
151 Most parameters which serve as on/off flags can be negated with a
152 leading "n" (for the short name) or a leading "no" or "no-" (for the
153 long name). For example, the flag to outdent long quotes is B<-olq>
154 or B<--outdent-long-quotes>. The flag to skip this is B<-nolq>
155 or B<--nooutdent-long-quotes> or B<--no-outdent-long-quotes>.
157 Options may not be bundled together. In other words, options B<-q> and
158 B<-g> may NOT be entered as B<-qg>.
160 Option names may be terminated early as long as they are uniquely identified.
161 For example, instead of B<--dump-token-types>, it would be sufficient to enter
162 B<--dump-tok>, or even B<--dump-t>, to uniquely identify this command.
166 The following parameters concern the files which are read and written.
170 =item B<-h>, B<--help>
172 Show summary of usage and exit.
174 =item B<-o>=filename, B<--outfile>=filename
176 Name of the output file (only if a single input file is being
177 processed). If no output file is specified, and output is not
178 redirected to the standard output (see B<-st>), the output will go to
179 F<filename.tdy>. [Note: - does not redirect to standard output. Use
182 =item B<-st>, B<--standard-output>
184 Perltidy must be able to operate on an arbitrarily large number of files
185 in a single run, with each output being directed to a different output
186 file. Obviously this would conflict with outputting to the single
187 standard output device, so a special flag, B<-st>, is required to
188 request outputting to the standard output. For example,
190 perltidy somefile.pl -st >somefile.new.pl
192 This option may only be used if there is just a single input file.
193 The default is B<-nst> or B<--nostandard-output>.
195 =item B<-se>, B<--standard-error-output>
197 If perltidy detects an error when processing file F<somefile.pl>, its
198 default behavior is to write error messages to file F<somefile.pl.ERR>.
199 Use B<-se> to cause all error messages to be sent to the standard error
200 output stream instead. This directive may be negated with B<-nse>.
201 Thus, you may place B<-se> in a F<.perltidyrc> and override it when
202 desired with B<-nse> on the command line.
204 =item B<-oext>=ext, B<--output-file-extension>=ext
206 Change the extension of the output file to be F<ext> instead of the
207 default F<tdy> (or F<html> in case the -B<-html> option is used).
208 See L<Specifying File Extensions>.
210 =item B<-opath>=path, B<--output-path>=path
212 When perltidy creates a filename for an output file, by default it merely
213 appends an extension to the path and basename of the input file. This
214 parameter causes the path to be changed to F<path> instead.
216 The path should end in a valid path separator character, but perltidy will try
217 to add one if it is missing.
221 perltidy somefile.pl -opath=/tmp/
223 will produce F</tmp/somefile.pl.tdy>. Otherwise, F<somefile.pl.tdy> will
224 appear in whatever directory contains F<somefile.pl>.
226 If the path contains spaces, it should be placed in quotes.
228 This parameter will be ignored if output is being directed to standard output,
229 or if it is being specified explicitly with the B<-o=s> parameter.
231 =item B<-b>, B<--backup-and-modify-in-place>
233 Modify the input file or files in-place and save the original with the
234 extension F<.bak>. Any existing F<.bak> file will be deleted. See next
235 item for changing the default backup extension, and for eliminating the
236 backup file altogether.
238 A B<-b> flag will be ignored if input is from standard input or goes to
239 standard output, or if the B<-html> flag is set.
241 In particular, if you want to use both the B<-b> flag and the B<-pbp>
242 (--perl-best-practices) flag, then you must put a B<-nst> flag after the
243 B<-pbp> flag because it contains a B<-st> flag as one of its components,
244 which means that output will go to the standard output stream.
246 =item B<-bext>=ext, B<--backup-file-extension>=ext
248 This parameter serves two purposes: (1) to change the extension of the backup
249 file to be something other than the default F<.bak>, and (2) to indicate
250 that no backup file should be saved.
252 To change the default extension to something other than F<.bak> see
253 L<Specifying File Extensions>.
255 A backup file of the source is always written, but you can request that it
256 be deleted at the end of processing if there were no errors. This is risky
257 unless the source code is being maintained with a source code control
260 To indicate that the backup should be deleted include one forward slash,
261 B</>, in the extension. If any text remains after the slash is removed
262 it will be used to define the backup file extension (which is always
263 created and only deleted if there were no errors).
265 Here are some examples:
267 Parameter Extension Backup File Treatment
268 <-bext=bak> F<.bak> Keep (same as the default behavior)
269 <-bext='/'> F<.bak> Delete if no errors
270 <-bext='/backup'> F<.backup> Delete if no errors
271 <-bext='original/'> F<.original> Delete if no errors
273 =item B<-w>, B<--warning-output>
275 Setting B<-w> causes any non-critical warning
276 messages to be reported as errors. These include messages
277 about possible pod problems, possibly bad starting indentation level,
278 and cautions about indirect object usage. The default, B<-nw> or
279 B<--nowarning-output>, is not to include these warnings.
281 =item B<-q>, B<--quiet>
283 Deactivate error messages and syntax checking (for running under
286 For example, if you use a vi-style editor, such as vim, you may execute
287 perltidy as a filter from within the editor using something like
291 where C<n1,n2> represents the selected text. Without the B<-q> flag,
292 any error message may mess up your screen, so be prepared to use your
295 =item B<-log>, B<--logfile>
297 Save the F<.LOG> file, which has many useful diagnostics. Perltidy always
298 creates a F<.LOG> file, but by default it is deleted unless a program bug is
299 suspected. Setting the B<-log> flag forces the log file to be saved.
301 =item B<-g=n>, B<--logfile-gap=n>
303 Set maximum interval between input code lines in the logfile. This purpose of
304 this flag is to assist in debugging nesting errors. The value of C<n> is
305 optional. If you set the flag B<-g> without the value of C<n>, it will be
306 taken to be 1, meaning that every line will be written to the log file. This
307 can be helpful if you are looking for a brace, paren, or bracket nesting error.
309 Setting B<-g> also causes the logfile to be saved, so it is not necessary to
310 also include B<-log>.
312 If no B<-g> flag is given, a value of 50 will be used, meaning that at least
313 every 50th line will be recorded in the logfile. This helps prevent
314 excessively long log files.
316 Setting a negative value of C<n> is the same as not setting B<-g> at all.
318 =item B<-npro> B<--noprofile>
320 Ignore any F<.perltidyrc> command file. Normally, perltidy looks first in
321 your current directory for a F<.perltidyrc> file of parameters. (The format
322 is described below). If it finds one, it applies those options to the
323 initial default values, and then it applies any that have been defined
324 on the command line. If no F<.perltidyrc> file is found, it looks for one
325 in your home directory.
327 If you set the B<-npro> flag, perltidy will not look for this file.
329 =item B<-pro=filename> or B<--profile=filename>
331 To simplify testing and switching .perltidyrc files, this command may be
332 used to specify a configuration file which will override the default
333 name of .perltidyrc. There must not be a space on either side of the
334 '=' sign. For example, the line
336 perltidy -pro=testcfg
338 would cause file F<testcfg> to be used instead of the
339 default F<.perltidyrc>.
341 A pathname begins with three dots, e.g. ".../.perltidyrc", indicates that
342 the file should be searched for starting in the current directory and
343 working upwards. This makes it easier to have multiple projects each with
344 their own .perltidyrc in their root directories.
346 =item B<-opt>, B<--show-options>
348 Write a list of all options used to the F<.LOG> file.
349 Please see B<--dump-options> for a simpler way to do this.
351 =item B<-f>, B<--force-read-binary>
353 Force perltidy to process binary files. To avoid producing excessive
354 error messages, perltidy skips files identified by the system as non-text.
355 However, valid perl scripts containing binary data may sometimes be identified
356 as non-text, and this flag forces perltidy to process them.
360 =head1 FORMATTING OPTIONS
368 This flag disables all formatting and causes the input to be copied unchanged
369 to the output except for possible changes in line ending characters and any
370 pre- and post-filters. This can be useful in conjunction with a hierarchical
371 set of F<.perltidyrc> files to avoid unwanted code tidying. See also
372 L<Skipping Selected Sections of Code> for a way to avoid tidying specific
375 =item B<-i=n>, B<--indent-columns=n>
377 Use n columns per indentation level (default n=4).
379 =item B<-l=n>, B<--maximum-line-length=n>
381 The default maximum line length is n=80 characters. Perltidy will try
382 to find line break points to keep lines below this length. However, long
383 quotes and side comments may cause lines to exceed this length.
384 Setting B<-l=0> is equivalent to setting B<-l=(a large number)>.
386 =item B<-vmll>, B<--variable-maximum-line-length>
388 A problem arises using a fixed maximum line length with very deeply nested code
389 and data structures because eventually the amount of leading whitespace used
390 for indicating indentation takes up most or all of the available line width,
391 leaving little or no space for the actual code or data. One solution is to use
392 a vary long line length. Another solution is to use the B<-vmll> flag, which
393 basically tells perltidy to ignore leading whitespace when measuring the line
396 To be precise, when the B<-vmll> parameter is set, the maximum line length of a
397 line of code will be M+L*I, where
399 M is the value of --maximum-line-length=M (-l=M), default 80,
400 I is the value of --indent-columns=I (-i=I), default 4,
401 L is the indentation level of the line of code
403 When this flag is set, the choice of breakpoints for a block of code should be
404 essentially independent of its nesting depth. However, the absolute line
405 lengths, including leading whitespace, can still be arbitrarily large. This
406 problem can be avoided by including the next parameter.
408 The default is not to do this (B<-nvmll>).
410 =item B<-wc=n>, B<--whitespace-cycle=n>
412 This flag also addresses problems with very deeply nested code and data
413 structures. When the nesting depth exceeds the value B<n> the leading
414 whitespace will be reduced and start at a depth of 1 again. The result is that
415 blocks of code will shift back to the left rather than moving arbitrarily far
416 to the right. This occurs cyclically to any depth.
418 For example if one level of indentation equals 4 spaces (B<-i=4>, the default),
419 and one uses B<-wc=15>, then if the leading whitespace on a line exceeds about
420 4*15=60 spaces it will be reduced back to 4*1=4 spaces and continue increasing
421 from there. If the whitespace never exceeds this limit the formatting remains
424 The combination of B<-vmll> and B<-wc=n> provides a solution to the problem of
425 displaying arbitrarily deep data structures and code in a finite window,
426 although B<-wc=n> may of course be used without B<-vmll>.
428 The default is not to use this, which can also be indicated using B<-wc=0>.
432 Using tab characters will almost certainly lead to future portability
433 and maintenance problems, so the default and recommendation is not to
434 use them. For those who prefer tabs, however, there are two different
437 Except for possibly introducing tab indentation characters, as outlined
438 below, perltidy does not introduce any tab characters into your file,
439 and it removes any tabs from the code (unless requested not to do so
440 with B<-fws>). If you have any tabs in your comments, quotes, or
441 here-documents, they will remain.
445 =item B<-et=n>, B<--entab-leading-whitespace>
447 This flag causes each B<n> initial space characters to be replaced by
448 one tab character. Note that the integer B<n> is completely independent
449 of the integer specified for indentation parameter, B<-i=n>.
451 =item B<-t>, B<--tabs>
453 This flag causes one leading tab character to be inserted for each level
454 of indentation. Certain other features are incompatible with this
455 option, and if these options are also given, then a warning message will
456 be issued and this flag will be unset. One example is the B<-lp>
459 =item B<-dt=n>, B<--default-tabsize=n>
461 If the first line of code passed to perltidy contains leading tabs but no
462 tab scheme is specified for the output stream then perltidy must guess how many
463 spaces correspond to each leading tab. This number of spaces B<n>
464 corresponding to each leading tab of the input stream may be specified with
465 B<-dt=n>. The default is B<n=8>.
467 This flag has no effect if a tab scheme is specified for the output stream,
468 because then the input stream is assumed to use the same tab scheme and
469 indentation spaces as for the output stream (any other assumption would lead to
474 =item B<-syn>, B<--check-syntax>
476 This flag is now ignored for safety, but the following documentation
477 has been retained for reference.
479 This flag causes perltidy to run C<perl -c -T> to check syntax of input
480 and output. (To change the flags passed to perl, see the next
481 item, B<-pscf>). The results are written to the F<.LOG> file, which
482 will be saved if an error is detected in the output script. The output
483 script is not checked if the input script has a syntax error. Perltidy
484 does its own checking, but this option employs perl to get a "second
487 If perl reports errors in the input file, they will not be reported in
488 the error output unless the B<--warning-output> flag is given.
490 The default is B<NOT> to do this type of syntax checking (although
491 perltidy will still do as much self-checking as possible). The reason
492 is that it causes all code in BEGIN blocks to be executed, for all
493 modules being used, and this opens the door to security issues and
494 infinite loops when running perltidy.
496 =item B<-pscf=s>, B<-perl-syntax-check-flags=s>
498 When perl is invoked to check syntax, the normal flags are C<-c -T>. In
499 addition, if the B<-x> flag is given to perltidy, then perl will also be
500 passed a B<-x> flag. It should not normally be necessary to change
501 these flags, but it can be done with the B<-pscf=s> flag. For example,
502 if the taint flag, C<-T>, is not wanted, the flag could be set to be just
505 Perltidy will pass your string to perl with the exception that it will
506 add a B<-c> and B<-x> if appropriate. The F<.LOG> file will show
507 exactly what flags were passed to perl.
509 =item B<-xs>, B<--extended-syntax>
511 A problem with formatting Perl code is that some modules can introduce new
512 syntax. This flag allows perltidy to handle certain common extensions
513 to the standard syntax without complaint.
515 For example, without this flag a structure such as the following would generate
516 a syntax error and the braces would not be balanced:
518 method deposit( Num $amount) {
519 $self->balance( $self->balance + $amount );
522 This flag is enabled by default but it can be deactivated with B<-nxs>.
523 Probably the only reason to deactivate this flag is to generate more diagnostic
524 messages when debugging a script.
527 =item B<-io>, B<--indent-only>
529 This flag is used to deactivate all whitespace and line break changes
530 within non-blank lines of code.
531 When it is in effect, the only change to the script will be
532 to the indentation and to the number of blank lines.
533 And any flags controlling whitespace and newlines will be ignored. You
534 might want to use this if you are perfectly happy with your whitespace
535 and line breaks, and merely want perltidy to handle the indentation.
536 (This also speeds up perltidy by well over a factor of two, so it might be
537 useful when perltidy is merely being used to help find a brace error in
540 Setting this flag is equivalent to setting B<--freeze-newlines> and
541 B<--freeze-whitespace>.
543 If you also want to keep your existing blank lines exactly
544 as they are, you can add B<--freeze-blank-lines>.
546 With this option perltidy is still free to modify the indenting (and
547 outdenting) of code and comments as it normally would. If you also want to
548 prevent long comment lines from being outdented, you can add either B<-noll> or
551 Setting this flag will prevent perltidy from doing any special operations on
552 closing side comments. You may still delete all side comments however when
553 this flag is in effect.
556 =item B<-enc=s>, B<--character-encoding=s>
558 where B<s>=B<none> or B<utf8>. This flag tells perltidy the character encoding
559 of both the input and output character streams. The value B<utf8> causes the
560 stream to be read and written as UTF-8. The value B<none> causes the stream to
561 be processed without special encoding assumptions. At present there is no
562 automatic detection of character encoding (even if there is a C<'use utf8'>
563 statement in your code) so this flag must be set for streams encoded in UTF-8.
564 Incorrectly setting this parameter can cause data corruption, so please
565 carefully check the output.
567 The default is B<none>.
569 The abbreviations B<-utf8> or B<-UTF8> are equivalent to B<-enc=utf8>.
570 So to process a file named B<file.pl> which is encoded in UTF-8 you can use:
572 perltidy -utf8 file.pl
574 =item B<-ole=s>, B<--output-line-ending=s>
576 where s=C<win>, C<dos>, C<unix>, or C<mac>. This flag tells perltidy
577 to output line endings for a specific system. Normally,
578 perltidy writes files with the line separator character of the host
579 system. The C<win> and C<dos> flags have an identical result.
581 =item B<-ple>, B<--preserve-line-endings>
583 This flag tells perltidy to write its output files with the same line
584 endings as the input file, if possible. It should work for
585 B<dos>, B<unix>, and B<mac> line endings. It will only work if perltidy
586 input comes from a filename (rather than stdin, for example). If
587 perltidy has trouble determining the input file line ending, it will
588 revert to the default behavior of using the line ending of the host system.
590 =item B<-it=n>, B<--iterations=n>
592 This flag causes perltidy to do B<n> complete iterations. The reason for this
593 flag is that code beautification is an iterative process and in some
594 cases the output from perltidy can be different if it is applied a second time.
595 For most purposes the default of B<n=1> should be satisfactory. However B<n=2>
596 can be useful when a major style change is being made, or when code is being
597 beautified on check-in to a source code control system. It has been found to
598 be extremely rare for the output to change after 2 iterations. If a value
599 B<n> is greater than 2 is input then a convergence test will be used to stop
600 the iterations as soon as possible, almost always after 2 iterations. See
601 the next item for a simplified iteration control.
603 This flag has no effect when perltidy is used to generate html.
605 =item B<-conv>, B<--converge>
607 This flag is equivalent to B<-it=4> and is included to simplify iteration
608 control. For all practical purposes one either does or does not want to be
609 sure that the output is converged, and there is no penalty to using a large
610 iteration limit since perltidy will check for convergence and stop iterating as
611 soon as possible. The default is B<-nconv> (no convergence check). Using
612 B<-conv> will approximately double run time since normally one extra iteration
613 is required to verify convergence.
617 =head2 Code Indentation Control
621 =item B<-ci=n>, B<--continuation-indentation=n>
623 Continuation indentation is extra indentation spaces applied when
624 a long line is broken. The default is n=2, illustrated here:
627 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
629 The same example, with n=0, is a little harder to read:
632 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
634 The value given to B<-ci> is also used by some commands when a small
635 space is required. Examples are commands for outdenting labels,
636 B<-ola>, and control keywords, B<-okw>.
638 When default values are not used, it is suggested that the value B<n>
639 given with B<-ci=n> be no more than about one-half of the number of
640 spaces assigned to a full indentation level on the B<-i=n> command.
642 =item B<-sil=n> B<--starting-indentation-level=n>
644 By default, perltidy examines the input file and tries to determine the
645 starting indentation level. While it is often zero, it may not be
646 zero for a code snippet being sent from an editing session.
648 To guess the starting indentation level perltidy simply assumes that
649 indentation scheme used to create the code snippet is the same as is being used
650 for the current perltidy process. This is the only sensible guess that can be
651 made. It should be correct if this is true, but otherwise it probably won't.
652 For example, if the input script was written with -i=2 and the current peltidy
653 flags have -i=4, the wrong initial indentation will be guessed for a code
654 snippet which has non-zero initial indentation. Likewise, if an entabbing
655 scheme is used in the input script and not in the current process then the
656 guessed indentation will be wrong.
658 If the default method does not work correctly, or you want to change the
659 starting level, use B<-sil=n>, to force the starting level to be n.
661 =item List indentation using B<-lp>, B<--line-up-parentheses>
663 By default, perltidy indents lists with 4 spaces, or whatever value
664 is specified with B<-i=n>. Here is a small list formatted in this way:
668 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
669 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
672 Use the B<-lp> flag to add extra indentation to cause the data to begin
673 past the opening parentheses of a sub call or list, or opening square
674 bracket of an anonymous array, or opening curly brace of an anonymous
675 hash. With this option, the above list would become:
679 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
680 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
683 If the available line length (see B<-l=n> ) does not permit this much
684 space, perltidy will use less. For alternate placement of the
685 closing paren, see the next section.
687 This option has no effect on code BLOCKS, such as if/then/else blocks,
688 which always use whatever is specified with B<-i=n>. Also, the
689 existence of line breaks and/or block comments between the opening and
690 closing parens may cause perltidy to temporarily revert to its default
693 Note: The B<-lp> option may not be used together with the B<-t> tabs option.
694 It may, however, be used with the B<-et=n> tab method.
696 In addition, any parameter which significantly restricts the ability of
697 perltidy to choose newlines will conflict with B<-lp> and will cause
698 B<-lp> to be deactivated. These include B<-io>, B<-fnl>, B<-nanl>, and
699 B<-ndnl>. The reason is that the B<-lp> indentation style can require
700 the careful coordination of an arbitrary number of break points in
701 hierarchical lists, and these flags may prevent that.
703 =item B<-cti=n>, B<--closing-token-indentation>
705 The B<-cti=n> flag controls the indentation of a line beginning with
706 a C<)>, C<]>, or a non-block C<}>. Such a line receives:
708 -cti = 0 no extra indentation (default)
709 -cti = 1 extra indentation such that the closing token
710 aligns with its opening token.
711 -cti = 2 one extra indentation level if the line looks like:
713 -cti = 3 one extra indentation level always
715 The flags B<-cti=1> and B<-cti=2> work well with the B<-lp> flag (previous
718 # perltidy -lp -cti=1
720 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
721 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
724 # perltidy -lp -cti=2
726 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
727 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
730 These flags are merely hints to the formatter and they may not always be
731 followed. In particular, if -lp is not being used, the indentation for
732 B<cti=1> is constrained to be no more than one indentation level.
734 If desired, this control can be applied independently to each of the
735 closing container token types. In fact, B<-cti=n> is merely an
736 abbreviation for B<-cpi=n -csbi=n -cbi=n>, where:
737 B<-cpi> or B<--closing-paren-indentation> controls B<)>'s,
738 B<-csbi> or B<--closing-square-bracket-indentation> controls B<]>'s,
739 B<-cbi> or B<--closing-brace-indentation> controls non-block B<}>'s.
741 =item B<-icp>, B<--indent-closing-paren>
743 The B<-icp> flag is equivalent to
744 B<-cti=2>, described in the previous section. The B<-nicp> flag is
745 equivalent B<-cti=0>. They are included for backwards compatibility.
747 =item B<-icb>, B<--indent-closing-brace>
749 The B<-icb> option gives one extra level of indentation to a brace which
750 terminates a code block . For example,
759 The default is not to do this, indicated by B<-nicb>.
761 =item B<-olq>, B<--outdent-long-quotes>
763 When B<-olq> is set, lines which is a quoted string longer than the
764 value B<maximum-line-length> will have their indentation removed to make
765 them more readable. This is the default. To prevent such out-denting,
766 use B<-nolq> or B<--nooutdent-long-lines>.
768 =item B<-oll>, B<--outdent-long-lines>
770 This command is equivalent to B<--outdent-long-quotes> and
771 B<--outdent-long-comments>, and it is included for compatibility with previous
772 versions of perltidy. The negation of this also works, B<-noll> or
773 B<--nooutdent-long-lines>, and is equivalent to setting B<-nolq> and B<-nolc>.
775 =item Outdenting Labels: B<-ola>, B<--outdent-labels>
777 This command will cause labels to be outdented by 2 spaces (or whatever B<-ci>
778 has been set to), if possible. This is the default. For example:
781 LOOP: while ( $i = <FOTOS> ) {
787 Use B<-nola> to not outdent labels.
789 =item Outdenting Keywords
793 =item B<-okw>, B<--outdent-keywords>
795 The command B<-okw> will cause certain leading control keywords to
796 be outdented by 2 spaces (or whatever B<-ci> has been set to), if
797 possible. By default, these keywords are C<redo>, C<next>, C<last>,
798 C<goto>, and C<return>. The intention is to make these control keywords
799 easier to see. To change this list of keywords being outdented, see
802 For example, using C<perltidy -okw> on the previous example gives:
805 LOOP: while ( $i = <FOTOS> ) {
811 The default is not to do this.
813 =item Specifying Outdented Keywords: B<-okwl=string>, B<--outdent-keyword-list=string>
815 This command can be used to change the keywords which are outdented with
816 the B<-okw> command. The parameter B<string> is a required list of perl
817 keywords, which should be placed in quotes if there are more than one.
818 By itself, it does not cause any outdenting to occur, so the B<-okw>
819 command is still required.
821 For example, the commands C<-okwl="next last redo goto" -okw> will cause
822 those four keywords to be outdented. It is probably simplest to place
823 any B<-okwl> command in a F<.perltidyrc> file.
829 =head2 Whitespace Control
831 Whitespace refers to the blank space between variables, operators,
832 and other code tokens.
836 =item B<-fws>, B<--freeze-whitespace>
838 This flag causes your original whitespace to remain unchanged, and
839 causes the rest of the whitespace commands in this section, the
840 Code Indentation section, and
841 the Comment Control section to be ignored.
843 =item Tightness of curly braces, parentheses, and square brackets.
845 Here the term "tightness" will mean the closeness with which
846 pairs of enclosing tokens, such as parentheses, contain the quantities
847 within. A numerical value of 0, 1, or 2 defines the tightness, with
848 0 being least tight and 2 being most tight. Spaces within containers
849 are always symmetric, so if there is a space after a C<(> then there
850 will be a space before the corresponding C<)>.
852 The B<-pt=n> or B<--paren-tightness=n> parameter controls the space within
853 parens. The example below shows the effect of the three possible
856 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
857 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
858 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
860 When n is 0, there is always a space to the right of a '(' and to the left
861 of a ')'. For n=2 there is never a space. For n=1, the default, there
862 is a space unless the quantity within the parens is a single token, such
863 as an identifier or quoted string.
865 Likewise, the parameter B<-sbt=n> or B<--square-bracket-tightness=n>
866 controls the space within square brackets, as illustrated below.
868 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
869 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
870 $width = $col[$j + $k] - $col[$j]; # -sbt=2
872 Curly braces which do not contain code blocks are controlled by
873 the parameter B<-bt=n> or B<--brace-tightness=n>.
875 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
876 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
877 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
879 And finally, curly braces which contain blocks of code are controlled by the
880 parameter B<-bbt=n> or B<--block-brace-tightness=n> as illustrated in the
883 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
884 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
885 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
887 To simplify input in the case that all of the tightness flags have the same
888 value <n>, the parameter <-act=n> or B<--all-containers-tightness=n> is an
889 abbreviation for the combination <-pt=n -sbt=n -bt=n -bbt=n>.
892 =item B<-tso>, B<--tight-secret-operators>
894 The flag B<-tso> causes certain perl token sequences (secret operators)
895 which might be considered to be a single operator to be formatted "tightly"
896 (without spaces). The operators currently modified by this flag are:
898 0+ +0 ()x!! ~~<> ,=> =( )=
900 For example the sequence B<0 +>, which converts a string to a number,
901 would be formatted without a space: B<0+> when the B<-tso> flag is set. This
902 flag is off by default.
904 =item B<-sts>, B<--space-terminal-semicolon>
906 Some programmers prefer a space before all terminal semicolons. The
907 default is for no such space, and is indicated with B<-nsts> or
908 B<--nospace-terminal-semicolon>.
911 $i = 1; # -nsts (default)
913 =item B<-sfs>, B<--space-for-semicolon>
915 Semicolons within B<for> loops may sometimes be hard to see,
916 particularly when commas are also present. This option places spaces on
917 both sides of these special semicolons, and is the default. Use
918 B<-nsfs> or B<--nospace-for-semicolon> to deactivate it.
920 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
921 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
923 =item B<-asc>, B<--add-semicolons>
925 Setting B<-asc> allows perltidy to add any missing optional semicolon at the end
926 of a line which is followed by a closing curly brace on the next line. This
927 is the default, and may be deactivated with B<-nasc> or B<--noadd-semicolons>.
929 =item B<-dsm>, B<--delete-semicolons>
931 Setting B<-dsm> allows perltidy to delete extra semicolons which are
932 simply empty statements. This is the default, and may be deactivated
933 with B<-ndsm> or B<--nodelete-semicolons>. (Such semicolons are not
934 deleted, however, if they would promote a side comment to a block
937 =item B<-aws>, B<--add-whitespace>
939 Setting this option allows perltidy to add certain whitespace improve
940 code readability. This is the default. If you do not want any
941 whitespace added, but are willing to have some whitespace deleted, use
942 B<-naws>. (Use B<-fws> to leave whitespace completely unchanged).
944 =item B<-dws>, B<--delete-old-whitespace>
946 Setting this option allows perltidy to remove some old whitespace
947 between characters, if necessary. This is the default. If you
948 do not want any old whitespace removed, use B<-ndws> or
949 B<--nodelete-old-whitespace>.
951 =item Detailed whitespace controls around tokens
953 For those who want more detailed control over the whitespace around
954 tokens, there are four parameters which can directly modify the default
955 whitespace rules built into perltidy for any token. They are:
957 B<-wls=s> or B<--want-left-space=s>,
959 B<-nwls=s> or B<--nowant-left-space=s>,
961 B<-wrs=s> or B<--want-right-space=s>,
963 B<-nwrs=s> or B<--nowant-right-space=s>.
965 These parameters are each followed by a quoted string, B<s>, containing a
966 list of token types. No more than one of each of these parameters
967 should be specified, because repeating a command-line parameter
968 always overwrites the previous one before perltidy ever sees it.
970 To illustrate how these are used, suppose it is desired that there be no
971 space on either side of the token types B<= + - / *>. The following two
972 parameters would specify this desire:
974 -nwls="= + - / *" -nwrs="= + - / *"
976 (Note that the token types are in quotes, and that they are separated by
977 spaces). With these modified whitespace rules, the following line of math:
979 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
983 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
985 These parameters should be considered to be hints to perltidy rather
986 than fixed rules, because perltidy must try to resolve conflicts that
987 arise between them and all of the other rules that it uses. One
988 conflict that can arise is if, between two tokens, the left token wants
989 a space and the right one doesn't. In this case, the token not wanting
990 a space takes priority.
992 It is necessary to have a list of all token types in order to create
993 this type of input. Such a list can be obtained by the command
994 B<--dump-token-types>. Also try the B<-D> flag on a short snippet of code
995 and look at the .DEBUG file to see the tokenization.
997 B<WARNING> Be sure to put these tokens in quotes to avoid having them
998 misinterpreted by your command shell.
1000 =item Space between specific keywords and opening paren
1002 When an opening paren follows a Perl keyword, no space is introduced after the
1003 keyword, unless it is (by default) one of these:
1005 my local our and or eq ne if else elsif until unless
1006 while for foreach return switch case given when
1008 These defaults can be modified with two commands:
1010 B<-sak=s> or B<--space-after-keyword=s> adds keywords.
1012 B<-nsak=s> or B<--nospace-after-keyword=s> removes keywords.
1014 where B<s> is a list of keywords (in quotes if necessary). For example,
1016 my ( $a, $b, $c ) = @_; # default
1017 my( $a, $b, $c ) = @_; # -nsak="my local our"
1019 The abbreviation B<-nsak='*'> is equivalent to including all of the
1020 keywords in the above list.
1022 When both B<-nsak=s> and B<-sak=s> commands are included, the B<-nsak=s>
1023 command is executed first. For example, to have space after only the
1024 keywords (my, local, our) you could use B<-nsak="*" -sak="my local our">.
1026 To put a space after all keywords, see the next item.
1028 =item Space between all keywords and opening parens
1030 When an opening paren follows a function or keyword, no space is introduced
1031 after the keyword except for the keywords noted in the previous item. To
1032 always put a space between a function or keyword and its opening paren,
1035 B<-skp> or B<--space-keyword-paren>
1037 You will probably also want to use the flag B<-sfp> (next item) too.
1039 =item Space between all function names and opening parens
1041 When an opening paren follows a function the default is not to introduce
1042 a space. To cause a space to be introduced use:
1044 B<-sfp> or B<--space-function-paren>
1046 myfunc( $a, $b, $c ); # default
1047 myfunc ( $a, $b, $c ); # -sfp
1049 You will probably also want to use the flag B<-skp> (previous item) too.
1051 =item Trimming whitespace around C<qw> quotes
1053 B<-tqw> or B<--trim-qw> provide the default behavior of trimming
1054 spaces around multi-line C<qw> quotes and indenting them appropriately.
1056 B<-ntqw> or B<--notrim-qw> cause leading and trailing whitespace around
1057 multi-line C<qw> quotes to be left unchanged. This option will not
1058 normally be necessary, but was added for testing purposes, because in
1059 some versions of perl, trimming C<qw> quotes changes the syntax tree.
1061 =item B<-sbq=n> or B<--space-backslash-quote=n>
1068 can confuse syntax highlighters unless a space is included between the backslash and the single or double quotation mark.
1070 This can be controlled with the value of B<n> as follows:
1072 -sbq=0 means no space between the backslash and quote
1073 -sbq=1 means follow the example of the source code
1074 -sbq=2 means always put a space between the backslash and quote
1076 The default is B<-sbq=1>, meaning that a space will be used 0if there is one in the source code.
1078 =item Trimming trailing whitespace from lines of POD
1080 B<-trp> or B<--trim-pod> will remove trailing whitespace from lines of POD.
1081 The default is not to do this.
1085 =head2 Comment Controls
1087 Perltidy has a number of ways to control the appearance of both block comments
1088 and side comments. The term B<block comment> here refers to a full-line
1089 comment, whereas B<side comment> will refer to a comment which appears on a
1090 line to the right of some code.
1094 =item B<-ibc>, B<--indent-block-comments>
1096 Block comments normally look best when they are indented to the same
1097 level as the code which follows them. This is the default behavior, but
1098 you may use B<-nibc> to keep block comments left-justified. Here is an
1101 # this comment is indented (-ibc, default)
1102 if ($task) { yyy(); }
1104 The alternative is B<-nibc>:
1106 # this comment is not indented (-nibc)
1107 if ($task) { yyy(); }
1109 See also the next item, B<-isbc>, as well as B<-sbc>, for other ways to
1110 have some indented and some outdented block comments.
1112 =item B<-isbc>, B<--indent-spaced-block-comments>
1114 If there is no leading space on the line, then the comment will not be
1115 indented, and otherwise it may be.
1117 If both B<-ibc> and B<-isbc> are set, then B<-isbc> takes priority.
1119 =item B<-olc>, B<--outdent-long-comments>
1121 When B<-olc> is set, lines which are full-line (block) comments longer
1122 than the value B<maximum-line-length> will have their indentation
1123 removed. This is the default; use B<-nolc> to prevent outdenting.
1125 =item B<-msc=n>, B<--minimum-space-to-comment=n>
1127 Side comments look best when lined up several spaces to the right of
1128 code. Perltidy will try to keep comments at least n spaces to the
1129 right. The default is n=4 spaces.
1131 =item B<-fpsc=n>, B<--fixed-position-side-comment=n>
1133 This parameter tells perltidy to line up side comments in column number B<n>
1134 whenever possible. The default, n=0, will not do this.
1136 =item B<-iscl>, B<--ignore-side-comment-lengths>
1138 This parameter causes perltidy to ignore the length of side comments when
1139 setting line breaks. The default, B<-niscl>, is to include the length of
1140 side comments when breaking lines to stay within the length prescribed
1141 by the B<-l=n> maximum line length parameter. For example, the following
1142 long single line would remain intact with -l=80 and -iscl:
1144 perltidy -l=80 -iscl
1145 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1147 whereas without the -iscl flag the line will be broken:
1150 $vmsfile =~ s/;[\d\-]*$//
1151 ; # Clip off version number; we can use a newer version as well
1154 =item B<-hsc>, B<--hanging-side-comments>
1156 By default, perltidy tries to identify and align "hanging side
1157 comments", which are something like this:
1159 my $IGNORE = 0; # This is a side comment
1160 # This is a hanging side comment
1163 A comment is considered to be a hanging side comment if (1) it immediately
1164 follows a line with a side comment, or another hanging side comment, and
1165 (2) there is some leading whitespace on the line.
1166 To deactivate this feature, use B<-nhsc> or B<--nohanging-side-comments>.
1167 If block comments are preceded by a blank line, or have no leading
1168 whitespace, they will not be mistaken as hanging side comments.
1170 =item Closing Side Comments
1172 A closing side comment is a special comment which perltidy can
1173 automatically create and place after the closing brace of a code block.
1174 They can be useful for code maintenance and debugging. The command
1175 B<-csc> (or B<--closing-side-comments>) adds or updates closing side
1176 comments. For example, here is a small code snippet
1179 if ( !defined( $_[0] ) ) {
1180 print("Hello, World\n");
1183 print( $_[0], "\n" );
1187 And here is the result of processing with C<perltidy -csc>:
1190 if ( !defined( $_[0] ) ) {
1191 print("Hello, World\n");
1194 print( $_[0], "\n" );
1196 } ## end sub message
1198 A closing side comment was added for C<sub message> in this case, but not
1199 for the C<if> and C<else> blocks, because they were below the 6 line
1200 cutoff limit for adding closing side comments. This limit may be
1201 changed with the B<-csci> command, described below.
1203 The command B<-dcsc> (or B<--delete-closing-side-comments>) reverses this
1204 process and removes these comments.
1206 Several commands are available to modify the behavior of these two basic
1207 commands, B<-csc> and B<-dcsc>:
1211 =item B<-csci=n>, or B<--closing-side-comment-interval=n>
1213 where C<n> is the minimum number of lines that a block must have in
1214 order for a closing side comment to be added. The default value is
1215 C<n=6>. To illustrate:
1217 # perltidy -csci=2 -csc
1219 if ( !defined( $_[0] ) ) {
1220 print("Hello, World\n");
1221 } ## end if ( !defined( $_[0] ))
1223 print( $_[0], "\n" );
1224 } ## end else [ if ( !defined( $_[0] ))
1225 } ## end sub message
1227 Now the C<if> and C<else> blocks are commented. However, now this has
1228 become very cluttered.
1230 =item B<-cscp=string>, or B<--closing-side-comment-prefix=string>
1232 where string is the prefix used before the name of the block type. The
1233 default prefix, shown above, is C<## end>. This string will be added to
1234 closing side comments, and it will also be used to recognize them in
1235 order to update, delete, and format them. Any comment identified as a
1236 closing side comment will be placed just a single space to the right of
1239 =item B<-cscl=string>, or B<--closing-side-comment-list>
1241 where C<string> is a list of block types to be tagged with closing side
1242 comments. By default, all code block types preceded by a keyword or
1243 label (such as C<if>, C<sub>, and so on) will be tagged. The B<-cscl>
1244 command changes the default list to be any selected block types; see
1245 L<Specifying Block Types>.
1246 For example, the following command
1247 requests that only C<sub>'s, labels, C<BEGIN>, and C<END> blocks be
1248 affected by any B<-csc> or B<-dcsc> operation:
1250 -cscl="sub : BEGIN END"
1252 =item B<-csct=n>, or B<--closing-side-comment-maximum-text=n>
1254 The text appended to certain block types, such as an C<if> block, is
1255 whatever lies between the keyword introducing the block, such as C<if>,
1256 and the opening brace. Since this might be too much text for a side
1257 comment, there needs to be a limit, and that is the purpose of this
1258 parameter. The default value is C<n=20>, meaning that no additional
1259 tokens will be appended to this text after its length reaches 20
1260 characters. Omitted text is indicated with C<...>. (Tokens, including
1261 sub names, are never truncated, however, so actual lengths may exceed
1262 this). To illustrate, in the above example, the appended text of the
1263 first block is C< ( !defined( $_[0] )...>. The existing limit of
1264 C<n=20> caused this text to be truncated, as indicated by the C<...>. See
1265 the next flag for additional control of the abbreviated text.
1267 =item B<-cscb>, or B<--closing-side-comments-balanced>
1269 As discussed in the previous item, when the
1270 closing-side-comment-maximum-text limit is exceeded the comment text must
1271 be truncated. Older versions of perltidy terminated with three dots, and this
1272 can still be achieved with -ncscb:
1274 perltidy -csc -ncscb
1275 } ## end foreach my $foo (sort { $b cmp $a ...
1277 However this causes a problem with editors which cannot recognize
1278 comments or are not configured to do so because they cannot "bounce" around in
1279 the text correctly. The B<-cscb> flag has been added to
1280 help them by appending appropriate balancing structure:
1283 } ## end foreach my $foo (sort { $b cmp $a ... })
1285 The default is B<-cscb>.
1287 =item B<-csce=n>, or B<--closing-side-comment-else-flag=n>
1289 The default, B<n=0>, places the text of the opening C<if> statement after any
1292 If B<n=2> is used, then each C<elsif> is also given the text of the opening
1293 C<if> statement. Also, an C<else> will include the text of a preceding
1294 C<elsif> statement. Note that this may result some long closing
1297 If B<n=1> is used, the results will be the same as B<n=2> whenever the
1298 resulting line length is less than the maximum allowed.
1300 =item B<-cscb>, or B<--closing-side-comments-balanced>
1302 When using closing-side-comments, and the closing-side-comment-maximum-text
1303 limit is exceeded, then the comment text must be abbreviated.
1304 It is terminated with three dots if the B<-cscb> flag is negated:
1306 perltidy -csc -ncscb
1307 } ## end foreach my $foo (sort { $b cmp $a ...
1309 This causes a problem with older editors which do not recognize comments
1310 because they cannot "bounce" around in the text correctly. The B<-cscb>
1311 flag tries to help them by appending appropriate terminal balancing structures:
1314 } ## end foreach my $foo (sort { $b cmp $a ... })
1316 The default is B<-cscb>.
1319 =item B<-cscw>, or B<--closing-side-comment-warnings>
1321 This parameter is intended to help make the initial transition to the use of
1322 closing side comments.
1324 things to happen if a closing side comment replaces an existing, different
1325 closing side comment: first, an error message will be issued, and second, the
1326 original side comment will be placed alone on a new specially marked comment
1327 line for later attention.
1329 The intent is to avoid clobbering existing hand-written side comments
1330 which happen to match the pattern of closing side comments. This flag
1331 should only be needed on the first run with B<-csc>.
1335 B<Important Notes on Closing Side Comments:>
1341 Closing side comments are only placed on lines terminated with a closing
1342 brace. Certain closing styles, such as the use of cuddled elses
1343 (B<-ce>), preclude the generation of some closing side comments.
1347 Please note that adding or deleting of closing side comments takes
1348 place only through the commands B<-csc> or B<-dcsc>. The other commands,
1349 if used, merely modify the behavior of these two commands.
1353 It is recommended that the B<-cscw> flag be used along with B<-csc> on
1354 the first use of perltidy on a given file. This will prevent loss of
1355 any existing side comment data which happens to have the csc prefix.
1359 Once you use B<-csc>, you should continue to use it so that any
1360 closing side comments remain correct as code changes. Otherwise, these
1361 comments will become incorrect as the code is updated.
1365 If you edit the closing side comments generated by perltidy, you must also
1366 change the prefix to be different from the closing side comment prefix.
1367 Otherwise, your edits will be lost when you rerun perltidy with B<-csc>. For
1368 example, you could simply change C<## end> to be C<## End>, since the test is
1369 case sensitive. You may also want to use the B<-ssc> flag to keep these
1370 modified closing side comments spaced the same as actual closing side comments.
1374 Temporarily generating closing side comments is a useful technique for
1375 exploring and/or debugging a perl script, especially one written by someone
1376 else. You can always remove them with B<-dcsc>.
1380 =item Static Block Comments
1382 Static block comments are block comments with a special leading pattern,
1383 C<##> by default, which will be treated slightly differently from other
1384 block comments. They effectively behave as if they had glue along their
1385 left and top edges, because they stick to the left edge and previous line
1386 when there is no blank spaces in those places. This option is
1387 particularly useful for controlling how commented code is displayed.
1391 =item B<-sbc>, B<--static-block-comments>
1393 When B<-sbc> is used, a block comment with a special leading pattern, C<##> by
1394 default, will be treated specially.
1396 Comments so identified are treated as follows:
1402 If there is no leading space on the line, then the comment will not
1403 be indented, and otherwise it may be,
1407 no new blank line will be
1408 inserted before such a comment, and
1412 such a comment will never become
1413 a hanging side comment.
1417 For example, assuming C<@month_of_year> is
1420 @month_of_year = ( # -sbc (default)
1421 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1425 Without this convention, the above code would become
1427 @month_of_year = ( # -nsbc
1428 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1434 which is not as clear.
1435 The default is to use B<-sbc>. This may be deactivated with B<-nsbc>.
1437 =item B<-sbcp=string>, B<--static-block-comment-prefix=string>
1439 This parameter defines the prefix used to identify static block comments
1440 when the B<-sbc> parameter is set. The default prefix is C<##>,
1441 corresponding to C<-sbcp=##>. The prefix is actually part of a perl
1442 pattern used to match lines and it must either begin with C<#> or C<^#>.
1443 In the first case a prefix ^\s* will be added to match any leading
1444 whitespace, while in the second case the pattern will match only
1445 comments with no leading whitespace. For example, to
1446 identify all comments as static block comments, one would use C<-sbcp=#>.
1447 To identify all left-adjusted comments as static block comments, use C<-sbcp='^#'>.
1449 Please note that B<-sbcp> merely defines the pattern used to identify static
1450 block comments; it will not be used unless the switch B<-sbc> is set. Also,
1451 please be aware that since this string is used in a perl regular expression
1452 which identifies these comments, it must enable a valid regular expression to
1455 A pattern which can be useful is:
1459 This pattern requires a static block comment to have at least one character
1460 which is neither a # nor a space. It allows a line containing only '#'
1461 characters to be rejected as a static block comment. Such lines are often used
1462 at the start and end of header information in subroutines and should not be
1463 separated from the intervening comments, which typically begin with just a
1466 =item B<-osbc>, B<--outdent-static-block-comments>
1468 The command B<-osbc> will cause static block comments to be outdented by 2
1469 spaces (or whatever B<-ci=n> has been set to), if possible.
1473 =item Static Side Comments
1475 Static side comments are side comments with a special leading pattern.
1476 This option can be useful for controlling how commented code is displayed
1477 when it is a side comment.
1481 =item B<-ssc>, B<--static-side-comments>
1483 When B<-ssc> is used, a side comment with a static leading pattern, which is
1484 C<##> by default, will be spaced only a single space from previous
1485 character, and it will not be vertically aligned with other side comments.
1487 The default is B<-nssc>.
1489 =item B<-sscp=string>, B<--static-side-comment-prefix=string>
1491 This parameter defines the prefix used to identify static side comments
1492 when the B<-ssc> parameter is set. The default prefix is C<##>,
1493 corresponding to C<-sscp=##>.
1495 Please note that B<-sscp> merely defines the pattern used to identify
1496 static side comments; it will not be used unless the switch B<-ssc> is
1497 set. Also, note that this string is used in a perl regular expression
1498 which identifies these comments, so it must enable a valid regular
1499 expression to be formed.
1506 =head2 Skipping Selected Sections of Code
1508 Selected lines of code may be passed verbatim to the output without any
1509 formatting. This feature is enabled by default but can be disabled with
1510 the B<--noformat-skipping> or B<-nfs> flag. It should be used sparingly to
1511 avoid littering code with markers, but it might be helpful for working
1512 around occasional problems. For example it might be useful for keeping
1513 the indentation of old commented code unchanged, keeping indentation of
1514 long blocks of aligned comments unchanged, keeping certain list
1515 formatting unchanged, or working around a glitch in perltidy.
1519 =item B<-fs>, B<--format-skipping>
1521 This flag, which is enabled by default, causes any code between
1522 special beginning and ending comment markers to be passed to the
1523 output without formatting. The default beginning marker is #<<<
1524 and the default ending marker is #>>> but they
1525 may be changed (see next items below). Additional text may appear on
1526 these special comment lines provided that it is separated from the
1527 marker by at least one space. For example
1529 #<<< do not let perltidy touch this
1537 The comment markers may be placed at any location that a block comment may
1538 appear. If they do not appear to be working, use the -log flag and examine the
1539 F<.LOG> file. Use B<-nfs> to disable this feature.
1541 =item B<-fsb=string>, B<--format-skipping-begin=string>
1543 The B<-fsb=string> parameter may be used to change the beginning marker for
1544 format skipping. The default is equivalent to -fsb='#<<<'. The string that
1545 you enter must begin with a # and should be in quotes as necessary to get past
1546 the command shell of your system. It is actually the leading text of a pattern
1547 that is constructed by appending a '\s', so you must also include backslashes
1548 for characters to be taken literally rather than as patterns.
1550 Some examples show how example strings become patterns:
1552 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1553 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1554 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1556 =item B<-fse=string>, B<--format-skipping-end=string>
1558 The B<-fsb=string> is the corresponding parameter used to change the
1559 ending marker for format skipping. The default is equivalent to
1564 =head2 Line Break Control
1566 The parameters in this section control breaks after
1567 non-blank lines of code. Blank lines are controlled
1568 separately by parameters in the section L<Blank Line
1573 =item B<-fnl>, B<--freeze-newlines>
1575 If you do not want any changes to the line breaks within
1576 lines of code in your script, set
1577 B<-fnl>, and they will remain fixed, and the rest of the commands in
1578 this section and sections
1579 L<Controlling List Formatting>,
1580 L<Retaining or Ignoring Existing Line Breaks>.
1581 You may want to use B<-noll> with this.
1583 Note: If you also want to keep your blank lines exactly
1584 as they are, you can use the B<-fbl> flag which is described
1585 in the section L<Blank Line Control>.
1587 =item B<-ce>, B<--cuddled-else>
1589 Enable the "cuddled else" style, in which C<else> and C<elsif> are
1590 follow immediately after the curly brace closing the previous block.
1591 The default is not to use cuddled elses, and is indicated with the flag
1592 B<-nce> or B<--nocuddled-else>. Here is a comparison of the
1610 In this example the keyword B<else> is placed on the same line which begins with
1611 the preceding closing block brace and is followed by its own opening block brace
1612 on the same line. Other keywords and function names which are formatted with
1613 this "cuddled" style are B<elsif>, B<continue>, B<catch>, B<finally>.
1615 Other block types can be formatted by specifying their names on a
1616 separate parameter B<-cbl>, described in a later section.
1618 Cuddling between a pair of code blocks requires that the closing brace of the
1619 first block start a new line. If this block is entirely on one line in the
1620 input file, it is necessary to decide if it should be broken to allow cuddling.
1621 This decision is controlled by the flag B<-cbo=n> discussed below. The default
1622 and recommended value of B<-cbo=1> bases this decision on the first block in
1623 the chain. If it spans multiple lines then cuddling is made and continues
1624 along the chain, regardless of the sizes of subsequent blocks. Otherwise, short
1625 lines remain intact.
1627 So for example, the B<-ce> flag would not have any effect if the above snippet
1630 if ($task) { yyy() }
1633 If the first block spans multiple lines, then cuddling can be done and will
1634 continue for the subsequent blocks in the chain, as illustrated in the previous
1637 If there are blank lines between cuddled blocks they will be eliminated. If
1638 there are comments after the closing brace where cuddling would occur then
1639 cuddling will be prevented. If this occurs, cuddling will restart later in the
1642 =item B<-cb>, B<--cuddled-blocks>
1644 This flag is equivalent to B<-ce>.
1647 =item B<-cbl>, B<--cuddled-block-list>
1649 The built-in default cuddled block types are B<else, elsif, continue, catch, finally>.
1651 Additional block types to which the B<-cuddled-blocks> style applies can be defined by
1652 this parameter. This parameter is a character string, giving a list of
1653 block types separated by commas or spaces. For example, to cuddle code blocks
1654 of type sort, map and grep, in addition to the default types, the string could
1657 -cbl="sort map grep"
1663 Note however that these particular block types are typically short so there might not be much
1664 opportunity for the cuddled format style.
1666 Using commas avoids the need to protect spaces with quotes.
1668 As a diagnostic check, the flag B<--dump-cuddled-block-list> or B<-dcbl> can be
1669 used to view the hash of values that are generated by this flag.
1671 Finally, note that the B<-cbl> flag by itself merely specifies which blocks are formatted
1672 with the cuddled format. It has no effect unless this formatting style is activated with
1675 =item B<-cblx>, B<--cuddled-block-list-exclusive>
1677 When cuddled else formatting is selected with B<-ce>, setting this flag causes
1678 perltidy to ignore its built-in defaults and rely exclusively on the block types
1679 specified on the B<-cbl> flag described in the previous section. For example,
1680 to avoid using cuddled B<catch> and B<finally>, which among in the defaults, the
1681 following set of parameters could be used:
1683 perltidy -ce -cbl='else elsif continue' -cblx
1686 =item B<-cbo=n>, B<--cuddled-break-option=n>
1688 Cuddled formatting is only possible between a pair of code blocks if the
1689 closing brace of the first block starts a new line. If a block is encountered
1690 which is entirely on a single line, and cuddled formatting is selected, it is
1691 necessary to make a decision as to whether or not to "break" the block, meaning
1692 to cause it to span multiple lines. This parameter controls that decision. The
1695 cbo=0 Never force a short block to break.
1696 cbo=1 If the first of a pair of blocks is broken in the input file,
1697 then break the second [DEFAULT].
1698 cbo=2 Break open all blocks for maximal cuddled formatting.
1700 The default and recommended value is B<cbo=1>. With this value, if the starting
1701 block of a chain spans multiple lines, then a cascade of breaks will occur for
1702 remaining blocks causing the entire chain to be cuddled.
1704 The option B<cbo=0> can produce erratic cuddling if there are numerous one-line
1707 The option B<cbo=2> produces maximal cuddling but will not allow any short blocks.
1710 =item B<-bl>, B<--opening-brace-on-new-line>
1712 Use the flag B<-bl> to place the opening brace on a new line:
1714 if ( $input_file eq '-' ) # -bl
1716 important_function();
1719 This flag applies to all structural blocks, including named sub's (unless
1720 the B<-sbl> flag is set -- see next item).
1722 The default style, B<-nbl>, places an opening brace on the same line as
1723 the keyword introducing it. For example,
1725 if ( $input_file eq '-' ) { # -nbl (default)
1727 =item B<-sbl>, B<--opening-sub-brace-on-new-line>
1729 The flag B<-sbl> can be used to override the value of B<-bl> for
1730 the opening braces of named sub's. For example,
1734 produces this result:
1738 if (!defined($_[0])) {
1739 print("Hello, World\n");
1746 This flag is negated with B<-nsbl>. If B<-sbl> is not specified,
1747 the value of B<-bl> is used.
1749 =item B<-asbl>, B<--opening-anonymous-sub-brace-on-new-line>
1751 The flag B<-asbl> is like the B<-sbl> flag except that it applies
1752 to anonymous sub's instead of named subs. For example
1756 produces this result:
1760 if ( !defined( $_[0] ) ) {
1761 print("Hello, World\n");
1764 print( $_[0], "\n" );
1768 This flag is negated with B<-nasbl>, and the default is B<-nasbl>.
1770 =item B<-bli>, B<--brace-left-and-indent>
1772 The flag B<-bli> is the same as B<-bl> but in addition it causes one
1773 unit of continuation indentation ( see B<-ci> ) to be placed before
1774 an opening and closing block braces.
1778 if ( $input_file eq '-' ) # -bli
1780 important_function();
1783 By default, this extra indentation occurs for blocks of type:
1784 B<if>, B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>,
1785 B<while>, B<until>, and also with a preceding label. The next item
1786 shows how to change this.
1788 =item B<-blil=s>, B<--brace-left-and-indent-list=s>
1790 Use this parameter to change the types of block braces for which the
1791 B<-bli> flag applies; see L<Specifying Block Types>. For example,
1792 B<-blil='if elsif else'> would apply it to only C<if/elsif/else> blocks.
1794 =item B<-bar>, B<--opening-brace-always-on-right>
1796 The default style, B<-nbl> places the opening code block brace on a new
1797 line if it does not fit on the same line as the opening keyword, like
1800 if ( $bigwasteofspace1 && $bigwasteofspace2
1801 || $bigwasteofspace3 && $bigwasteofspace4 )
1803 big_waste_of_time();
1806 To force the opening brace to always be on the right, use the B<-bar>
1807 flag. In this case, the above example becomes
1809 if ( $bigwasteofspace1 && $bigwasteofspace2
1810 || $bigwasteofspace3 && $bigwasteofspace4 ) {
1811 big_waste_of_time();
1814 A conflict occurs if both B<-bl> and B<-bar> are specified.
1816 =item B<-otr>, B<--opening-token-right> and related flags
1818 The B<-otr> flag is a hint that perltidy should not place a break between a
1819 comma and an opening token. For example:
1821 # default formatting
1822 push @{ $self->{$module}{$key} },
1824 accno => $ref->{accno},
1825 description => $ref->{description}
1829 push @{ $self->{$module}{$key} }, {
1830 accno => $ref->{accno},
1831 description => $ref->{description}
1834 The flag B<-otr> is actually an abbreviation for three other flags
1835 which can be used to control parens, hash braces, and square brackets
1836 separately if desired:
1838 -opr or --opening-paren-right
1839 -ohbr or --opening-hash-brace-right
1840 -osbr or --opening-square-bracket-right
1842 =item B<-wn>, B<--weld-nested-containers>
1844 The B<-wn> flag causes closely nested pairs of opening and closing container
1845 symbols (curly braces, brackets, or parens) to be "welded" together, meaning
1846 that they are treated as if combined into a single unit, with the indentation
1847 of the innermost code reduced to be as if there were just a single container
1852 # default formatting
1862 } } until $x++ > $z;
1864 When this flag is set perltidy makes a preliminary pass through the file and
1865 identifies all nested pairs of containers. To qualify as a nested pair, the
1866 closing container symbols must be immediately adjacent. The opening symbols
1867 must either be adjacent, or, if the outer opening symbol is an opening
1868 paren, they may be separated by any single non-container symbol or something
1869 that looks like a function evaluation.
1871 Any container symbol may serve as both the inner container of one pair and as
1872 the outer container of an adjacent pair. Consequently, any number of adjacent
1873 opening or closing symbols may join together in weld. For example, here are
1874 three levels of wrapped function calls:
1876 # default formatting
1877 my (@date_time) = Localtime(
1880 $year, $month, $day, $hour, $minute, $second,
1881 '0', $offset, '0', '0'
1887 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
1888 $year, $month, $day, $hour, $minute, $second,
1889 '0', $offset, '0', '0'
1892 Notice how the indentation of the inner lines are reduced by two levels in this
1893 case. This example also shows the typical result of this formatting, namely it
1894 is a sandwich consisting of an initial opening layer, a central section of any
1895 complexity forming the "meat" of the sandwich, and a final closing layer. This
1896 predictable structure helps keep the compacted structure readable.
1898 The inner sandwich layer is required to be at least one line thick. If this
1899 cannot be achieved, welding does not occur. This constraint can cause
1900 formatting to take a couple of iterations to stabilize when it is first applied
1901 to a script. The B<-conv> flag can be used to insure that the final format is
1902 achieved in a single run.
1904 Here is an example illustrating a welded container within a welded containers:
1906 # default formatting
1911 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1921 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
1926 This format option is quite general but there are some limitations.
1928 One limitation is that any line length limit still applies and can cause long
1929 welded sections to be broken into multiple lines.
1931 Another limitation is that an opening symbol which delimits quoted text cannot
1932 be included in a welded pair. This is because quote delimiters are treated
1933 specially in perltidy.
1935 Finally, the stacking of containers defined by this flag have priority over
1936 any other container stacking flags. This is because any welding is done first.
1939 =item B<Vertical tightness> of non-block curly braces, parentheses, and square brackets.
1941 These parameters control what shall be called vertical tightness. Here are the
1948 Opening tokens (except for block braces) are controlled by B<-vt=n>, or
1949 B<--vertical-tightness=n>, where
1951 -vt=0 always break a line after opening token (default).
1952 -vt=1 do not break unless this would produce more than one
1953 step in indentation in a line.
1954 -vt=2 never break a line after opening token
1958 You must also use the B<-lp> flag when you use the B<-vt> flag; the
1959 reason is explained below.
1963 Closing tokens (except for block braces) are controlled by B<-vtc=n>, or
1964 B<--vertical-tightness-closing=n>, where
1966 -vtc=0 always break a line before a closing token (default),
1967 -vtc=1 do not break before a closing token which is followed
1968 by a semicolon or another closing token, and is not in
1970 -vtc=2 never break before a closing token.
1972 The rules for B<-vtc=1> are designed to maintain a reasonable balance
1973 between tightness and readability in complex lists.
1977 Different controls may be applied to different token types,
1978 and it is also possible to control block braces; see below.
1982 Finally, please note that these vertical tightness flags are merely
1983 hints to the formatter, and it cannot always follow them. Things which
1984 make it difficult or impossible include comments, blank lines, blocks of
1985 code within a list, and possibly the lack of the B<-lp> parameter.
1986 Also, these flags may be ignored for very small lists (2 or 3 lines in
1991 Here are some examples:
1993 # perltidy -lp -vt=0 -vtc=0
2001 # perltidy -lp -vt=1 -vtc=0
2002 %romanNumerals = ( one => 'I',
2008 # perltidy -lp -vt=1 -vtc=1
2009 %romanNumerals = ( one => 'I',
2014 The difference between B<-vt=1> and B<-vt=2> is shown here:
2016 # perltidy -lp -vt=1
2018 mysprintf( "(void)find_threadsv(%s);",
2019 cstring( $threadsv_names[ $op->targ ] )
2023 # perltidy -lp -vt=2
2024 $init->add( mysprintf( "(void)find_threadsv(%s);",
2025 cstring( $threadsv_names[ $op->targ ] )
2029 With B<-vt=1>, the line ending in C<add(> does not combine with the next
2030 line because the next line is not balanced. This can help with
2031 readability, but B<-vt=2> can be used to ignore this rule.
2033 The tightest, and least readable, code is produced with both C<-vt=2> and
2036 # perltidy -lp -vt=2 -vtc=2
2037 $init->add( mysprintf( "(void)find_threadsv(%s);",
2038 cstring( $threadsv_names[ $op->targ ] ) ) );
2040 Notice how the code in all of these examples collapses vertically as
2041 B<-vt> increases, but the indentation remains unchanged. This is
2042 because perltidy implements the B<-vt> parameter by first formatting as
2043 if B<-vt=0>, and then simply overwriting one output line on top of the
2044 next, if possible, to achieve the desired vertical tightness. The
2045 B<-lp> indentation style has been designed to allow this vertical
2046 collapse to occur, which is why it is required for the B<-vt> parameter.
2048 The B<-vt=n> and B<-vtc=n> parameters apply to each type of container
2049 token. If desired, vertical tightness controls can be applied
2050 independently to each of the closing container token types.
2052 The parameters for controlling parentheses are B<-pvt=n> or
2053 B<--paren-vertical-tightness=n>, and B<-pcvt=n> or
2054 B<--paren-vertical-tightness-closing=n>.
2056 Likewise, the parameters for square brackets are B<-sbvt=n> or
2057 B<--square-bracket-vertical-tightness=n>, and B<-sbcvt=n> or
2058 B<--square-bracket-vertical-tightness-closing=n>.
2060 Finally, the parameters for controlling non-code block braces are
2061 B<-bvt=n> or B<--brace-vertical-tightness=n>, and B<-bcvt=n> or
2062 B<--brace-vertical-tightness-closing=n>.
2064 In fact, the parameter B<-vt=n> is actually just an abbreviation for
2065 B<-pvt=n -bvt=n sbvt=n>, and likewise B<-vtc=n> is an abbreviation
2066 for B<-pvtc=n -bvtc=n sbvtc=n>.
2068 =item B<-bbvt=n> or B<--block-brace-vertical-tightness=n>
2070 The B<-bbvt=n> flag is just like the B<-vt=n> flag but applies
2071 to opening code block braces.
2073 -bbvt=0 break after opening block brace (default).
2074 -bbvt=1 do not break unless this would produce more than one
2075 step in indentation in a line.
2076 -bbvt=2 do not break after opening block brace.
2078 It is necessary to also use either B<-bl> or B<-bli> for this to work,
2079 because, as with other vertical tightness controls, it is implemented by
2080 simply overwriting a line ending with an opening block brace with the
2081 subsequent line. For example:
2083 # perltidy -bli -bbvt=0
2084 if ( open( FILE, "< $File" ) )
2086 while ( $File = <FILE> )
2094 # perltidy -bli -bbvt=1
2095 if ( open( FILE, "< $File" ) )
2096 { while ( $File = <FILE> )
2103 By default this applies to blocks associated with keywords B<if>,
2104 B<elsif>, B<else>, B<unless>, B<for>, B<foreach>, B<sub>, B<while>,
2105 B<until>, and also with a preceding label. This can be changed with
2106 the parameter B<-bbvtl=string>, or
2107 B<--block-brace-vertical-tightness-list=string>, where B<string> is a
2108 space-separated list of block types. For more information on the
2109 possible values of this string, see L<Specifying Block Types>
2111 For example, if we want to just apply this style to C<if>,
2112 C<elsif>, and C<else> blocks, we could use
2113 C<perltidy -bli -bbvt=1 -bbvtl='if elsif else'>.
2115 There is no vertical tightness control for closing block braces; with
2116 one exception they will be placed on separate lines.
2117 The exception is that a cascade of closing block braces may
2118 be stacked on a single line. See B<-scbb>.
2120 =item B<-sot>, B<--stack-opening-tokens> and related flags
2122 The B<-sot> flag tells perltidy to "stack" opening tokens
2123 when possible to avoid lines with isolated opening tokens.
2128 $opt_c = Text::CSV_XS->new(
2137 $opt_c = Text::CSV_XS->new( {
2144 For detailed control of individual closing tokens the following
2145 controls can be used:
2147 -sop or --stack-opening-paren
2148 -sohb or --stack-opening-hash-brace
2149 -sosb or --stack-opening-square-bracket
2150 -sobb or --stack-opening-block-brace
2152 The flag B<-sot> is an abbreviation for B<-sop -sohb -sosb>.
2154 The flag B<-sobb> is an abbreviation for B<-bbvt=2 -bbvtl='*'>. This
2155 will case a cascade of opening block braces to appear on a single line,
2156 although this an uncommon occurrence except in test scripts.
2158 =item B<-sct>, B<--stack-closing-tokens> and related flags
2160 The B<-sct> flag tells perltidy to "stack" closing tokens
2161 when possible to avoid lines with isolated closing tokens.
2166 $opt_c = Text::CSV_XS->new(
2175 $opt_c = Text::CSV_XS->new(
2182 The B<-sct> flag is somewhat similar to the B<-vtc> flags, and in some
2183 cases it can give a similar result. The difference is that the B<-vtc>
2184 flags try to avoid lines with leading opening tokens by "hiding" them at
2185 the end of a previous line, whereas the B<-sct> flag merely tries to
2186 reduce the number of lines with isolated closing tokens by stacking them
2187 but does not try to hide them. For example:
2190 $opt_c = Text::CSV_XS->new(
2194 always_quote => 1, } );
2196 For detailed control of the stacking of individual closing tokens the
2197 following controls can be used:
2199 -scp or --stack-closing-paren
2200 -schb or --stack-closing-hash-brace
2201 -scsb or --stack-closing-square-bracket
2202 -scbb or --stack-closing-block-brace
2204 The flag B<-sct> is an abbreviation for stacking the non-block closing
2205 tokens, B<-scp -schb -scsb>.
2207 Stacking of closing block braces, B<-scbb>, causes a cascade of isolated
2208 closing block braces to be combined into a single line as in the following
2216 push( @lines, "$w1 $w2 $w3 $w4\n" );
2219 To simplify input even further for the case in which both opening and closing
2220 non-block containers are stacked, the flag B<-sac> or B<--stack-all-containers>
2221 is an abbreviation for B<-sot -sot>.
2223 =item B<-dnl>, B<--delete-old-newlines>
2225 By default, perltidy first deletes all old line break locations, and then it
2226 looks for good break points to match the desired line length. Use B<-ndnl>
2227 or B<--nodelete-old-newlines> to force perltidy to retain all old line break
2230 =item B<-anl>, B<--add-newlines>
2232 By default, perltidy will add line breaks when necessary to create
2233 continuations of long lines and to improve the script appearance. Use
2234 B<-nanl> or B<--noadd-newlines> to prevent any new line breaks.
2236 This flag does not prevent perltidy from eliminating existing line
2237 breaks; see B<--freeze-newlines> to completely prevent changes to line
2240 =item Controlling whether perltidy breaks before or after operators
2242 Four command line parameters provide some control over whether
2243 a line break should be before or after specific token types.
2244 Two parameters give detailed control:
2246 B<-wba=s> or B<--want-break-after=s>, and
2248 B<-wbb=s> or B<--want-break-before=s>.
2250 These parameters are each followed by a quoted string, B<s>, containing
2251 a list of token types (separated only by spaces). No more than one of each
2252 of these parameters should be specified, because repeating a
2253 command-line parameter always overwrites the previous one before
2254 perltidy ever sees it.
2256 By default, perltidy breaks B<after> these token types:
2257 % + - * / x != == >= <= =~ !~ < > | &
2258 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2260 And perltidy breaks B<before> these token types by default:
2263 To illustrate, to cause a break after a concatenation operator, C<'.'>,
2264 rather than before it, the command line would be
2268 As another example, the following command would cause a break before
2269 math operators C<'+'>, C<'-'>, C<'/'>, and C<'*'>:
2273 These commands should work well for most of the token types that perltidy uses
2274 (use B<--dump-token-types> for a list). Also try the B<-D> flag on a short
2275 snippet of code and look at the .DEBUG file to see the tokenization. However,
2276 for a few token types there may be conflicts with hardwired logic which cause
2277 unexpected results. One example is curly braces, which should be controlled
2278 with the parameter B<bl> provided for that purpose.
2280 B<WARNING> Be sure to put these tokens in quotes to avoid having them
2281 misinterpreted by your command shell.
2283 Two additional parameters are available which, though they provide no further
2284 capability, can simplify input are:
2286 B<-baao> or B<--break-after-all-operators>,
2288 B<-bbao> or B<--break-before-all-operators>.
2290 The -baao sets the default to be to break after all of the following operators:
2292 % + - * / x != == >= <= =~ !~ < > | &
2293 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2294 . : ? && || and or err xor
2296 and the B<-bbao> flag sets the default to break before all of these operators.
2297 These can be used to define an initial break preference which can be fine-tuned
2298 with the B<-wba> and B<-wbb> flags. For example, to break before all operators
2299 except an B<=> one could use --bbao -wba='=' rather than listing every
2300 single perl operator except B<=> on a -wbb flag.
2304 =head2 Controlling List Formatting
2306 Perltidy attempts to place comma-separated arrays of values in tables
2307 which look good. Its default algorithms usually work well, and they
2308 have been improving with each release, but several parameters are
2309 available to control list formatting.
2313 =item B<-boc>, B<--break-at-old-comma-breakpoints>
2315 This flag tells perltidy to try to break at all old commas. This is not
2316 the default. Normally, perltidy makes a best guess at list formatting,
2317 and seldom uses old comma breakpoints. Usually this works well,
2326 The default formatting will flatten this down to one line:
2328 # perltidy (default)
2329 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2331 which hides the structure. Using B<-boc>, plus additional flags
2332 to retain the original style, yields
2334 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2341 A disadvantage of this flag is that all tables in the file
2342 must already be nicely formatted. For another possibility see
2343 the -fs flag in L<Skipping Selected Sections of Code>.
2345 =item B<-mft=n>, B<--maximum-fields-per-table=n>
2347 If the computed number of fields for any table exceeds B<n>, then it
2348 will be reduced to B<n>. The default value for B<n> is a large number,
2349 40. While this value should probably be left unchanged as a general
2350 rule, it might be used on a small section of code to force a list to
2351 have a particular number of fields per line, and then either the B<-boc>
2352 flag could be used to retain this formatting, or a single comment could
2353 be introduced somewhere to freeze the formatting in future applications
2366 =item B<-cab=n>, B<--comma-arrow-breakpoints=n>
2368 A comma which follows a comma arrow, '=>', is given special
2369 consideration. In a long list, it is common to break at all such
2370 commas. This parameter can be used to control how perltidy breaks at
2371 these commas. (However, it will have no effect if old comma breaks are
2372 being forced because B<-boc> is used). The possible values of B<n> are:
2374 n=0 break at all commas after =>
2375 n=1 stable: break at all commas after => if container is open,
2376 EXCEPT FOR one-line containers
2377 n=2 break at all commas after =>, BUT try to form the maximum
2378 maximum one-line container lengths
2379 n=3 do not treat commas after => specially at all
2380 n=4 break everything: like n=0 but ALSO break a short container with
2381 a => not followed by a comma when -vt=0 is used
2382 n=5 stable: like n=1 but ALSO break at open one-line containers when
2383 -vt=0 is used (default)
2385 For example, given the following single line, perltidy by default will
2386 not add any line breaks because it would break the existing one-line
2389 bless { B => $B, Root => $Root } => $package;
2391 Using B<-cab=0> will force a break after each comma-arrow item:
2399 If perltidy is subsequently run with this container broken, then by
2400 default it will break after each '=>' because the container is now
2401 broken. To reform a one-line container, the parameter B<-cab=2> could
2404 The flag B<-cab=3> can be used to prevent these commas from being
2405 treated specially. In this case, an item such as "01" => 31 is
2406 treated as a single item in a table. The number of fields in this table
2407 will be determined by the same rules that are used for any other table.
2412 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
2413 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
2414 "09" => 30, "10" => 31, "11" => 30, "12" => 31
2419 =head2 Retaining or Ignoring Existing Line Breaks
2421 Several additional parameters are available for controlling the extent
2422 to which line breaks in the input script influence the output script.
2423 In most cases, the default parameter values are set so that, if a choice
2424 is possible, the output style follows the input style. For example, if
2425 a short logical container is broken in the input script, then the
2426 default behavior is for it to remain broken in the output script.
2428 Most of the parameters in this section would only be required for a
2429 one-time conversion of a script from short container lengths to longer
2430 container lengths. The opposite effect, of converting long container
2431 lengths to shorter lengths, can be obtained by temporarily using a short
2432 maximum line length.
2436 =item B<-bol>, B<--break-at-old-logical-breakpoints>
2438 By default, if a logical expression is broken at a C<&&>, C<||>, C<and>,
2439 or C<or>, then the container will remain broken. Also, breaks
2440 at internal keywords C<if> and C<unless> will normally be retained.
2441 To prevent this, and thus form longer lines, use B<-nbol>.
2443 =item B<-bom>, B<--break-at-old-method-breakpoints>
2445 By default, a method call arrow C<-E<gt>> is considered a candidate for
2446 a breakpoint, but method chains will fill to the line width before a break is
2447 considered. With B<-bom>, breaks before the arrow are preserved, so if you
2448 have preformatted a method chain:
2451 ->related_resultset('CDs')
2452 ->related_resultset('Tracks')
2454 'track.id' => {-ident => 'none_search.id'},
2457 It will B<keep> these breaks, rather than become this:
2459 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
2460 'track.id' => {-ident => 'none_search.id'},
2463 This flag will also look for and keep a 'cuddled' style of calls,
2464 in which lines begin with a closing paren followed by a call arrow,
2467 my $q = $rs->related_resultset(
2469 )->related_resultset(
2472 'track.id' => { -ident => 'none_search.id' },
2475 You may want to include the B<-weld-nested-containers> flag in this case to keep
2476 nested braces and parens together, as in the last line.
2479 =item B<-bok>, B<--break-at-old-keyword-breakpoints>
2481 By default, perltidy will retain a breakpoint before keywords which may
2482 return lists, such as C<sort> and <map>. This allows chains of these
2483 operators to be displayed one per line. Use B<-nbok> to prevent
2484 retaining these breakpoints.
2486 =item B<-bot>, B<--break-at-old-ternary-breakpoints>
2488 By default, if a conditional (ternary) operator is broken at a C<:>,
2489 then it will remain broken. To prevent this, and thereby
2490 form longer lines, use B<-nbot>.
2492 =item B<-boa>, B<--break-at-old-attribute-breakpoints>
2494 By default, if an attribute list is broken at a C<:> in the source file, then
2495 it will remain broken. For example, given the following code, the line breaks
2496 at the ':'s will be retained:
2501 : Get('Name' => 'foo') : Set('Name');
2503 If the attributes are on a single line in the source code then they will remain
2504 on a single line if possible.
2506 To prevent this, and thereby always form longer lines, use B<-nboa>.
2508 =item B<-iob>, B<--ignore-old-breakpoints>
2510 Use this flag to tell perltidy to ignore existing line breaks to the
2511 maximum extent possible. This will tend to produce the longest possible
2512 containers, regardless of type, which do not exceed the line length
2515 =item B<-kis>, B<--keep-interior-semicolons>
2517 Use the B<-kis> flag to prevent breaking at a semicolon if
2518 there was no break there in the input file. Normally
2519 perltidy places a newline after each semicolon which
2520 terminates a statement unless several statements are
2521 contained within a one-line brace block. To illustrate,
2522 consider the following input lines:
2524 dbmclose(%verb_delim); undef %verb_delim;
2525 dbmclose(%expanded); undef %expanded;
2527 The default is to break after each statement, giving
2529 dbmclose(%verb_delim);
2531 dbmclose(%expanded);
2534 With B<perltidy -kis> the multiple statements are retained:
2536 dbmclose(%verb_delim); undef %verb_delim;
2537 dbmclose(%expanded); undef %expanded;
2539 The statements are still subject to the specified value
2540 of B<maximum-line-length> and will be broken if this
2541 maximum is exceeded.
2545 =head2 Blank Line Control
2547 Blank lines can improve the readability of a script if they are carefully
2548 placed. Perltidy has several commands for controlling the insertion,
2549 retention, and removal of blank lines.
2553 =item B<-fbl>, B<--freeze-blank-lines>
2555 Set B<-fbl> if you want to the blank lines in your script to
2556 remain exactly as they are. The rest of the parameters in
2557 this section may then be ignored. (Note: setting the B<-fbl> flag
2558 is equivalent to setting B<-mbl=0> and B<-kbl=2>).
2560 =item B<-bbc>, B<--blanks-before-comments>
2562 A blank line will be introduced before a full-line comment. This is the
2563 default. Use B<-nbbc> or B<--noblanks-before-comments> to prevent
2564 such blank lines from being introduced.
2566 =item B<-blbs=n>, B<--blank-lines-before-subs=n>
2568 The parameter B<-blbs=n> requests that least B<n> blank lines precede a sub
2569 definition which does not follow a comment and which is more than one-line
2570 long. The default is <-blbs=1>. B<BEGIN> and B<END> blocks are included.
2572 The requested number of blanks statement will be inserted regardless of the
2573 value of B<--maximum-consecutive-blank-lines=n> (B<-mbl=n>) with the exception
2574 that if B<-mbl=0> then no blanks will be output.
2576 This parameter interacts with the value B<k> of the parameter B<--maximum-consecutive-blank-lines=k> (B<-mbl=k>) as follows:
2578 1. If B<-mbl=0> then no blanks will be output. This allows all blanks to be suppressed with a single parameter. Otherwise,
2580 2. If the number of old blank lines in the script is less than B<n> then
2581 additional blanks will be inserted to make the total B<n> regardless of the
2584 3. If the number of old blank lines in the script equals or exceeds B<n> then
2585 this parameter has no effect, however the total will not exceed
2586 value specified on the B<-mbl=k> flag.
2589 =item B<-blbp=n>, B<--blank-lines-before-packages=n>
2591 The parameter B<-blbp=n> requests that least B<n> blank lines precede a package
2592 which does not follow a comment. The default is B<-blbp=1>.
2594 This parameter interacts with the value B<k> of the parameter
2595 B<--maximum-consecutive-blank-lines=k> (B<-mbl=k>) in the same way as described
2596 for the previous item B<-blbs=n>.
2599 =item B<-bbs>, B<--blanks-before-subs>
2601 For compatibility with previous versions, B<-bbs> or B<--blanks-before-subs>
2602 is equivalent to F<-blbp=1> and F<-blbs=1>.
2604 Likewise, B<-nbbs> or B<--noblanks-before-subs>
2605 is equivalent to F<-blbp=0> and F<-blbs=0>.
2607 =item B<-bbb>, B<--blanks-before-blocks>
2609 A blank line will be introduced before blocks of coding delimited by
2610 B<for>, B<foreach>, B<while>, B<until>, and B<if>, B<unless>, in the following
2617 The block is not preceded by a comment.
2621 The block is not a one-line block.
2625 The number of consecutive non-blank lines at the current indentation depth is at least B<-lbl>
2630 This is the default. The intention of this option is to introduce
2631 some space within dense coding.
2632 This is negated with B<-nbbb> or B<--noblanks-before-blocks>.
2634 =item B<-lbl=n> B<--long-block-line-count=n>
2636 This controls how often perltidy is allowed to add blank lines before
2637 certain block types (see previous section). The default is 8. Entering
2638 a value of B<0> is equivalent to entering a very large number.
2640 =item B<-blao=i> or B<--blank-lines-after-opening-block=i>
2642 This control places a minimum of B<i> blank lines B<after> a line which B<ends>
2643 with an opening block brace of a specified type. By default, this only applies
2644 to the block of a named B<sub>, but this can be changed (see B<-blaol> below).
2645 The default is not to do this (B<i=0>).
2647 Please see the note below on using the B<-blao> and B<-blbc> options.
2649 =item B<-blbc=i> or B<--blank-lines-before-closing-block=i>
2651 This control places a minimum of B<i> blank lines B<before> a line which
2652 B<begins> with a closing block brace of a specified type. By default, this
2653 only applies to the block of a named B<sub>, but this can be changed (see
2654 B<-blbcl> below). The default is not to do this (B<i=0>).
2656 =item B<-blaol=s> or B<--blank-lines-after-opening-block-list=s>
2658 The parameter B<s> is a list of block type keywords to which the flag B<-blao>
2659 should apply. The section L<"Specifying Block Types"> explains how to list
2662 =item B<-blbcl=s> or B<--blank-lines-before-closing-block-list=s>
2664 This parameter is a list of block type keywords to which the flag B<-blbc>
2665 should apply. The section L<"Specifying Block Types"> explains how to list
2668 =item Note on using the B<-blao> and B<-blbc> options.
2670 These blank line controls introduce a certain minimum number of blank lines in
2671 the text, but the final number of blank lines may be greater, depending on
2672 values of the other blank line controls and the number of old blank lines. A
2673 consequence is that introducing blank lines with these and other controls
2674 cannot be exactly undone, so some experimentation with these controls is
2675 recommended before using them.
2677 For example, suppose that for some reason we decide to introduce one blank
2678 space at the beginning and ending of all blocks. We could do
2681 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
2683 Now suppose the script continues to be developed, but at some later date we
2684 decide we don't want these spaces after all. we might expect that running with
2685 the flags B<-blao=0> and B<-blbc=0> will undo them. However, by default
2686 perltidy retains single blank lines, so the blank lines remain.
2688 We can easily fix this by telling perltidy to ignore old blank lines by
2689 including the added parameter B<-kbl=0> and rerunning. Then the unwanted blank
2690 lines will be gone. However, this will cause all old blank lines to be
2691 ignored, perhaps even some that were added by hand to improve formatting. So
2692 please be cautious when using these parameters.
2694 =item B<-mbl=n> B<--maximum-consecutive-blank-lines=n>
2696 This parameter specifies the maximum number of consecutive blank lines which
2697 will be output within code sections of a script. The default is n=1. If the
2698 input file has more than n consecutive blank lines, the number will be reduced
2699 to n except as noted above for the B<-blbp> and B<-blbs> parameters. If B<n=0>
2700 then no blank lines will be output (unless all old blank lines are retained
2701 with the B<-kbl=2> flag of the next section).
2703 This flag obviously does not apply to pod sections,
2704 here-documents, and quotes.
2706 =item B<-kbl=n>, B<--keep-old-blank-lines=n>
2708 The B<-kbl=n> flag gives you control over how your existing blank lines are
2711 The possible values of B<n> are:
2713 n=0 ignore all old blank lines
2714 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
2715 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
2717 The default is B<n=1>.
2719 =item B<-sob>, B<--swallow-optional-blank-lines>
2721 This is equivalent to B<kbl=0> and is included for compatibility with
2724 =item B<-nsob>, B<--noswallow-optional-blank-lines>
2726 This is equivalent to B<kbl=1> and is included for compatibility with
2731 B<Controls for blank lines around lines of consecutive keywords>
2733 The parameters in this section provide some control over the placement of blank
2734 lines within and around groups of statements beginning with selected keywords.
2735 These blank lines are called here B<keyword group blanks>, and all of the
2736 parameters begin with B<--keyword-group-blanks*>, or B<-kgb*> for short. The
2737 default settings do not employ these controls but they can be enabled with the
2738 following parameters:
2740 B<-kgbl=s> or B<--keyword-group-blanks-list=s>; B<s> is a quoted string of keywords
2742 B<-kgbs=s> or B<--keyword-group-blanks-size=s>; B<s> gives the number of keywords required to form a group.
2744 B<-kgbb=n> or B<--keyword-group-blanks-before=n>; B<n> = (0, 1, or 2) controls a leading blank
2746 B<-kgba=n> or B<--keyword-group-blanks-after=n>; B<n> = (0, 1, or 2) controls a trailing blank
2748 B<-kgbi> or B<--keyword-group-blanks-inside> is a switch for adding blanks between subgroups
2750 B<-kgbd> or B<--keyword-group-blanks-delete> is a switch for removing initial blank lines between keywords
2752 B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> can limit the number of times this logic is applied
2754 In addition, the following abbreviations are available to for simplified usage:
2756 B<-kgb> or B<--keyword-group-blanks> is short for B<-kgbb=2 -kgba=2 kgbi>
2758 B<-nkgb> or B<--nokeyword-group-blanks>, is short for B<-kgbb=1 -kgba=1 nkgbi>
2760 Before describing the meaning of the parameters in detail let us look at an
2761 example which is formatted with default parameter settings.
2763 print "Entering test 2\n";
2765 use Encode qw(from_to encode decode
2766 encode_utf8 decode_utf8
2767 find_encoding is_utf8);
2768 use charnames qw(greek);
2769 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2770 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2771 my @source = qw(ascii iso8859-1 cp1250);
2772 my @destiny = qw(cp1047 cp37 posix-bc);
2773 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2774 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2775 return unless ($str);
2777 using B<perltidy -kgb> gives:
2779 print "Entering test 2\n";
2780 <----------this blank controlled by -kgbb
2782 use Encode qw(from_to encode decode
2783 encode_utf8 decode_utf8
2784 find_encoding is_utf8);
2785 use charnames qw(greek);
2786 <---------this blank controlled by -kgbi
2787 my @encodings = grep( /iso-?8859/, Encode::encodings() );
2788 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
2789 my @source = qw(ascii iso8859-1 cp1250);
2790 my @destiny = qw(cp1047 cp37 posix-bc);
2791 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
2792 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
2793 <----------this blank controlled by -kgba
2794 return unless ($str);
2796 Blank lines have been introduced around the B<my> and B<use> sequences. What
2797 happened is that the default keyword list includes B<my> and B<use> but not
2798 B<print> and B<return>. So a continuous sequence of nine B<my> and B<use>
2799 statements was located. This number exceeds the default threshold of five, so
2800 blanks were placed before and after the entire group. Then, since there was
2801 also a subsequence of six B<my> lines, a blank line was introduced to separate
2804 Finer control over blank placement can be achieved by using the individual
2805 parameters rather than the B<-kgb> flag. The individual controls are as follows.
2807 B<-kgbl=s> or B<--keyword-group-blanks-list=s>, where B<s> is a quoted string,
2808 defines the set of keywords which will be formed into groups. The string is a
2809 space separated list of keywords. The default set is B<s="use require local
2810 our my">, but any list of keywords may be used. Comment lines may also be included in a keyword group, even though they are not keywords. To include ordinary block comments, include the symbol B<BC>. To include static block comments (which normally begin with '##'), include the symbol B<SBC>.
2812 B<-kgbs=s> or B<--keyword-group-blanks-size=s>, where B<s> is a string
2813 describing the number of consecutive keyword statements forming a group. If
2814 B<s> is an integer then it is the minimum number required for a group. A
2815 maximum value may also be given with the format B<s=min.max>, where B<min> is
2816 the minimum number and B<max> is the maximum number, and the min and max values
2817 are separated by one or more dots. No groups will be found if the maximum is
2818 less than the minimum. The maximum is unlimited if not given. The default is
2819 B<s=5>. Some examples:
2821 s min max number for group
2822 3 3 unlimited 3 or more
2828 B<-kgbb=n> or B<--keyword-group-blanks-before=n> specifies whether
2829 a blank should appear before the first line of the group, as follows:
2831 n=0 => (delete) an existing blank line will be removed
2832 n=1 => (stable) no change to the input file is made [DEFAULT]
2833 n=2 => (insert) a blank line is introduced if possible
2835 B<-kgba=n> or B<--keyword-group-blanks-after=n> likewise specifies
2836 whether a blank should appear after the last line of the group, using the same
2837 scheme (0=delete, 1=stable, 2=insert).
2839 B<-kgbi> or B<--keyword-group-blanks-inside> controls
2840 the insertion of blank lines between the first and last statement of the entire
2841 group. If there is a continuous run of a single statement type with more than
2842 the minimum threshold number (as specified with B<-kgbs=s>) then this
2843 switch causes a blank line be inserted between this
2844 subgroup and the others. In the example above this happened between the
2845 B<use> and B<my> statements.
2847 B<-kgbd> or B<--keyword-group-blanks-delete> controls the deletion of any
2848 blank lines that exist in the the group when it is first scanned. When
2849 statements are initially scanned, any existing blank lines are included in the
2850 collection. Any such orignial blank lines will be deleted before any other
2851 insertions are made when the parameter B<-kgbd> is set. The default is not to
2854 B<-kgbr=n> or B<--keyword-group-blanks-repeat-count=n> specifies B<n>, the
2855 maximum number of times this logic will be applied to any file. The special
2856 value B<n=0> is the same as n=infinity which means it will be applied to an
2857 entire script [Default]. A value B<n=1> could be used to make it apply just
2858 one time for example. This might be useful for adjusting just the B<use>
2859 statements in the top part of a module for example.
2861 B<-kgb> or B<--keyword-group-blanks> is an abbreviation equivalent to setting
2862 B<-kgbb=1 -kgba=1 -kgbi>. This turns on keyword group formatting with a set of
2865 B<-nkgb> or B<--nokeyword-group-blanks> is equivalent to B<-kgbb=0 -kgba
2866 nkgbi>. This flag turns off keyword group blank lines and is the default
2869 Here are a few notes about the functioning of this technique.
2875 These parameters are probably more useful as part of a major code reformatting
2876 operation rather than as a routine formatting operation.
2878 In particular, note that deleting old blank lines with B<-kgbd> is an
2879 irreversible operation so it should be applied with care. Existing blank lines
2880 may be serving an important role in controlling vertical alignment.
2884 Conflicts which arise among these B<kgb*> parameters and other blank line
2885 controls are generally resolved by producing the maximum number of blank lines
2886 implied by any parameter.
2888 For example, if the flags B<--freeze-blank-lines>, or
2889 B<--keep-old-blank-lines=2>, are set, then they have priority over any blank
2890 line deletion implied by the B<-kgb> flags of this section, so no blank lines
2893 For another example, if a keyword group ends at a B<sub> and the flag B<kgba=0> requests no blank line there, but we also have B<--blank-lines-before-subs=2>, then two blank lines will still be introduced before the sub.
2897 The introduction of blank lines does not occur if it would conflict with other
2898 input controls or code validity. For example, a blank line will not be placed
2899 within a here-doc or within a section of code marked with format skipping
2900 comments. And in general, a blank line will only be introduced at the end of a
2901 group if the next statement is a line of code.
2905 The count which is used to determine the group size is not the number of lines
2906 but rather the total number of keywords which are found. Individual statements
2907 with a certain leading keyword may continue on multiple lines, but if any of
2908 these lines is nested more than one level deep then that group will be ended.
2912 The search for groups of lines with similar leading keywords is based on the
2913 input source, not the final formatted source. Consequently, if the source code
2914 is badly formatted, it would be best to make a first formatting pass without
2921 A style refers to a convenient collection of existing parameters.
2925 =item B<-gnu>, B<--gnu-style>
2927 B<-gnu> gives an approximation to the GNU Coding Standards (which do
2928 not apply to perl) as they are sometimes implemented. At present, this
2929 style overrides the default style with the following parameters:
2931 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
2933 =item B<-pbp>, B<--perl-best-practices>
2935 B<-pbp> is an abbreviation for the parameters in the book B<Perl Best Practices>
2938 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
2939 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
2940 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
2942 Please note that this parameter set includes -st and -se flags, which make
2943 perltidy act as a filter on one file only. These can be overridden by placing
2944 B<-nst> and/or B<-nse> after the -pbp parameter.
2946 Also note that the value of continuation indentation, -ci=4, is equal to the
2947 value of the full indentation, -i=4. In some complex statements perltidy will
2948 produce nicer results with -ci=2. This can be implemented by including -ci=2
2949 after the -pbp parameter. For example,
2954 : $type eq 'item' ? "the $section entry"
2955 : "the section on $section"
2959 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2960 : ' elsewhere in this document'
2963 # perltidy -pbp -ci=2
2966 : $type eq 'item' ? "the $section entry"
2967 : "the section on $section"
2971 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
2972 : ' elsewhere in this document'
2976 =item One-line blocks
2978 There are a few points to note regarding one-line blocks. A one-line
2979 block is something like this,
2981 if ($x > 0) { $y = 1 / $x }
2983 where the contents within the curly braces is short enough to fit
2986 With few exceptions, perltidy retains existing one-line blocks, if it
2987 is possible within the line-length constraint, but it does not attempt
2988 to form new ones. In other words, perltidy will try to follow the
2989 one-line block style of the input file.
2991 If an existing one-line block is longer than the maximum line length,
2992 however, it will be broken into multiple lines. When this happens, perltidy
2993 checks for and adds any optional terminating semicolon (unless the B<-nasc>
2994 option is used) if the block is a code block.
2996 The main exception is that perltidy will attempt to form new one-line
2997 blocks following the keywords C<map>, C<eval>, and C<sort>, because
2998 these code blocks are often small and most clearly displayed in a single
3001 One-line block rules can conflict with the cuddled-else option. When
3002 the cuddled-else option is used, perltidy retains existing one-line
3003 blocks, even if they do not obey cuddled-else formatting.
3005 Occasionally, when one-line blocks get broken because they exceed the
3006 available line length, the formatting will violate the requested brace style.
3007 If this happens, reformatting the script a second time should correct
3010 Sometimes it might be desirable to convert a script to have one-line blocks
3011 whenever possible. Although there is currently no flag for this, a simple
3012 workaround is to execute perltidy twice, once with the flag B<-noadd-newlines>
3013 and then once again with normal parameters, like this:
3015 cat infile | perltidy -nanl | perltidy >outfile
3017 When executed on this snippet
3020 die "failed to execute: $!\n";
3023 print "Had enough.\n";
3024 die "failed to execute: $!\n";
3029 if ( $? == -1 ) { die "failed to execute: $!\n"; }
3031 print "Had enough.\n";
3032 die "failed to execute: $!\n";
3035 This shows that blocks with a single statement become one-line blocks.
3038 =item B<-olbs=n>, B<--one-line-block-semicolons=n>
3040 This flag controls the placement of semicolons at the end of one-line blocks.
3041 Semicolons are optional before a closing block brace, and frequently they are
3042 omitted at the end of a one-line block containing just a single statement.
3043 By default, perltidy follows the input file regarding these semicolons,
3044 but this behavior can be controlled by this flag. The values of n are:
3046 n=0 remove terminal semicolons in one-line blocks having a single statement
3047 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
3048 n=2 add terminal semicolons in all one-line blocks
3050 Note that the B<n=2> option has no effect if adding semicolons is prohibited
3051 with the B<-nasc> flag. Also not that while B<n=2> adds missing semicolons to
3052 all one-line blocks, regardless of complexity, the B<n=0> option only removes
3053 ending semicolons which terminate one-line blocks containing just one
3054 semicolon. So these two options are not exact inverses.
3059 =head2 Controlling Vertical Alignment
3061 Vertical alignment refers to lining up certain symbols in list of consecutive
3062 similar lines to improve readability. For example, the "fat commas" are
3063 aligned in the following statement:
3066 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
3067 PeerPort => $port[4] * 256 + $port[5],
3071 The only explicit control on vertical alignment is to turn it off using
3072 B<-novalign>, a flag mainly intended for debugging. However, vertical
3073 alignment can be forced to stop and restart by selectively introducing blank
3074 lines. For example, a blank has been inserted in the following code
3075 to keep somewhat similar things aligned.
3078 'format' => [ 'tidy', 'html', 'user' ],
3079 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
3080 'character-encoding' => [ 'none', 'utf8' ],
3082 'block-brace-tightness' => [ 0, 2 ],
3083 'brace-tightness' => [ 0, 2 ],
3084 'paren-tightness' => [ 0, 2 ],
3085 'square-bracket-tightness' => [ 0, 2 ],
3089 =head2 Other Controls
3093 =item Deleting selected text
3095 Perltidy can selectively delete comments and/or pod documentation. The
3096 command B<-dac> or B<--delete-all-comments> will delete all comments
3097 B<and> all pod documentation, leaving just code and any leading system
3100 The command B<-dp> or B<--delete-pod> will remove all pod documentation
3103 Two commands which remove comments (but not pod) are: B<-dbc> or
3104 B<--delete-block-comments> and B<-dsc> or B<--delete-side-comments>.
3105 (Hanging side comments will be deleted with block comments here.)
3107 The negatives of these commands also work, and are the defaults. When
3108 block comments are deleted, any leading 'hash-bang' will be retained.
3109 Also, if the B<-x> flag is used, any system commands before a leading
3110 hash-bang will be retained (even if they are in the form of comments).
3112 =item Writing selected text to a file
3114 When perltidy writes a formatted text file, it has the ability to also
3115 send selected text to a file with a F<.TEE> extension. This text can
3116 include comments and pod documentation.
3118 The command B<-tac> or B<--tee-all-comments> will write all comments
3119 B<and> all pod documentation.
3121 The command B<-tp> or B<--tee-pod> will write all pod documentation (but
3124 The commands which write comments (but not pod) are: B<-tbc> or
3125 B<--tee-block-comments> and B<-tsc> or B<--tee-side-comments>.
3126 (Hanging side comments will be written with block comments here.)
3128 The negatives of these commands also work, and are the defaults.
3130 =item Using a F<.perltidyrc> command file
3132 If you use perltidy frequently, you probably won't be happy until you
3133 create a F<.perltidyrc> file to avoid typing commonly-used parameters.
3134 Perltidy will first look in your current directory for a command file
3135 named F<.perltidyrc>. If it does not find one, it will continue looking
3136 for one in other standard locations.
3138 These other locations are system-dependent, and may be displayed with
3139 the command C<perltidy -dpro>. Under Unix systems, it will first look
3140 for an environment variable B<PERLTIDY>. Then it will look for a
3141 F<.perltidyrc> file in the home directory, and then for a system-wide
3142 file F</usr/local/etc/perltidyrc>, and then it will look for
3143 F</etc/perltidyrc>. Note that these last two system-wide files do not
3144 have a leading dot. Further system-dependent information will be found
3145 in the INSTALL file distributed with perltidy.
3147 Under Windows, perltidy will also search for a configuration file named perltidy.ini since Windows does not allow files with a leading period (.).
3148 Use C<perltidy -dpro> to see the possible locations for your system.
3149 An example might be F<C:\Documents and Settings\All Users\perltidy.ini>.
3151 Another option is the use of the PERLTIDY environment variable.
3152 The method for setting environment variables depends upon the version of
3153 Windows that you are using. Instructions for Windows 95 and later versions can
3156 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3158 Under Windows NT / 2000 / XP the PERLTIDY environment variable can be placed in
3159 either the user section or the system section. The later makes the
3160 configuration file common to all users on the machine. Be sure to enter the
3161 full path of the configuration file in the value of the environment variable.
3162 Ex. PERLTIDY=C:\Documents and Settings\perltidy.ini
3164 The configuration file is free format, and simply a list of parameters, just as
3165 they would be entered on a command line. Any number of lines may be used, with
3166 any number of parameters per line, although it may be easiest to read with one
3167 parameter per line. Comment text begins with a #, and there must
3168 also be a space before the # for side comments. It is a good idea to
3169 put complex parameters in either single or double quotes.
3171 Here is an example of a F<.perltidyrc> file:
3173 # This is a simple of a .perltidyrc configuration file
3174 # This implements a highly spaced style
3175 -se # errors to standard error output
3176 -w # show all warnings
3177 -bl # braces on new lines
3178 -pt=0 # parens not tight at all
3179 -bt=0 # braces not tight
3180 -sbt=0 # square brackets not tight
3182 The parameters in the F<.perltidyrc> file are installed first, so any
3183 parameters given on the command line will have priority over them.
3185 To avoid confusion, perltidy ignores any command in the .perltidyrc
3186 file which would cause some kind of dump and an exit. These are:
3188 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3190 There are several options may be helpful in debugging a F<.perltidyrc>
3197 A very helpful command is B<--dump-profile> or B<-dpro>. It writes a
3198 list of all configuration filenames tested to standard output, and
3199 if a file is found, it dumps the content to standard output before
3200 exiting. So, to find out where perltidy looks for its configuration
3201 files, and which one if any it selects, just enter
3207 It may be simplest to develop and test configuration files with
3208 alternative names, and invoke them with B<-pro=filename> on the command
3209 line. Then rename the desired file to F<.perltidyrc> when finished.
3213 The parameters in the F<.perltidyrc> file can be switched off with
3214 the B<-npro> option.
3218 The commands B<--dump-options>, B<--dump-defaults>, B<--dump-long-names>,
3219 and B<--dump-short-names>, all described below, may all be helpful.
3223 =item Creating a new abbreviation
3225 A special notation is available for use in a F<.perltidyrc> file
3226 for creating an abbreviation for a group
3227 of options. This can be used to create a
3228 shorthand for one or more styles which are frequently, but not always,
3229 used. The notation is to group the options within curly braces which
3230 are preceded by the name of the alias (without leading dashes), like this:
3237 where B<newword> is the abbreviation, and B<opt1>, etc, are existing parameters
3238 I<or other abbreviations>. The main syntax requirement is that the new
3239 abbreviation along with its opening curly brace must begin on a new line.
3240 Space before and after the curly braces is optional.
3242 specific example, the following line
3244 airy {-bl -pt=0 -bt=0 -sbt=0}
3246 could be placed in a F<.perltidyrc> file, and then invoked at will with
3248 perltidy -airy somefile.pl
3250 (Either C<-airy> or C<--airy> may be used).
3252 =item Skipping leading non-perl commands with B<-x> or B<--look-for-hash-bang>
3254 If your script has leading lines of system commands or other text which
3255 are not valid perl code, and which are separated from the start of the
3256 perl code by a "hash-bang" line, ( a line of the form C<#!...perl> ),
3257 you must use the B<-x> flag to tell perltidy not to parse and format any
3258 lines before the "hash-bang" line. This option also invokes perl with a
3259 -x flag when checking the syntax. This option was originally added to
3260 allow perltidy to parse interactive VMS scripts, but it should be used
3261 for any script which is normally invoked with C<perl -x>.
3263 =item Making a file unreadable
3265 The goal of perltidy is to improve the readability of files, but there
3266 are two commands which have the opposite effect, B<--mangle> and
3267 B<--extrude>. They are actually
3268 merely aliases for combinations of other parameters. Both of these
3269 strip all possible whitespace, but leave comments and pod documents,
3270 so that they are essentially reversible. The
3271 difference between these is that B<--mangle> puts the fewest possible
3272 line breaks in a script while B<--extrude> puts the maximum possible.
3273 Note that these options do not provided any meaningful obfuscation, because
3274 perltidy can be used to reformat the files. They were originally
3275 developed to help test the tokenization logic of perltidy, but they
3277 One use for B<--mangle> is the following:
3279 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
3281 This will form the maximum possible number of one-line blocks (see next
3282 section), and can sometimes help clean up a badly formatted script.
3284 A similar technique can be used with B<--extrude> instead of B<--mangle>
3285 to make the minimum number of one-line blocks.
3287 Another use for B<--mangle> is to combine it with B<-dac> to reduce
3288 the file size of a perl script.
3292 The following flags are available for debugging:
3294 B<--dump-cuddled-block-list> or B<-dcbl> will dump to standard output the
3295 internal hash of cuddled block types created by a B<-cuddled-block-list> input
3298 B<--dump-defaults> or B<-ddf> will write the default option set to standard output and quit
3300 B<--dump-profile> or B<-dpro> will write the name of the current
3301 configuration file and its contents to standard output and quit.
3303 B<--dump-options> or B<-dop> will write current option set to standard
3306 B<--dump-long-names> or B<-dln> will write all command line long names (passed
3307 to Get_options) to standard output and quit.
3309 B<--dump-short-names> or B<-dsn> will write all command line short names
3310 to standard output and quit.
3312 B<--dump-token-types> or B<-dtt> will write a list of all token types
3313 to standard output and quit.
3315 B<--dump-want-left-space> or B<-dwls> will write the hash %want_left_space
3316 to standard output and quit. See the section on controlling whitespace
3319 B<--dump-want-right-space> or B<-dwrs> will write the hash %want_right_space
3320 to standard output and quit. See the section on controlling whitespace
3323 B<--no-memoize> or B<-nmem> will turn of memoizing.
3324 Memoization can reduce run time when running perltidy repeatedly in a
3325 single process. It is on by default but can be deactivated for
3326 testing with B<-nmem>.
3328 B<--no-timestamp> or B<-nts> will eliminate any time stamps in output files to prevent
3329 differences in dates from causing test installation scripts to fail. There are just
3330 a couple of places where timestamps normally occur. One is in the headers of
3331 html files, and another is when the B<-cscw> option is selected. The default is
3332 to allow timestamps (B<--timestamp> or B<-ts>).
3334 B<--file-size-order> or B<-fso> will cause files to be processed in order of
3335 increasing size, when multiple files are being processed. This is useful
3336 during program development, when large numbers of files with varying sizes are
3337 processed, because it can reduce virtual memory usage.
3339 B<-DEBUG> will write a file with extension F<.DEBUG> for each input file
3340 showing the tokenization of all lines of code.
3342 =item Working with MakeMaker, AutoLoader and SelfLoader
3344 The first $VERSION line of a file which might be eval'd by MakeMaker
3345 is passed through unchanged except for indentation.
3346 Use B<--nopass-version-line>, or B<-npvl>, to deactivate this feature.
3348 If the AutoLoader module is used, perltidy will continue formatting
3349 code after seeing an __END__ line.
3350 Use B<--nolook-for-autoloader>, or B<-nlal>, to deactivate this feature.
3352 Likewise, if the SelfLoader module is used, perltidy will continue formatting
3353 code after seeing a __DATA__ line.
3354 Use B<--nolook-for-selfloader>, or B<-nlsl>, to deactivate this feature.
3356 =item Working around problems with older version of Perl
3358 Perltidy contains a number of rules which help avoid known subtleties
3359 and problems with older versions of perl, and these rules always
3360 take priority over whatever formatting flags have been set. For example,
3361 perltidy will usually avoid starting a new line with a bareword, because
3362 this might cause problems if C<use strict> is active.
3364 There is no way to override these rules.
3372 =item The B<-html> master switch
3374 The flag B<-html> causes perltidy to write an html file with extension
3375 F<.html>. So, for example, the following command
3377 perltidy -html somefile.pl
3379 will produce a syntax-colored html file named F<somefile.pl.html>
3380 which may be viewed with a browser.
3382 B<Please Note>: In this case, perltidy does not do any formatting to the
3383 input file, and it does not write a formatted file with extension
3384 F<.tdy>. This means that two perltidy runs are required to create a
3385 fully reformatted, html copy of a script.
3387 =item The B<-pre> flag for code snippets
3389 When the B<-pre> flag is given, only the pre-formatted section, within
3390 the <PRE> and </PRE> tags, will be output. This simplifies inclusion
3391 of the output in other files. The default is to output a complete
3394 =item The B<-nnn> flag for line numbering
3396 When the B<-nnn> flag is given, the output lines will be numbered.
3398 =item The B<-toc>, or B<--html-table-of-contents> flag
3400 By default, a table of contents to packages and subroutines will be
3401 written at the start of html output. Use B<-ntoc> to prevent this.
3402 This might be useful, for example, for a pod document which contains a
3403 number of unrelated code snippets. This flag only influences the code
3404 table of contents; it has no effect on any table of contents produced by
3405 pod2html (see next item).
3407 =item The B<-pod>, or B<--pod2html> flag
3409 There are two options for formatting pod documentation. The default is
3410 to pass the pod through the Pod::Html module (which forms the basis of
3411 the pod2html utility). Any code sections are formatted by perltidy, and
3412 the results then merged. Note: perltidy creates a temporary file when
3413 Pod::Html is used; see L<"FILES">. Also, Pod::Html creates temporary
3414 files for its cache.
3416 NOTE: Perltidy counts the number of C<=cut> lines, and either moves the
3417 pod text to the top of the html file if there is one C<=cut>, or leaves
3418 the pod text in its original order (interleaved with code) otherwise.
3420 Most of the flags accepted by pod2html may be included in the perltidy
3421 command line, and they will be passed to pod2html. In some cases,
3422 the flags have a prefix C<pod> to emphasize that they are for the
3423 pod2html, and this prefix will be removed before they are passed to
3424 pod2html. The flags which have the additional C<pod> prefix are:
3426 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
3427 --[no]podverbose --podflush
3429 The flags which are unchanged from their use in pod2html are:
3431 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
3432 --podpath=s --podroot=s
3434 where 's' is an appropriate character string. Not all of these flags are
3435 available in older versions of Pod::Html. See your Pod::Html documentation for
3438 The alternative, indicated with B<-npod>, is not to use Pod::Html, but
3439 rather to format pod text in italics (or whatever the stylesheet
3440 indicates), without special html markup. This is useful, for example,
3441 if pod is being used as an alternative way to write comments.
3443 =item The B<-frm>, or B<--frames> flag
3445 By default, a single html output file is produced. This can be changed
3446 with the B<-frm> option, which creates a frame holding a table of
3447 contents in the left panel and the source code in the right side. This
3448 simplifies code browsing. Assume, for example, that the input file is
3449 F<MyModule.pm>. Then, for default file extension choices, these three
3450 files will be created:
3452 MyModule.pm.html - the frame
3453 MyModule.pm.toc.html - the table of contents
3454 MyModule.pm.src.html - the formatted source code
3456 Obviously this file naming scheme requires that output be directed to a real
3457 file (as opposed to, say, standard output). If this is not the
3458 case, or if the file extension is unknown, the B<-frm> option will be
3461 =item The B<-text=s>, or B<--html-toc-extension> flag
3463 Use this flag to specify the extra file extension of the table of contents file
3464 when html frames are used. The default is "toc".
3465 See L<Specifying File Extensions>.
3467 =item The B<-sext=s>, or B<--html-src-extension> flag
3469 Use this flag to specify the extra file extension of the content file when html
3470 frames are used. The default is "src".
3471 See L<Specifying File Extensions>.
3473 =item The B<-hent>, or B<--html-entities> flag
3475 This flag controls the use of Html::Entities for html formatting. By
3476 default, the module Html::Entities is used to encode special symbols.
3477 This may not be the right thing for some browser/language
3478 combinations. Use --nohtml-entities or -nhent to prevent this.
3482 Style sheets make it very convenient to control and adjust the
3483 appearance of html pages. The default behavior is to write a page of
3484 html with an embedded style sheet.
3486 An alternative to an embedded style sheet is to create a page with a
3487 link to an external style sheet. This is indicated with the
3488 B<-css=filename>, where the external style sheet is F<filename>. The
3489 external style sheet F<filename> will be created if and only if it does
3490 not exist. This option is useful for controlling multiple pages from a
3493 To cause perltidy to write a style sheet to standard output and exit,
3494 use the B<-ss>, or B<--stylesheet>, flag. This is useful if the style
3495 sheet could not be written for some reason, such as if the B<-pre> flag
3496 was used. Thus, for example,
3498 perltidy -html -ss >mystyle.css
3500 will write a style sheet with the default properties to file
3503 The use of style sheets is encouraged, but a web page without a style
3504 sheets can be created with the flag B<-nss>. Use this option if you
3505 must to be sure that older browsers (roughly speaking, versions prior to
3506 4.0 of Netscape Navigator and Internet Explorer) can display the
3507 syntax-coloring of the html files.
3509 =item Controlling HTML properties
3511 Note: It is usually more convenient to accept the default properties
3512 and then edit the stylesheet which is produced. However, this section
3513 shows how to control the properties with flags to perltidy.
3515 Syntax colors may be changed from their default values by flags of the either
3516 the long form, B<-html-color-xxxxxx=n>, or more conveniently the short form,
3517 B<-hcx=n>, where B<xxxxxx> is one of the following words, and B<x> is the
3518 corresponding abbreviation:
3521 ---------- -------- --
3524 identifier identifier i
3525 bareword, function bareword w
3527 quite, pattern quote q
3528 here doc text here-doc-text h
3529 here doc target here-doc-target hh
3530 punctuation punctuation pu
3532 structural braces structure s
3533 semicolon semicolon sc
3537 sub definition name subroutine m
3538 pod text pod-text pd
3540 A default set of colors has been defined, but they may be changed by providing
3541 values to any of the following parameters, where B<n> is either a 6 digit
3542 hex RGB color value or an ascii name for a color, such as 'red'.
3544 To illustrate, the following command will produce an html
3545 file F<somefile.pl.html> with "aqua" keywords:
3547 perltidy -html -hck=00ffff somefile.pl
3549 and this should be equivalent for most browsers:
3551 perltidy -html -hck=aqua somefile.pl
3553 Perltidy merely writes any non-hex names that it sees in the html file.
3554 The following 16 color names are defined in the HTML 3.2 standard:
3573 Many more names are supported in specific browsers, but it is safest
3574 to use the hex codes for other colors. Helpful color tables can be
3575 located with an internet search for "HTML color tables".
3577 Besides color, two other character attributes may be set: bold, and italics.
3578 To set a token type to use bold, use the flag
3579 B<--html-bold-xxxxxx> or B<-hbx>, where B<xxxxxx> or B<x> are the long
3580 or short names from the above table. Conversely, to set a token type to
3581 NOT use bold, use B<--nohtml-bold-xxxxxx> or B<-nhbx>.
3583 Likewise, to set a token type to use an italic font, use the flag
3584 B<--html-italic-xxxxxx> or B<-hix>, where again B<xxxxxx> or B<x> are the
3585 long or short names from the above table. And to set a token type to
3586 NOT use italics, use B<--nohtml-italic-xxxxxx> or B<-nhix>.
3588 For example, to use bold braces and lime color, non-bold, italics keywords the
3589 following command would be used:
3591 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
3593 The background color can be specified with B<--html-color-background=n>,
3594 or B<-hcbg=n> for short, where n is a 6 character hex RGB value. The
3595 default color of text is the value given to B<punctuation>, which is
3598 Here are some notes and hints:
3600 1. If you find a preferred set of these parameters, you may want
3601 to create a F<.perltidyrc> file containing them. See the perltidy man
3602 page for an explanation.
3604 2. Rather than specifying values for these parameters, it is probably
3605 easier to accept the defaults and then edit a style sheet. The style
3606 sheet contains comments which should make this easy.
3608 3. The syntax-colored html files can be very large, so it may be best to
3609 split large files into smaller pieces to improve download times.
3613 =head1 SOME COMMON INPUT CONVENTIONS
3615 =head2 Specifying Block Types
3617 Several parameters which refer to code block types may be customized by also
3618 specifying an associated list of block types. The type of a block is the name
3619 of the keyword which introduces that block, such as B<if>, B<else>, or B<sub>.
3620 An exception is a labeled block, which has no keyword, and should be specified
3621 with just a colon. To specify all blocks use B<'*'>.
3623 The keyword B<sub> indicates a named sub. For anonymous subs, use the special
3626 For example, the following parameter specifies C<sub>, labels, C<BEGIN>, and
3629 -cscl="sub : BEGIN END"
3631 (the meaning of the -cscl parameter is described above.) Note that
3632 quotes are required around the list of block types because of the
3633 spaces. For another example, the following list specifies all block types
3634 for vertical tightness:
3638 =head2 Specifying File Extensions
3640 Several parameters allow default file extensions to be overridden. For
3641 example, a backup file extension may be specified with B<-bext=ext>,
3642 where B<ext> is some new extension. In order to provides the user some
3643 flexibility, the following convention is used in all cases to decide if
3644 a leading '.' should be used. If the extension C<ext> begins with
3645 C<A-Z>, C<a-z>, or C<0-9>, then it will be appended to the filename with
3646 an intermediate '.' (or perhaps an '_' on VMS systems). Otherwise, it
3647 will be appended directly.
3649 For example, suppose the file is F<somefile.pl>. For C<-bext=old>, a '.' is
3650 added to give F<somefile.pl.old>. For C<-bext=.old>, no additional '.' is
3651 added, so again the backup file is F<somefile.pl.old>. For C<-bext=~>, then no
3652 dot is added, and the backup file will be F<somefile.pl~> .
3654 =head1 SWITCHES WHICH MAY BE NEGATED
3656 The following list shows all short parameter names which allow a prefix
3657 'n' to produce the negated form:
3659 D anl asc aws b bbb bbc bbs bl bli boc bok bol bot ce
3660 csc dac dbc dcsc ddf dln dnl dop dp dpro dsc dsm dsn dtt dwls
3661 dwrs dws f fll frm fs hsc html ibc icb icp iob isbc lal log
3662 lp lsl ohbr okw ola oll opr opt osbr otr ple pod pvl q
3663 sbc sbl schb scp scsb sct se sfp sfs skp sob sohb sop sosb sot
3664 ssc st sts syn t tac tbc toc tp tqw tsc w x bar kis
3666 Equivalently, the prefix 'no' or 'no-' on the corresponding long names may be
3673 =item Parsing Limitations
3675 Perltidy should work properly on most perl scripts. It does a lot of
3676 self-checking, but still, it is possible that an error could be
3677 introduced and go undetected. Therefore, it is essential to make
3678 careful backups and to test reformatted scripts.
3680 The main current limitation is that perltidy does not scan modules
3681 included with 'use' statements. This makes it necessary to guess the
3682 context of any bare words introduced by such modules. Perltidy has good
3683 guessing algorithms, but they are not infallible. When it must guess,
3684 it leaves a message in the log file.
3686 If you encounter a bug, please report it.
3688 =item What perltidy does not parse and format
3690 Perltidy indents but does not reformat comments and C<qw> quotes.
3691 Perltidy does not in any way modify the contents of here documents or
3692 quoted text, even if they contain source code. (You could, however,
3693 reformat them separately). Perltidy does not format 'format' sections
3694 in any way. And, of course, it does not modify pod documents.
3702 =item Temporary files
3704 Under the -html option with the default --pod2html flag, a temporary file is
3705 required to pass text to Pod::Html. Unix systems will try to use the POSIX
3706 tmpnam() function. Otherwise the file F<perltidy.TMP> will be temporarily
3707 created in the current working directory.
3709 =item Special files when standard input is used
3711 When standard input is used, the log file, if saved, is F<perltidy.LOG>,
3712 and any errors are written to F<perltidy.ERR> unless the B<-se> flag is
3713 set. These are saved in the current working directory.
3715 =item Files overwritten
3717 The following file extensions are used by perltidy, and files with these
3718 extensions may be overwritten or deleted: F<.ERR>, F<.LOG>, F<.TEE>,
3719 and/or F<.tdy>, F<.html>, and F<.bak>, depending on the run type and
3722 =item Files extensions limitations
3724 Perltidy does not operate on files for which the run could produce a file with
3725 a duplicated file extension. These extensions include F<.LOG>, F<.ERR>,
3726 F<.TEE>, and perhaps F<.tdy> and F<.bak>, depending on the run type. The
3727 purpose of this rule is to prevent generating confusing filenames such as
3728 F<somefile.tdy.tdy.tdy>.
3734 perlstyle(1), Perl::Tidy(3)
3738 This man page documents perltidy version 20190601
3742 A list of current bugs and issues can be found at the CPAN site L<https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
3744 To report a new bug or problem, use the link on this page.
3746 The source code repository is at L<https://github.com/perltidy/perltidy>.
3750 Copyright (c) 2000-2018 by Steve Hancock
3754 This package is free software; you can redistribute it and/or modify it
3755 under the terms of the "GNU General Public License".
3757 Please refer to the file "COPYING" for details.
3761 This package is distributed in the hope that it will be useful,
3762 but WITHOUT ANY WARRANTY; without even the implied warranty of
3763 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
3765 See the "GNU General Public License" for more details.
projects / perltidy.git / blob