1=head1 A Brief Perltidy Tutorial 2 3Perltidy can save you a lot of tedious editing if you spend a few 4minutes learning to use it effectively. Perltidy is highly 5configurable, but for many programmers the default parameter set will be 6satisfactory, with perhaps a few additional parameters to account for 7style preferences. 8 9This tutorial assumes that perltidy has been installed on your system. 10Installation instructions accompany the package. To follow along with 11this tutorial, please find a small Perl script and place a copy in a 12temporary directory. For example, here is a small (and silly) script: 13 14 print "Help Desk -- What Editor do you use?"; 15 chomp($editor = <STDIN>); 16 if ($editor =~ /emacs/i) { 17 print "Why aren't you using vi?\n"; 18 } elsif ($editor =~ /vi/i) { 19 print "Why aren't you using emacs?\n"; 20 } else { 21 print "I think that's the problem\n"; 22 } 23 24It is included in the F<docs> section of the distribution. 25 26=head2 A First Test 27 28Assume that the name of your script is F<testfile.pl>. You can reformat it 29with the default options to use the style recommended in the perlstyle man 30pages with the command: 31 32 perltidy testfile.pl 33 34For safety, perltidy never overwrites your original file. In this case, 35its output will go to a file named F<testfile.pl.tdy>, which you should 36examine now with your editor. Here is what the above file looks like 37with the default options: 38 39 print "Help Desk -- What Editor do you use?"; 40 chomp( $editor = <STDIN> ); 41 if ( $editor =~ /emacs/i ) { 42 print "Why aren't you using vi?\n"; 43 } 44 elsif ( $editor =~ /vi/i ) { 45 print "Why aren't you using emacs?\n"; 46 } 47 else { 48 print "I think that's the problem\n"; 49 } 50 51You'll notice an immediate style change from the "cuddled-else" style of 52the original to the default "non-cuddled-else" style. This is because 53perltidy has to make some kind of default selection of formatting 54options, and this default tries to follow the suggestions in the 55perlstyle man pages. 56 57If you prefer the original "cuddled-else" style, don't worry, you can 58indicate that with a B<-ce> flag. So if you rerun with that flag 59 60 perltidy -ce testfile.pl 61 62you will see a return to the original "cuddled-else" style. There are 63many more parameters for controlling style, and some of the most useful 64of these are discussed below. 65 66=head2 Indentation 67 68Another noticeable difference between the original and the reformatted 69file is that the indentation has been changed from 2 spaces to 4 spaces. 70That's because 4 spaces is the default. You may change this to be a 71different number with B<-i=n>. 72 73To get some practice, try these examples, and examine the resulting 74F<testfile.pl.tdy> file: 75 76 perltidy -i=8 testfile.pl 77 78This changes the default of 4 spaces per indentation level to be 8. Now 79just to emphasize the point, try this and examine the result: 80 81 perltidy -i=0 testfile.pl 82 83There will be no indentation at all in this case. 84 85=head2 Input Flags 86 87This is a good place to mention a few points regarding the input flags. 88First, for each option, there are two forms, a long form and a short 89form, and either may be used. 90 91For example, if you want to change the number of columns corresponding to one 92indentation level to 3 (from the default of 4) you may use either 93 94 -i=3 or --indent-columns=3 95 96The short forms are convenient for entering parameters by hand, whereas 97the long forms, though often ridiculously long, are self-documenting and 98therefore useful in configuration scripts. You may use either one or 99two dashes ahead of the parameters. Also, the '=' sign is optional, 100and may be a single space instead. However, the value of a parameter 101must NOT be adjacent to the flag, like this B<-i3> (WRONG). Also, 102flags must be input separately, never bundled together. 103 104=head2 Line Length and Continuation Indentation. 105 106If you change the indentation spaces you will probably also need to 107change the continuation indentation spaces with the parameter B<-ci=n>. 108The continuation indentation is the extra indentation -- 2 spaces by 109default -- given to that portion of a long line which has been placed 110below the start of a statement. For example: 111 112 croak "Couldn't pop genome file" 113 unless sysread( $impl->{file}, $element, $impl->{group} ) 114 and truncate( $impl->{file}, $new_end ); 115 116There is no fixed rule for setting the value for B<-ci=n>, but it should 117probably not exceed one-half of the number of spaces of a full 118indentation level. 119 120In the above snippet, the statement was broken into three lines. The 121actual number is governed by a parameter, the maximum line length, as 122well as by what perltidy considers to be good break points. The maximum 123line length is 80 characters by default. You can change this to be any 124number B<n> with the B<-l=n> flag. Perltidy tries to produce lines 125which do not exceed this length, and it does this by finding good break 126points. For example, the above snippet would look like this with 127B<perltidy -l=40>: 128 129 croak "Couldn't pop genome file" 130 unless 131 sysread( $impl->{file}, $element, 132 $impl->{group} ) 133 and 134 truncate( $impl->{file}, $new_end ); 135 136You may be wondering what would happen with, say, B<-l=1>. Go 137ahead and try it. 138 139=head2 Tabs or Spaces? 140 141With indentation, there is always a tab issue to resolve. By default, 142perltidy will use leading ascii space characters instead of tabs. The 143reason is that this will be displayed correctly by virtually all 144editors, and in the long run, will avoid maintenance problems. 145 146However, if you prefer, you may have perltidy entab the leading 147whitespace of a line with the command B<-et=n>, where B<n> is the number 148of spaces which will be represented by one tab. But note that your text 149will not be displayed properly unless viewed with software that is 150configured to display B<n> spaces per tab. 151 152=head2 Input/Output Control 153 154In the first example, we saw that if we pass perltidy the name 155of a file on the command line, it reformats it and creates a 156new filename by appending an extension, F<.tdy>. This is the 157default behavior, but there are several other options. 158 159On most systems, you may use wildcards to reformat a whole batch of 160files at once, like this for example: 161 162 perltidy *.pl 163 164and in this case, each of the output files will be have a name equal to 165the input file with the extension F<.tdy> appended. If you decide that 166the formatting is acceptable, you will want to backup your originals and 167then remove the F<.tdy> extensions from the reformatted files. There is 168an powerful perl script called C<rename> that can be used for this 169purpose; if you don't have it, you can find it for example in B<The Perl 170Cookbook>. 171 172If you find that the formatting done by perltidy is usually acceptable, 173you may want to save some effort by letting perltidy do a simple backup 174of the original files and then reformat them in place. You specify this 175with a B<-b> flag. For example, the command 176 177 perltidy -b *.pl 178 179will rename the original files by appending a F<.bak> extension, and then 180create reformatted files with the same names as the originals. (If you don't 181like the default backup extension choice F<.bak>, the manual tells how to 182change it). Each time you run perltidy with the B<-b> option, the previous 183F<.bak> files will be overwritten, so please make regular separate backups. 184 185If there is no input filename specified on the command line, then input 186is assumed to come from standard input and output will go to standard 187output. On systems with a Unix-like interface, you can use perltidy as 188a filter, like this: 189 190 perltidy <somefile.pl >newfile.pl 191 192What happens in this case is that the shell takes care of the redirected 193input files, '<somefile.pl', and so perltidy never sees the filename. 194Therefore, it knows to use the standard input and standard output 195channels. 196 197If you are executing perltidy on a file and want to force the output 198to standard output, rather than create a F<.tdy> file, you can 199indicate this with the flag B<-st>, like this: 200 201 perltidy somefile.pl -st >otherfile.pl 202 203You can also control the name of the output file with the B<-o> flag, 204like this: 205 206 perltidy testfile.pl -o=testfile.new.pl 207 208=head2 Style Variations 209 210Perltidy has to make some kind of default selection of formatting 211options, and its choice is to try to follow the suggestions in the 212perlstyle man pages. Many programmers more or less follow these 213suggestions with a few exceptions. In this section we will 214look at just a few of the most commonly used style parameters. Later, 215you may want to systematically develop a set of style 216parameters with the help of 217the perltidy B<stylekey> web page at 218http://perltidy.sourceforge.net/stylekey.html 219 220=over 4 221 222=item B<-ce>, cuddled elses 223 224If you prefer cuddled elses, use the B<-ce> flag. 225 226=item B<-bl>, braces left 227 228Here is what the C<if> block in the above script looks like with B<-bl>: 229 230 if ( $editor =~ /emacs/i ) 231 { 232 print "Why aren't you using vi?\n"; 233 } 234 elsif ( $editor =~ /vi/i ) 235 { 236 print "Why aren't you using emacs?\n"; 237 } 238 else 239 { 240 print "I think that's the problem\n"; 241 } 242 243=item B<-lp>, Lining up with parentheses 244 245The B<-lp> parameter can enhance the readability of lists by adding 246extra indentation. Consider: 247 248 %romanNumerals = ( 249 one => 'I', 250 two => 'II', 251 three => 'III', 252 four => 'IV', 253 five => 'V', 254 six => 'VI', 255 seven => 'VII', 256 eight => 'VIII', 257 nine => 'IX', 258 ten => 'X' 259 ); 260 261With the B<-lp> flag, this is formatted as: 262 263 %romanNumerals = ( 264 one => 'I', 265 two => 'II', 266 three => 'III', 267 four => 'IV', 268 five => 'V', 269 six => 'VI', 270 seven => 'VII', 271 eight => 'VIII', 272 nine => 'IX', 273 ten => 'X' 274 ); 275 276which is preferred by some. (I've actually used B<-lp> and B<-cti=1> to 277format this block. The B<-cti=1> flag causes the closing paren to align 278vertically with the opening paren, which works well with the B<-lp> 279indentation style). An advantage of B<-lp> indentation are that it 280displays lists nicely. A disadvantage is that deeply nested lists can 281require a long line length. 282 283=item B<-bt>,B<-pt>,B<-sbt>: Container tightness 284 285These are parameters for controlling the amount of space within 286containing parentheses, braces, and square brackets. The example below 287shows the effect of the three possible values, 0, 1, and 2, for the case 288of parentheses: 289 290 if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 291 if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) 292 if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 293 294A value of 0 causes all parens to be padded on the inside with a space, 295and a value of 2 causes this never to happen. With a value of 1, spaces 296will be introduced if the item within is more than a single token. 297 298=back 299 300=head2 Configuration Files 301 302While style preferences vary, most people would agree that it is 303important to maintain a uniform style within a script, and this is a 304major benefit provided by perltidy. Once you have decided on which, if 305any, special options you prefer, you may want to avoid having to enter 306them each time you run it. You can do this by creating a special file 307named F<.perltidyrc> in either your home directory, your current 308directory, or certain system-dependent locations. (Note the leading "." 309in the file name). 310 311A handy command to know when you start using a configuration file is 312 313 perltidy -dpro 314 315which will dump to standard output the search that perltidy makes when 316looking for a configuration file, and the contents of the one that it 317selects, if any. This is one of a number of useful "dump and die" 318commands, in which perltidy will dump some information to standard 319output and then immediately exit. Others include B<-h>, which dumps 320help information, and B<-v>, which dumps the version number. 321 322Another useful command when working with configuration files is 323 324 perltidy -pro=file 325 326which causes the contents of F<file> to be used as the configuration 327file instead of a F<.perltidyrc> file. With this command, you can 328easily switch among several different candidate configuration files 329during testing. 330 331This F<.perltidyrc> file is free format. It is simply a list of 332parameters, just as they would be entered on a command line. Any number 333of lines may be used, with any number of parameters per line, although 334it may be easiest to read with one parameter per line. Blank lines are 335ignored, and text after a '#' is ignored to the end of a line. 336 337Here is an example of a F<.perltidyrc> file: 338 339 # This is a simple of a .perltidyrc configuration file 340 # This implements a highly spaced style 341 -bl # braces on new lines 342 -pt=0 # parens not tight at all 343 -bt=0 # braces not tight 344 -sbt=0 # square brackets not tight 345 346If you experiment with this file, remember that it is in your directory, 347since if you are running on a Unix system, files beginning with a "." 348are normally hidden. 349 350If you have a F<.perltidyrc> file, and want perltidy to ignore it, 351use the B<-npro> flag on the command line. 352 353=head2 Error Reporting 354 355Let's run through a 'fire drill' to see how perltidy reports errors. Try 356introducing an extra opening brace somewhere in a test file. For example, 357introducing an extra brace in the file listed above produces the following 358message on the terminal (or standard error output): 359 360 ## Please see file testfile.pl.ERR! 361 362Here is what F<testfile.pl.ERR> contains: 363 364 10: final indentation level: 1 365 366 Final nesting depth of '{'s is 1 367 The most recent un-matched '{' is on line 6 368 6: } elsif ($temperature < 68) {{ 369 ^ 370 371This shows how perltidy will, by default, write error messages to a file 372with the extension F<.ERR>, and it will write a note that it did so to 373the standard error device. If you would prefer to have the error 374messages sent to standard output, instead of to a F<.ERR> file, use the 375B<-se> flag. 376 377Almost every programmer would want to see error messages of this type, 378but there are a number of messages which, if reported, would be 379annoying. To manage this problem, perltidy puts its messages into two 380categories: errors and warnings. The default is to just report the 381errors, but you can control this with input flags, as follows: 382 383 flag what this does 384 ---- -------------- 385 default: report errors but not warnings 386 -w report all errors and warnings 387 -q quiet! do not report either errors or warnings 388 389The default is generally a good choice, but it's not a bad idea to check 390programs with B<-w> occasionally, especially if your are looking for a 391bug. For example, it will ask if you really want '=' instead of '=~' in 392this line: 393 394 $line = s/^\s*//; 395 396This kind of error can otherwise be hard to find. 397 398=head2 The Log File 399 400One last topic that needs to be touched upon concerns the F<.LOG> file. 401This is where perltidy records messages that are not normally of any 402interest, but which just might occasionally be useful. This file is not 403saved, though, unless perltidy detects that it has made a mistake or you 404ask for it to be saved. 405 406There are a couple of ways to ask perltidy to save a log file. To 407create a relatively sparse log file, use 408 409 perltidy -log testfile.pl 410 411and for a verbose log file, use 412 413 perltidy -g testfile.pl 414 415The difference is that the first form only saves detailed information at 416least every 50th line, while the second form saves detailed information 417about every line. 418 419So returning to our example, lets force perltidy to save a 420verbose log file by issuing the following command 421 422 perltidy -g testfile.pl 423 424You will find that a file named F<testfile.pl.LOG> has been 425created in your directory. 426 427If you open this file, you will see that it is a text file with a 428combination of warning messages and informative messages. All you need 429to know for now is that it exists; someday it may be useful. 430 431=head2 Using Perltidy as a Filter on Selected Text from an Editor 432 433Most programmer's editors allow a selected group of lines to be passed 434through an external filter. Perltidy has been designed to work well as 435a filter, and it is well worthwhile learning the appropriate commands to 436do this with your editor. This means that you can enter a few 437keystrokes and watch a block of text get reformatted. If you are not 438doing this, you are missing out of a lot of fun! You may want to supply 439the B<-q> flag to prevent error messages regarding incorrect syntax, 440since errors may be obvious in the indentation of the reformatted text. 441This is entirely optional, but if you do not use the B<-q> flag, you 442will need to use the undo keys in case an error message appears on the 443screen. 444 445For example, within the B<vim> editor it is only necessary to select the 446text by any of the text selection methods, and then issue the command 447!perltidy in command mode. Thus, an entire file can be formatted using 448 449 :%!perltidy -q 450 451or, without the B<-q> flag, just 452 453 :%!perltidy 454 455It isn't necessary to format an entire file, however. Perltidy will 456probably work well as long as you select blocks of text whose braces, 457parentheses, and square brackets are properly balanced. You can 458even format an C<elsif> block without the leading C<if> block, as 459long as the text you select has all braces balanced. 460 461For the B<emacs> editor, first mark a region and then pipe it through 462perltidy. For example, to format an entire file, select it with C<C-x h> 463and then pipe it with C<M-1 M-|> and then C<perltidy>. The numeric 464argument, C<M-1> causes the output from perltidy to replace the marked 465text. See "GNU Emacs Manual" for more information, 466http://www.gnu.org/manual/emacs-20.3/html_node/emacs_toc.html 467 468If you have difficulty with an editor, try the B<-st> flag, which will 469force perltidy to send output to standard output. This might be needed, 470for example, if the editor passes text to perltidy as temporary filename 471instead of through the standard input. If this works, you might put the 472B<-st> flag in your F<.perltidyrc> file. 473 474If you have some tips for making perltidy work with your editor, and 475are willing to share them, please email me (see below) and I'll try to 476incorporate them in this document or put up a link to them. 477 478After you get your editor and perltidy successfully talking to each 479other, try formatting a snippet of code with a brace error to see what 480happens. (Do not use the quiet flag, B<-q>, for this test). Perltidy 481will send one line starting with C<##> to standard error output. Your 482editor may either display it at the top of the reformatted text or at 483the bottom (or even midstream!). You probably cannot control this, and 484perltidy can't, but you need to know where to look when an actual error 485is detected. 486 487=head2 Writing an HTML File 488 489Perltidy can switch between two different output modes. We have been 490discussing what might be called its "beautifier" mode, but it can also 491output in HTML. To do this, use the B<-html> flag, like this: 492 493 perltidy -html testfile.pl 494 495which will produce a file F<testfile.pl.html>. There are many 496parameters available for adjusting the appearance of an HTML file, but a 497very easy way is to just write the HTML file with this simple command 498and then edit the stylesheet which is embedded at its top. 499 500One important thing to know about the B<-html> flag is that perltidy can 501either send its output to its beautifier or to its HTML writer, but 502(unfortunately) not both in a single run. So the situation can be 503represented like this: 504 505 ------------ 506 | | --->beautifier--> testfile.pl.tdy 507 testfile.pl --> | perltidy | --> 508 | | --->HTML -------> testfile.pl.html 509 ------------ 510 511And in the future, there may be more output filters. So if you would 512like to both beautify a script and write it to HTML, you need to do it 513in two steps. 514 515=head2 Summary 516 517That's enough to get started using perltidy. 518When you are ready to create a F<.perltidyrc> file, you may find it 519helpful to use the F<stylekey> page as a guide at 520http://perltidy.sourceforge.net/stylekey.html 521 522Many additional special 523features and capabilities can be found in the manual pages for perltidy 524at 525http://perltidy.sourceforge.net/perltidy.html 526 527We hope that perltidy makes perl programming a little more fun. 528Please check the perltidy 529web site http://perltidy.sourceforge.net occasionally 530for updates. 531 532The author may be contacted at perltidy at users.sourceforge.net. 533 534=cut 535