1PERLTIDY(1) User Contributed Perl Documentation PERLTIDY(1)
2
3
4
6 perltidy - a perl script indenter and reformatter
7
9 perltidy [ options ] file1 file2 file3 ...
10 (output goes to file1.tdy, file2.tdy, file3.tdy, ...)
11 perltidy [ options ] file1 -o outfile
12 perltidy [ options ] file1 -st >outfile
13 perltidy [ options ] <infile >outfile
14
16 Perltidy reads a perl script and writes an indented, reformatted
17 script.
18
19 Many users will find enough information in "EXAMPLES" to get started.
20 New users may benefit from the short tutorial which can be found at
21 http://perltidy.sourceforge.net/tutorial.html
22
23 A convenient aid to systematically defining a set of style parameters
24 can be found at http://perltidy.sourceforge.net/stylekey.html
25
26 Perltidy can produce output on either of two modes, depending on the
27 existence of an -html flag. Without this flag, the output is passed
28 through a formatter. The default formatting tries to follow the
29 recommendations in perlstyle(1), but it can be controlled in detail
30 with numerous input parameters, which are described in "FORMATTING
31 OPTIONS".
32
33 When the -html flag is given, the output is passed through an HTML
34 formatter which is described in "HTML OPTIONS".
35
37 perltidy somefile.pl
38
39 This will produce a file somefile.pl.tdy containing the script
40 reformatted using the default options, which approximate the style
41 suggested in perlstyle(1). The source file somefile.pl is unchanged.
42
43 perltidy *.pl
44
45 Execute perltidy on all .pl files in the current directory with the
46 default options. The output will be in files with an appended .tdy
47 extension. For any file with an error, there will be a file with
48 extension .ERR.
49
50 perltidy -b file1.pl file2.pl
51
52 Modify file1.pl and file2.pl in place, and backup the originals to
53 file1.pl.bak and file2.pl.bak. If file1.pl.bak and/or file2.pl.bak
54 already exist, they will be overwritten.
55
56 perltidy -b -bext='/' file1.pl file2.pl
57
58 Same as the previous example except that the backup files file1.pl.bak
59 and file2.pl.bak will be deleted if there are no errors.
60
61 perltidy -gnu somefile.pl
62
63 Execute perltidy on file somefile.pl with a style which approximates
64 the GNU Coding Standards for C programs. The output will be
65 somefile.pl.tdy.
66
67 perltidy -i=3 somefile.pl
68
69 Execute perltidy on file somefile.pl, with 3 columns for each level of
70 indentation (-i=3) instead of the default 4 columns. There will not be
71 any tabs in the reformatted script, except for any which already exist
72 in comments, pod documents, quotes, and here documents. Output will be
73 somefile.pl.tdy.
74
75 perltidy -i=3 -et=8 somefile.pl
76
77 Same as the previous example, except that leading whitespace will be
78 entabbed with one tab character per 8 spaces.
79
80 perltidy -ce -l=72 somefile.pl
81
82 Execute perltidy on file somefile.pl with all defaults except use
83 "cuddled elses" (-ce) and a maximum line length of 72 columns (-l=72)
84 instead of the default 80 columns.
85
86 perltidy -g somefile.pl
87
88 Execute perltidy on file somefile.pl and save a log file
89 somefile.pl.LOG which shows the nesting of braces, parentheses, and
90 square brackets at the start of every line.
91
92 perltidy -html somefile.pl
93
94 This will produce a file somefile.pl.html containing the script with
95 html markup. The output file will contain an embedded style sheet in
96 the <HEAD> section which may be edited to change the appearance.
97
98 perltidy -html -css=mystyle.css somefile.pl
99
100 This will produce a file somefile.pl.html containing the script with
101 html markup. This output file will contain a link to a separate style
102 sheet file mystyle.css. If the file mystyle.css does not exist, it
103 will be created. If it exists, it will not be overwritten.
104
105 perltidy -html -pre somefile.pl
106
107 Write an html snippet with only the PRE section to somefile.pl.html.
108 This is useful when code snippets are being formatted for inclusion in
109 a larger web page. No style sheet will be written in this case.
110
111 perltidy -html -ss >mystyle.css
112
113 Write a style sheet to mystyle.css and exit.
114
115 perltidy -html -frm mymodule.pm
116
117 Write html with a frame holding a table of contents and the source
118 code. The output files will be mymodule.pm.html (the frame),
119 mymodule.pm.toc.html (the table of contents), and mymodule.pm.src.html
120 (the source code).
121
123 The entire command line is scanned for options, and they are processed
124 before any files are processed. As a result, it does not matter
125 whether flags are before or after any filenames. However, the relative
126 order of parameters is important, with later parameters overriding the
127 values of earlier parameters.
128
129 For each parameter, there is a long name and a short name. The short
130 names are convenient for keyboard input, while the long names are self-
131 documenting and therefore useful in scripts. It is customary to use
132 two leading dashes for long names, but one may be used.
133
134 Most parameters which serve as on/off flags can be negated with a
135 leading "n" (for the short name) or a leading "no" or "no-" (for the
136 long name). For example, the flag to outdent long quotes is -olq or
137 --outdent-long-quotes. The flag to skip this is -nolq or
138 --nooutdent-long-quotes or --no-outdent-long-quotes.
139
140 Options may not be bundled together. In other words, options -q and -g
141 may NOT be entered as -qg.
142
143 Option names may be terminated early as long as they are uniquely
144 identified. For example, instead of --dump-token-types, it would be
145 sufficient to enter --dump-tok, or even --dump-t, to uniquely identify
146 this command.
147
148 I/O control
149 The following parameters concern the files which are read and written.
150
151 -h, --help
152 Show summary of usage and exit.
153
154 -o=filename, --outfile=filename
155 Name of the output file (only if a single input file is being
156 processed). If no output file is specified, and output is not
157 redirected to the standard output (see -st), the output will go to
158 filename.tdy. [Note: - does not redirect to standard output. Use
159 -st instead.]
160
161 -st, --standard-output
162 Perltidy must be able to operate on an arbitrarily large number of
163 files in a single run, with each output being directed to a
164 different output file. Obviously this would conflict with
165 outputting to the single standard output device, so a special flag,
166 -st, is required to request outputting to the standard output. For
167 example,
168
169 perltidy somefile.pl -st >somefile.new.pl
170
171 This option may only be used if there is just a single input file.
172 The default is -nst or --nostandard-output.
173
174 -se, --standard-error-output
175 If perltidy detects an error when processing file somefile.pl, its
176 default behavior is to write error messages to file
177 somefile.pl.ERR. Use -se to cause all error messages to be sent to
178 the standard error output stream instead. This directive may be
179 negated with -nse. Thus, you may place -se in a .perltidyrc and
180 override it when desired with -nse on the command line.
181
182 -oext=ext, --output-file-extension=ext
183 Change the extension of the output file to be ext instead of the
184 default tdy (or html in case the --html option is used). See
185 "Specifying File Extensions".
186
187 -opath=path, --output-path=path
188 When perltidy creates a filename for an output file, by default it
189 merely appends an extension to the path and basename of the input
190 file. This parameter causes the path to be changed to path
191 instead.
192
193 The path should end in a valid path separator character, but
194 perltidy will try to add one if it is missing.
195
196 For example
197
198 perltidy somefile.pl -opath=/tmp/
199
200 will produce /tmp/somefile.pl.tdy. Otherwise, somefile.pl.tdy will
201 appear in whatever directory contains somefile.pl.
202
203 If the path contains spaces, it should be placed in quotes.
204
205 This parameter will be ignored if output is being directed to
206 standard output, or if it is being specified explicitly with the
207 -o=s parameter.
208
209 -b, --backup-and-modify-in-place
210 Modify the input file or files in-place and save the original with
211 the extension .bak. Any existing .bak file will be deleted. See
212 next item for changing the default backup extension, and for
213 eliminating the backup file altogether.
214
215 A -b flag will be ignored if input is from standard input or goes
216 to standard output, or if the -html flag is set.
217
218 In particular, if you want to use both the -b flag and the -pbp
219 (--perl-best-practices) flag, then you must put a -nst flag after
220 the -pbp flag because it contains a -st flag as one of its
221 components, which means that output will go to the standard output
222 stream.
223
224 -bext=ext, --backup-file-extension=ext
225 This parameter serves two purposes: (1) to change the extension of
226 the backup file to be something other than the default .bak, and
227 (2) to indicate that no backup file should be saved.
228
229 To change the default extension to something other than .bak see
230 "Specifying File Extensions".
231
232 A backup file of the source is always written, but you can request
233 that it be deleted at the end of processing if there were no
234 errors. This is risky unless the source code is being maintained
235 with a source code control system.
236
237 To indicate that the backup should be deleted include one forward
238 slash, /, in the extension. If any text remains after the slash is
239 removed it will be used to define the backup file extension (which
240 is always created and only deleted if there were no errors).
241
242 Here are some examples:
243
244 Parameter Extension Backup File Treatment
245 <-bext=bak> F<.bak> Keep (same as the default behavior)
246 <-bext='/'> F<.bak> Delete if no errors
247 <-bext='/backup'> F<.backup> Delete if no errors
248 <-bext='original/'> F<.original> Delete if no errors
249
250 -w, --warning-output
251 Setting -w causes any non-critical warning messages to be reported
252 as errors. These include messages about possible pod problems,
253 possibly bad starting indentation level, and cautions about
254 indirect object usage. The default, -nw or --nowarning-output, is
255 not to include these warnings.
256
257 -q, --quiet
258 Deactivate error messages (for running under an editor).
259
260 For example, if you use a vi-style editor, such as vim, you may
261 execute perltidy as a filter from within the editor using something
262 like
263
264 :n1,n2!perltidy -q
265
266 where "n1,n2" represents the selected text. Without the -q flag,
267 any error message may mess up your screen, so be prepared to use
268 your "undo" key.
269
270 -log, --logfile
271 Save the .LOG file, which has many useful diagnostics. Perltidy
272 always creates a .LOG file, but by default it is deleted unless a
273 program bug is suspected. Setting the -log flag forces the log
274 file to be saved.
275
276 -g=n, --logfile-gap=n
277 Set maximum interval between input code lines in the logfile. This
278 purpose of this flag is to assist in debugging nesting errors. The
279 value of "n" is optional. If you set the flag -g without the value
280 of "n", it will be taken to be 1, meaning that every line will be
281 written to the log file. This can be helpful if you are looking
282 for a brace, paren, or bracket nesting error.
283
284 Setting -g also causes the logfile to be saved, so it is not
285 necessary to also include -log.
286
287 If no -g flag is given, a value of 50 will be used, meaning that at
288 least every 50th line will be recorded in the logfile. This helps
289 prevent excessively long log files.
290
291 Setting a negative value of "n" is the same as not setting -g at
292 all.
293
294 -npro --noprofile
295 Ignore any .perltidyrc command file. Normally, perltidy looks
296 first in your current directory for a .perltidyrc file of
297 parameters. (The format is described below). If it finds one, it
298 applies those options to the initial default values, and then it
299 applies any that have been defined on the command line. If no
300 .perltidyrc file is found, it looks for one in your home directory.
301
302 If you set the -npro flag, perltidy will not look for this file.
303
304 -pro=filename or --profile=filename
305 To simplify testing and switching .perltidyrc files, this command
306 may be used to specify a configuration file which will override the
307 default name of .perltidyrc. There must not be a space on either
308 side of the '=' sign. For example, the line
309
310 perltidy -pro=testcfg
311
312 would cause file testcfg to be used instead of the default
313 .perltidyrc.
314
315 A pathname begins with three dots, e.g. ".../.perltidyrc",
316 indicates that the file should be searched for starting in the
317 current directory and working upwards. This makes it easier to have
318 multiple projects each with their own .perltidyrc in their root
319 directories.
320
321 -opt, --show-options
322 Write a list of all options used to the .LOG file. Please see
323 --dump-options for a simpler way to do this.
324
325 -f, --force-read-binary
326 Force perltidy to process binary files. To avoid producing
327 excessive error messages, perltidy skips files identified by the
328 system as non-text. However, valid perl scripts containing binary
329 data may sometimes be identified as non-text, and this flag forces
330 perltidy to process them.
331
332 -ast, --assert-tidy
333 This flag asserts that the input and output code streams are
334 identical, or in other words that the input code is already 'tidy'
335 according to the formatting parameters. If this is not the case,
336 an error message noting this is produced. This error message will
337 cause the process to return a non-zero exit code. The test for
338 this is made by comparing an MD5 hash value for the input and
339 output code streams. This flag has no other effect on the
340 functioning of perltidy. This might be useful for certain code
341 maintenance operations. Note: you will not see this message if you
342 have error messages turned off with the -quiet flag.
343
344 -asu, --assert-untidy
345 This flag asserts that the input and output code streams are
346 different, or in other words that the input code is 'untidy'
347 according to the formatting parameters. If this is not the case,
348 an error message noting this is produced. This flag has no other
349 effect on the functioning of perltidy.
350
351 -sal=s, --sub-alias-list=s
352 This flag causes one or more words to be treated the same as if
353 they were the keyword 'sub'. The string s contains one or more
354 alias words, separated by spaces or commas.
355
356 For example,
357
358 perltidy -sal='method fun _sub M4'
359
360 will cause the perltidy to treate the words 'method', 'fun', '_sub'
361 and 'M4' to be treated the same as if they were 'sub'. Note that
362 if the alias words are separated by spaces then the string of words
363 should be placed in quotes.
364
365 Note that several other parameters accept a list of keywords,
366 including 'sub' (see "Specifying Block Types"). You do not need to
367 include any sub aliases in these lists. Just include keyword 'sub'
368 if you wish, and all aliases are automatically included.
369
371 Basic Options
372 --notidy
373 This flag disables all formatting and causes the input to be copied
374 unchanged to the output except for possible changes in line ending
375 characters and any pre- and post-filters. This can be useful in
376 conjunction with a hierarchical set of .perltidyrc files to avoid
377 unwanted code tidying. See also "Skipping Selected Sections of
378 Code" for a way to avoid tidying specific sections of code.
379
380 -i=n, --indent-columns=n
381 Use n columns per indentation level (default n=4).
382
383 -l=n, --maximum-line-length=n
384 The default maximum line length is n=80 characters. Perltidy will
385 try to find line break points to keep lines below this length.
386 However, long quotes and side comments may cause lines to exceed
387 this length.
388
389 The default length of 80 comes from the past when this was the
390 standard CRT screen width. Many programmers prefer to increase
391 this to something like 120.
392
393 Setting -l=0 is equivalent to setting -l=(a very large number).
394 But this is not recommended because, for example, a very long list
395 will be formatted in a single long line.
396
397 -vmll, --variable-maximum-line-length
398 A problem arises using a fixed maximum line length with very deeply
399 nested code and data structures because eventually the amount of
400 leading whitespace used for indicating indentation takes up most or
401 all of the available line width, leaving little or no space for the
402 actual code or data. One solution is to use a vary long line
403 length. Another solution is to use the -vmll flag, which basically
404 tells perltidy to ignore leading whitespace when measuring the line
405 length.
406
407 To be precise, when the -vmll parameter is set, the maximum line
408 length of a line of code will be M+L*I, where
409
410 M is the value of --maximum-line-length=M (-l=M), default 80,
411 I is the value of --indent-columns=I (-i=I), default 4,
412 L is the indentation level of the line of code
413
414 When this flag is set, the choice of breakpoints for a block of
415 code should be essentially independent of its nesting depth.
416 However, the absolute line lengths, including leading whitespace,
417 can still be arbitrarily large. This problem can be avoided by
418 including the next parameter.
419
420 The default is not to do this (-nvmll).
421
422 -wc=n, --whitespace-cycle=n
423 This flag also addresses problems with very deeply nested code and
424 data structures. When the nesting depth exceeds the value n the
425 leading whitespace will be reduced and start at a depth of 1 again.
426 The result is that blocks of code will shift back to the left
427 rather than moving arbitrarily far to the right. This occurs
428 cyclically to any depth.
429
430 For example if one level of indentation equals 4 spaces (-i=4, the
431 default), and one uses -wc=15, then if the leading whitespace on a
432 line exceeds about 4*15=60 spaces it will be reduced back to 4*1=4
433 spaces and continue increasing from there. If the whitespace never
434 exceeds this limit the formatting remains unchanged.
435
436 The combination of -vmll and -wc=n provides a solution to the
437 problem of displaying arbitrarily deep data structures and code in
438 a finite window, although -wc=n may of course be used without
439 -vmll.
440
441 The default is not to use this, which can also be indicated using
442 -wc=0.
443
444 Tabs
445 Using tab characters will almost certainly lead to future
446 portability and maintenance problems, so the default and
447 recommendation is not to use them. For those who prefer tabs,
448 however, there are two different options.
449
450 Except for possibly introducing tab indentation characters, as
451 outlined below, perltidy does not introduce any tab characters into
452 your file, and it removes any tabs from the code (unless requested
453 not to do so with -fws). If you have any tabs in your comments,
454 quotes, or here-documents, they will remain.
455
456 -et=n, --entab-leading-whitespace
457 This flag causes each n initial space characters to be replaced
458 by one tab character.
459
460 The value of the integer n can be any value but can be
461 coordinated with the number of spaces used for intentation. For
462 example, -et=4 -ci=4 -i=4 will produce one tab for each
463 indentation level and and one for each continuation indentation
464 level. You may want to coordinate the value of n with what
465 your display software assumes for the spacing of a tab.
466
467 -t, --tabs
468 This flag causes one leading tab character to be inserted for
469 each level of indentation. Certain other features are
470 incompatible with this option, and if these options are also
471 given, then a warning message will be issued and this flag will
472 be unset. One example is the -lp option. This flag is retained
473 for backwards compatability, but if you use tabs, the -et=n
474 flag is recommended.
475
476 -dt=n, --default-tabsize=n
477 If the first line of code passed to perltidy contains leading
478 tabs but no tab scheme is specified for the output stream then
479 perltidy must guess how many spaces correspond to each leading
480 tab. This number of spaces n corresponding to each leading tab
481 of the input stream may be specified with -dt=n. The default
482 is n=8.
483
484 This flag has no effect if a tab scheme is specified for the
485 output stream, because then the input stream is assumed to use
486 the same tab scheme and indentation spaces as for the output
487 stream (any other assumption would lead to unstable editing).
488
489 -syn, --check-syntax
490 This flag is now ignored for safety, but the following
491 documentation has been retained for reference.
492
493 This flag causes perltidy to run "perl -c -T" to check syntax of
494 input and output. (To change the flags passed to perl, see the
495 next item, -pscf). The results are written to the .LOG file, which
496 will be saved if an error is detected in the output script. The
497 output script is not checked if the input script has a syntax
498 error. Perltidy does its own checking, but this option employs
499 perl to get a "second opinion".
500
501 If perl reports errors in the input file, they will not be reported
502 in the error output unless the --warning-output flag is given.
503
504 The default is NOT to do this type of syntax checking (although
505 perltidy will still do as much self-checking as possible). The
506 reason is that it causes all code in BEGIN blocks to be executed,
507 for all modules being used, and this opens the door to security
508 issues and infinite loops when running perltidy.
509
510 -pscf=s, -perl-syntax-check-flags=s
511 When perl is invoked to check syntax, the normal flags are "-c -T".
512 In addition, if the -x flag is given to perltidy, then perl will
513 also be passed a -x flag. It should not normally be necessary to
514 change these flags, but it can be done with the -pscf=s flag. For
515 example, if the taint flag, "-T", is not wanted, the flag could be
516 set to be just -pscf=-c.
517
518 Perltidy will pass your string to perl with the exception that it
519 will add a -c and -x if appropriate. The .LOG file will show
520 exactly what flags were passed to perl.
521
522 -xs, --extended-syntax
523 A problem with formatting Perl code is that some modules can
524 introduce new syntax. This flag allows perltidy to handle certain
525 common extensions to the standard syntax without complaint.
526
527 For example, without this flag a structure such as the following
528 would generate a syntax error and the braces would not be balanced:
529
530 method deposit( Num $amount) {
531 $self->balance( $self->balance + $amount );
532 }
533
534 For one of the extensions, module Switch::Plain, colons are marked
535 as labels. If you use this module, you may want to also use the
536 --nooutdent-labels flag to prevent lines such as 'default:' from
537 being outdented.
538
539 This flag is enabled by default but it can be deactivated with
540 -nxs. Probably the only reason to deactivate this flag is to
541 generate more diagnostic messages when debugging a script.
542
543 -io, --indent-only
544 This flag is used to deactivate all whitespace and line break
545 changes within non-blank lines of code. When it is in effect, the
546 only change to the script will be to the indentation and to the
547 number of blank lines. And any flags controlling whitespace and
548 newlines will be ignored. You might want to use this if you are
549 perfectly happy with your whitespace and line breaks, and merely
550 want perltidy to handle the indentation. (This also speeds up
551 perltidy by well over a factor of two, so it might be useful when
552 perltidy is merely being used to help find a brace error in a large
553 script).
554
555 Setting this flag is equivalent to setting --freeze-newlines and
556 --freeze-whitespace.
557
558 If you also want to keep your existing blank lines exactly as they
559 are, you can add --freeze-blank-lines.
560
561 With this option perltidy is still free to modify the indenting
562 (and outdenting) of code and comments as it normally would. If you
563 also want to prevent long comment lines from being outdented, you
564 can add either -noll or -l=0.
565
566 Setting this flag will prevent perltidy from doing any special
567 operations on closing side comments. You may still delete all side
568 comments however when this flag is in effect.
569
570 -enc=s, --character-encoding=s
571 This flag indicates the character encoding, if any, of the input
572 data stream. Perltidy does not look for the encoding directives in
573 the soure stream, such as use utf8, and instead relies on this flag
574 to determine the encoding. (Note that perltidy often works on
575 snippets of code rather than complete files so it cannot rely on
576 use utf8 directives).
577
578 The possible values for s [22mare (1) the name of an encoding
579 recognized by the Encode.pm module, (2) none if no encoding is
580 used, or (3) <guess> if perltidy should guess.
581
582 For example, the value utf8 causes the stream to be read and
583 written as UTF-8. If the input stream cannot be decoded with a
584 specified encoding then processing is not done.
585
586 The value none causes the stream to be processed without special
587 encoding assumptions. This is appropriate for files which are
588 written in single-byte character encodings such as latin-1.
589
590 The value guess tells perltidy to guess between either utf8
591 encoding or no encoding (meaning one character per byte). The
592 guess uses the Encode::Guess module and this restricted range of
593 guesses covers the most common cases. Testing showed that
594 considering any greater number of encodings as guess suspects is
595 too risky.
596
597 The current default is guess.
598
599 The abbreviations -utf8 or -UTF8 are equivalent to -enc=utf8, and
600 the abbreviation -guess is equivalent to <-enc=guess>. So to
601 process a file named file.pl which is encoded in UTF-8 you can use:
602
603 perltidy -utf8 file.pl
604
605 or
606 perltidy -guess file.pl
607
608 To process a file in euc-jp you could use
609
610 perltidy -enc=euc-jp file.pl
611
612 A perltidy output file is unencoded if the input file is unencoded,
613 and otherwise it is encoded as utf8, even if the input encoding was
614 not utf8.
615
616 -gcs, --use-unicode-gcstring
617 This flag controls whether or not perltidy may use module
618 Unicode::GCString to obtain accurate display widths of wide
619 characters. The default is --nouse-unicode-gcstring.
620
621 If this flag is set, and text is encoded, perltidy will look for
622 the module Unicode::GCString and, if found, will use it to obtain
623 character display widths. This can improve displayed vertical
624 alignment for files with wide characters. It is a nice feature but
625 it is off by default to avoid conflicting formatting when there are
626 multiple developers. Perltidy installation does not require
627 Unicode::GCString, so users wanting to use this feature need set
628 this flag and also to install Unicode::GCString separately.
629
630 If this flag is set and perltidy does not find module
631 Unicode::GCString, a warning message will be produced and
632 processing will continue but without the potential benefit provided
633 by the module.
634
635 Also note that actual vertical alignment depends upon the fonts
636 used by the text display software, so vertical alignment may not be
637 optimal even when Unicode::GCString is used.
638
639 -ole=s, --output-line-ending=s
640 where s="win", "dos", "unix", or "mac". This flag tells perltidy
641 to output line endings for a specific system. Normally, perltidy
642 writes files with the line separator character of the host system.
643 The "win" and "dos" flags have an identical result.
644
645 -ple, --preserve-line-endings
646 This flag tells perltidy to write its output files with the same
647 line endings as the input file, if possible. It should work for
648 dos, unix, and mac line endings. It will only work if perltidy
649 input comes from a filename (rather than stdin, for example). If
650 perltidy has trouble determining the input file line ending, it
651 will revert to the default behavior of using the line ending of the
652 host system.
653
654 -it=n, --iterations=n
655 This flag causes perltidy to do n complete iterations. The reason
656 for this flag is that code beautification is an iterative process
657 and in some cases the output from perltidy can be different if it
658 is applied a second time. For most purposes the default of n=1
659 should be satisfactory. However n=2 can be useful when a major
660 style change is being made, or when code is being beautified on
661 check-in to a source code control system. It has been found to be
662 extremely rare for the output to change after 2 iterations. If a
663 value n is greater than 2 is input then a convergence test will be
664 used to stop the iterations as soon as possible, almost always
665 after 2 iterations. See the next item for a simplified iteration
666 control.
667
668 This flag has no effect when perltidy is used to generate html.
669
670 -conv, --converge
671 This flag is equivalent to -it=4 and is included to simplify
672 iteration control. For all practical purposes one either does or
673 does not want to be sure that the output is converged, and there is
674 no penalty to using a large iteration limit since perltidy will
675 check for convergence and stop iterating as soon as possible. The
676 default is -nconv (no convergence check). Using -conv will
677 approximately double run time since typically one extra iteration
678 is required to verify convergence. No extra iterations are
679 required if no new line breaks are made, and two extra iterations
680 are occasionally needed when reformatting complex code structures,
681 such as deeply nested ternary statements.
682
683 Code Indentation Control
684 -ci=n, --continuation-indentation=n
685 Continuation indentation is extra indentation spaces applied when a
686 long line is broken. The default is n=2, illustrated here:
687
688 my $level = # -ci=2
689 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
690
691 The same example, with n=0, is a little harder to read:
692
693 my $level = # -ci=0
694 ( $max_index_to_go >= 0 ) ? $levels_to_go[0] : $last_output_level;
695
696 The value given to -ci is also used by some commands when a small
697 space is required. Examples are commands for outdenting labels,
698 -ola, and control keywords, -okw.
699
700 When default values are not used, it is recommended that either
701
702 (1) the value n given with -ci=n be no more than about one-half of
703 the number of spaces assigned to a full indentation level on the
704 -i=n command, or
705
706 (2) the flag -extended-continuation-indentation is used (see next
707 section).
708
709 -xci, --extended-continuation-indentation
710 This flag allows perltidy to use some improvements which have been
711 made to its indentation model. One of the things it does is
712 "extend" continuation indentation deeper into structures, hence the
713 name. The improved indentation is particularly noticable when the
714 flags -ci=n and -i=n use the same value of n. There are no
715 significant disadvantages to using this flag, but to avoid
716 disturbing existing formatting the default is not to use it, -nxci.
717
718 Please see the section "-pbp, --perl-best-practices" for an example
719 of how this flag can improve the formatting of ternary statements.
720 It can also improve indentation of some multi-line qw lists as
721 shown below.
722
723 # perltidy
724 foreach $color (
725 qw(
726 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
727 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
728 ),
729 qw(
730 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
731 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
732 )
733 )
734
735 # perltidy -xci
736 foreach $color (
737 qw(
738 AntiqueWhite3 Bisque1 Bisque2 Bisque3 Bisque4
739 SlateBlue3 RoyalBlue1 SteelBlue2 DeepSkyBlue3
740 ),
741 qw(
742 LightBlue1 DarkSlateGray1 Aquamarine2 DarkSeaGreen2
743 SeaGreen1 Yellow1 IndianRed1 IndianRed2 Tan1 Tan4
744 )
745 )
746
747 -sil=n --starting-indentation-level=n
748 By default, perltidy examines the input file and tries to determine
749 the starting indentation level. While it is often zero, it may not
750 be zero for a code snippet being sent from an editing session.
751
752 To guess the starting indentation level perltidy simply assumes
753 that indentation scheme used to create the code snippet is the same
754 as is being used for the current perltidy process. This is the
755 only sensible guess that can be made. It should be correct if this
756 is true, but otherwise it probably won't. For example, if the
757 input script was written with -i=2 and the current peltidy flags
758 have -i=4, the wrong initial indentation will be guessed for a code
759 snippet which has non-zero initial indentation. Likewise, if an
760 entabbing scheme is used in the input script and not in the current
761 process then the guessed indentation will be wrong.
762
763 If the default method does not work correctly, or you want to
764 change the starting level, use -sil=n, to force the starting level
765 to be n.
766
767 List indentation using -lp, --line-up-parentheses
768 By default, perltidy indents lists with 4 spaces, or whatever value
769 is specified with -i=n. Here is a small list formatted in this
770 way:
771
772 # perltidy (default)
773 @month_of_year = (
774 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
775 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
776 );
777
778 Use the -lp flag to add extra indentation to cause the data to
779 begin past the opening parentheses of a sub call or list, or
780 opening square bracket of an anonymous array, or opening curly
781 brace of an anonymous hash. With this option, the above list would
782 become:
783
784 # perltidy -lp
785 @month_of_year = (
786 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
787 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
788 );
789
790 If the available line length (see -l=n ) does not permit this much
791 space, perltidy will use less. For alternate placement of the
792 closing paren, see the next section.
793
794 This option has no effect on code BLOCKS, such as if/then/else
795 blocks, which always use whatever is specified with -i=n. Also,
796 the existence of line breaks and/or block comments between the
797 opening and closing parens may cause perltidy to temporarily revert
798 to its default method.
799
800 Note: The -lp option may not be used together with the -t tabs
801 option. It may, however, be used with the -et=n tab method.
802
803 In addition, any parameter which significantly restricts the
804 ability of perltidy to choose newlines will conflict with -lp and
805 will cause -lp to be deactivated. These include -io, -fnl, -nanl,
806 and -ndnl. The reason is that the -lp indentation style can
807 require the careful coordination of an arbitrary number of break
808 points in hierarchical lists, and these flags may prevent that.
809
810 -lpxl=s, --line-up-parentheses-exclusion-list
811 This is an experimental parameter; the details might change as
812 experience with it is gained.
813
814 The -lp indentation style works well for some types of coding but
815 can produce very long lines when variables have long names and/or
816 containers are very deeply nested. The -lpxl=s flag is intended to
817 help mitigate this problem by providing control over the containers
818 to which the -lp indentation style is applied. The -lp flag by
819 default is "greedy" and applies to as many containers as possible.
820 This flag specifies a list of things which should not be use -lp
821 indentation.
822
823 This list is a string with space-separated items. Each item
824 consists of up to three pieces of information in this order: (1) an
825 optional letter code (2) a required container type, and (3) an
826 optional numeric code.
827
828 The only required piece of information is a container type, which
829 is one of '(', '[', or '{'. For example the string
830
831 -lpxl='[ {'
832
833 means do NOT include use -lp formatting within square-bracets or
834 braces. The only unspecified container is '(', so this string
835 means that only the contens within parens will use -lp indentation.
836
837 An optional numeric code may follow any of the container types to
838 further refine the selection based on container contents. The
839 numeric codes are:
840
841 '0' or blank: no check on contents
842 '1' reject -lp unless the contents is a simple list without sublists
843 '2' reject -lp unless the contents is a simple list without sublists, without
844 code blocks, and without ternary operators
845
846 For example,
847
848 -lpxl = '[ { (2'
849
850 means only apply -lp to parenthesized lists which do not contain
851 any sublists, code blocks or ternary expressions.
852
853 A third optional item of information which can be given for parens
854 is an alphanumeric letter which is used to limit the selection
855 further depending on the type of token immediately before the
856 paren. The possible letters are currently 'k', 'K', 'f', 'F', 'w',
857 and 'W', with these meanings:
858
859 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
860 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
861 'f' matches if the previous token is a function other than a keyword.
862 'F' matches if 'f' does not.
863 'w' matches if either 'k' or 'f' match.
864 'W' matches if 'w' does not.
865
866 For example,
867
868 -lpxl = '[ { F(2'
869
870 means only apply -lp to parenthesized lists which follow a function
871 call and which do not contain any sublists, code blocks or ternary
872 expressions. The logic of writing these codes is somewhat counter-
873 intuitive because they describe what is not getting the -lp
874 indentation. So the 'F' indicates that non-function calls are not
875 getting -lp, or in other words that function calls are getting the
876 -lp indentation.
877
878 -cti=n, --closing-token-indentation
879 The -cti=n flag controls the indentation of a line beginning with a
880 ")", "]", or a non-block "}". Such a line receives:
881
882 -cti = 0 no extra indentation (default)
883 -cti = 1 extra indentation such that the closing token
884 aligns with its opening token.
885 -cti = 2 one extra indentation level if the line looks like:
886 ); or ]; or };
887 -cti = 3 one extra indentation level always
888
889 The flags -cti=1 and -cti=2 work well with the -lp flag (previous
890 section).
891
892 # perltidy -lp -cti=1
893 @month_of_year = (
894 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
895 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
896 );
897
898 # perltidy -lp -cti=2
899 @month_of_year = (
900 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
901 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
902 );
903
904 These flags are merely hints to the formatter and they may not
905 always be followed. In particular, if -lp is not being used, the
906 indentation for cti=1 is constrained to be no more than one
907 indentation level.
908
909 If desired, this control can be applied independently to each of
910 the closing container token types. In fact, -cti=n is merely an
911 abbreviation for -cpi=n -csbi=n -cbi=n, where: -cpi or
912 --closing-paren-indentation controls )'s, -csbi or
913 --closing-square-bracket-indentation controls ]'s, -cbi or
914 --closing-brace-indentation controls non-block }'s.
915
916 -icp, --indent-closing-paren
917 The -icp flag is equivalent to -cti=2, described in the previous
918 section. The -nicp flag is equivalent -cti=0. They are included
919 for backwards compatibility.
920
921 -icb, --indent-closing-brace
922 The -icb option gives one extra level of indentation to a brace
923 which terminates a code block . For example,
924
925 if ($task) {
926 yyy();
927 } # -icb
928 else {
929 zzz();
930 }
931
932 The default is not to do this, indicated by -nicb.
933
934 -nib, --non-indenting-braces
935 Normally, lines of code contained within a pair of block braces
936 receive one additional level of indentation. This flag, which is
937 enabled by default, causes perltidy to look for opening block
938 braces which are followed by a special side comment. This special
939 side comment is #<<< by default. If found, the code between this
940 opening brace and its corresponding closing brace will not be given
941 the normal extra indentation level. For example:
942
943 { #<<< a closure to contain lexical vars
944
945 my $var; # this line does not get one level of indentation
946 ...
947
948 }
949
950 # this line does not 'see' $var;
951
952 This can be useful, for example, when combining code from different
953 files. Different sections of code can be placed within braces to
954 keep their lexical variables from being visible to the end of the
955 file. To keep the new braces from causing all of their contained
956 code to be indented if you run perltidy, and possibly introducing
957 new line breaks in long lines, you can mark the opening braces with
958 this special side comment.
959
960 Only the opening brace needs to be marked, since perltidy knows
961 where the closing brace is. Braces contained within marked braces
962 may also be marked as non-indenting.
963
964 If your code happens to have some opening braces followed by
965 '#<<<', and you don't want this behavior, you can use -nnib to
966 deactivate it. To make it easy to remember, the default string is
967 the same as the string for starting a format-skipping section.
968 There is no confusion because in that case it is for a block
969 comment rather than a side-comment.
970
971 The special side comment can be changed with the next parameter.
972
973 -nibp=s, --non-indenting-brace-prefix=s
974 The -nibp=string parameter may be used to change the marker for
975 non-indenting braces. The default is equivalent to -nibp='#<<<'.
976 The string that you enter must begin with a # and should be in
977 quotes as necessary to get past the command shell of your system.
978 This string is the leading text of a regex pattern that is
979 constructed by appending pre-pending a '^' and appending a'\s', so
980 you must also include backslashes for characters to be taken
981 literally rather than as patterns.
982
983 For example, to match the side comment '#++', the parameter would
984 be
985
986 -nibp='#\+\+'
987
988 -olq, --outdent-long-quotes
989 When -olq is set, lines which is a quoted string longer than the
990 value maximum-line-length will have their indentation removed to
991 make them more readable. This is the default. To prevent such
992 out-denting, use -nolq or --nooutdent-long-lines.
993
994 -oll, --outdent-long-lines
995 This command is equivalent to --outdent-long-quotes and
996 --outdent-long-comments, and it is included for compatibility with
997 previous versions of perltidy. The negation of this also works,
998 -noll or --nooutdent-long-lines, and is equivalent to setting -nolq
999 and -nolc.
1000
1001 Outdenting Labels: -ola, --outdent-labels
1002 This command will cause labels to be outdented by 2 spaces (or
1003 whatever -ci has been set to), if possible. This is the default.
1004 For example:
1005
1006 my $i;
1007 LOOP: while ( $i = <FOTOS> ) {
1008 chomp($i);
1009 next unless $i;
1010 fixit($i);
1011 }
1012
1013 Use -nola to not outdent labels.
1014
1015 Outdenting Keywords
1016 -okw, --outdent-keywords
1017 The command -okw will cause certain leading control keywords to
1018 be outdented by 2 spaces (or whatever -ci has been set to), if
1019 possible. By default, these keywords are "redo", "next",
1020 "last", "goto", and "return". The intention is to make these
1021 control keywords easier to see. To change this list of
1022 keywords being outdented, see the next section.
1023
1024 For example, using "perltidy -okw" on the previous example
1025 gives:
1026
1027 my $i;
1028 LOOP: while ( $i = <FOTOS> ) {
1029 chomp($i);
1030 next unless $i;
1031 fixit($i);
1032 }
1033
1034 The default is not to do this.
1035
1036 Specifying Outdented Keywords: -okwl=string,
1037 --outdent-keyword-list=string
1038 This command can be used to change the keywords which are
1039 outdented with the -okw command. The parameter string is a
1040 required list of perl keywords, which should be placed in
1041 quotes if there are more than one. By itself, it does not
1042 cause any outdenting to occur, so the -okw command is still
1043 required.
1044
1045 For example, the commands "-okwl="next last redo goto" -okw"
1046 will cause those four keywords to be outdented. It is probably
1047 simplest to place any -okwl command in a .perltidyrc file.
1048
1049 Whitespace Control
1050 Whitespace refers to the blank space between variables, operators, and
1051 other code tokens.
1052
1053 -fws, --freeze-whitespace
1054 This flag causes your original whitespace to remain unchanged, and
1055 causes the rest of the whitespace commands in this section, the
1056 Code Indentation section, and the Comment Control section to be
1057 ignored.
1058
1059 Tightness of curly braces, parentheses, and square brackets
1060 Here the term "tightness" will mean the closeness with which pairs
1061 of enclosing tokens, such as parentheses, contain the quantities
1062 within. A numerical value of 0, 1, or 2 defines the tightness,
1063 with 0 being least tight and 2 being most tight. Spaces within
1064 containers are always symmetric, so if there is a space after a "("
1065 then there will be a space before the corresponding ")".
1066
1067 The -pt=n or --paren-tightness=n parameter controls the space
1068 within parens. The example below shows the effect of the three
1069 possible values, 0, 1, and 2:
1070
1071 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0
1072 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default)
1073 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2
1074
1075 When n is 0, there is always a space to the right of a '(' and to
1076 the left of a ')'. For n=2 there is never a space. For n=1, the
1077 default, there is a space unless the quantity within the parens is
1078 a single token, such as an identifier or quoted string.
1079
1080 Likewise, the parameter -sbt=n or --square-bracket-tightness=n
1081 controls the space within square brackets, as illustrated below.
1082
1083 $width = $col[ $j + $k ] - $col[ $j ]; # -sbt=0
1084 $width = $col[ $j + $k ] - $col[$j]; # -sbt=1 (default)
1085 $width = $col[$j + $k] - $col[$j]; # -sbt=2
1086
1087 Curly braces which do not contain code blocks are controlled by the
1088 parameter -bt=n or --brace-tightness=n.
1089
1090 $obj->{ $parsed_sql->{ 'table' }[0] }; # -bt=0
1091 $obj->{ $parsed_sql->{'table'}[0] }; # -bt=1 (default)
1092 $obj->{$parsed_sql->{'table'}[0]}; # -bt=2
1093
1094 And finally, curly braces which contain blocks of code are
1095 controlled by the parameter -bbt=n or --block-brace-tightness=n as
1096 illustrated in the example below.
1097
1098 %bf = map { $_ => -M $_ } grep { /\.deb$/ } dirents '.'; # -bbt=0 (default)
1099 %bf = map { $_ => -M $_ } grep {/\.deb$/} dirents '.'; # -bbt=1
1100 %bf = map {$_ => -M $_} grep {/\.deb$/} dirents '.'; # -bbt=2
1101
1102 To simplify input in the case that all of the tightness flags have
1103 the same value <n>, the parameter <-act=n> or
1104 --all-containers-tightness=n is an abbreviation for the combination
1105 <-pt=n -sbt=n -bt=n -bbt=n>.
1106
1107 -tso, --tight-secret-operators
1108 The flag -tso causes certain perl token sequences (secret
1109 operators) which might be considered to be a single operator to be
1110 formatted "tightly" (without spaces). The operators currently
1111 modified by this flag are:
1112
1113 0+ +0 ()x!! ~~<> ,=> =( )=
1114
1115 For example the sequence 0 +, which converts a string to a number,
1116 would be formatted without a space: 0+ when the -tso flag is set.
1117 This flag is off by default.
1118
1119 -sts, --space-terminal-semicolon
1120 Some programmers prefer a space before all terminal semicolons.
1121 The default is for no such space, and is indicated with -nsts or
1122 --nospace-terminal-semicolon.
1123
1124 $i = 1 ; # -sts
1125 $i = 1; # -nsts (default)
1126
1127 -sfs, --space-for-semicolon
1128 Semicolons within for loops may sometimes be hard to see,
1129 particularly when commas are also present. This option places
1130 spaces on both sides of these special semicolons, and is the
1131 default. Use -nsfs or --nospace-for-semicolon to deactivate it.
1132
1133 for ( @a = @$ap, $u = shift @a ; @a ; $u = $v ) { # -sfs (default)
1134 for ( @a = @$ap, $u = shift @a; @a; $u = $v ) { # -nsfs
1135
1136 -asc, --add-semicolons
1137 Setting -asc allows perltidy to add any missing optional semicolon
1138 at the end of a line which is followed by a closing curly brace on
1139 the next line. This is the default, and may be deactivated with
1140 -nasc or --noadd-semicolons.
1141
1142 -dsm, --delete-semicolons
1143 Setting -dsm allows perltidy to delete extra semicolons which are
1144 simply empty statements. This is the default, and may be
1145 deactivated with -ndsm or --nodelete-semicolons. (Such semicolons
1146 are not deleted, however, if they would promote a side comment to a
1147 block comment).
1148
1149 -aws, --add-whitespace
1150 Setting this option allows perltidy to add certain whitespace to
1151 improve code readability. This is the default. If you do not want
1152 any whitespace added, but are willing to have some whitespace
1153 deleted, use -naws. (Use -fws to leave whitespace completely
1154 unchanged).
1155
1156 -dws, --delete-old-whitespace
1157 Setting this option allows perltidy to remove some old whitespace
1158 between characters, if necessary. This is the default. If you do
1159 not want any old whitespace removed, use -ndws or
1160 --nodelete-old-whitespace.
1161
1162 Detailed whitespace controls around tokens
1163 For those who want more detailed control over the whitespace around
1164 tokens, there are four parameters which can directly modify the
1165 default whitespace rules built into perltidy for any token. They
1166 are:
1167
1168 -wls=s or --want-left-space=s,
1169
1170 -nwls=s or --nowant-left-space=s,
1171
1172 -wrs=s or --want-right-space=s,
1173
1174 -nwrs=s or --nowant-right-space=s.
1175
1176 These parameters are each followed by a quoted string, s,
1177 containing a list of token types. No more than one of each of
1178 these parameters should be specified, because repeating a command-
1179 line parameter always overwrites the previous one before perltidy
1180 ever sees it.
1181
1182 To illustrate how these are used, suppose it is desired that there
1183 be no space on either side of the token types = + - / *. The
1184 following two parameters would specify this desire:
1185
1186 -nwls="= + - / *" -nwrs="= + - / *"
1187
1188 (Note that the token types are in quotes, and that they are
1189 separated by spaces). With these modified whitespace rules, the
1190 following line of math:
1191
1192 $root = -$b + sqrt( $b * $b - 4. * $a * $c ) / ( 2. * $a );
1193
1194 becomes this:
1195
1196 $root=-$b+sqrt( $b*$b-4.*$a*$c )/( 2.*$a );
1197
1198 These parameters should be considered to be hints to perltidy
1199 rather than fixed rules, because perltidy must try to resolve
1200 conflicts that arise between them and all of the other rules that
1201 it uses. One conflict that can arise is if, between two tokens,
1202 the left token wants a space and the right one doesn't. In this
1203 case, the token not wanting a space takes priority.
1204
1205 It is necessary to have a list of all token types in order to
1206 create this type of input. Such a list can be obtained by the
1207 command --dump-token-types. Also try the -D flag on a short
1208 snippet of code and look at the .DEBUG file to see the
1209 tokenization.
1210
1211 WARNING Be sure to put these tokens in quotes to avoid having them
1212 misinterpreted by your command shell.
1213
1214 Note1: Perltidy does always follow whitespace controls
1215 The various parameters controlling whitespace within a program are
1216 requests which perltidy follows as well as possible, but there are
1217 a number of situations where changing whitespace could change
1218 program behavior and is not done. Some of these are obvious; for
1219 example, we should not remove the space between the two plus
1220 symbols in '$x+ +$y' to avoid creating a '++' operator. Some are
1221 more subtle and involve the whitespace around bareword symbols and
1222 locations of possible filehandles. For example, consider the
1223 problem of formatting the following subroutine:
1224
1225 sub print_div {
1226 my ($x,$y)=@_;
1227 print $x/$y;
1228 }
1229
1230 Suppose the user requests that / signs have a space to the left but
1231 not to the right. Perltidy will refuse to do this, but if this were
1232 done the result would be
1233
1234 sub print_div {
1235 my ($x,$y)=@_;
1236 print $x /$y;
1237 }
1238
1239 If formatted in this way, the program will not run (at least with
1240 recent versions of perl) because the $x is taken to be a filehandle
1241 and / is assumed to start a quote. In a complex program, there
1242 might happen to be a / which terminates the multiline quote without
1243 a syntax error, allowing the program to run, but not as intended.
1244
1245 Related issues arise with other binary operator symbols, such as +
1246 and -, and in older versions of perl there could be problems with
1247 ternary operators. So to avoid changing program behavior, perltidy
1248 has the simple rule that whitespace around possible filehandles is
1249 left unchanged. Likewise, whitespace around barewords is left
1250 unchanged. The reason is that if the barewords are defined in
1251 other modules, or in code that has not even been written yet,
1252 perltidy will not have seen their prototypes and must treat them
1253 cautiously.
1254
1255 In perltidy this is implemented in the tokenizer by marking token
1256 following a print keyword as a special type Z. When formatting is
1257 being done, whitespace following this token type is generally left
1258 unchanged as a precaution against changing program behavior. This
1259 is excessively conservative but simple and easy to implement.
1260 Keywords which are treated similarly to print include printf, sort,
1261 exec, system. Changes in spacing around parameters following these
1262 keywords may have to be made manually. For example, the space, or
1263 lack of space, after the parameter $foo in the following line will
1264 be unchanged in formatting.
1265
1266 system($foo );
1267 system($foo);
1268
1269 To find if a token is of type Z you can use perltidy -DEBUG. For
1270 the first line above the result is
1271
1272 1: system($foo );
1273 1: kkkkkk{ZZZZb};
1274
1275 which shows that system is type k (keyword) and $foo is type Z.
1276
1277 Note2: Perltidy's whitespace rules are not perfect
1278 Despite these precautions, it is still possible to introduce syntax
1279 errors with some asymmetric whitespace rules, particularly when
1280 call parameters are not placed in containg parens or braces. For
1281 example, the following two lines will be parsed by perl without a
1282 syntax error:
1283
1284 # original programming, syntax ok
1285 my @newkeys = map $_-$nrecs+@data, @oldkeys;
1286
1287 # perltidy default, syntax ok
1288 my @newkeys = map $_ - $nrecs + @data, @oldkeys;
1289
1290 But the following will give a syntax error:
1291
1292 # perltidy -nwrs='-'
1293 my @newkeys = map $_ -$nrecs + @data, @oldkeys;
1294
1295 For another example, the following two lines will be parsed without
1296 syntax error:
1297
1298 # original programming, syntax ok
1299 for my $severity ( reverse $SEVERITY_LOWEST+1 .. $SEVERITY_HIGHEST ) { ... }
1300
1301 # perltidy default, syntax ok
1302 for my $severity ( reverse $SEVERITY_LOWEST + 1 .. $SEVERITY_HIGHEST ) { ... }
1303
1304 But the following will give a syntax error:
1305
1306 # perltidy -nwrs='+', syntax error:
1307 for my $severity ( reverse $SEVERITY_LOWEST +1 .. $SEVERITY_HIGHEST ) { ... }
1308
1309 To avoid subtle parsing problems like this, it is best to avoid
1310 spacing a binary operator asymetrically with a space on the left
1311 but not on the right.
1312
1313 Space between specific keywords and opening paren
1314 When an opening paren follows a Perl keyword, no space is
1315 introduced after the keyword, unless it is (by default) one of
1316 these:
1317
1318 my local our and or xor eq ne if else elsif until unless
1319 while for foreach return switch case given when
1320
1321 These defaults can be modified with two commands:
1322
1323 -sak=s or --space-after-keyword=s adds keywords.
1324
1325 -nsak=s or --nospace-after-keyword=s removes keywords.
1326
1327 where s is a list of keywords (in quotes if necessary). For
1328 example,
1329
1330 my ( $a, $b, $c ) = @_; # default
1331 my( $a, $b, $c ) = @_; # -nsak="my local our"
1332
1333 The abbreviation -nsak='*' is equivalent to including all of the
1334 keywords in the above list.
1335
1336 When both -nsak=s and -sak=s commands are included, the -nsak=s
1337 command is executed first. For example, to have space after only
1338 the keywords (my, local, our) you could use -nsak="*" -sak="my
1339 local our".
1340
1341 To put a space after all keywords, see the next item.
1342
1343 Space between all keywords and opening parens
1344 When an opening paren follows a function or keyword, no space is
1345 introduced after the keyword except for the keywords noted in the
1346 previous item. To always put a space between a function or keyword
1347 and its opening paren, use the command:
1348
1349 -skp or --space-keyword-paren
1350
1351 You may also want to use the flag -sfp (next item) too.
1352
1353 Space between all function names and opening parens
1354 When an opening paren follows a function the default and
1355 recommended formatting is not to introduce a space. To cause a
1356 space to be introduced use:
1357
1358 -sfp or --space-function-paren
1359
1360 myfunc( $a, $b, $c ); # default
1361 myfunc ( $a, $b, $c ); # -sfp
1362
1363 You will probably also want to use the flag -skp (previous item)
1364 too.
1365
1366 The reason this is not recommended is that spacing a function paren
1367 can make a program vulnerable to parsing problems by Perl. For
1368 example, the following two-line program will run as written but
1369 will have a syntax error if reformatted with -sfp:
1370
1371 if ( -e filename() ) { print "I'm here\n"; }
1372 sub filename { return $0 }
1373
1374 In this particular case the syntax error can be removed if the line
1375 order is reversed, so that Perl parses 'sub filename' first.
1376
1377 -fpva or --function-paren-vertical-alignment
1378 A side-effect of using the -sfp flag is that the parens may become
1379 vertically aligned. For example,
1380
1381 # perltidy -sfp
1382 myfun ( $aaa, $b, $cc );
1383 mylongfun ( $a, $b, $c );
1384
1385 This is the default behavior. To prevent this alignment use
1386 -nfpva:
1387
1388 # perltidy -sfp -nfpva
1389 myfun ( $aaa, $b, $cc );
1390 mylongfun ( $a, $b, $c );
1391
1392 -spp=n or --space-prototype-paren=n
1393 This flag can be used to control whether a function prototype is
1394 preceded by a space. For example, the following prototype does not
1395 have a space.
1396
1397 sub usage();
1398
1399 This integer n may have the value 0, 1, or 2 as follows:
1400
1401 -spp=0 means no space before the paren
1402 -spp=1 means follow the example of the source code [DEFAULT]
1403 -spp=2 means always put a space before the paren
1404
1405 The default is -spp=1, meaning that a space will be used if and
1406 only if there is one in the source code. Given the above line of
1407 code, the result of applying the different options would be:
1408
1409 sub usage(); # n=0 [no space]
1410 sub usage(); # n=1 [default; follows input]
1411 sub usage (); # n=2 [space]
1412
1413 -kpit=n or --keyword-paren-inner-tightness=n
1414 The space inside of an opening paren, which itself follows a
1415 certain keyword, can be controlled by this parameter. The space on
1416 the inside of the corresponding closing paren will be treated in
1417 the same (balanced) manner. This parameter has precedence over any
1418 other paren spacing rules. The values of n are as follows:
1419
1420 -kpit=0 means always put a space (not tight)
1421 -kpit=1 means ignore this parameter [default]
1422 -kpit=2 means never put a space (tight)
1423
1424 To illustrate, the following snippet is shown formatted in three
1425 ways:
1426
1427 if ( seek( DATA, 0, 0 ) ) { ... } # perltidy (default)
1428 if (seek(DATA, 0, 0)) { ... } # perltidy -pt=2
1429 if ( seek(DATA, 0, 0) ) { ... } # perltidy -pt=2 -kpit=0
1430
1431 In the second case the -pt=2 parameter makes all of the parens
1432 tight. In the third case the -kpit=0 flag causes the space within
1433 the 'if' parens to have a space, since 'if' is one of the keywords
1434 to which the -kpit flag applies by default. The remaining parens
1435 are still tight because of the -pt=2 parameter.
1436
1437 The set of keywords to which this parameter applies are by default
1438 are:
1439
1440 if elsif unless while until for foreach
1441
1442 These can be changed with the parameter -kpitl=s described in the
1443 next section.
1444
1445 -kpitl=string or --keyword-paren-inner-tightness=string
1446 This command can be used to change the keywords to which the the
1447 -kpit=n command applies. The parameter string is a required list
1448 either keywords or functions, which should be placed in quotes if
1449 there are more than one. By itself, this parameter does not cause
1450 any change in spacing, so the -kpit=n command is still required.
1451
1452 For example, the commands "-kpitl="if else while" -kpit=2" will
1453 cause the just the spaces inside parens following 'if', 'else',
1454 and 'while' keywords to follow the tightness value indicated by the
1455 -kpit=2 flag.
1456
1457 -lop or --logical-padding
1458 In the following example some extra space has been inserted on the
1459 second line between the two open parens. This extra space is called
1460 "logical padding" and is intended to help align similar things
1461 vertically in some logical or ternary expressions.
1462
1463 # perltidy [default formatting]
1464 $same =
1465 ( ( $aP eq $bP )
1466 && ( $aS eq $bS )
1467 && ( $aT eq $bT )
1468 && ( $a->{'title'} eq $b->{'title'} )
1469 && ( $a->{'href'} eq $b->{'href'} ) );
1470
1471 Note that this is considered to be a different operation from
1472 "vertical alignment" because space at just one line is being
1473 adjusted, whereas in "vertical alignment" the spaces at all lines
1474 are being adjusted. So it sort of a local version of vertical
1475 alignment.
1476
1477 Here is an example involving a ternary operator:
1478
1479 # perltidy [default formatting]
1480 $bits =
1481 $top > 0xffff ? 32
1482 : $top > 0xff ? 16
1483 : $top > 1 ? 8
1484 : 1;
1485
1486 This behavior is controlled with the flag --logical-padding, which
1487 is set 'on' by default. If it is not desired it can be turned off
1488 using --nological-padding or -nlop. The above two examples become,
1489 with -nlop:
1490
1491 # perltidy -nlop
1492 $same =
1493 ( ( $aP eq $bP )
1494 && ( $aS eq $bS )
1495 && ( $aT eq $bT )
1496 && ( $a->{'title'} eq $b->{'title'} )
1497 && ( $a->{'href'} eq $b->{'href'} ) );
1498
1499 # perltidy -nlop
1500 $bits =
1501 $top > 0xffff ? 32
1502 : $top > 0xff ? 16
1503 : $top > 1 ? 8
1504 : 1;
1505
1506 Trimming whitespace around "qw" quotes
1507 -tqw or --trim-qw provide the default behavior of trimming spaces
1508 around multi-line "qw" quotes and indenting them appropriately.
1509
1510 -ntqw or --notrim-qw cause leading and trailing whitespace around
1511 multi-line "qw" quotes to be left unchanged. This option will not
1512 normally be necessary, but was added for testing purposes, because
1513 in some versions of perl, trimming "qw" quotes changes the syntax
1514 tree.
1515
1516 -sbq=n or --space-backslash-quote=n
1517 lines like
1518
1519 $str1=\"string1";
1520 $str2=\'string2';
1521
1522 can confuse syntax highlighters unless a space is included between
1523 the backslash and the single or double quotation mark.
1524
1525 this can be controlled with the value of n as follows:
1526
1527 -sbq=0 means no space between the backslash and quote
1528 -sbq=1 means follow the example of the source code
1529 -sbq=2 means always put a space between the backslash and quote
1530
1531 The default is -sbq=1, meaning that a space will be used if there
1532 is one in the source code.
1533
1534 Trimming trailing whitespace from lines of POD
1535 -trp or --trim-pod will remove trailing whitespace from lines of
1536 POD. The default is not to do this.
1537
1538 Comment Controls
1539 Perltidy has a number of ways to control the appearance of both block
1540 comments and side comments. The term block comment here refers to a
1541 full-line comment, whereas side comment will refer to a comment which
1542 appears on a line to the right of some code.
1543
1544 -ibc, --indent-block-comments
1545 Block comments normally look best when they are indented to the
1546 same level as the code which follows them. This is the default
1547 behavior, but you may use -nibc to keep block comments left-
1548 justified. Here is an example:
1549
1550 # this comment is indented (-ibc, default)
1551 if ($task) { yyy(); }
1552
1553 The alternative is -nibc:
1554
1555 # this comment is not indented (-nibc)
1556 if ($task) { yyy(); }
1557
1558 See also the next item, -isbc, as well as -sbc, for other ways to
1559 have some indented and some outdented block comments.
1560
1561 -isbc, --indent-spaced-block-comments
1562 If there is no leading space on the line, then the comment will not
1563 be indented, and otherwise it may be.
1564
1565 If both -ibc and -isbc are set, then -isbc takes priority.
1566
1567 -olc, --outdent-long-comments
1568 When -olc is set, lines which are full-line (block) comments longer
1569 than the value maximum-line-length will have their indentation
1570 removed. This is the default; use -nolc to prevent outdenting.
1571
1572 -msc=n, --minimum-space-to-comment=n
1573 Side comments look best when lined up several spaces to the right
1574 of code. Perltidy will try to keep comments at least n spaces to
1575 the right. The default is n=4 spaces.
1576
1577 -fpsc=n, --fixed-position-side-comment=n
1578 This parameter tells perltidy to line up side comments in column
1579 number n whenever possible. The default, n=0, will not do this.
1580
1581 -iscl, --ignore-side-comment-lengths
1582 This parameter causes perltidy to ignore the length of side
1583 comments when setting line breaks. The default, -niscl, is to
1584 include the length of side comments when breaking lines to stay
1585 within the length prescribed by the -l=n maximum line length
1586 parameter. For example, the following long single line would
1587 remain intact with -l=80 and -iscl:
1588
1589 perltidy -l=80 -iscl
1590 $vmsfile =~ s/;[\d\-]*$//; # Clip off version number; we can use a newer version as well
1591
1592 whereas without the -iscl flag the line will be broken:
1593
1594 perltidy -l=80
1595 $vmsfile =~ s/;[\d\-]*$//
1596 ; # Clip off version number; we can use a newer version as well
1597
1598 -hsc, --hanging-side-comments
1599 By default, perltidy tries to identify and align "hanging side
1600 comments", which are something like this:
1601
1602 my $IGNORE = 0; # This is a side comment
1603 # This is a hanging side comment
1604 # And so is this
1605
1606 A comment is considered to be a hanging side comment if (1) it
1607 immediately follows a line with a side comment, or another hanging
1608 side comment, and (2) there is some leading whitespace on the line.
1609 To deactivate this feature, use -nhsc or --nohanging-side-comments.
1610 If block comments are preceded by a blank line, or have no leading
1611 whitespace, they will not be mistaken as hanging side comments.
1612
1613 Closing Side Comments
1614 A closing side comment is a special comment which perltidy can
1615 automatically create and place after the closing brace of a code
1616 block. They can be useful for code maintenance and debugging. The
1617 command -csc (or --closing-side-comments) adds or updates closing
1618 side comments. For example, here is a small code snippet
1619
1620 sub message {
1621 if ( !defined( $_[0] ) ) {
1622 print("Hello, World\n");
1623 }
1624 else {
1625 print( $_[0], "\n" );
1626 }
1627 }
1628
1629 And here is the result of processing with "perltidy -csc":
1630
1631 sub message {
1632 if ( !defined( $_[0] ) ) {
1633 print("Hello, World\n");
1634 }
1635 else {
1636 print( $_[0], "\n" );
1637 }
1638 } ## end sub message
1639
1640 A closing side comment was added for "sub message" in this case,
1641 but not for the "if" and "else" blocks, because they were below the
1642 6 line cutoff limit for adding closing side comments. This limit
1643 may be changed with the -csci command, described below.
1644
1645 The command -dcsc (or --delete-closing-side-comments) reverses this
1646 process and removes these comments.
1647
1648 Several commands are available to modify the behavior of these two
1649 basic commands, -csc and -dcsc:
1650
1651 -csci=n, or --closing-side-comment-interval=n
1652 where "n" is the minimum number of lines that a block must have
1653 in order for a closing side comment to be added. The default
1654 value is "n=6". To illustrate:
1655
1656 # perltidy -csci=2 -csc
1657 sub message {
1658 if ( !defined( $_[0] ) ) {
1659 print("Hello, World\n");
1660 } ## end if ( !defined( $_[0] ))
1661 else {
1662 print( $_[0], "\n" );
1663 } ## end else [ if ( !defined( $_[0] ))
1664 } ## end sub message
1665
1666 Now the "if" and "else" blocks are commented. However, now
1667 this has become very cluttered.
1668
1669 -cscp=string, or --closing-side-comment-prefix=string
1670 where string is the prefix used before the name of the block
1671 type. The default prefix, shown above, is "## end". This
1672 string will be added to closing side comments, and it will also
1673 be used to recognize them in order to update, delete, and
1674 format them. Any comment identified as a closing side comment
1675 will be placed just a single space to the right of its closing
1676 brace.
1677
1678 -cscl=string, or --closing-side-comment-list
1679 where "string" is a list of block types to be tagged with
1680 closing side comments. By default, all code block types
1681 preceded by a keyword or label (such as "if", "sub", and so on)
1682 will be tagged. The -cscl command changes the default list to
1683 be any selected block types; see "Specifying Block Types". For
1684 example, the following command requests that only "sub"'s,
1685 labels, "BEGIN", and "END" blocks be affected by any -csc or
1686 -dcsc operation:
1687
1688 -cscl="sub : BEGIN END"
1689
1690 -csct=n, or --closing-side-comment-maximum-text=n
1691 The text appended to certain block types, such as an "if"
1692 block, is whatever lies between the keyword introducing the
1693 block, such as "if", and the opening brace. Since this might
1694 be too much text for a side comment, there needs to be a limit,
1695 and that is the purpose of this parameter. The default value
1696 is "n=20", meaning that no additional tokens will be appended
1697 to this text after its length reaches 20 characters. Omitted
1698 text is indicated with "...". (Tokens, including sub names,
1699 are never truncated, however, so actual lengths may exceed
1700 this). To illustrate, in the above example, the appended text
1701 of the first block is " ( !defined( $_[0] )...". The existing
1702 limit of "n=20" caused this text to be truncated, as indicated
1703 by the "...". See the next flag for additional control of the
1704 abbreviated text.
1705
1706 -cscb, or --closing-side-comments-balanced
1707 As discussed in the previous item, when the closing-side-
1708 comment-maximum-text limit is exceeded the comment text must be
1709 truncated. Older versions of perltidy terminated with three
1710 dots, and this can still be achieved with -ncscb:
1711
1712 perltidy -csc -ncscb
1713 } ## end foreach my $foo (sort { $b cmp $a ...
1714
1715 However this causes a problem with editors which cannot
1716 recognize comments or are not configured to do so because they
1717 cannot "bounce" around in the text correctly. The -cscb flag
1718 has been added to help them by appending appropriate balancing
1719 structure:
1720
1721 perltidy -csc -cscb
1722 } ## end foreach my $foo (sort { $b cmp $a ... })
1723
1724 The default is -cscb.
1725
1726 -csce=n, or --closing-side-comment-else-flag=n
1727 The default, n=0, places the text of the opening "if" statement
1728 after any terminal "else".
1729
1730 If n=2 is used, then each "elsif" is also given the text of the
1731 opening "if" statement. Also, an "else" will include the text
1732 of a preceding "elsif" statement. Note that this may result
1733 some long closing side comments.
1734
1735 If n=1 is used, the results will be the same as n=2 whenever
1736 the resulting line length is less than the maximum allowed.
1737
1738 -cscb, or --closing-side-comments-balanced
1739 When using closing-side-comments, and the closing-side-comment-
1740 maximum-text limit is exceeded, then the comment text must be
1741 abbreviated. It is terminated with three dots if the -cscb
1742 flag is negated:
1743
1744 perltidy -csc -ncscb
1745 } ## end foreach my $foo (sort { $b cmp $a ...
1746
1747 This causes a problem with older editors which do not recognize
1748 comments because they cannot "bounce" around in the text
1749 correctly. The -cscb flag tries to help them by appending
1750 appropriate terminal balancing structures:
1751
1752 perltidy -csc -cscb
1753 } ## end foreach my $foo (sort { $b cmp $a ... })
1754
1755 The default is -cscb.
1756
1757 -cscw, or --closing-side-comment-warnings
1758 This parameter is intended to help make the initial transition
1759 to the use of closing side comments. It causes two things to
1760 happen if a closing side comment replaces an existing,
1761 different closing side comment: first, an error message will
1762 be issued, and second, the original side comment will be placed
1763 alone on a new specially marked comment line for later
1764 attention.
1765
1766 The intent is to avoid clobbering existing hand-written side
1767 comments which happen to match the pattern of closing side
1768 comments. This flag should only be needed on the first run with
1769 -csc.
1770
1771 Important Notes on Closing Side Comments:
1772
1773 • Closing side comments are only placed on lines terminated with
1774 a closing brace. Certain closing styles, such as the use of
1775 cuddled elses (-ce), preclude the generation of some closing
1776 side comments.
1777
1778 • Please note that adding or deleting of closing side comments
1779 takes place only through the commands -csc or -dcsc. The other
1780 commands, if used, merely modify the behavior of these two
1781 commands.
1782
1783 • It is recommended that the -cscw flag be used along with -csc
1784 on the first use of perltidy on a given file. This will
1785 prevent loss of any existing side comment data which happens to
1786 have the csc prefix.
1787
1788 • Once you use -csc, you should continue to use it so that any
1789 closing side comments remain correct as code changes.
1790 Otherwise, these comments will become incorrect as the code is
1791 updated.
1792
1793 • If you edit the closing side comments generated by perltidy,
1794 you must also change the prefix to be different from the
1795 closing side comment prefix. Otherwise, your edits will be
1796 lost when you rerun perltidy with -csc. For example, you
1797 could simply change "## end" to be "## End", since the test is
1798 case sensitive. You may also want to use the -ssc flag to keep
1799 these modified closing side comments spaced the same as actual
1800 closing side comments.
1801
1802 • Temporarily generating closing side comments is a useful
1803 technique for exploring and/or debugging a perl script,
1804 especially one written by someone else. You can always remove
1805 them with -dcsc.
1806
1807 Static Block Comments
1808 Static block comments are block comments with a special leading
1809 pattern, "##" by default, which will be treated slightly
1810 differently from other block comments. They effectively behave as
1811 if they had glue along their left and top edges, because they stick
1812 to the left edge and previous line when there is no blank spaces in
1813 those places. This option is particularly useful for controlling
1814 how commented code is displayed.
1815
1816 -sbc, --static-block-comments
1817 When -sbc is used, a block comment with a special leading
1818 pattern, "##" by default, will be treated specially.
1819
1820 Comments so identified are treated as follows:
1821
1822 • If there is no leading space on the line, then the comment
1823 will not be indented, and otherwise it may be,
1824
1825 • no new blank line will be inserted before such a comment,
1826 and
1827
1828 • such a comment will never become a hanging side comment.
1829
1830 For example, assuming @month_of_year is left-adjusted:
1831
1832 @month_of_year = ( # -sbc (default)
1833 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1834 ## 'Dec', 'Nov'
1835 'Nov', 'Dec');
1836
1837 Without this convention, the above code would become
1838
1839 @month_of_year = ( # -nsbc
1840 'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct',
1841
1842 ## 'Dec', 'Nov'
1843 'Nov', 'Dec'
1844 );
1845
1846 which is not as clear. The default is to use -sbc. This may
1847 be deactivated with -nsbc.
1848
1849 -sbcp=string, --static-block-comment-prefix=string
1850 This parameter defines the prefix used to identify static block
1851 comments when the -sbc parameter is set. The default prefix is
1852 "##", corresponding to "-sbcp=##". The prefix is actually part
1853 of a perl pattern used to match lines and it must either begin
1854 with "#" or "^#". In the first case a prefix ^\s* will be
1855 added to match any leading whitespace, while in the second case
1856 the pattern will match only comments with no leading
1857 whitespace. For example, to identify all comments as static
1858 block comments, one would use "-sbcp=#". To identify all left-
1859 adjusted comments as static block comments, use "-sbcp='^#'".
1860
1861 Please note that -sbcp merely defines the pattern used to
1862 identify static block comments; it will not be used unless the
1863 switch -sbc is set. Also, please be aware that since this
1864 string is used in a perl regular expression which identifies
1865 these comments, it must enable a valid regular expression to be
1866 formed.
1867
1868 A pattern which can be useful is:
1869
1870 -sbcp=^#{2,}[^\s#]
1871
1872 This pattern requires a static block comment to have at least
1873 one character which is neither a # nor a space. It allows a
1874 line containing only '#' characters to be rejected as a static
1875 block comment. Such lines are often used at the start and end
1876 of header information in subroutines and should not be
1877 separated from the intervening comments, which typically begin
1878 with just a single '#'.
1879
1880 -osbc, --outdent-static-block-comments
1881 The command -osbc will cause static block comments to be
1882 outdented by 2 spaces (or whatever -ci=n has been set to), if
1883 possible.
1884
1885 Static Side Comments
1886 Static side comments are side comments with a special leading
1887 pattern. This option can be useful for controlling how commented
1888 code is displayed when it is a side comment.
1889
1890 -ssc, --static-side-comments
1891 When -ssc is used, a side comment with a static leading
1892 pattern, which is "##" by default, will be spaced only a single
1893 space from previous character, and it will not be vertically
1894 aligned with other side comments.
1895
1896 The default is -nssc.
1897
1898 -sscp=string, --static-side-comment-prefix=string
1899 This parameter defines the prefix used to identify static side
1900 comments when the -ssc parameter is set. The default prefix is
1901 "##", corresponding to "-sscp=##".
1902
1903 Please note that -sscp merely defines the pattern used to
1904 identify static side comments; it will not be used unless the
1905 switch -ssc is set. Also, note that this string is used in a
1906 perl regular expression which identifies these comments, so it
1907 must enable a valid regular expression to be formed.
1908
1909 Skipping Selected Sections of Code
1910 Selected lines of code may be passed verbatim to the output without any
1911 formatting. This feature is enabled by default but can be disabled
1912 with the --noformat-skipping or -nfs flag. It should be used sparingly
1913 to avoid littering code with markers, but it might be helpful for
1914 working around occasional problems. For example it might be useful for
1915 keeping the indentation of old commented code unchanged, keeping
1916 indentation of long blocks of aligned comments unchanged, keeping
1917 certain list formatting unchanged, or working around a glitch in
1918 perltidy.
1919
1920 -fs, --format-skipping
1921 This flag, which is enabled by default, causes any code between
1922 special beginning and ending comment markers to be passed to the
1923 output without formatting. The default beginning marker is #<<<
1924 and the default ending marker is #>>> but they may be changed (see
1925 next items below). Additional text may appear on these special
1926 comment lines provided that it is separated from the marker by at
1927 least one space. For example
1928
1929 #<<< do not let perltidy touch this
1930 my @list = (1,
1931 1, 1,
1932 1, 2, 1,
1933 1, 3, 3, 1,
1934 1, 4, 6, 4, 1,);
1935 #>>>
1936
1937 Format skipping begins when a format skipping comment is seen and
1938 continues until either a format-skipping end pattern is found or
1939 until the end of file.
1940
1941 The comment markers may be placed at any location that a block
1942 comment may appear. If they do not appear to be working, use the
1943 -log flag and examine the .LOG file. Use -nfs to disable this
1944 feature.
1945
1946 This method works for any code. For the specific case of a comma-
1947 separated list of values, as in this example, another possibility
1948 is to insert a blank or comment somewhere between the opening and
1949 closing parens. See the section "Controlling List Formatting".
1950
1951 -fsb=string, --format-skipping-begin=string
1952 The -fsb=string parameter may be used to change the beginning
1953 marker for format skipping. The default is equivalent to
1954 -fsb='#<<<'. The string that you enter must begin with a # and
1955 should be in quotes as necessary to get past the command shell of
1956 your system. It is actually the leading text of a pattern that is
1957 constructed by appending a '\s', so you must also include
1958 backslashes for characters to be taken literally rather than as
1959 patterns.
1960
1961 Some examples show how example strings become patterns:
1962
1963 -fsb='#\{\{\{' becomes /^#\{\{\{\s/ which matches #{{{ but not #{{{{
1964 -fsb='#\*\*' becomes /^#\*\*\s/ which matches #** but not #***
1965 -fsb='#\*{2,}' becomes /^#\*{2,}\s/ which matches #** and #*****
1966
1967 -fse=string, --format-skipping-end=string
1968 The -fse=string is the corresponding parameter used to change the
1969 ending marker for format skipping. The default is equivalent to
1970 -fse='#<<<'.
1971
1972 The beginning and ending strings may be the same, but it is
1973 preferable to make them different for clarity.
1974
1975 Line Break Control
1976 The parameters in this section control breaks after non-blank lines of
1977 code. Blank lines are controlled separately by parameters in the
1978 section "Blank Line Control".
1979
1980 -fnl, --freeze-newlines
1981 If you do not want any changes to the line breaks within lines of
1982 code in your script, set -fnl, and they will remain fixed, and the
1983 rest of the commands in this section and sections "Controlling List
1984 Formatting", "Retaining or Ignoring Existing Line Breaks". You may
1985 want to use -noll with this.
1986
1987 Note: If you also want to keep your blank lines exactly as they
1988 are, you can use the -fbl flag which is described in the section
1989 "Blank Line Control".
1990
1991 -ce, --cuddled-else
1992 Enable the "cuddled else" style, in which "else" and "elsif" are
1993 follow immediately after the curly brace closing the previous
1994 block. The default is not to use cuddled elses, and is indicated
1995 with the flag -nce or --nocuddled-else. Here is a comparison of
1996 the alternatives:
1997
1998 # -ce
1999 if ($task) {
2000 yyy();
2001 } else {
2002 zzz();
2003 }
2004
2005 # -nce (default)
2006 if ($task) {
2007 yyy();
2008 }
2009 else {
2010 zzz();
2011 }
2012
2013 In this example the keyword else is placed on the same line which
2014 begins with the preceding closing block brace and is followed by
2015 its own opening block brace on the same line. Other keywords and
2016 function names which are formatted with this "cuddled" style are
2017 elsif, continue, catch, finally.
2018
2019 Other block types can be formatted by specifying their names on a
2020 separate parameter -cbl, described in a later section.
2021
2022 Cuddling between a pair of code blocks requires that the closing
2023 brace of the first block start a new line. If this block is
2024 entirely on one line in the input file, it is necessary to decide
2025 if it should be broken to allow cuddling. This decision is
2026 controlled by the flag -cbo=n discussed below. The default and
2027 recommended value of -cbo=1 bases this decision on the first block
2028 in the chain. If it spans multiple lines then cuddling is made and
2029 continues along the chain, regardless of the sizes of subsequent
2030 blocks. Otherwise, short lines remain intact.
2031
2032 So for example, the -ce flag would not have any effect if the above
2033 snippet is rewritten as
2034
2035 if ($task) { yyy() }
2036 else { zzz() }
2037
2038 If the first block spans multiple lines, then cuddling can be done
2039 and will continue for the subsequent blocks in the chain, as
2040 illustrated in the previous snippet.
2041
2042 If there are blank lines between cuddled blocks they will be
2043 eliminated. If there are comments after the closing brace where
2044 cuddling would occur then cuddling will be prevented. If this
2045 occurs, cuddling will restart later in the chain if possible.
2046
2047 -cb, --cuddled-blocks
2048 This flag is equivalent to -ce.
2049
2050 -cbl, --cuddled-block-list
2051 The built-in default cuddled block types are else, elsif, continue,
2052 catch, finally.
2053
2054 Additional block types to which the -cuddled-blocks style applies
2055 can be defined by this parameter. This parameter is a character
2056 string, giving a list of block types separated by commas or spaces.
2057 For example, to cuddle code blocks of type sort, map and grep, in
2058 addition to the default types, the string could be set to
2059
2060 -cbl="sort map grep"
2061
2062 or equivalently
2063
2064 -cbl=sort,map,grep
2065
2066 Note however that these particular block types are typically short
2067 so there might not be much opportunity for the cuddled format
2068 style.
2069
2070 Using commas avoids the need to protect spaces with quotes.
2071
2072 As a diagnostic check, the flag --dump-cuddled-block-list or -dcbl
2073 can be used to view the hash of values that are generated by this
2074 flag.
2075
2076 Finally, note that the -cbl flag by itself merely specifies which
2077 blocks are formatted with the cuddled format. It has no effect
2078 unless this formatting style is activated with -ce.
2079
2080 -cblx, --cuddled-block-list-exclusive
2081 When cuddled else formatting is selected with -ce, setting this
2082 flag causes perltidy to ignore its built-in defaults and rely
2083 exclusively on the block types specified on the -cbl flag described
2084 in the previous section. For example, to avoid using cuddled catch
2085 and finally, which among in the defaults, the following set of
2086 parameters could be used:
2087
2088 perltidy -ce -cbl='else elsif continue' -cblx
2089
2090 -cbo=n, --cuddled-break-option=n
2091 Cuddled formatting is only possible between a pair of code blocks
2092 if the closing brace of the first block starts a new line. If a
2093 block is encountered which is entirely on a single line, and
2094 cuddled formatting is selected, it is necessary to make a decision
2095 as to whether or not to "break" the block, meaning to cause it to
2096 span multiple lines. This parameter controls that decision. The
2097 options are:
2098
2099 cbo=0 Never force a short block to break.
2100 cbo=1 If the first of a pair of blocks is broken in the input file,
2101 then break the second [DEFAULT].
2102 cbo=2 Break open all blocks for maximal cuddled formatting.
2103
2104 The default and recommended value is cbo=1. With this value, if
2105 the starting block of a chain spans multiple lines, then a cascade
2106 of breaks will occur for remaining blocks causing the entire chain
2107 to be cuddled.
2108
2109 The option cbo=0 can produce erratic cuddling if there are numerous
2110 one-line blocks.
2111
2112 The option cbo=2 produces maximal cuddling but will not allow any
2113 short blocks.
2114
2115 -bl, --opening-brace-on-new-line
2116 Use the flag -bl to place the opening brace on a new line:
2117
2118 if ( $input_file eq '-' ) # -bl
2119 {
2120 important_function();
2121 }
2122
2123 This flag applies to all structural blocks, including named sub's
2124 (unless the -sbl flag is set -- see next item).
2125
2126 The default style, -nbl, places an opening brace on the same line
2127 as the keyword introducing it. For example,
2128
2129 if ( $input_file eq '-' ) { # -nbl (default)
2130
2131 -sbl, --opening-sub-brace-on-new-line
2132 The flag -sbl can be used to override the value of -bl for the
2133 opening braces of named sub's. For example,
2134
2135 perltidy -sbl
2136
2137 produces this result:
2138
2139 sub message
2140 {
2141 if (!defined($_[0])) {
2142 print("Hello, World\n");
2143 }
2144 else {
2145 print($_[0], "\n");
2146 }
2147 }
2148
2149 This flag is negated with -nsbl. If -sbl is not specified, the
2150 value of -bl is used.
2151
2152 -asbl, --opening-anonymous-sub-brace-on-new-line
2153 The flag -asbl is like the -sbl flag except that it applies to
2154 anonymous sub's instead of named subs. For example
2155
2156 perltidy -asbl
2157
2158 produces this result:
2159
2160 $a = sub
2161 {
2162 if ( !defined( $_[0] ) ) {
2163 print("Hello, World\n");
2164 }
2165 else {
2166 print( $_[0], "\n" );
2167 }
2168 };
2169
2170 This flag is negated with -nasbl, and the default is -nasbl.
2171
2172 -bli, --brace-left-and-indent
2173 The flag -bli is the same as -bl but in addition it causes one unit
2174 of continuation indentation ( see -ci ) to be placed before an
2175 opening and closing block braces.
2176
2177 For example,
2178
2179 if ( $input_file eq '-' ) # -bli
2180 {
2181 important_function();
2182 }
2183
2184 By default, this extra indentation occurs for blocks of type: if,
2185 elsif, else, unless, for, foreach, sub, while, until, and also with
2186 a preceding label. The next item shows how to change this.
2187
2188 -blil=s, --brace-left-and-indent-list=s
2189 Use this parameter to change the types of block braces for which
2190 the -bli flag applies; see "Specifying Block Types". For example,
2191 -blil='if elsif else' would apply it to only "if/elsif/else"
2192 blocks.
2193
2194 -bar, --opening-brace-always-on-right
2195 The default style, -nbl places the opening code block brace on a
2196 new line if it does not fit on the same line as the opening
2197 keyword, like this:
2198
2199 if ( $bigwasteofspace1 && $bigwasteofspace2
2200 || $bigwasteofspace3 && $bigwasteofspace4 )
2201 {
2202 big_waste_of_time();
2203 }
2204
2205 To force the opening brace to always be on the right, use the -bar
2206 flag. In this case, the above example becomes
2207
2208 if ( $bigwasteofspace1 && $bigwasteofspace2
2209 || $bigwasteofspace3 && $bigwasteofspace4 ) {
2210 big_waste_of_time();
2211 }
2212
2213 A conflict occurs if both -bl and -bar are specified.
2214
2215 -otr, --opening-token-right and related flags
2216 The -otr flag is a hint that perltidy should not place a break
2217 between a comma and an opening token. For example:
2218
2219 # default formatting
2220 push @{ $self->{$module}{$key} },
2221 {
2222 accno => $ref->{accno},
2223 description => $ref->{description}
2224 };
2225
2226 # perltidy -otr
2227 push @{ $self->{$module}{$key} }, {
2228 accno => $ref->{accno},
2229 description => $ref->{description}
2230 };
2231
2232 The flag -otr is actually an abbreviation for three other flags
2233 which can be used to control parens, hash braces, and square
2234 brackets separately if desired:
2235
2236 -opr or --opening-paren-right
2237 -ohbr or --opening-hash-brace-right
2238 -osbr or --opening-square-bracket-right
2239
2240 -bbhb=n, --break-before-hash-brace=n and related flags
2241 When a list of items spans multiple lines, the default formatting
2242 is to place the opening brace (or other container token) at the end
2243 of the starting line, like this:
2244
2245 $romanNumerals = {
2246 one => 'I',
2247 two => 'II',
2248 three => 'III',
2249 four => 'IV',
2250 };
2251
2252 This flag can change the default behavior to cause a line break to
2253 be placed before the opening brace according to the value given to
2254 the integer n:
2255
2256 -bbhb=0 never break [default]
2257 -bbhb=1 stable: break if the input script had a break
2258 -bbhb=2 break if list is 'complex' (see note below)
2259 -bbhb=3 always break
2260
2261 For example,
2262
2263 # perltidy -bbhb=3
2264 $romanNumerals =
2265 {
2266 one => 'I',
2267 two => 'II',
2268 three => 'III',
2269 four => 'IV',
2270 };
2271
2272 There are several points to note about this flag:
2273
2274 • This parameter only applies if the opening brace is preceded by
2275 an '=' or '=>'.
2276
2277 • This parameter only applies if the contents of the container
2278 looks like a list. The contents need to contain some commas or
2279 '=>'s at the next interior level to be considered a list.
2280
2281 • For the n=2 option, a list is considered 'complex' if it is
2282 part of a nested list structure which spans multiple lines in
2283 the input file.
2284
2285 • If multiple opening tokens have been 'welded' together with the
2286 -wn parameter, then this parameter has no effect.
2287
2288 • The indentation of the braces will normally be one level of
2289 continuation indentation by default. This can be changed with
2290 the parameter -bbhbi=n in the next section.
2291
2292 • Similar flags for controlling parens and square brackets are
2293 given in the subsequent section.
2294
2295 -bbhbi=n, --break-before-hash-brace-and-indent=n
2296 This flag is a companion to -bbhb=n for controlling the indentation
2297 of an opening hash brace which is placed on a new line by that
2298 parameter. The indentation is as follows:
2299
2300 -bbhbi=0 one continuation level [default]
2301 -bbhbi=1 outdent by one continuation level
2302 -bbhbi=2 indent one full indentation level
2303
2304 For example:
2305
2306 # perltidy -bbhb=3 -bbhbi=1
2307 $romanNumerals =
2308 {
2309 one => 'I',
2310 two => 'II',
2311 three => 'III',
2312 four => 'IV',
2313 };
2314
2315 # perltidy -bbhb=3 -bbhbi=2
2316 $romanNumerals =
2317 {
2318 one => 'I',
2319 two => 'II',
2320 three => 'III',
2321 four => 'IV',
2322 };
2323
2324 Note that this parameter has no effect unless -bbhb=n is also set.
2325
2326 -bbsb=n, --break-before-square-bracket=n
2327 This flag is similar to the flag described above, except it applies
2328 to lists contained within square brackets.
2329
2330 -bbsb=0 never break [default]
2331 -bbsb=1 stable: break if the input script had a break
2332 -bbsb=2 break if list is 'complex' (part of nested list structure)
2333 -bbsb=3 always break
2334
2335 -bbsbi=n, --break-before-square-bracket-and-indent=n
2336 This flag is a companion to -bbsb=n for controlling the indentation
2337 of an opening square bracket which is placed on a new line by that
2338 parameter. The indentation is as follows:
2339
2340 -bbsbi=0 one continuation level [default]
2341 -bbsbi=1 outdent by one continuation level
2342 -bbsbi=2 indent one full indentation level
2343
2344 -bbp=n, --break-before-paren=n
2345 This flag is similar to -bbhb=n, described above, except it applies
2346 to lists contained within parens.
2347
2348 -bbp=0 never break [default]
2349 -bbp=1 stable: break if the input script had a break
2350 -bpb=2 break if list is 'complex' (part of nested list structure)
2351 -bbp=3 always break
2352
2353 -bbpi=n, --break-before-paren-and-indent=n
2354 This flag is a companion to -bbp=n for controlling the indentation
2355 of an opening paren which is placed on a new line by that
2356 parameter. The indentation is as follows:
2357
2358 -bbpi=0 one continuation level [default]
2359 -bbpi=1 outdent by one continuation level
2360 -bbpi=2 indent one full indentation level
2361
2362 -wn, --weld-nested-containers
2363 The -wn flag causes closely nested pairs of opening and closing
2364 container symbols (curly braces, brackets, or parens) to be
2365 "welded" together, meaning that they are treated as if combined
2366 into a single unit, with the indentation of the innermost code
2367 reduced to be as if there were just a single container symbol.
2368
2369 For example:
2370
2371 # default formatting
2372 do {
2373 {
2374 next if $x == $y;
2375 }
2376 } until $x++ > $z;
2377
2378 # perltidy -wn
2379 do { {
2380 next if $x == $y;
2381 } } until $x++ > $z;
2382
2383 When this flag is set perltidy makes a preliminary pass through the
2384 file and identifies all nested pairs of containers. To qualify as
2385 a nested pair, the closing container symbols must be immediately
2386 adjacent and the opening symbols must either (1) be adjacent as in
2387 the above example, or (2) have an anonymous sub declaration
2388 following an outer opening container symbol which is not a code
2389 block brace, or (3) have an outer opening paren separated from the
2390 inner opening symbol by any single non-container symbol or
2391 something that looks like a function evaluation, as illustrated in
2392 the next examples.
2393
2394 Any container symbol may serve as both the inner container of one
2395 pair and as the outer container of an adjacent pair. Consequently,
2396 any number of adjacent opening or closing symbols may join together
2397 in weld. For example, here are three levels of wrapped function
2398 calls:
2399
2400 # default formatting
2401 my (@date_time) = Localtime(
2402 Date_to_Time(
2403 Add_Delta_DHMS(
2404 $year, $month, $day, $hour, $minute, $second,
2405 '0', $offset, '0', '0'
2406 )
2407 )
2408 );
2409
2410 # perltidy -wn
2411 my (@date_time) = Localtime( Date_to_Time( Add_Delta_DHMS(
2412 $year, $month, $day, $hour, $minute, $second,
2413 '0', $offset, '0', '0'
2414 ) ) );
2415
2416 Notice how the indentation of the inner lines are reduced by two
2417 levels in this case. This example also shows the typical result of
2418 this formatting, namely it is a sandwich consisting of an initial
2419 opening layer, a central section of any complexity forming the
2420 "meat" of the sandwich, and a final closing layer. This
2421 predictable structure helps keep the compacted structure readable.
2422
2423 The inner sandwich layer is required to be at least one line thick.
2424 If this cannot be achieved, welding does not occur. This
2425 constraint can cause formatting to take a couple of iterations to
2426 stabilize when it is first applied to a script. The -conv flag can
2427 be used to insure that the final format is achieved in a single
2428 run.
2429
2430 Here is an example illustrating a welded container within a welded
2431 containers:
2432
2433 # default formatting
2434 $x->badd(
2435 bmul(
2436 $class->new(
2437 abs(
2438 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2439 )
2440 ),
2441 $m
2442 )
2443 );
2444
2445 # perltidy -wn
2446 $x->badd( bmul(
2447 $class->new( abs(
2448 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() )
2449 ) ),
2450 $m
2451 ) );
2452
2453 The welded closing tokens are by default on a separate line but
2454 this can be modified with the -vtc=n flag (described in the next
2455 section). For example, the same example adding -vtc=2 is
2456
2457 # perltidy -wn -vtc=2
2458 $x->badd( bmul(
2459 $class->new( abs(
2460 $sx * int( $xr->numify() ) & $sy * int( $yr->numify() ) ) ),
2461 $m ) );
2462
2463 This format option is quite general but there are some limitations.
2464
2465 One limitation is that any line length limit still applies and can
2466 cause long welded sections to be broken into multiple lines.
2467
2468 Another limitation is that an opening symbol which delimits quoted
2469 text cannot be included in a welded pair. This is because quote
2470 delimiters are treated specially in perltidy.
2471
2472 Finally, the stacking of containers defined by this flag have
2473 priority over any other container stacking flags. This is because
2474 any welding is done first.
2475
2476 -wnxl=s, --weld-nested-exclusion-list
2477 The -wnxl=s flag provides some control over the types of containers
2478 which can be welded. The -wn flag by default is "greedy" in
2479 welding adjacent containers. If it welds more types of containers
2480 than desired, this flag provides a capability to reduce the amount
2481 of welding by specifying a list of things which should not be
2482 welded.
2483
2484 The logic in perltidy to apply this is straightforward. As each
2485 container token is being considered for joining a weld, any
2486 exclusion rules are consulted and used to reject the weld if
2487 necessary.
2488
2489 This list is a string with space-separated items. Each item
2490 consists of up to three pieces of information: (1) an optional
2491 position, (2) an optional preceding type, and (3) a container type.
2492
2493 The only required piece of information is a container type, which
2494 is one of '(', '[', '{' or 'q'. The first three of these are
2495 container tokens and the last represents a quoted list. For
2496 example the string
2497
2498 -wnxl='[ { q'
2499
2500 means do NOT include square-bracets, braces, or quotes in any
2501 welds. The only unspecified container is '(', so this string means
2502 that only welds involving parens will be made.
2503
2504 To illustrate, following welded snippet consists of a chain of
2505 three welded containers with types '(' '[' and 'q':
2506
2507 # perltidy -wn
2508 skip_symbols( [ qw(
2509 Perl_dump_fds
2510 Perl_ErrorNo
2511 Perl_GetVars
2512 PL_sys_intern
2513 ) ] );
2514
2515 Even though the qw term uses parens as the quote delimiter, it has
2516 a special type 'q' here. If it appears in a weld it always appears
2517 at the end of the welded chain.
2518
2519 Any of the container types '[', '{', and '(' may be prefixed with a
2520 position indicator which is either '^', to indicate the first token
2521 of a welded sequence, or '.', to indicate an interior token of a
2522 welded sequence. (Since a quoted string 'q' always ends a chain it
2523 does need a position indicator).
2524
2525 For example, if we do not want a sequence of welded containers to
2526 start with a square bracket we could use
2527
2528 -wnxl='^['
2529
2530 In the above snippet, there is a square bracket but it does not
2531 start the chain, so the formatting would be unchanged if it were
2532 formatted with this restriction.
2533
2534 A third optional item of information which can be given is an
2535 alphanumeric letter which is used to limit the selection further
2536 depending on the type of token immediately before the container.
2537 If given, it goes just before the container symbol. The possible
2538 letters are currently 'k', 'K', 'f', 'F', 'w', and 'W', with these
2539 meanings:
2540
2541 'k' matches if the previous nonblank token is a perl builtin keyword (such as 'if', 'while'),
2542 'K' matches if 'k' does not, meaning that the previous token is not a keyword.
2543 'f' matches if the previous token is a function other than a keyword.
2544 'F' matches if 'f' does not.
2545 'w' matches if either 'k' or 'f' match.
2546 'W' matches if 'w' does not.
2547
2548 For example, compare
2549
2550 # perltidy -wn
2551 if ( defined( $_Cgi_Query{
2552 $Config{'methods'}{'authentication'}{'remote'}{'cgi'}{'username'}
2553 } ) )
2554
2555 with
2556
2557 # perltidy -wn -wnxl='^K( {'
2558 if ( defined(
2559 $_Cgi_Query{ $Config{'methods'}{'authentication'}{'remote'}{'cgi'}
2560 {'username'} }
2561 ) )
2562
2563 The first case does maximum welding. In the second case the leading
2564 paren is retained by the rule (it would have been rejected if
2565 preceded by a non-keyword) but the curly brace is rejected by the
2566 rule.
2567
2568 Here are some additional example strings and their meanings:
2569
2570 '^(' - the weld must not start with a paren
2571 '.(' - the second and later tokens may not be parens
2572 '(' - no parens in a weld
2573 '^K(' - exclude a leading paren preceded by a non-keyword
2574 '.k(' - exclude a secondary paren preceded by a keyword
2575 '[ {' - exclude all brackets and braces
2576
2577 Vertical tightness of non-block curly braces, parentheses, and square
2578 brackets.
2579 These parameters control what shall be called vertical tightness.
2580 Here are the main points:
2581
2582 • Opening tokens (except for block braces) are controlled by
2583 -vt=n, or --vertical-tightness=n, where
2584
2585 -vt=0 always break a line after opening token (default).
2586 -vt=1 do not break unless this would produce more than one
2587 step in indentation in a line.
2588 -vt=2 never break a line after opening token
2589
2590 • You must also use the -lp flag when you use the -vt flag; the
2591 reason is explained below.
2592
2593 • Closing tokens (except for block braces) are controlled by
2594 -vtc=n, or --vertical-tightness-closing=n, where
2595
2596 -vtc=0 always break a line before a closing token (default),
2597 -vtc=1 do not break before a closing token which is followed
2598 by a semicolon or another closing token, and is not in
2599 a list environment.
2600 -vtc=2 never break before a closing token.
2601
2602 The rules for -vtc=1 are designed to maintain a reasonable
2603 balance between tightness and readability in complex lists.
2604
2605 • Different controls may be applied to different token types, and
2606 it is also possible to control block braces; see below.
2607
2608 • Finally, please note that these vertical tightness flags are
2609 merely hints to the formatter, and it cannot always follow
2610 them. Things which make it difficult or impossible include
2611 comments, blank lines, blocks of code within a list, and
2612 possibly the lack of the -lp parameter. Also, these flags may
2613 be ignored for very small lists (2 or 3 lines in length).
2614
2615 Here are some examples:
2616
2617 # perltidy -lp -vt=0 -vtc=0
2618 %romanNumerals = (
2619 one => 'I',
2620 two => 'II',
2621 three => 'III',
2622 four => 'IV',
2623 );
2624
2625 # perltidy -lp -vt=1 -vtc=0
2626 %romanNumerals = ( one => 'I',
2627 two => 'II',
2628 three => 'III',
2629 four => 'IV',
2630 );
2631
2632 # perltidy -lp -vt=1 -vtc=1
2633 %romanNumerals = ( one => 'I',
2634 two => 'II',
2635 three => 'III',
2636 four => 'IV', );
2637
2638 The difference between -vt=1 and -vt=2 is shown here:
2639
2640 # perltidy -lp -vt=1
2641 $init->add(
2642 mysprintf( "(void)find_threadsv(%s);",
2643 cstring( $threadsv_names[ $op->targ ] )
2644 )
2645 );
2646
2647 # perltidy -lp -vt=2
2648 $init->add( mysprintf( "(void)find_threadsv(%s);",
2649 cstring( $threadsv_names[ $op->targ ] )
2650 )
2651 );
2652
2653 With -vt=1, the line ending in "add(" does not combine with the
2654 next line because the next line is not balanced. This can help
2655 with readability, but -vt=2 can be used to ignore this rule.
2656
2657 The tightest, and least readable, code is produced with both
2658 "-vt=2" and "-vtc=2":
2659
2660 # perltidy -lp -vt=2 -vtc=2
2661 $init->add( mysprintf( "(void)find_threadsv(%s);",
2662 cstring( $threadsv_names[ $op->targ ] ) ) );
2663
2664 Notice how the code in all of these examples collapses vertically
2665 as -vt increases, but the indentation remains unchanged. This is
2666 because perltidy implements the -vt parameter by first formatting
2667 as if -vt=0, and then simply overwriting one output line on top of
2668 the next, if possible, to achieve the desired vertical tightness.
2669 The -lp indentation style has been designed to allow this vertical
2670 collapse to occur, which is why it is required for the -vt
2671 parameter.
2672
2673 The -vt=n and -vtc=n parameters apply to each type of container
2674 token. If desired, vertical tightness controls can be applied
2675 independently to each of the closing container token types.
2676
2677 The parameters for controlling parentheses are -pvt=n or
2678 --paren-vertical-tightness=n, and -pcvt=n or
2679 --paren-vertical-tightness-closing=n.
2680
2681 Likewise, the parameters for square brackets are -sbvt=n or
2682 --square-bracket-vertical-tightness=n, and -sbcvt=n or
2683 --square-bracket-vertical-tightness-closing=n.
2684
2685 Finally, the parameters for controlling non-code block braces are
2686 -bvt=n or --brace-vertical-tightness=n, and -bcvt=n or
2687 --brace-vertical-tightness-closing=n.
2688
2689 In fact, the parameter -vt=n is actually just an abbreviation for
2690 -pvt=n -bvt=n sbvt=n, and likewise -vtc=n is an abbreviation for
2691 -pvtc=n -bvtc=n sbvtc=n.
2692
2693 -bbvt=n or --block-brace-vertical-tightness=n
2694 The -bbvt=n flag is just like the -vt=n flag but applies to opening
2695 code block braces.
2696
2697 -bbvt=0 break after opening block brace (default).
2698 -bbvt=1 do not break unless this would produce more than one
2699 step in indentation in a line.
2700 -bbvt=2 do not break after opening block brace.
2701
2702 It is necessary to also use either -bl or -bli for this to work,
2703 because, as with other vertical tightness controls, it is
2704 implemented by simply overwriting a line ending with an opening
2705 block brace with the subsequent line. For example:
2706
2707 # perltidy -bli -bbvt=0
2708 if ( open( FILE, "< $File" ) )
2709 {
2710 while ( $File = <FILE> )
2711 {
2712 $In .= $File;
2713 $count++;
2714 }
2715 close(FILE);
2716 }
2717
2718 # perltidy -bli -bbvt=1
2719 if ( open( FILE, "< $File" ) )
2720 { while ( $File = <FILE> )
2721 { $In .= $File;
2722 $count++;
2723 }
2724 close(FILE);
2725 }
2726
2727 By default this applies to blocks associated with keywords if,
2728 elsif, else, unless, for, foreach, sub, while, until, and also with
2729 a preceding label. This can be changed with the parameter
2730 -bbvtl=string, or --block-brace-vertical-tightness-list=string,
2731 where string is a space-separated list of block types. For more
2732 information on the possible values of this string, see "Specifying
2733 Block Types"
2734
2735 For example, if we want to just apply this style to "if", "elsif",
2736 and "else" blocks, we could use "perltidy -bli -bbvt=1 -bbvtl='if
2737 elsif else'".
2738
2739 There is no vertical tightness control for closing block braces;
2740 with one exception they will be placed on separate lines. The
2741 exception is that a cascade of closing block braces may be stacked
2742 on a single line. See -scbb.
2743
2744 -sot, --stack-opening-tokens and related flags
2745 The -sot flag tells perltidy to "stack" opening tokens when
2746 possible to avoid lines with isolated opening tokens.
2747
2748 For example:
2749
2750 # default
2751 $opt_c = Text::CSV_XS->new(
2752 {
2753 binary => 1,
2754 sep_char => $opt_c,
2755 always_quote => 1,
2756 }
2757 );
2758
2759 # -sot
2760 $opt_c = Text::CSV_XS->new( {
2761 binary => 1,
2762 sep_char => $opt_c,
2763 always_quote => 1,
2764 }
2765 );
2766
2767 For detailed control of individual closing tokens the following
2768 controls can be used:
2769
2770 -sop or --stack-opening-paren
2771 -sohb or --stack-opening-hash-brace
2772 -sosb or --stack-opening-square-bracket
2773 -sobb or --stack-opening-block-brace
2774
2775 The flag -sot is an abbreviation for -sop -sohb -sosb.
2776
2777 The flag -sobb is an abbreviation for -bbvt=2 -bbvtl='*'. This
2778 will case a cascade of opening block braces to appear on a single
2779 line, although this an uncommon occurrence except in test scripts.
2780
2781 -sct, --stack-closing-tokens and related flags
2782 The -sct flag tells perltidy to "stack" closing tokens when
2783 possible to avoid lines with isolated closing tokens.
2784
2785 For example:
2786
2787 # default
2788 $opt_c = Text::CSV_XS->new(
2789 {
2790 binary => 1,
2791 sep_char => $opt_c,
2792 always_quote => 1,
2793 }
2794 );
2795
2796 # -sct
2797 $opt_c = Text::CSV_XS->new(
2798 {
2799 binary => 1,
2800 sep_char => $opt_c,
2801 always_quote => 1,
2802 } );
2803
2804 The -sct flag is somewhat similar to the -vtc flags, and in some
2805 cases it can give a similar result. The difference is that the
2806 -vtc flags try to avoid lines with leading opening tokens by
2807 "hiding" them at the end of a previous line, whereas the -sct flag
2808 merely tries to reduce the number of lines with isolated closing
2809 tokens by stacking them but does not try to hide them. For
2810 example:
2811
2812 # -vtc=2
2813 $opt_c = Text::CSV_XS->new(
2814 {
2815 binary => 1,
2816 sep_char => $opt_c,
2817 always_quote => 1, } );
2818
2819 For detailed control of the stacking of individual closing tokens
2820 the following controls can be used:
2821
2822 -scp or --stack-closing-paren
2823 -schb or --stack-closing-hash-brace
2824 -scsb or --stack-closing-square-bracket
2825 -scbb or --stack-closing-block-brace
2826
2827 The flag -sct is an abbreviation for stacking the non-block closing
2828 tokens, -scp -schb -scsb.
2829
2830 Stacking of closing block braces, -scbb, causes a cascade of
2831 isolated closing block braces to be combined into a single line as
2832 in the following example:
2833
2834 # -scbb:
2835 for $w1 (@w1) {
2836 for $w2 (@w2) {
2837 for $w3 (@w3) {
2838 for $w4 (@w4) {
2839 push( @lines, "$w1 $w2 $w3 $w4\n" );
2840 } } } }
2841
2842 To simplify input even further for the case in which both opening
2843 and closing non-block containers are stacked, the flag -sac or
2844 --stack-all-containers is an abbreviation for -sot -sct.
2845
2846 Please note that if both opening and closing tokens are to be
2847 stacked, then the newer flag -weld-nested-containers may be
2848 preferable because it insures that stacking is always done
2849 symmetrically. It also removes an extra level of unnecessary
2850 indentation within welded containers. It is able to do this
2851 because it works on formatting globally rather than locally, as the
2852 -sot and -sct flags do.
2853
2854 -dnl, --delete-old-newlines
2855 By default, perltidy first deletes all old line break locations,
2856 and then it looks for good break points to match the desired line
2857 length. Use -ndnl or --nodelete-old-newlines to force perltidy to
2858 retain all old line break points.
2859
2860 -anl, --add-newlines
2861 By default, perltidy will add line breaks when necessary to create
2862 continuations of long lines and to improve the script appearance.
2863 Use -nanl or --noadd-newlines to prevent any new line breaks.
2864
2865 This flag does not prevent perltidy from eliminating existing line
2866 breaks; see --freeze-newlines to completely prevent changes to line
2867 break points.
2868
2869 Controlling whether perltidy breaks before or after operators
2870 Four command line parameters provide some control over whether a
2871 line break should be before or after specific token types. Two
2872 parameters give detailed control:
2873
2874 -wba=s or --want-break-after=s, and
2875
2876 -wbb=s or --want-break-before=s.
2877
2878 These parameters are each followed by a quoted string, s,
2879 containing a list of token types (separated only by spaces). No
2880 more than one of each of these parameters should be specified,
2881 because repeating a command-line parameter always overwrites the
2882 previous one before perltidy ever sees it.
2883
2884 By default, perltidy breaks after these token types:
2885 % + - * / x != == >= <= =~ !~ < > | &
2886 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2887
2888 And perltidy breaks before these token types by default:
2889 . << >> -> && || //
2890
2891 To illustrate, to cause a break after a concatenation operator,
2892 '.', rather than before it, the command line would be
2893
2894 -wba="."
2895
2896 As another example, the following command would cause a break
2897 before math operators '+', '-', '/', and '*':
2898
2899 -wbb="+ - / *"
2900
2901 These commands should work well for most of the token types that
2902 perltidy uses (use --dump-token-types for a list). Also try the -D
2903 flag on a short snippet of code and look at the .DEBUG file to see
2904 the tokenization. However, for a few token types there may be
2905 conflicts with hardwired logic which cause unexpected results. One
2906 example is curly braces, which should be controlled with the
2907 parameter bl provided for that purpose.
2908
2909 WARNING Be sure to put these tokens in quotes to avoid having them
2910 misinterpreted by your command shell.
2911
2912 Two additional parameters are available which, though they provide
2913 no further capability, can simplify input are:
2914
2915 -baao or --break-after-all-operators,
2916
2917 -bbao or --break-before-all-operators.
2918
2919 The -baao sets the default to be to break after all of the
2920 following operators:
2921
2922 % + - * / x != == >= <= =~ !~ < > | &
2923 = **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x=
2924 . : ? && || and or err xor
2925
2926 and the -bbao flag sets the default to break before all of these
2927 operators. These can be used to define an initial break preference
2928 which can be fine-tuned with the -wba and -wbb flags. For example,
2929 to break before all operators except an = one could use --bbao
2930 -wba='=' rather than listing every single perl operator except = on
2931 a -wbb flag.
2932
2933 Controlling List Formatting
2934 Perltidy attempts to format lists of comma-separated values in tables
2935 which look good. Its default algorithms usually work well, but
2936 sometimes they don't. In this case, there are several methods
2937 available to control list formatting.
2938
2939 A very simple way to prevent perltidy from changing the line breaks
2940 within a comma-separated list of values is to insert a blank line,
2941 comment, or side-comment anywhere between the opening and closing
2942 parens (or braces or brackets). This causes perltidy to skip over its
2943 list formatting logic. (The reason is that any of these items put a
2944 constraint on line breaks, and perltidy needs complete control over
2945 line breaks within a container to adjust a list layout). For example,
2946 let us consider
2947
2948 my @list = (1,
2949 1, 1,
2950 1, 2, 1,
2951 1, 3, 3, 1,
2952 1, 4, 6, 4, 1,);
2953
2954 The default formatting, which allows a maximum line length of 80, will
2955 flatten this down to one line:
2956
2957 # perltidy (default)
2958 my @list = ( 1, 1, 1, 1, 2, 1, 1, 3, 3, 1, 1, 4, 6, 4, 1, );
2959
2960 This formatting loses important information. If we place a side
2961 comment on one of the lines, for example, we get the following result
2962 with with default formatting parameters:
2963
2964 my @list = (
2965 1, # a side comment, comment, or blank keeps list intact
2966 1, 1,
2967 1, 2, 1,
2968 1, 3, 3, 1,
2969 1, 4, 6, 4, 1,
2970 );
2971
2972 We could achieve the same result with a blank line or full comment
2973 anywhere between the opening and closing parens.
2974
2975 For another possibility see the -fs flag in "Skipping Selected Sections
2976 of Code".
2977
2978 -boc, --break-at-old-comma-breakpoints
2979 The -boc flag is another way to prevent comma-separated lists from
2980 being reformatted. Using -boc on the above example, plus
2981 additional flags to retain the original style, yields
2982
2983 # perltidy -boc -lp -pt=2 -vt=1 -vtc=1
2984 my @list = (1,
2985 1, 1,
2986 1, 2, 1,
2987 1, 3, 3, 1,
2988 1, 4, 6, 4, 1,);
2989
2990 A disadvantage of this flag is that all tables in the file must
2991 already be nicely formatted.
2992
2993 -mft=n, --maximum-fields-per-table=n
2994 If the computed number of fields for any table exceeds n, then it
2995 will be reduced to n. The default value for n is a large number,
2996 40. While this value should probably be left unchanged as a
2997 general rule, it might be used on a small section of code to force
2998 a list to have a particular number of fields per line, and then
2999 either the -boc flag could be used to retain this formatting, or a
3000 single comment could be introduced somewhere to freeze the
3001 formatting in future applications of perltidy.
3002
3003 # perltidy -mft=2
3004 @month_of_year = (
3005 'Jan', 'Feb',
3006 'Mar', 'Apr',
3007 'May', 'Jun',
3008 'Jul', 'Aug',
3009 'Sep', 'Oct',
3010 'Nov', 'Dec'
3011 );
3012
3013 -cab=n, --comma-arrow-breakpoints=n
3014 A comma which follows a comma arrow, '=>', is given special
3015 consideration. In a long list, it is common to break at all such
3016 commas. This parameter can be used to control how perltidy breaks
3017 at these commas. (However, it will have no effect if old comma
3018 breaks are being forced because -boc is used). The possible values
3019 of n are:
3020
3021 n=0 break at all commas after =>
3022 n=1 stable: break at all commas after => if container is open,
3023 EXCEPT FOR one-line containers
3024 n=2 break at all commas after =>, BUT try to form the maximum
3025 one-line container lengths
3026 n=3 do not treat commas after => specially at all
3027 n=4 break everything: like n=0 but ALSO break a short container with
3028 a => not followed by a comma when -vt=0 is used
3029 n=5 stable: like n=1 but ALSO break at open one-line containers when
3030 -vt=0 is used (default)
3031
3032 For example, given the following single line, perltidy by default
3033 will not add any line breaks because it would break the existing
3034 one-line container:
3035
3036 bless { B => $B, Root => $Root } => $package;
3037
3038 Using -cab=0 will force a break after each comma-arrow item:
3039
3040 # perltidy -cab=0:
3041 bless {
3042 B => $B,
3043 Root => $Root
3044 } => $package;
3045
3046 If perltidy is subsequently run with this container broken, then by
3047 default it will break after each '=>' because the container is now
3048 broken. To reform a one-line container, the parameter -cab=2 could
3049 be used.
3050
3051 The flag -cab=3 can be used to prevent these commas from being
3052 treated specially. In this case, an item such as "01" => 31 is
3053 treated as a single item in a table. The number of fields in this
3054 table will be determined by the same rules that are used for any
3055 other table. Here is an example.
3056
3057 # perltidy -cab=3
3058 my %last_day = (
3059 "01" => 31, "02" => 29, "03" => 31, "04" => 30,
3060 "05" => 31, "06" => 30, "07" => 31, "08" => 31,
3061 "09" => 30, "10" => 31, "11" => 30, "12" => 31
3062 );
3063
3064 Retaining or Ignoring Existing Line Breaks
3065 Several additional parameters are available for controlling the extent
3066 to which line breaks in the input script influence the output script.
3067 In most cases, the default parameter values are set so that, if a
3068 choice is possible, the output style follows the input style. For
3069 example, if a short logical container is broken in the input script,
3070 then the default behavior is for it to remain broken in the output
3071 script.
3072
3073 Most of the parameters in this section would only be required for a
3074 one-time conversion of a script from short container lengths to longer
3075 container lengths. The opposite effect, of converting long container
3076 lengths to shorter lengths, can be obtained by temporarily using a
3077 short maximum line length.
3078
3079 -bol, --break-at-old-logical-breakpoints
3080 By default, if a logical expression is broken at a "&&", "||",
3081 "and", or "or", then the container will remain broken. Also,
3082 breaks at internal keywords "if" and "unless" will normally be
3083 retained. To prevent this, and thus form longer lines, use -nbol.
3084
3085 Please note that this flag does not duplicate old logical
3086 breakpoints. They are merely used as a hint with this flag that a
3087 statement should remain broken. Without this flag, perltidy will
3088 normally try to combine relatively short expressions into a single
3089 line.
3090
3091 For example, given this snippet:
3092
3093 return unless $cmd = $cmd || ($dot
3094 && $Last_Shell) || &prompt('|');
3095
3096 # perltidy -bol [default]
3097 return
3098 unless $cmd = $cmd
3099 || ( $dot
3100 && $Last_Shell )
3101 || &prompt('|');
3102
3103 # perltidy -nbol
3104 return unless $cmd = $cmd || ( $dot && $Last_Shell ) || &prompt('|');
3105
3106 -bom, --break-at-old-method-breakpoints
3107 By default, a method call arrow "->" is considered a candidate for
3108 a breakpoint, but method chains will fill to the line width before
3109 a break is considered. With -bom, breaks before the arrow are
3110 preserved, so if you have preformatted a method chain:
3111
3112 my $q = $rs
3113 ->related_resultset('CDs')
3114 ->related_resultset('Tracks')
3115 ->search({
3116 'track.id' => {-ident => 'none_search.id'},
3117 })->as_query;
3118
3119 It will keep these breaks, rather than become this:
3120
3121 my $q = $rs->related_resultset('CDs')->related_resultset('Tracks')->search({
3122 'track.id' => {-ident => 'none_search.id'},
3123 })->as_query;
3124
3125 This flag will also look for and keep a 'cuddled' style of calls,
3126 in which lines begin with a closing paren followed by a call arrow,
3127 as in this example:
3128
3129 my $q = $rs->related_resultset(
3130 'CDs'
3131 )->related_resultset(
3132 'Tracks'
3133 )->search( {
3134 'track.id' => { -ident => 'none_search.id' },
3135 } )->as_query;
3136
3137 You may want to include the -weld-nested-containers flag in this
3138 case to keep nested braces and parens together, as in the last
3139 line.
3140
3141 -bos, --break-at-old-semicolon-breakpoints
3142 Semicolons are normally placed at the end of a statement. This
3143 means that formatted lines do not normally begin with semicolons.
3144 If the input stream has some lines which begin with semicolons,
3145 these can be retained by setting this flag. For example, consider
3146 the following two-line input snippet:
3147
3148 $z = sqrt($x**2 + $y**2)
3149 ;
3150
3151 The default formatting will be:
3152
3153 $z = sqrt( $x**2 + $y**2 );
3154
3155 The result using perltidy -bos keeps the isolated semicolon:
3156
3157 $z = sqrt( $x**2 + $y**2 )
3158 ;
3159
3160 The default is not to do this, -nbos.
3161
3162 -bok, --break-at-old-keyword-breakpoints
3163 By default, perltidy will retain a breakpoint before keywords which
3164 may return lists, such as "sort" and <map>. This allows chains of
3165 these operators to be displayed one per line. Use -nbok to prevent
3166 retaining these breakpoints.
3167
3168 -bot, --break-at-old-ternary-breakpoints
3169 By default, if a conditional (ternary) operator is broken at a ":",
3170 then it will remain broken. To prevent this, and thereby form
3171 longer lines, use -nbot.
3172
3173 -boa, --break-at-old-attribute-breakpoints
3174 By default, if an attribute list is broken at a ":" in the source
3175 file, then it will remain broken. For example, given the following
3176 code, the line breaks at the ':'s will be retained:
3177
3178 my @field
3179 : field
3180 : Default(1)
3181 : Get('Name' => 'foo') : Set('Name');
3182
3183 If the attributes are on a single line in the source code then they
3184 will remain on a single line if possible.
3185
3186 To prevent this, and thereby always form longer lines, use -nboa.
3187
3188 Keeping old breakpoints at specific token types
3189 Two command line parameters provide detailed control over whether
3190 perltidy should keep an old line break before or after a specific
3191 token type:
3192
3193 -kbb=s or --keep-old-breakpoints-before=s, and
3194
3195 -kba=s or --keep-old-breakpoints-after=s
3196
3197 These parameters are each followed by a quoted string, s,
3198 containing a list of token types (separated only by spaces). No
3199 more than one of each of these parameters should be specified,
3200 because repeating a command-line parameter always overwrites the
3201 previous one before perltidy ever sees it.
3202
3203 For example, -kbb='=>' means that if an input line begins with a
3204 '=>' then the output script should also have a line break before
3205 that token.
3206
3207 For example, given the script:
3208
3209 method 'foo'
3210 => [ Int, Int ]
3211 => sub {
3212 my ( $self, $x, $y ) = ( shift, @_ );
3213 ...;
3214 };
3215
3216 # perltidy [default]
3217 method 'foo' => [ Int, Int ] => sub {
3218 my ( $self, $x, $y ) = ( shift, @_ );
3219 ...;
3220 };
3221
3222 # perltidy -kbb='=>'
3223 method 'foo'
3224 => [ Int, Int ]
3225 => sub {
3226 my ( $self, $x, $y ) = ( shift, @_ );
3227 ...;
3228 };
3229
3230 -iob, --ignore-old-breakpoints
3231 Use this flag to tell perltidy to ignore existing line breaks to
3232 the maximum extent possible. This will tend to produce the longest
3233 possible containers, regardless of type, which do not exceed the
3234 line length limit. But please note that this parameter has priority
3235 over all other parameters requesting that certain old breakpoints
3236 be kept.
3237
3238 -kis, --keep-interior-semicolons
3239 Use the -kis flag to prevent breaking at a semicolon if there was
3240 no break there in the input file. Normally perltidy places a
3241 newline after each semicolon which terminates a statement unless
3242 several statements are contained within a one-line brace block. To
3243 illustrate, consider the following input lines:
3244
3245 dbmclose(%verb_delim); undef %verb_delim;
3246 dbmclose(%expanded); undef %expanded;
3247
3248 The default is to break after each statement, giving
3249
3250 dbmclose(%verb_delim);
3251 undef %verb_delim;
3252 dbmclose(%expanded);
3253 undef %expanded;
3254
3255 With perltidy -kis the multiple statements are retained:
3256
3257 dbmclose(%verb_delim); undef %verb_delim;
3258 dbmclose(%expanded); undef %expanded;
3259
3260 The statements are still subject to the specified value of maximum-
3261 line-length and will be broken if this maximum is exceeded.
3262
3263 Blank Line Control
3264 Blank lines can improve the readability of a script if they are
3265 carefully placed. Perltidy has several commands for controlling the
3266 insertion, retention, and removal of blank lines.
3267
3268 -fbl, --freeze-blank-lines
3269 Set -fbl if you want to the blank lines in your script to remain
3270 exactly as they are. The rest of the parameters in this section
3271 may then be ignored. (Note: setting the -fbl flag is equivalent to
3272 setting -mbl=0 and -kbl=2).
3273
3274 -bbc, --blanks-before-comments
3275 A blank line will be introduced before a full-line comment. This
3276 is the default. Use -nbbc or --noblanks-before-comments to
3277 prevent such blank lines from being introduced.
3278
3279 -blbs=n, --blank-lines-before-subs=n
3280 The parameter -blbs=n requests that least n blank lines precede a
3281 sub definition which does not follow a comment and which is more
3282 than one-line long. The default is <-blbs=1>. BEGIN and END
3283 blocks are included.
3284
3285 The requested number of blanks statement will be inserted
3286 regardless of the value of --maximum-consecutive-blank-lines=n
3287 (-mbl=n) with the exception that if -mbl=0 then no blanks will be
3288 output.
3289
3290 This parameter interacts with the value k of the parameter
3291 --maximum-consecutive-blank-lines=k (-mbl=k) as follows:
3292
3293 1. If -mbl=0 then no blanks will be output. This allows all blanks
3294 to be suppressed with a single parameter. Otherwise,
3295
3296 2. If the number of old blank lines in the script is less than n
3297 then additional blanks will be inserted to make the total n
3298 regardless of the value of -mbl=k.
3299
3300 3. If the number of old blank lines in the script equals or exceeds
3301 n then this parameter has no effect, however the total will not
3302 exceed value specified on the -mbl=k flag.
3303
3304 -blbp=n, --blank-lines-before-packages=n
3305 The parameter -blbp=n requests that least n blank lines precede a
3306 package which does not follow a comment. The default is -blbp=1.
3307
3308 This parameter interacts with the value k of the parameter
3309 --maximum-consecutive-blank-lines=k (-mbl=k) in the same way as
3310 described for the previous item -blbs=n.
3311
3312 -bbs, --blanks-before-subs
3313 For compatibility with previous versions, -bbs or
3314 --blanks-before-subs is equivalent to -blbp=1 and -blbs=1.
3315
3316 Likewise, -nbbs or --noblanks-before-subs is equivalent to -blbp=0
3317 and -blbs=0.
3318
3319 -bbb, --blanks-before-blocks
3320 A blank line will be introduced before blocks of coding delimited
3321 by for, foreach, while, until, and if, unless, in the following
3322 circumstances:
3323
3324 • The block is not preceded by a comment.
3325
3326 • The block is not a one-line block.
3327
3328 • The number of consecutive non-blank lines at the current
3329 indentation depth is at least -lbl (see next section).
3330
3331 This is the default. The intention of this option is to introduce
3332 some space within dense coding. This is negated with -nbbb or
3333 --noblanks-before-blocks.
3334
3335 -lbl=n --long-block-line-count=n
3336 This controls how often perltidy is allowed to add blank lines
3337 before certain block types (see previous section). The default is
3338 8. Entering a value of 0 is equivalent to entering a very large
3339 number.
3340
3341 -blao=i or --blank-lines-after-opening-block=i
3342 This control places a minimum of i blank lines after a line which
3343 ends with an opening block brace of a specified type. By default,
3344 this only applies to the block of a named sub, but this can be
3345 changed (see -blaol below). The default is not to do this (i=0).
3346
3347 Please see the note below on using the -blao and -blbc options.
3348
3349 -blbc=i or --blank-lines-before-closing-block=i
3350 This control places a minimum of i blank lines before a line which
3351 begins with a closing block brace of a specified type. By default,
3352 this only applies to the block of a named sub, but this can be
3353 changed (see -blbcl below). The default is not to do this (i=0).
3354
3355 -blaol=s or --blank-lines-after-opening-block-list=s
3356 The parameter s is a list of block type keywords to which the flag
3357 -blao should apply. The section "Specifying Block Types" explains
3358 how to list block types.
3359
3360 -blbcl=s or --blank-lines-before-closing-block-list=s
3361 This parameter is a list of block type keywords to which the flag
3362 -blbc should apply. The section "Specifying Block Types" explains
3363 how to list block types.
3364
3365 Note on using the -blao and -blbc options.
3366 These blank line controls introduce a certain minimum number of
3367 blank lines in the text, but the final number of blank lines may be
3368 greater, depending on values of the other blank line controls and
3369 the number of old blank lines. A consequence is that introducing
3370 blank lines with these and other controls cannot be exactly undone,
3371 so some experimentation with these controls is recommended before
3372 using them.
3373
3374 For example, suppose that for some reason we decide to introduce
3375 one blank space at the beginning and ending of all blocks. We
3376 could do this using
3377
3378 perltidy -blao=2 -blbc=2 -blaol='*' -blbcl='*' filename
3379
3380 Now suppose the script continues to be developed, but at some later
3381 date we decide we don't want these spaces after all. we might
3382 expect that running with the flags -blao=0 and -blbc=0 will undo
3383 them. However, by default perltidy retains single blank lines, so
3384 the blank lines remain.
3385
3386 We can easily fix this by telling perltidy to ignore old blank
3387 lines by including the added parameter -kbl=0 and rerunning. Then
3388 the unwanted blank lines will be gone. However, this will cause
3389 all old blank lines to be ignored, perhaps even some that were
3390 added by hand to improve formatting. So please be cautious when
3391 using these parameters.
3392
3393 -mbl=n --maximum-consecutive-blank-lines=n
3394 This parameter specifies the maximum number of consecutive blank
3395 lines which will be output within code sections of a script. The
3396 default is n=1. If the input file has more than n consecutive
3397 blank lines, the number will be reduced to n except as noted above
3398 for the -blbp and -blbs parameters. If n=0 then no blank lines
3399 will be output (unless all old blank lines are retained with the
3400 -kbl=2 flag of the next section).
3401
3402 This flag obviously does not apply to pod sections, here-documents,
3403 and quotes.
3404
3405 -kbl=n, --keep-old-blank-lines=n
3406 The -kbl=n flag gives you control over how your existing blank
3407 lines are treated.
3408
3409 The possible values of n are:
3410
3411 n=0 ignore all old blank lines
3412 n=1 stable: keep old blanks, but limited by the value of the B<-mbl=n> flag
3413 n=2 keep all old blank lines, regardless of the value of the B<-mbl=n> flag
3414
3415 The default is n=1.
3416
3417 -sob, --swallow-optional-blank-lines
3418 This is equivalent to kbl=0 and is included for compatibility with
3419 previous versions.
3420
3421 -nsob, --noswallow-optional-blank-lines
3422 This is equivalent to kbl=1 and is included for compatibility with
3423 previous versions.
3424
3425 Controls for blank lines around lines of consecutive keywords
3426
3427 The parameters in this section provide some control over the placement
3428 of blank lines within and around groups of statements beginning with
3429 selected keywords. These blank lines are called here keyword group
3430 blanks, and all of the parameters begin with --keyword-group-blanks*,
3431 or -kgb* for short. The default settings do not employ these controls
3432 but they can be enabled with the following parameters:
3433
3434 -kgbl=s or --keyword-group-blanks-list=s; s is a quoted string of
3435 keywords
3436
3437 -kgbs=s or --keyword-group-blanks-size=s; s gives the number of
3438 keywords required to form a group.
3439
3440 -kgbb=n or --keyword-group-blanks-before=n; n = (0, 1, or 2) controls a
3441 leading blank
3442
3443 -kgba=n or --keyword-group-blanks-after=n; n = (0, 1, or 2) controls a
3444 trailing blank
3445
3446 -kgbi or --keyword-group-blanks-inside is a switch for adding blanks
3447 between subgroups
3448
3449 -kgbd or --keyword-group-blanks-delete is a switch for removing initial
3450 blank lines between keywords
3451
3452 -kgbr=n or --keyword-group-blanks-repeat-count=n can limit the number
3453 of times this logic is applied
3454
3455 In addition, the following abbreviations are available to for
3456 simplified usage:
3457
3458 -kgb or --keyword-group-blanks is short for -kgbb=2 -kgba=2 kgbi
3459
3460 -nkgb or --nokeyword-group-blanks, is short for -kgbb=1 -kgba=1 nkgbi
3461
3462 Before describing the meaning of the parameters in detail let us look
3463 at an example which is formatted with default parameter settings.
3464
3465 print "Entering test 2\n";
3466 use Test;
3467 use Encode qw(from_to encode decode
3468 encode_utf8 decode_utf8
3469 find_encoding is_utf8);
3470 use charnames qw(greek);
3471 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3472 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3473 my @source = qw(ascii iso8859-1 cp1250);
3474 my @destiny = qw(cp1047 cp37 posix-bc);
3475 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3476 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3477 return unless ($str);
3478
3479 using perltidy -kgb gives:
3480
3481 print "Entering test 2\n";
3482 <----------this blank controlled by -kgbb
3483 use Test;
3484 use Encode qw(from_to encode decode
3485 encode_utf8 decode_utf8
3486 find_encoding is_utf8);
3487 use charnames qw(greek);
3488 <---------this blank controlled by -kgbi
3489 my @encodings = grep( /iso-?8859/, Encode::encodings() );
3490 my @character_set = ( '0' .. '9', 'A' .. 'Z', 'a' .. 'z' );
3491 my @source = qw(ascii iso8859-1 cp1250);
3492 my @destiny = qw(cp1047 cp37 posix-bc);
3493 my @ebcdic_sets = qw(cp1047 cp37 posix-bc);
3494 my $str = join( '', map( chr($_), 0x20 .. 0x7E ) );
3495 <----------this blank controlled by -kgba
3496 return unless ($str);
3497
3498 Blank lines have been introduced around the my and use sequences. What
3499 happened is that the default keyword list includes my and use but not
3500 print and return. So a continuous sequence of nine my and use
3501 statements was located. This number exceeds the default threshold of
3502 five, so blanks were placed before and after the entire group. Then,
3503 since there was also a subsequence of six my lines, a blank line was
3504 introduced to separate them.
3505
3506 Finer control over blank placement can be achieved by using the
3507 individual parameters rather than the -kgb flag. The individual
3508 controls are as follows.
3509
3510 -kgbl=s or --keyword-group-blanks-list=s, where s is a quoted string,
3511 defines the set of keywords which will be formed into groups. The
3512 string is a space separated list of keywords. The default set is
3513 s="use require local our my", but any list of keywords may be used.
3514 Comment lines may also be included in a keyword group, even though they
3515 are not keywords. To include ordinary block comments, include the
3516 symbol BC. To include static block comments (which normally begin with
3517 '##'), include the symbol SBC.
3518
3519 -kgbs=s or --keyword-group-blanks-size=s, where s is a string
3520 describing the number of consecutive keyword statements forming a
3521 group. If s is an integer then it is the minimum number required for a
3522 group. A maximum value may also be given with the format s=min.max,
3523 where min is the minimum number and max is the maximum number, and the
3524 min and max values are separated by one or more dots. No groups will
3525 be found if the maximum is less than the minimum. The maximum is
3526 unlimited if not given. The default is s=5. Some examples:
3527
3528 s min max number for group
3529 3 3 unlimited 3 or more
3530 1.1 1 1 1
3531 1..3 1 3 1 to 3
3532 1.0 1 0 (no match)
3533
3534 -kgbb=n or --keyword-group-blanks-before=n specifies whether a blank
3535 should appear before the first line of the group, as follows:
3536
3537 n=0 => (delete) an existing blank line will be removed
3538 n=1 => (stable) no change to the input file is made [DEFAULT]
3539 n=2 => (insert) a blank line is introduced if possible
3540
3541 -kgba=n or --keyword-group-blanks-after=n likewise specifies whether a
3542 blank should appear after the last line of the group, using the same
3543 scheme (0=delete, 1=stable, 2=insert).
3544
3545 -kgbi or --keyword-group-blanks-inside controls the insertion of blank
3546 lines between the first and last statement of the entire group. If
3547 there is a continuous run of a single statement type with more than the
3548 minimum threshold number (as specified with -kgbs=s) then this switch
3549 causes a blank line be inserted between this subgroup and the others.
3550 In the example above this happened between the use and my statements.
3551
3552 -kgbd or --keyword-group-blanks-delete controls the deletion of any
3553 blank lines that exist in the the group when it is first scanned. When
3554 statements are initially scanned, any existing blank lines are included
3555 in the collection. Any such orignial blank lines will be deleted
3556 before any other insertions are made when the parameter -kgbd is set.
3557 The default is not to do this, -nkgbd.
3558
3559 -kgbr=n or --keyword-group-blanks-repeat-count=n specifies n, the
3560 maximum number of times this logic will be applied to any file. The
3561 special value n=0 is the same as n=infinity which means it will be
3562 applied to an entire script [Default]. A value n=1 could be used to
3563 make it apply just one time for example. This might be useful for
3564 adjusting just the use statements in the top part of a module for
3565 example.
3566
3567 -kgb or --keyword-group-blanks is an abbreviation equivalent to setting
3568 -kgbb=1 -kgba=1 -kgbi. This turns on keyword group formatting with a
3569 set of default values.
3570
3571 -nkgb or --nokeyword-group-blanks is equivalent to -kgbb=0 -kgba nkgbi.
3572 This flag turns off keyword group blank lines and is the default
3573 setting.
3574
3575 Here are a few notes about the functioning of this technique.
3576
3577 • These parameters are probably more useful as part of a major code
3578 reformatting operation rather than as a routine formatting
3579 operation.
3580
3581 In particular, note that deleting old blank lines with -kgbd is an
3582 irreversible operation so it should be applied with care. Existing
3583 blank lines may be serving an important role in controlling
3584 vertical alignment.
3585
3586 • Conflicts which arise among these kgb* parameters and other blank
3587 line controls are generally resolved by producing the maximum
3588 number of blank lines implied by any parameter.
3589
3590 For example, if the flags --freeze-blank-lines, or
3591 --keep-old-blank-lines=2, are set, then they have priority over any
3592 blank line deletion implied by the -kgb flags of this section, so
3593 no blank lines will be deleted.
3594
3595 For another example, if a keyword group ends at a sub and the flag
3596 kgba=0 requests no blank line there, but we also have
3597 --blank-lines-before-subs=2, then two blank lines will still be
3598 introduced before the sub.
3599
3600 • The introduction of blank lines does not occur if it would conflict
3601 with other input controls or code validity. For example, a blank
3602 line will not be placed within a here-doc or within a section of
3603 code marked with format skipping comments. And in general, a blank
3604 line will only be introduced at the end of a group if the next
3605 statement is a line of code.
3606
3607 • The count which is used to determine the group size is not the
3608 number of lines but rather the total number of keywords which are
3609 found. Individual statements with a certain leading keyword may
3610 continue on multiple lines, but if any of these lines is nested
3611 more than one level deep then that group will be ended.
3612
3613 • The search for groups of lines with similar leading keywords is
3614 based on the input source, not the final formatted source.
3615 Consequently, if the source code is badly formatted, it would be
3616 best to make a first formatting pass without these options.
3617
3618 Styles
3619 A style refers to a convenient collection of existing parameters.
3620
3621 -gnu, --gnu-style
3622 -gnu gives an approximation to the GNU Coding Standards (which do
3623 not apply to perl) as they are sometimes implemented. At present,
3624 this style overrides the default style with the following
3625 parameters:
3626
3627 -lp -bl -noll -pt=2 -bt=2 -sbt=2 -icp
3628
3629 -pbp, --perl-best-practices
3630 -pbp is an abbreviation for the parameters in the book Perl Best
3631 Practices by Damian Conway:
3632
3633 -l=78 -i=4 -ci=4 -st -se -vt=2 -cti=0 -pt=1 -bt=1 -sbt=1 -bbt=1 -nsfs -nolq
3634 -wbb="% + - * / x != == >= <= =~ !~ < > | & =
3635 **= += *= &= <<= &&= -= /= |= >>= ||= //= .= %= ^= x="
3636
3637 Please note that this parameter set includes -st and -se flags,
3638 which make perltidy act as a filter on one file only. These can be
3639 overridden by placing -nst and/or -nse after the -pbp parameter.
3640
3641 Also note that the value of continuation indentation, -ci=4, is
3642 equal to the value of the full indentation, -i=4. It is
3643 recommended that the either (1) the parameter -ci=2 be used
3644 instead, or the flag -xci be set. This will help show structure,
3645 particularly when there are ternary statements. The following
3646 snippet illustrates these options.
3647
3648 # perltidy -pbp
3649 $self->{_text} = (
3650 !$section ? ''
3651 : $type eq 'item' ? "the $section entry"
3652 : "the section on $section"
3653 )
3654 . (
3655 $page
3656 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3657 : ' elsewhere in this document'
3658 );
3659
3660 # perltidy -pbp -ci=2
3661 $self->{_text} = (
3662 !$section ? ''
3663 : $type eq 'item' ? "the $section entry"
3664 : "the section on $section"
3665 )
3666 . (
3667 $page
3668 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3669 : ' elsewhere in this document'
3670 );
3671
3672 # perltidy -pbp -xci
3673 $self->{_text} = (
3674 !$section ? ''
3675 : $type eq 'item' ? "the $section entry"
3676 : "the section on $section"
3677 )
3678 . ( $page
3679 ? ( $section ? ' in ' : '' ) . "the $page$page_ext manpage"
3680 : ' elsewhere in this document'
3681 );
3682
3683 The -xci flag was developed after the -pbp parameters were
3684 published so you need to include it separately.
3685
3686 One-line blocks
3687 There are a few points to note regarding one-line blocks. A one-
3688 line block is something like this,
3689
3690 where the contents within the curly braces is short enough to fit
3691 on a single line.
3692
3693 With few exceptions, perltidy retains existing one-line blocks, if
3694 it is possible within the line-length constraint, but it does not
3695 attempt to form new ones. In other words, perltidy will try to
3696 follow the one-line block style of the input file.
3697
3698 If an existing one-line block is longer than the maximum line
3699 length, however, it will be broken into multiple lines. When this
3700 happens, perltidy checks for and adds any optional terminating
3701 semicolon (unless the -nasc option is used) if the block is a code
3702 block.
3703
3704 The main exception is that perltidy will attempt to form new one-
3705 line blocks following the keywords "map", "eval", and "sort",
3706 because these code blocks are often small and most clearly
3707 displayed in a single line.
3708
3709 One-line block rules can conflict with the cuddled-else option.
3710 When the cuddled-else option is used, perltidy retains existing
3711 one-line blocks, even if they do not obey cuddled-else formatting.
3712
3713 Occasionally, when one-line blocks get broken because they exceed
3714 the available line length, the formatting will violate the
3715 requested brace style. If this happens, reformatting the script a
3716 second time should correct the problem.
3717
3718 Sometimes it might be desirable to convert a script to have one-
3719 line blocks whenever possible. Although there is currently no flag
3720 for this, a simple workaround is to execute perltidy twice, once
3721 with the flag -noadd-newlines and then once again with normal
3722 parameters, like this:
3723
3724 cat infile | perltidy -nanl | perltidy >outfile
3725
3726 When executed on this snippet
3727
3728 if ( $? == -1 ) {
3729 die "failed to execute: $!\n";
3730 }
3731 if ( $? == -1 ) {
3732 print "Had enough.\n";
3733 die "failed to execute: $!\n";
3734 }
3735
3736 the result is
3737
3738 if ( $? == -1 ) { die "failed to execute: $!\n"; }
3739 if ( $? == -1 ) {
3740 print "Had enough.\n";
3741 die "failed to execute: $!\n";
3742 }
3743
3744 This shows that blocks with a single statement become one-line
3745 blocks.
3746
3747 -olbs=n, --one-line-block-semicolons=n
3748 This flag controls the placement of semicolons at the end of one-
3749 line blocks. Semicolons are optional before a closing block brace,
3750 and frequently they are omitted at the end of a one-line block
3751 containing just a single statement. By default, perltidy follows
3752 the input file regarding these semicolons, but this behavior can be
3753 controlled by this flag. The values of n are:
3754
3755 n=0 remove terminal semicolons in one-line blocks having a single statement
3756 n=1 stable; keep input file placement of terminal semicolons [DEFAULT ]
3757 n=2 add terminal semicolons in all one-line blocks
3758
3759 Note that the n=2 option has no effect if adding semicolons is
3760 prohibited with the -nasc flag. Also not that while n=2 adds
3761 missing semicolons to all one-line blocks, regardless of
3762 complexity, the n=0 option only removes ending semicolons which
3763 terminate one-line blocks containing just one semicolon. So these
3764 two options are not exact inverses.
3765
3766 -olbn=n, --one-line-block-nesting=n
3767 Nested one-line blocks are lines with code blocks which themselves
3768 contain code blocks. For example, the following line is a nested
3769 one-line block.
3770
3771 foreach (@list) { if ($_ eq $asked_for) { last } ++$found }
3772
3773 The default behavior is to break such lines into multiple lines,
3774 but this behavior can be controlled with this flag. The values of
3775 n are:
3776
3777 n=0 break nested one-line blocks into multiple lines [DEFAULT]
3778 n=1 stable: keep existing nested-one line blocks intact
3779
3780 For the above example, the default formatting (-olbn=0) is
3781
3782 foreach (@list) {
3783 if ( $_ eq $asked_for ) { last }
3784 ++$found;
3785 }
3786
3787 If the parameter -olbn=1 is given, then the line will be left
3788 intact if it is a single line in the source, or it will be broken
3789 into multiple lines if it is broken in multiple lines in the
3790 source.
3791
3792 Controlling Vertical Alignment
3793 Vertical alignment refers to lining up certain symbols in a list of
3794 consecutive similar lines to improve readability. For example, the
3795 "fat commas" are aligned in the following statement:
3796
3797 $data = $pkg->new(
3798 PeerAddr => join( ".", @port[ 0 .. 3 ] ),
3799 PeerPort => $port[4] * 256 + $port[5],
3800 Proto => 'tcp'
3801 );
3802
3803 Vertical alignment can be completely turned off using -novalign, a flag
3804 mainly intended for debugging. However, vertical alignment can be
3805 forced to stop and restart by selectively introducing blank lines. For
3806 example, a blank has been inserted in the following code to keep
3807 somewhat similar things aligned.
3808
3809 %option_range = (
3810 'format' => [ 'tidy', 'html', 'user' ],
3811 'output-line-ending' => [ 'dos', 'win', 'mac', 'unix' ],
3812 'character-encoding' => [ 'none', 'utf8' ],
3813
3814 'block-brace-tightness' => [ 0, 2 ],
3815 'brace-tightness' => [ 0, 2 ],
3816 'paren-tightness' => [ 0, 2 ],
3817 'square-bracket-tightness' => [ 0, 2 ],
3818 );
3819
3820 Vertical alignment is implemented by locally increasing an existing
3821 blank space to produce alignment with an adjacent line. It cannot
3822 occur if there is no blank space to increase. So if a particular space
3823 is removed by one of the existing controls then vertical alignment
3824 cannot occur. Likewise, if a space is added with one of the controls,
3825 then vertical alignment might occur.
3826
3827 For example,
3828
3829 # perltidy -nwls='=>'
3830 $data = $pkg->new(
3831 PeerAddr=> join( ".", @port[ 0 .. 3 ] ),
3832 PeerPort=> $port[4] * 256 + $port[5],
3833 Proto=> 'tcp'
3834 );
3835
3836 Other Controls
3837 Deleting selected text
3838 Perltidy can selectively delete comments and/or pod documentation.
3839 The command -dac or --delete-all-comments will delete all comments
3840 and all pod documentation, leaving just code and any leading system
3841 control lines.
3842
3843 The command -dp or --delete-pod will remove all pod documentation
3844 (but not comments).
3845
3846 Two commands which remove comments (but not pod) are: -dbc or
3847 --delete-block-comments and -dsc or --delete-side-comments.
3848 (Hanging side comments will be deleted with side comments here.)
3849
3850 The negatives of these commands also work, and are the defaults.
3851 When block comments are deleted, any leading 'hash-bang' will be
3852 retained. Also, if the -x flag is used, any system commands before
3853 a leading hash-bang will be retained (even if they are in the form
3854 of comments).
3855
3856 Writing selected text to a file
3857 When perltidy writes a formatted text file, it has the ability to
3858 also send selected text to a file with a .TEE extension. This text
3859 can include comments and pod documentation.
3860
3861 The command -tac or --tee-all-comments will write all comments and
3862 all pod documentation.
3863
3864 The command -tp or --tee-pod will write all pod documentation (but
3865 not comments).
3866
3867 The commands which write comments (but not pod) are: -tbc or
3868 --tee-block-comments and -tsc or --tee-side-comments. (Hanging
3869 side comments will be written with side comments here.)
3870
3871 The negatives of these commands also work, and are the defaults.
3872
3873 Using a .perltidyrc command file
3874 If you use perltidy frequently, you probably won't be happy until
3875 you create a .perltidyrc file to avoid typing commonly-used
3876 parameters. Perltidy will first look in your current directory for
3877 a command file named .perltidyrc. If it does not find one, it will
3878 continue looking for one in other standard locations.
3879
3880 These other locations are system-dependent, and may be displayed
3881 with the command "perltidy -dpro". Under Unix systems, it will
3882 first look for an environment variable PERLTIDY. Then it will look
3883 for a .perltidyrc file in the home directory, and then for a
3884 system-wide file /usr/local/etc/perltidyrc, and then it will look
3885 for /etc/perltidyrc. Note that these last two system-wide files do
3886 not have a leading dot. Further system-dependent information will
3887 be found in the INSTALL file distributed with perltidy.
3888
3889 Under Windows, perltidy will also search for a configuration file
3890 named perltidy.ini since Windows does not allow files with a
3891 leading period (.). Use "perltidy -dpro" to see the possible
3892 locations for your system. An example might be C:\Documents and
3893 Settings\All Users\perltidy.ini.
3894
3895 Another option is the use of the PERLTIDY environment variable.
3896 The method for setting environment variables depends upon the
3897 version of Windows that you are using. Instructions for Windows 95
3898 and later versions can be found here:
3899
3900 http://www.netmanage.com/000/20021101_005_tcm21-6336.pdf
3901
3902 Under Windows NT / 2000 / XP the PERLTIDY environment variable can
3903 be placed in either the user section or the system section. The
3904 later makes the configuration file common to all users on the
3905 machine. Be sure to enter the full path of the configuration file
3906 in the value of the environment variable. Ex.
3907 PERLTIDY=C:\Documents and Settings\perltidy.ini
3908
3909 The configuration file is free format, and simply a list of
3910 parameters, just as they would be entered on a command line. Any
3911 number of lines may be used, with any number of parameters per
3912 line, although it may be easiest to read with one parameter per
3913 line. Comment text begins with a #, and there must also be a space
3914 before the # for side comments. It is a good idea to put complex
3915 parameters in either single or double quotes.
3916
3917 Here is an example of a .perltidyrc file:
3918
3919 # This is a simple of a .perltidyrc configuration file
3920 # This implements a highly spaced style
3921 -se # errors to standard error output
3922 -w # show all warnings
3923 -bl # braces on new lines
3924 -pt=0 # parens not tight at all
3925 -bt=0 # braces not tight
3926 -sbt=0 # square brackets not tight
3927
3928 The parameters in the .perltidyrc file are installed first, so any
3929 parameters given on the command line will have priority over them.
3930
3931 To avoid confusion, perltidy ignores any command in the .perltidyrc
3932 file which would cause some kind of dump and an exit. These are:
3933
3934 -h -v -ddf -dln -dop -dsn -dtt -dwls -dwrs -ss
3935
3936 There are several options may be helpful in debugging a .perltidyrc
3937 file:
3938
3939 • A very helpful command is --dump-profile or -dpro. It writes a
3940 list of all configuration filenames tested to standard output,
3941 and if a file is found, it dumps the content to standard output
3942 before exiting. So, to find out where perltidy looks for its
3943 configuration files, and which one if any it selects, just
3944 enter
3945
3946 perltidy -dpro
3947
3948 • It may be simplest to develop and test configuration files with
3949 alternative names, and invoke them with -pro=filename on the
3950 command line. Then rename the desired file to .perltidyrc when
3951 finished.
3952
3953 • The parameters in the .perltidyrc file can be switched off with
3954 the -npro option.
3955
3956 • The commands --dump-options, --dump-defaults,
3957 --dump-long-names, and --dump-short-names, all described below,
3958 may all be helpful.
3959
3960 Creating a new abbreviation
3961 A special notation is available for use in a .perltidyrc file for
3962 creating an abbreviation for a group of options. This can be used
3963 to create a shorthand for one or more styles which are frequently,
3964 but not always, used. The notation is to group the options within
3965 curly braces which are preceded by the name of the alias (without
3966 leading dashes), like this:
3967
3968 newword {
3969 -opt1
3970 -opt2
3971 }
3972
3973 where newword is the abbreviation, and opt1, etc, are existing
3974 parameters or other abbreviations. The main syntax requirement is
3975 that the new abbreviation along with its opening curly brace must
3976 begin on a new line. Space before and after the curly braces is
3977 optional. For a specific example, the following line
3978
3979 airy {-bl -pt=0 -bt=0 -sbt=0}
3980
3981 could be placed in a .perltidyrc file, and then invoked at will
3982 with
3983
3984 perltidy -airy somefile.pl
3985
3986 (Either "-airy" or "--airy" may be used).
3987
3988 Skipping leading non-perl commands with -x or --look-for-hash-bang
3989 If your script has leading lines of system commands or other text
3990 which are not valid perl code, and which are separated from the
3991 start of the perl code by a "hash-bang" line, ( a line of the form
3992 "#!...perl" ), you must use the -x flag to tell perltidy not to
3993 parse and format any lines before the "hash-bang" line. This
3994 option also invokes perl with a -x flag when checking the syntax.
3995 This option was originally added to allow perltidy to parse
3996 interactive VMS scripts, but it should be used for any script which
3997 is normally invoked with "perl -x".
3998
3999 Please note: do not use this flag unless you are sure your script
4000 needs it. Parsing errors can occur if it does not have a hash-
4001 bang, or, for example, if the actual first hash-bang is in a here-
4002 doc. In that case a parsing error will occur because the
4003 tokenization will begin in the middle of the here-doc.
4004
4005 Making a file unreadable
4006 The goal of perltidy is to improve the readability of files, but
4007 there are two commands which have the opposite effect, --mangle and
4008 --extrude. They are actually merely aliases for combinations of
4009 other parameters. Both of these strip all possible whitespace, but
4010 leave comments and pod documents, so that they are essentially
4011 reversible. The difference between these is that --mangle puts the
4012 fewest possible line breaks in a script while --extrude puts the
4013 maximum possible. Note that these options do not provided any
4014 meaningful obfuscation, because perltidy can be used to reformat
4015 the files. They were originally developed to help test the
4016 tokenization logic of perltidy, but they have other uses. One use
4017 for --mangle is the following:
4018
4019 perltidy --mangle myfile.pl -st | perltidy -o myfile.pl.new
4020
4021 This will form the maximum possible number of one-line blocks (see
4022 next section), and can sometimes help clean up a badly formatted
4023 script.
4024
4025 A similar technique can be used with --extrude instead of --mangle
4026 to make the minimum number of one-line blocks.
4027
4028 Another use for --mangle is to combine it with -dac to reduce the
4029 file size of a perl script.
4030
4031 Debugging
4032 The following flags are available for debugging:
4033
4034 --dump-cuddled-block-list or -dcbl will dump to standard output the
4035 internal hash of cuddled block types created by a
4036 -cuddled-block-list input string.
4037
4038 --dump-defaults or -ddf will write the default option set to
4039 standard output and quit
4040
4041 --dump-profile or -dpro will write the name of the current
4042 configuration file and its contents to standard output and quit.
4043
4044 --dump-options or -dop will write current option set to standard
4045 output and quit.
4046
4047 --dump-long-names or -dln will write all command line long names
4048 (passed to Get_options) to standard output and quit.
4049
4050 --dump-short-names or -dsn will write all command line short names
4051 to standard output and quit.
4052
4053 --dump-token-types or -dtt will write a list of all token types to
4054 standard output and quit.
4055
4056 --dump-want-left-space or -dwls will write the hash
4057 %want_left_space to standard output and quit. See the section on
4058 controlling whitespace around tokens.
4059
4060 --dump-want-right-space or -dwrs will write the hash
4061 %want_right_space to standard output and quit. See the section on
4062 controlling whitespace around tokens.
4063
4064 --no-memoize or -nmem will turn of memoizing. Memoization can
4065 reduce run time when running perltidy repeatedly in a single
4066 process. It is on by default but can be deactivated for testing
4067 with -nmem.
4068
4069 --no-timestamp or -nts will eliminate any time stamps in output
4070 files to prevent differences in dates from causing test
4071 installation scripts to fail. There are just a couple of places
4072 where timestamps normally occur. One is in the headers of html
4073 files, and another is when the -cscw option is selected. The
4074 default is to allow timestamps (--timestamp or -ts).
4075
4076 --file-size-order or -fso will cause files to be processed in order
4077 of increasing size, when multiple files are being processed. This
4078 is useful during program development, when large numbers of files
4079 with varying sizes are processed, because it can reduce virtual
4080 memory usage.
4081
4082 --maximum-file-size-mb=n or -maxfs=n specifies the maximum file
4083 size in megabytes that perltidy will attempt to format. This
4084 parameter is provided to avoid causing system problems by
4085 accidentally attempting to format an extremely large data file.
4086 Most perl scripts are less than about 2 MB in size. The integer n
4087 has a default value of 10, so perltidy will skip formatting files
4088 which have a size greater than 10 MB. The command to increase the
4089 limit to 20 MB for example would be
4090
4091 perltidy -maxfs=20
4092
4093 This only applies to files specified by filename on the command
4094 line.
4095
4096 --maximum-level-errors=n or -maxle=n specifies the maximum number
4097 of indentation level errors are allowed before perltidy skips
4098 formatting and just outputs a file verbatim. The default is n=1.
4099 This means that if the final indentation of a script differs from
4100 the starting indentation by more than 1 levels, the file will be
4101 output verbatim. To avoid formatting if there are any indentation
4102 level errors use -maxle=0. To skip this check you can either set n
4103 equal to a large number, such as n=100, or set n=-1.
4104
4105 For example, the following script has level error of 3 and will be
4106 output verbatim
4107
4108 Input and default output:
4109 {{{
4110
4111
4112 perltidy -maxle=100
4113 {
4114 {
4115 {
4116
4117 --maximum-unexpected-errors=n or -maxue=n specifies the maximum
4118 number of unexpected tokenization errors are allowed before
4119 formatting is skipped and a script is output verbatim. The
4120 intention is to avoid accidentally formatting a non-perl script,
4121 such as an html file for example. This check can be turned off by
4122 setting n=0.
4123
4124 A recommended value is n=3. However, the default is n=0 (skip this
4125 check) to avoid causing problems with scripts which have extended
4126 syntaxes.
4127
4128 -DEBUG will write a file with extension .DEBUG for each input file
4129 showing the tokenization of all lines of code.
4130
4131 Working with MakeMaker, AutoLoader and SelfLoader
4132 The first $VERSION line of a file which might be eval'd by
4133 MakeMaker is passed through unchanged except for indentation. Use
4134 --nopass-version-line, or -npvl, to deactivate this feature.
4135
4136 If the AutoLoader module is used, perltidy will continue formatting
4137 code after seeing an __END__ line. Use --nolook-for-autoloader, or
4138 -nlal, to deactivate this feature.
4139
4140 Likewise, if the SelfLoader module is used, perltidy will continue
4141 formatting code after seeing a __DATA__ line. Use
4142 --nolook-for-selfloader, or -nlsl, to deactivate this feature.
4143
4144 Working around problems with older version of Perl
4145 Perltidy contains a number of rules which help avoid known
4146 subtleties and problems with older versions of perl, and these
4147 rules always take priority over whatever formatting flags have been
4148 set. For example, perltidy will usually avoid starting a new line
4149 with a bareword, because this might cause problems if "use strict"
4150 is active.
4151
4152 There is no way to override these rules.
4153
4155 The -html master switch
4156 The flag -html causes perltidy to write an html file with extension
4157 .html. So, for example, the following command
4158
4159 perltidy -html somefile.pl
4160
4161 will produce a syntax-colored html file named somefile.pl.html
4162 which may be viewed with a browser.
4163
4164 Please Note: In this case, perltidy does not do any formatting to
4165 the input file, and it does not write a formatted file with
4166 extension .tdy. This means that two perltidy runs are required to
4167 create a fully reformatted, html copy of a script.
4168
4169 The -pre flag for code snippets
4170 When the -pre flag is given, only the pre-formatted section, within
4171 the <PRE> and </PRE> tags, will be output. This simplifies
4172 inclusion of the output in other files. The default is to output a
4173 complete web page.
4174
4175 The -nnn flag for line numbering
4176 When the -nnn flag is given, the output lines will be numbered.
4177
4178 The -toc, or --html-table-of-contents flag
4179 By default, a table of contents to packages and subroutines will be
4180 written at the start of html output. Use -ntoc to prevent this.
4181 This might be useful, for example, for a pod document which
4182 contains a number of unrelated code snippets. This flag only
4183 influences the code table of contents; it has no effect on any
4184 table of contents produced by pod2html (see next item).
4185
4186 The -pod, or --pod2html flag
4187 There are two options for formatting pod documentation. The
4188 default is to pass the pod through the Pod::Html module (which
4189 forms the basis of the pod2html utility). Any code sections are
4190 formatted by perltidy, and the results then merged. Note: perltidy
4191 creates a temporary file when Pod::Html is used; see "FILES".
4192 Also, Pod::Html creates temporary files for its cache.
4193
4194 NOTE: Perltidy counts the number of "=cut" lines, and either moves
4195 the pod text to the top of the html file if there is one "=cut", or
4196 leaves the pod text in its original order (interleaved with code)
4197 otherwise.
4198
4199 Most of the flags accepted by pod2html may be included in the
4200 perltidy command line, and they will be passed to pod2html. In
4201 some cases, the flags have a prefix "pod" to emphasize that they
4202 are for the pod2html, and this prefix will be removed before they
4203 are passed to pod2html. The flags which have the additional "pod"
4204 prefix are:
4205
4206 --[no]podheader --[no]podindex --[no]podrecurse --[no]podquiet
4207 --[no]podverbose --podflush
4208
4209 The flags which are unchanged from their use in pod2html are:
4210
4211 --backlink=s --cachedir=s --htmlroot=s --libpods=s --title=s
4212 --podpath=s --podroot=s
4213
4214 where 's' is an appropriate character string. Not all of these
4215 flags are available in older versions of Pod::Html. See your
4216 Pod::Html documentation for more information.
4217
4218 The alternative, indicated with -npod, is not to use Pod::Html, but
4219 rather to format pod text in italics (or whatever the stylesheet
4220 indicates), without special html markup. This is useful, for
4221 example, if pod is being used as an alternative way to write
4222 comments.
4223
4224 The -frm, or --frames flag
4225 By default, a single html output file is produced. This can be
4226 changed with the -frm option, which creates a frame holding a table
4227 of contents in the left panel and the source code in the right
4228 side. This simplifies code browsing. Assume, for example, that the
4229 input file is MyModule.pm. Then, for default file extension
4230 choices, these three files will be created:
4231
4232 MyModule.pm.html - the frame
4233 MyModule.pm.toc.html - the table of contents
4234 MyModule.pm.src.html - the formatted source code
4235
4236 Obviously this file naming scheme requires that output be directed
4237 to a real file (as opposed to, say, standard output). If this is
4238 not the case, or if the file extension is unknown, the -frm option
4239 will be ignored.
4240
4241 The -text=s, or --html-toc-extension flag
4242 Use this flag to specify the extra file extension of the table of
4243 contents file when html frames are used. The default is "toc".
4244 See "Specifying File Extensions".
4245
4246 The -sext=s, or --html-src-extension flag
4247 Use this flag to specify the extra file extension of the content
4248 file when html frames are used. The default is "src". See
4249 "Specifying File Extensions".
4250
4251 The -hent, or --html-entities flag
4252 This flag controls the use of Html::Entities for html formatting.
4253 By default, the module Html::Entities is used to encode special
4254 symbols. This may not be the right thing for some browser/language
4255 combinations. Use --nohtml-entities or -nhent to prevent this.
4256
4257 Style Sheets
4258 Style sheets make it very convenient to control and adjust the
4259 appearance of html pages. The default behavior is to write a page
4260 of html with an embedded style sheet.
4261
4262 An alternative to an embedded style sheet is to create a page with
4263 a link to an external style sheet. This is indicated with the
4264 -css=filename, where the external style sheet is filename. The
4265 external style sheet filename will be created if and only if it
4266 does not exist. This option is useful for controlling multiple
4267 pages from a single style sheet.
4268
4269 To cause perltidy to write a style sheet to standard output and
4270 exit, use the -ss, or --stylesheet, flag. This is useful if the
4271 style sheet could not be written for some reason, such as if the
4272 -pre flag was used. Thus, for example,
4273
4274 perltidy -html -ss >mystyle.css
4275
4276 will write a style sheet with the default properties to file
4277 mystyle.css.
4278
4279 The use of style sheets is encouraged, but a web page without a
4280 style sheets can be created with the flag -nss. Use this option if
4281 you must to be sure that older browsers (roughly speaking, versions
4282 prior to 4.0 of Netscape Navigator and Internet Explorer) can
4283 display the syntax-coloring of the html files.
4284
4285 Controlling HTML properties
4286 Note: It is usually more convenient to accept the default
4287 properties and then edit the stylesheet which is produced.
4288 However, this section shows how to control the properties with
4289 flags to perltidy.
4290
4291 Syntax colors may be changed from their default values by flags of
4292 the either the long form, -html-color-xxxxxx=n, or more
4293 conveniently the short form, -hcx=n, where xxxxxx is one of the
4294 following words, and x is the corresponding abbreviation:
4295
4296 Token Type xxxxxx x
4297 ---------- -------- --
4298 comment comment c
4299 number numeric n
4300 identifier identifier i
4301 bareword, function bareword w
4302 keyword keyword k
4303 quite, pattern quote q
4304 here doc text here-doc-text h
4305 here doc target here-doc-target hh
4306 punctuation punctuation pu
4307 parentheses paren p
4308 structural braces structure s
4309 semicolon semicolon sc
4310 colon colon co
4311 comma comma cm
4312 label label j
4313 sub definition name subroutine m
4314 pod text pod-text pd
4315
4316 A default set of colors has been defined, but they may be changed
4317 by providing values to any of the following parameters, where n is
4318 either a 6 digit hex RGB color value or an ascii name for a color,
4319 such as 'red'.
4320
4321 To illustrate, the following command will produce an html file
4322 somefile.pl.html with "aqua" keywords:
4323
4324 perltidy -html -hck=00ffff somefile.pl
4325
4326 and this should be equivalent for most browsers:
4327
4328 perltidy -html -hck=aqua somefile.pl
4329
4330 Perltidy merely writes any non-hex names that it sees in the html
4331 file. The following 16 color names are defined in the HTML 3.2
4332 standard:
4333
4334 black => 000000,
4335 silver => c0c0c0,
4336 gray => 808080,
4337 white => ffffff,
4338 maroon => 800000,
4339 red => ff0000,
4340 purple => 800080,
4341 fuchsia => ff00ff,
4342 green => 008000,
4343 lime => 00ff00,
4344 olive => 808000,
4345 yellow => ffff00
4346 navy => 000080,
4347 blue => 0000ff,
4348 teal => 008080,
4349 aqua => 00ffff,
4350
4351 Many more names are supported in specific browsers, but it is
4352 safest to use the hex codes for other colors. Helpful color tables
4353 can be located with an internet search for "HTML color tables".
4354
4355 Besides color, two other character attributes may be set: bold, and
4356 italics. To set a token type to use bold, use the flag
4357 --html-bold-xxxxxx or -hbx, where xxxxxx or x are the long or short
4358 names from the above table. Conversely, to set a token type to NOT
4359 use bold, use --nohtml-bold-xxxxxx or -nhbx.
4360
4361 Likewise, to set a token type to use an italic font, use the flag
4362 --html-italic-xxxxxx or -hix, where again xxxxxx or x are the long
4363 or short names from the above table. And to set a token type to
4364 NOT use italics, use --nohtml-italic-xxxxxx or -nhix.
4365
4366 For example, to use bold braces and lime color, non-bold, italics
4367 keywords the following command would be used:
4368
4369 perltidy -html -hbs -hck=00FF00 -nhbk -hik somefile.pl
4370
4371 The background color can be specified with
4372 --html-color-background=n, or -hcbg=n for short, where n is a 6
4373 character hex RGB value. The default color of text is the value
4374 given to punctuation, which is black as a default.
4375
4376 Here are some notes and hints:
4377
4378 1. If you find a preferred set of these parameters, you may want to
4379 create a .perltidyrc file containing them. See the perltidy man
4380 page for an explanation.
4381
4382 2. Rather than specifying values for these parameters, it is
4383 probably easier to accept the defaults and then edit a style sheet.
4384 The style sheet contains comments which should make this easy.
4385
4386 3. The syntax-colored html files can be very large, so it may be
4387 best to split large files into smaller pieces to improve download
4388 times.
4389
4391 Specifying Block Types
4392 Several parameters which refer to code block types may be customized by
4393 also specifying an associated list of block types. The type of a block
4394 is the name of the keyword which introduces that block, such as if,
4395 else, or sub. An exception is a labeled block, which has no keyword,
4396 and should be specified with just a colon. To specify all blocks use
4397 '*'.
4398
4399 The keyword sub indicates a named sub. For anonymous subs, use the
4400 special keyword asub.
4401
4402 For example, the following parameter specifies "sub", labels, "BEGIN",
4403 and "END" blocks:
4404
4405 -cscl="sub : BEGIN END"
4406
4407 (the meaning of the -cscl parameter is described above.) Note that
4408 quotes are required around the list of block types because of the
4409 spaces. For another example, the following list specifies all block
4410 types for vertical tightness:
4411
4412 -bbvtl='*'
4413
4414 Specifying File Extensions
4415 Several parameters allow default file extensions to be overridden. For
4416 example, a backup file extension may be specified with -bext=ext, where
4417 ext is some new extension. In order to provides the user some
4418 flexibility, the following convention is used in all cases to decide if
4419 a leading '.' should be used. If the extension "ext" begins with
4420 "A-Z", "a-z", or "0-9", then it will be appended to the filename with
4421 an intermediate '.' (or perhaps a '_' on VMS systems). Otherwise, it
4422 will be appended directly.
4423
4424 For example, suppose the file is somefile.pl. For "-bext=old", a '.'
4425 is added to give somefile.pl.old. For "-bext=.old", no additional '.'
4426 is added, so again the backup file is somefile.pl.old. For "-bext=~",
4427 then no dot is added, and the backup file will be somefile.pl~ .
4428
4430 The following list shows all short parameter names which allow a prefix
4431 'n' to produce the negated form:
4432
4433 D anl asbl asc ast asu aws b baa baao
4434 bar bbao bbb bbc bbs bl bli boa boc bok
4435 bol bom bos bot cblx ce conv csc cscb cscw
4436 dac dbc dcbl dcsc ddf dln dnl dop dp dpro
4437 dsc dsm dsn dtt dwls dwrs dws f fll frm
4438 fs fso gcs hbc hbcm hbco hbh hbhh hbi hbj
4439 hbk hbm hbn hbp hbpd hbpu hbq hbs hbsc hbv
4440 hbw hent hic hicm hico hih hihh hii hij hik
4441 him hin hip hipd hipu hiq his hisc hiv hiw
4442 hsc html ibc icb icp iob isbc iscl kgb kgbd
4443 kgbi kis lal log lop lp lsl mem nib ohbr
4444 okw ola olc oll olq opr opt osbc osbr otr
4445 ple pod pvl q sac sbc sbl scbb schb scp
4446 scsb sct se sfp sfs skp sob sobb sohb sop
4447 sosb sot ssc st sts t tac tbc toc tp
4448 tqw trp ts tsc tso vmll w wn x xci
4449 xs
4450
4451 Equivalently, the prefix 'no' or 'no-' on the corresponding long names
4452 may be used.
4453
4455 Parsing Limitations
4456 Perltidy should work properly on most perl scripts. It does a lot
4457 of self-checking, but still, it is possible that an error could be
4458 introduced and go undetected. Therefore, it is essential to make
4459 careful backups and to test reformatted scripts.
4460
4461 The main current limitation is that perltidy does not scan modules
4462 included with 'use' statements. This makes it necessary to guess
4463 the context of any bare words introduced by such modules. Perltidy
4464 has good guessing algorithms, but they are not infallible. When it
4465 must guess, it leaves a message in the log file.
4466
4467 If you encounter a bug, please report it.
4468
4469 What perltidy does not parse and format
4470 Perltidy indents but does not reformat comments and "qw" quotes.
4471 Perltidy does not in any way modify the contents of here documents
4472 or quoted text, even if they contain source code. (You could,
4473 however, reformat them separately). Perltidy does not format
4474 'format' sections in any way. And, of course, it does not modify
4475 pod documents.
4476
4478 Temporary files
4479 Under the -html option with the default --pod2html flag, a
4480 temporary file is required to pass text to Pod::Html. Unix systems
4481 will try to use the POSIX tmpnam() function. Otherwise the file
4482 perltidy.TMP will be temporarily created in the current working
4483 directory.
4484
4485 Special files when standard input is used
4486 When standard input is used, the log file, if saved, is
4487 perltidy.LOG, and any errors are written to perltidy.ERR unless the
4488 -se flag is set. These are saved in the current working directory.
4489
4490 Files overwritten
4491 The following file extensions are used by perltidy, and files with
4492 these extensions may be overwritten or deleted: .ERR, .LOG, .TEE,
4493 and/or .tdy, .html, and .bak, depending on the run type and
4494 settings.
4495
4496 Files extensions limitations
4497 Perltidy does not operate on files for which the run could produce
4498 a file with a duplicated file extension. These extensions include
4499 .LOG, .ERR, .TEE, and perhaps .tdy and .bak, depending on the run
4500 type. The purpose of this rule is to prevent generating confusing
4501 filenames such as somefile.tdy.tdy.tdy.
4502
4504 An exit value of 0, 1, or 2 is returned by perltidy to indicate the
4505 status of the result.
4506
4507 A exit value of 0 indicates that perltidy ran to completion with no
4508 error messages.
4509
4510 A non-zero exit value indicates some kind of problem was detected.
4511
4512 An exit value of 1 indicates that perltidy terminated prematurely,
4513 usually due to some kind of errors in the input parameters. This can
4514 happen for example if a parameter is misspelled or given an invalid
4515 value. Error messages in the standard error output will indicate the
4516 cause of any problem. If perltidy terminates prematurely then no
4517 output files will be produced.
4518
4519 An exit value of 2 indicates that perltidy was able to run to
4520 completion but there there are (1) warning messages in the standard
4521 error output related to parameter errors or problems and/or (2) warning
4522 messages in the perltidy error file(s) relating to possible syntax
4523 errors in one or more of the source script(s) being tidied. When
4524 multiple files are being processed, an error detected in any single
4525 file will produce this type of exit condition.
4526
4528 perlstyle(1), Perl::Tidy(3)
4529
4531 The perltidy binary uses the Perl::Tidy module and is installed when
4532 that module is installed. The module name is case-sensitive. For
4533 example, the basic command for installing with cpanm is 'cpanm
4534 Perl::Tidy'.
4535
4537 This man page documents perltidy version 20210402
4538
4540 A list of current bugs and issues can be found at the CPAN site
4541 <https://rt.cpan.org/Public/Dist/Display.html?Name=Perl-Tidy>
4542
4543 To report a new bug or problem, use the link on this page.
4544
4545 The source code repository is at
4546 <https://github.com/perltidy/perltidy>.
4547
4549 Copyright (c) 2000-2021 by Steve Hancock
4550
4552 This package is free software; you can redistribute it and/or modify it
4553 under the terms of the "GNU General Public License".
4554
4555 Please refer to the file "COPYING" for details.
4556
4558 This package is distributed in the hope that it will be useful, but
4559 WITHOUT ANY WARRANTY; without even the implied warranty of
4560 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
4561
4562 See the "GNU General Public License" for more details.
4563
4564
4565
4566perl v5.32.1 2021-04-01 PERLTIDY(1)