X-Git-Url: https://git.donarmstrong.com/?a=blobdiff_plain;f=docs%2Ftutorial.pod;fp=docs%2Ftutorial.pod;h=0000000000000000000000000000000000000000;hb=657098da8da16dccd551721ffc180956d8aab7fc;hp=9d1f2606c5e33a65e6e0c09f9768c2aedc8fe6ec;hpb=5af8685bea60c00aae46266c726ddfb0132d7d12;p=perltidy.git diff --git a/docs/tutorial.pod b/docs/tutorial.pod deleted file mode 100644 index 9d1f260..0000000 --- a/docs/tutorial.pod +++ /dev/null @@ -1,534 +0,0 @@ -=head1 A Brief Perltidy Tutorial - -Perltidy can save you a lot of tedious editing if you spend a few -minutes learning to use it effectively. Perltidy is highly -configurable, but for many programmers the default parameter set will be -satisfactory, with perhaps a few additional parameters to account for -style preferences. - -This tutorial assumes that perltidy has been installed on your system. -Installation instructions accompany the package. To follow along with -this tutorial, please find a small Perl script and place a copy in a -temporary directory. For example, here is a small (and silly) script: - - print "Help Desk -- What Editor do you use?"; - chomp($editor = ); - if ($editor =~ /emacs/i) { - print "Why aren't you using vi?\n"; - } elsif ($editor =~ /vi/i) { - print "Why aren't you using emacs?\n"; - } else { - print "I think that's the problem\n"; - } - -It is included in the F section of the distribution. - -=head2 A First Test - -Assume that the name of your script is F. You can reformat it -with the default options to use the style recommended in the perlstyle man -pages with the command: - - perltidy testfile.pl - -For safety, perltidy never overwrites your original file. In this case, -its output will go to a file named F, which you should -examine now with your editor. Here is what the above file looks like -with the default options: - - print "Help Desk -- What Editor do you use?"; - chomp( $editor = ); - if ( $editor =~ /emacs/i ) { - print "Why aren't you using vi?\n"; - } - elsif ( $editor =~ /vi/i ) { - print "Why aren't you using emacs?\n"; - } - else { - print "I think that's the problem\n"; - } - -You'll notice an immediate style change from the "cuddled-else" style of -the original to the default "non-cuddled-else" style. This is because -perltidy has to make some kind of default selection of formatting -options, and this default tries to follow the suggestions in the -perlstyle man pages. - -If you prefer the original "cuddled-else" style, don't worry, you can -indicate that with a B<-ce> flag. So if you rerun with that flag - - perltidy -ce testfile.pl - -you will see a return to the original "cuddled-else" style. There are -many more parameters for controlling style, and some of the most useful -of these are discussed below. - -=head2 Indentation - -Another noticeable difference between the original and the reformatted -file is that the indentation has been changed from 2 spaces to 4 spaces. -That's because 4 spaces is the default. You may change this to be a -different number with B<-i=n>. - -To get some practice, try these examples, and examine the resulting -F file: - - perltidy -i=8 testfile.pl - -This changes the default of 4 spaces per indentation level to be 8. Now -just to emphasize the point, try this and examine the result: - - perltidy -i=0 testfile.pl - -There will be no indentation at all in this case. - -=head2 Input Flags - -This is a good place to mention a few points regarding the input flags. -First, for each option, there are two forms, a long form and a short -form, and either may be used. - -For example, if you want to change the number of columns corresponding to one -indentation level to 3 (from the default of 4) you may use either - - -i=3 or --indent-columns=3 - -The short forms are convenient for entering parameters by hand, whereas -the long forms, though often ridiculously long, are self-documenting and -therefore useful in configuration scripts. You may use either one or -two dashes ahead of the parameters. Also, the '=' sign is optional, -and may be a single space instead. However, the value of a parameter -must NOT be adjacent to the flag, like this B<-i3> (WRONG). Also, -flags must be input separately, never bundled together. - -=head2 Line Length and Continuation Indentation. - -If you change the indentation spaces you will probably also need to -change the continuation indentation spaces with the parameter B<-ci=n>. -The continuation indentation is the extra indentation -- 2 spaces by -default -- given to that portion of a long line which has been placed -below the start of a statement. For example: - - croak "Couldn't pop genome file" - unless sysread( $impl->{file}, $element, $impl->{group} ) - and truncate( $impl->{file}, $new_end ); - -There is no fixed rule for setting the value for B<-ci=n>, but it should -probably not exceed one-half of the number of spaces of a full -indentation level. - -In the above snippet, the statement was broken into three lines. The -actual number is governed by a parameter, the maximum line length, as -well as by what perltidy considers to be good break points. The maximum -line length is 80 characters by default. You can change this to be any -number B with the B<-l=n> flag. Perltidy tries to produce lines -which do not exceed this length, and it does this by finding good break -points. For example, the above snippet would look like this with -B: - - croak "Couldn't pop genome file" - unless - sysread( $impl->{file}, $element, - $impl->{group} ) - and - truncate( $impl->{file}, $new_end ); - -You may be wondering what would happen with, say, B<-l=1>. Go -ahead and try it. - -=head2 Tabs or Spaces? - -With indentation, there is always a tab issue to resolve. By default, -perltidy will use leading ascii space characters instead of tabs. The -reason is that this will be displayed correctly by virtually all -editors, and in the long run, will avoid maintenance problems. - -However, if you prefer, you may have perltidy entab the leading -whitespace of a line with the command B<-et=n>, where B is the number -of spaces which will be represented by one tab. But note that your text -will not be displayed properly unless viewed with software that is -configured to display B spaces per tab. - -=head2 Input/Output Control - -In the first example, we saw that if we pass perltidy the name -of a file on the command line, it reformats it and creates a -new filename by appending an extension, F<.tdy>. This is the -default behavior, but there are several other options. - -On most systems, you may use wildcards to reformat a whole batch of -files at once, like this for example: - - perltidy *.pl - -and in this case, each of the output files will be have a name equal to -the input file with the extension F<.tdy> appended. If you decide that -the formatting is acceptable, you will want to backup your originals and -then remove the F<.tdy> extensions from the reformatted files. There is -an powerful perl script called C that can be used for this -purpose; if you don't have it, you can find it for example in B. - -If you find that the formatting done by perltidy is usually acceptable, -you may want to save some effort by letting perltidy do a simple backup -of the original files and then reformat them in place. You specify this -with a B<-b> flag. For example, the command - - perltidy -b *.pl - -will rename the original files by appending a F<.bak> extension, and then -create reformatted files with the same names as the originals. (If you don't -like the default backup extension choice F<.bak>, the manual tells how to -change it). Each time you run perltidy with the B<-b> option, the previous -F<.bak> files will be overwritten, so please make regular separate backups. - -If there is no input filename specified on the command line, then input -is assumed to come from standard input and output will go to standard -output. On systems with a Unix-like interface, you can use perltidy as -a filter, like this: - - perltidy newfile.pl - -What happens in this case is that the shell takes care of the redirected -input files, ' file, you can -indicate this with the flag B<-st>, like this: - - perltidy somefile.pl -st >otherfile.pl - -You can also control the name of the output file with the B<-o> flag, -like this: - - perltidy testfile.pl -o=testfile.new.pl - -=head2 Style Variations - -Perltidy has to make some kind of default selection of formatting -options, and its choice is to try to follow the suggestions in the -perlstyle man pages. Many programmers more or less follow these -suggestions with a few exceptions. In this section we will -look at just a few of the most commonly used style parameters. Later, -you may want to systematically develop a set of style -parameters with the help of -the perltidy B web page at -http://perltidy.sourceforge.net/stylekey.html - -=over 4 - -=item B<-ce>, cuddled elses - -If you prefer cuddled elses, use the B<-ce> flag. - -=item B<-bl>, braces left - -Here is what the C block in the above script looks like with B<-bl>: - - if ( $editor =~ /emacs/i ) - { - print "Why aren't you using vi?\n"; - } - elsif ( $editor =~ /vi/i ) - { - print "Why aren't you using emacs?\n"; - } - else - { - print "I think that's the problem\n"; - } - -=item B<-lp>, Lining up with parentheses - -The B<-lp> parameter can enhance the readability of lists by adding -extra indentation. Consider: - - %romanNumerals = ( - one => 'I', - two => 'II', - three => 'III', - four => 'IV', - five => 'V', - six => 'VI', - seven => 'VII', - eight => 'VIII', - nine => 'IX', - ten => 'X' - ); - -With the B<-lp> flag, this is formatted as: - - %romanNumerals = ( - one => 'I', - two => 'II', - three => 'III', - four => 'IV', - five => 'V', - six => 'VI', - seven => 'VII', - eight => 'VIII', - nine => 'IX', - ten => 'X' - ); - -which is preferred by some. (I've actually used B<-lp> and B<-cti=1> to -format this block. The B<-cti=1> flag causes the closing paren to align -vertically with the opening paren, which works well with the B<-lp> -indentation style). An advantage of B<-lp> indentation are that it -displays lists nicely. A disadvantage is that deeply nested lists can -require a long line length. - -=item B<-bt>,B<-pt>,B<-sbt>: Container tightness - -These are parameters for controlling the amount of space within -containing parentheses, braces, and square brackets. The example below -shows the effect of the three possible values, 0, 1, and 2, for the case -of parentheses: - - if ( ( my $len_tab = length( $tabstr ) ) > 0 ) { # -pt=0 - if ( ( my $len_tab = length($tabstr) ) > 0 ) { # -pt=1 (default) - if ((my $len_tab = length($tabstr)) > 0) { # -pt=2 - -A value of 0 causes all parens to be padded on the inside with a space, -and a value of 2 causes this never to happen. With a value of 1, spaces -will be introduced if the item within is more than a single token. - -=back - -=head2 Configuration Files - -While style preferences vary, most people would agree that it is -important to maintain a uniform style within a script, and this is a -major benefit provided by perltidy. Once you have decided on which, if -any, special options you prefer, you may want to avoid having to enter -them each time you run it. You can do this by creating a special file -named F<.perltidyrc> in either your home directory, your current -directory, or certain system-dependent locations. (Note the leading "." -in the file name). - -A handy command to know when you start using a configuration file is - - perltidy -dpro - -which will dump to standard output the search that perltidy makes when -looking for a configuration file, and the contents of the one that it -selects, if any. This is one of a number of useful "dump and die" -commands, in which perltidy will dump some information to standard -output and then immediately exit. Others include B<-h>, which dumps -help information, and B<-v>, which dumps the version number. - -Another useful command when working with configuration files is - - perltidy -pro=file - -which causes the contents of F to be used as the configuration -file instead of a F<.perltidyrc> file. With this command, you can -easily switch among several different candidate configuration files -during testing. - -This F<.perltidyrc> file is free format. It is simply a list of -parameters, just as they would be entered on a command line. Any number -of lines may be used, with any number of parameters per line, although -it may be easiest to read with one parameter per line. Blank lines are -ignored, and text after a '#' is ignored to the end of a line. - -Here is an example of a F<.perltidyrc> file: - - # This is a simple of a .perltidyrc configuration file - # This implements a highly spaced style - -bl # braces on new lines - -pt=0 # parens not tight at all - -bt=0 # braces not tight - -sbt=0 # square brackets not tight - -If you experiment with this file, remember that it is in your directory, -since if you are running on a Unix system, files beginning with a "." -are normally hidden. - -If you have a F<.perltidyrc> file, and want perltidy to ignore it, -use the B<-npro> flag on the command line. - -=head2 Error Reporting - -Let's run through a 'fire drill' to see how perltidy reports errors. Try -introducing an extra opening brace somewhere in a test file. For example, -introducing an extra brace in the file listed above produces the following -message on the terminal (or standard error output): - - ## Please see file testfile.pl.ERR! - -Here is what F contains: - - 10: final indentation level: 1 - - Final nesting depth of '{'s is 1 - The most recent un-matched '{' is on line 6 - 6: } elsif ($temperature < 68) {{ - ^ - -This shows how perltidy will, by default, write error messages to a file -with the extension F<.ERR>, and it will write a note that it did so to -the standard error device. If you would prefer to have the error -messages sent to standard output, instead of to a F<.ERR> file, use the -B<-se> flag. - -Almost every programmer would want to see error messages of this type, -but there are a number of messages which, if reported, would be -annoying. To manage this problem, perltidy puts its messages into two -categories: errors and warnings. The default is to just report the -errors, but you can control this with input flags, as follows: - - flag what this does - ---- -------------- - default: report errors but not warnings - -w report all errors and warnings - -q quiet! do not report either errors or warnings - -The default is generally a good choice, but it's not a bad idea to check -programs with B<-w> occasionally, especially if your are looking for a -bug. For example, it will ask if you really want '=' instead of '=~' in -this line: - - $line = s/^\s*//; - -This kind of error can otherwise be hard to find. - -=head2 The Log File - -One last topic that needs to be touched upon concerns the F<.LOG> file. -This is where perltidy records messages that are not normally of any -interest, but which just might occasionally be useful. This file is not -saved, though, unless perltidy detects that it has made a mistake or you -ask for it to be saved. - -There are a couple of ways to ask perltidy to save a log file. To -create a relatively sparse log file, use - - perltidy -log testfile.pl - -and for a verbose log file, use - - perltidy -g testfile.pl - -The difference is that the first form only saves detailed information at -least every 50th line, while the second form saves detailed information -about every line. - -So returning to our example, lets force perltidy to save a -verbose log file by issuing the following command - - perltidy -g testfile.pl - -You will find that a file named F has been -created in your directory. - -If you open this file, you will see that it is a text file with a -combination of warning messages and informative messages. All you need -to know for now is that it exists; someday it may be useful. - -=head2 Using Perltidy as a Filter on Selected Text from an Editor - -Most programmer's editors allow a selected group of lines to be passed -through an external filter. Perltidy has been designed to work well as -a filter, and it is well worthwhile learning the appropriate commands to -do this with your editor. This means that you can enter a few -keystrokes and watch a block of text get reformatted. If you are not -doing this, you are missing out of a lot of fun! You may want to supply -the B<-q> flag to prevent error messages regarding incorrect syntax, -since errors may be obvious in the indentation of the reformatted text. -This is entirely optional, but if you do not use the B<-q> flag, you -will need to use the undo keys in case an error message appears on the -screen. - -For example, within the B editor it is only necessary to select the -text by any of the text selection methods, and then issue the command -!perltidy in command mode. Thus, an entire file can be formatted using - - :%!perltidy -q - -or, without the B<-q> flag, just - - :%!perltidy - -It isn't necessary to format an entire file, however. Perltidy will -probably work well as long as you select blocks of text whose braces, -parentheses, and square brackets are properly balanced. You can -even format an C block without the leading C block, as -long as the text you select has all braces balanced. - -For the B editor, first mark a region and then pipe it through -perltidy. For example, to format an entire file, select it with C -and then pipe it with C and then C. The numeric -argument, C causes the output from perltidy to replace the marked -text. See "GNU Emacs Manual" for more information, -http://www.gnu.org/manual/emacs-20.3/html_node/emacs_toc.html - -If you have difficulty with an editor, try the B<-st> flag, which will -force perltidy to send output to standard output. This might be needed, -for example, if the editor passes text to perltidy as temporary filename -instead of through the standard input. If this works, you might put the -B<-st> flag in your F<.perltidyrc> file. - -If you have some tips for making perltidy work with your editor, and -are willing to share them, please email me (see below) and I'll try to -incorporate them in this document or put up a link to them. - -After you get your editor and perltidy successfully talking to each -other, try formatting a snippet of code with a brace error to see what -happens. (Do not use the quiet flag, B<-q>, for this test). Perltidy -will send one line starting with C<##> to standard error output. Your -editor may either display it at the top of the reformatted text or at -the bottom (or even midstream!). You probably cannot control this, and -perltidy can't, but you need to know where to look when an actual error -is detected. - -=head2 Writing an HTML File - -Perltidy can switch between two different output modes. We have been -discussing what might be called its "beautifier" mode, but it can also -output in HTML. To do this, use the B<-html> flag, like this: - - perltidy -html testfile.pl - -which will produce a file F. There are many -parameters available for adjusting the appearance of an HTML file, but a -very easy way is to just write the HTML file with this simple command -and then edit the stylesheet which is embedded at its top. - -One important thing to know about the B<-html> flag is that perltidy can -either send its output to its beautifier or to its HTML writer, but -(unfortunately) not both in a single run. So the situation can be -represented like this: - - ------------ - | | --->beautifier--> testfile.pl.tdy - testfile.pl --> | perltidy | --> - | | --->HTML -------> testfile.pl.html - ------------ - -And in the future, there may be more output filters. So if you would -like to both beautify a script and write it to HTML, you need to do it -in two steps. - -=head2 Summary - -That's enough to get started using perltidy. -When you are ready to create a F<.perltidyrc> file, you may find it -helpful to use the F page as a guide at -http://perltidy.sourceforge.net/stylekey.html - -Many additional special -features and capabilities can be found in the manual pages for perltidy -at -http://perltidy.sourceforge.net/perltidy.html - -We hope that perltidy makes perl programming a little more fun. -Please check the perltidy -web site http://perltidy.sourceforge.net occasionally -for updates. - -The author may be contacted at perltidy at users.sourceforge.net. - -=cut