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