--- /dev/null
+=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 = <STDIN>);
+ 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<docs> section of the distribution.
+
+=head2 A First Test
+
+Assume that the name of your script is F<testfile.pl>. 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<testfile.pl.tdy>, 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 = <STDIN> );
+ 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<testfile.pl.tdy> 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<n> 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<perltidy -l=40>:
+
+ 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<n> 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<n> 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<rename> that can be used for this
+purpose; if you don't have it, you can find it for example in B<The Perl
+Cookbook>.
+
+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 <somefile.pl >newfile.pl
+
+What happens in this case is that the shell takes care of the redirected
+input files, '<somefile.pl', and so perltidy never sees the filename.
+Therefore, it knows to use the standard input and standard output
+channels.
+
+If you are executing perltidy on a file and want to force the output
+to standard output, rather than create a F<.tdy> 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<stylekey> 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<if> 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<file> 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<testfile.pl.ERR> 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<testfile.pl.LOG> 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<vim> 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<elsif> block without the leading C<if> block, as
+long as the text you select has all braces balanced.
+
+For the B<emacs> editor, first mark a region and then pipe it through
+perltidy. For example, to format an entire file, select it with C<C-x h>
+and then pipe it with C<M-1 M-|> and then C<perltidy>. The numeric
+argument, C<M-1> 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<testfile.pl.html>. 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<stylekey> 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
projects / perltidy.git / blobdiff