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