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