]> git.donarmstrong.com Git - perltidy.git/blobdiff - docs/tutorial.pod
New upstream version 20190601
[perltidy.git] / docs / tutorial.pod
diff --git a/docs/tutorial.pod b/docs/tutorial.pod
deleted file mode 100644 (file)
index 9d1f260..0000000
+++ /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 = <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