This is a live mirror of the Perl 5 development currently hosted at https://github.com/perl/perl5
perlvar: Fix long lines
authorFather Chrysostomos <sprout@cpan.org>
Thu, 8 Mar 2012 01:08:51 +0000 (17:08 -0800)
committerFather Chrysostomos <sprout@cpan.org>
Thu, 8 Mar 2012 01:08:51 +0000 (17:08 -0800)
Also, make all indented code start with a four-space indent.  Before
this it was inconsistent throughout.

pod/perlvar.pod

index ed4b370..72968f1 100644 (file)
@@ -41,11 +41,11 @@ declaration and are always forced to be in package C<main>; they are
 also exempt from C<strict 'vars'> errors.  A few other names are also
 exempt in these ways:
 
-       ENV      STDIN
-       INC      STDOUT
-       ARGV     STDERR
-       ARGVOUT
-       SIG
+    ENV      STDIN
+    INC      STDOUT
+    ARGV     STDERR
+    ARGVOUT
+    SIG
 
 In particular, the special C<${^_XYZ}> variables are always taken
 to be in package C<main>, regardless of any C<package> declarations
@@ -57,7 +57,7 @@ The following names have special meaning to Perl.  Most punctuation
 names have reasonable mnemonics, or analogs in the shells.
 Nevertheless, if you wish to use long variable names, you need only say:
 
-       use English;
+    use English;
 
 at the top of your program.  This aliases all the short names to the long
 names in the current package.  Some even have medium names, generally
@@ -65,7 +65,7 @@ borrowed from B<awk>.  To avoid a performance hit, if you don't need the
 C<$PREMATCH>, C<$MATCH>, or C<$POSTMATCH> it's best to use the C<English>
 module without them:
 
-       use English '-no_match_vars';
+    use English '-no_match_vars';
 
 Before you continue, note the sort order for variables.  In general, we
 first list the variables in case-insensitive, almost-lexigraphical
@@ -86,17 +86,17 @@ X<$_> X<$ARG>
 The default input and pattern-searching space.  The following pairs are
 equivalent:
 
-       while (<>) {...}    # equivalent only in while!
-       while (defined($_ = <>)) {...}
+    while (<>) {...}    # equivalent only in while!
+    while (defined($_ = <>)) {...}
 
-       /^Subject:/
-       $_ =~ /^Subject:/
+    /^Subject:/
+    $_ =~ /^Subject:/
 
-       tr/a-z/A-Z/
-       $_ =~ tr/a-z/A-Z/
+    tr/a-z/A-Z/
+    $_ =~ tr/a-z/A-Z/
 
-       chomp
-       chomp($_)
+    chomp
+    chomp($_)
 
 Here are the places where Perl will assume C<$_> even if you don't use it:
 
@@ -171,11 +171,11 @@ When an array or an array slice is interpolated into a double-quoted
 string or a similar context such as C</.../>, its elements are
 separated by this value.  Default is a space.  For example, this:
 
-       print "The array is: @array\n";
+    print "The array is: @array\n";
 
 is equivalent to this:
 
-       print "The array is: " . join($", @array) . "\n";
+    print "The array is: " . join($", @array) . "\n";
 
 Mnemonic: works in double-quoted context.
 
@@ -341,8 +341,8 @@ X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
 
 The effective uid of this process.  For example:
 
-       $< = $>;            # set real to effective uid
-       ($<,$>) = ($>,$<);  # swap real and effective uids
+    $< = $>;            # set real to effective uid
+    ($<,$>) = ($>,$<);  # swap real and effective uids
 
 You can change both the effective uid and the real uid at the same
 time by using C<POSIX::setuid()>.  Changes to C<< $> >> require a check
@@ -363,19 +363,19 @@ X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
 The subscript separator for multidimensional array emulation.  If you
 refer to a hash element as
 
-       $foo{$a,$b,$c}
+    $foo{$a,$b,$c}
 
 it really means
 
-       $foo{join($;, $a, $b, $c)}
+    $foo{join($;, $a, $b, $c)}
 
 But don't put
 
-       @foo{$a,$b,$c}  # a slice--note the @
+    @foo{$a,$b,$c}     # a slice--note the @
 
 which means
 
-       ($foo{$a},$foo{$b},$foo{$c})
+    ($foo{$a},$foo{$b},$foo{$c})
 
 Default is "\034", the same as SUBSEP in B<awk>.  If your keys contain
 binary data there might not be any safe value for C<$;>.
@@ -439,8 +439,8 @@ either by C<-T> or by C<-t>.)  If you need to modify this at runtime,
 you should use the C<use lib> pragma to get the machine-dependent
 library properly loaded also:
 
-       use lib '/mypath/libdir/';
-       use SomeMod;
+    use lib '/mypath/libdir/';
+    use SomeMod;
 
 You can also insert hooks into the file inclusion system by putting Perl
 code directly into C<@INC>.  Those hooks may be subroutine references,
@@ -481,7 +481,7 @@ as an emergency memory pool after C<die()>ing.  Suppose that your Perl
 were compiled with C<-DPERL_EMERGENCY_SBRK> and used Perl's malloc.
 Then
 
-       $^M = 'a' x (1 << 16);
+    $^M = 'a' x (1 << 16);
 
 would allocate a 64K buffer for use in an emergency.  See the
 F<INSTALL> file in the Perl distribution for information on how to
@@ -516,18 +516,18 @@ X<%SIG>
 
 The hash C<%SIG> contains signal handlers for signals.  For example:
 
-       sub handler {   # 1st argument is signal name
-               my($sig) = @_;
-               print "Caught a SIG$sig--shutting down\n";
-               close(LOG);
-               exit(0);
-               }
+    sub handler {   # 1st argument is signal name
+       my($sig) = @_;
+       print "Caught a SIG$sig--shutting down\n";
+       close(LOG);
+       exit(0);
+       }
 
-       $SIG{'INT'}  = \&handler;
-       $SIG{'QUIT'} = \&handler;
-       ...
-       $SIG{'INT'}  = 'DEFAULT';   # restore default action
-       $SIG{'QUIT'} = 'IGNORE';    # ignore SIGQUIT
+    $SIG{'INT'}  = \&handler;
+    $SIG{'QUIT'} = \&handler;
+    ...
+    $SIG{'INT'}  = 'DEFAULT';   # restore default action
+    $SIG{'QUIT'} = 'IGNORE';    # ignore SIGQUIT
 
 Using a value of C<'IGNORE'> usually has the effect of ignoring the
 signal, except for the C<CHLD> signal.  See L<perlipc> for more about
@@ -535,10 +535,13 @@ this special case.
 
 Here are some other examples:
 
-       $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not recommended)
-       $SIG{"PIPE"} = \&Plumber;   # just fine; assume current Plumber
-       $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
-       $SIG{"PIPE"} = Plumber();   # oops, what did Plumber() return??
+    $SIG{"PIPE"} = "Plumber";   # assumes main::Plumber (not
+                               # recommended)
+    $SIG{"PIPE"} = \&Plumber;   # just fine; assume current
+                               # Plumber
+    $SIG{"PIPE"} = *Plumber;    # somewhat esoteric
+    $SIG{"PIPE"} = Plumber();   # oops, what did Plumber()
+                               # return??
 
 Be sure not to use a bareword as the name of a signal handler,
 lest you inadvertently call it.
@@ -558,13 +561,13 @@ ordinary printing of warnings to C<STDERR> to be suppressed.  You can
 use this to save warnings in a variable, or turn warnings into fatal
 errors, like this:
 
-       local $SIG{__WARN__} = sub { die $_[0] };
-       eval $proggie;
+    local $SIG{__WARN__} = sub { die $_[0] };
+    eval $proggie;
 
 As the C<'IGNORE'> hook is not supported by C<__WARN__>, you can
 disable warnings using the empty subroutine:
 
-       local $SIG{__WARN__} = sub {};
+    local $SIG{__WARN__} = sub {};
 
 The routine indicated by C<$SIG{__DIE__}> is called when a fatal
 exception is about to be thrown.  The error message is passed as the
@@ -590,10 +593,11 @@ evaluate Perl code from such a handler will probably result in a
 segfault.  This means that warnings or errors that result from parsing
 Perl should be used with extreme caution, like this:
 
-       require Carp if defined $^S;
-       Carp::confess("Something wrong") if defined &Carp::confess;
-       die "Something wrong, but could not load Carp to give backtrace...
-          To see backtrace try starting Perl with -MCarp switch";
+    require Carp if defined $^S;
+    Carp::confess("Something wrong") if defined &Carp::confess;
+    die "Something wrong, but could not load Carp to give "
+      . "backtrace...\n\t"
+      . "To see backtrace try starting Perl with -MCarp switch";
 
 Here the first line will load C<Carp> I<unless> it is the parser who
 called the handler.  The second line will print backtrace and die if
@@ -632,12 +636,12 @@ as a v-string.
 C<$^V> can be used to determine whether the Perl interpreter executing
 a script is in the right range of versions.  For example:
 
-       warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
+    warn "Hashes not randomized!\n" if !$^V or $^V lt v5.8.1
 
 To convert C<$^V> into its string representation use C<sprintf()>'s
 C<"%vd"> conversion:
 
-       printf "version is v%vd\n", $^V;  # Perl's version
+    printf "version is v%vd\n", $^V;  # Perl's version
 
 See the documentation of C<use VERSION> and C<require VERSION>
 for a convenient way to fail if the running Perl interpreter is too old.
@@ -684,7 +688,7 @@ value may or may not include a version number.
 You usually can use the value of C<$^X> to re-invoke an independent
 copy of the same perl that is currently running, e.g.,
 
-       @first_run = `$^X -le "print int rand 100 for 1..100"`;
+    @first_run = `$^X -le "print int rand 100 for 1..100"`;
 
 But recall that not all operating systems support forking or
 capturing of the output of commands, so this complex statement
@@ -696,13 +700,13 @@ executable files do not require use of the suffix when invoking
 a command.  To convert the value of C<$^X> to a path name, use the
 following statements:
 
-       # Build up a set of file names (not command names).
-       use Config;
-       my $this_perl = $^X;
-       if ($^O ne 'VMS') {
-               $this_perl .= $Config{_exe}
-                 unless $this_perl =~ m/$Config{_exe}$/i;
-               }
+    # Build up a set of file names (not command names).
+    use Config;
+    my $this_perl = $^X;
+    if ($^O ne 'VMS') {
+       $this_perl .= $Config{_exe}
+         unless $this_perl =~ m/$Config{_exe}$/i;
+       }
 
 Because many operating systems permit anyone with read access to
 the Perl program file to make a copy of it, patch the copy, and
@@ -712,12 +716,12 @@ copy referenced by C<$^X>.  The following statements accomplish
 this goal, and produce a pathname that can be invoked as a
 command or referenced as a file.
 
-       use Config;
-       my $secure_perl_path = $Config{perlpath};
-       if ($^O ne 'VMS') {
-               $secure_perl_path .= $Config{_exe}
-                       unless $secure_perl_path =~ m/$Config{_exe}$/i;
-               }
+    use Config;
+    my $secure_perl_path = $Config{perlpath};
+    if ($^O ne 'VMS') {
+       $secure_perl_path .= $Config{_exe}
+           unless $secure_perl_path =~ m/$Config{_exe}$/i;
+       }
 
 =back
 
@@ -727,9 +731,9 @@ Most of the special variables related to regular expressions are side
 effects.  Perl sets these variables when it has a successful match, so
 you should check the match result before using them.  For instance:
 
-       if( /P(A)TT(ER)N/ ) {
-               print "I found $1 and $2\n";
-               }
+    if( /P(A)TT(ER)N/ ) {
+       print "I found $1 and $2\n";
+       }
 
 These variables are read-only and dynamically-scoped, unless we note
 otherwise.
@@ -738,23 +742,23 @@ The dynamic nature of the regular expression variables means that
 their value is limited to the block that they are in, as demonstrated
 by this bit of code:
 
-       my $outer = 'Wallace and Grommit';
-       my $inner = 'Mutt and Jeff';
+    my $outer = 'Wallace and Grommit';
+    my $inner = 'Mutt and Jeff';
 
-       my $pattern = qr/(\S+) and (\S+)/;
+    my $pattern = qr/(\S+) and (\S+)/;
 
-       sub show_n { print "\$1 is $1; \$2 is $2\n" }
+    sub show_n { print "\$1 is $1; \$2 is $2\n" }
 
-       {
-       OUTER:
-               show_n() if $outer =~ m/$pattern/;
+    {
+    OUTER:
+       show_n() if $outer =~ m/$pattern/;
 
-               INNER: {
-                       show_n() if $inner =~ m/$pattern/;
-                       }
+       INNER: {
+           show_n() if $inner =~ m/$pattern/;
+           }
 
-               show_n();
-       }
+       show_n();
+    }
 
 The output shows that while in the C<OUTER> block, the values of C<$1>
 and C<$2> are from the match against C<$outer>.  Inside the C<INNER>
@@ -764,9 +768,9 @@ scope).  After the C<INNER> block completes, the values of C<$1> and
 C<$2> return to the values for the match against C<$outer> even though
 we have not made another match:
 
-       $1 is Wallace; $2 is Grommit
-       $1 is Mutt; $2 is Jeff
-       $1 is Wallace; $2 is Grommit
+    $1 is Wallace; $2 is Grommit
+    $1 is Mutt; $2 is Jeff
+    $1 is Wallace; $2 is Grommit
 
 Due to an unfortunate accident of Perl's implementation, C<use
 English> imposes a considerable performance penalty on all regular
@@ -775,7 +779,7 @@ C<$'>, regardless of whether they occur in the scope of C<use
 English>.  For that reason, saying C<use English> in libraries is
 strongly discouraged unless you import it without the match variables:
 
-       use English '-no_match_vars'
+    use English '-no_match_vars'
 
 The C<Devel::NYTProf> and C<Devel::FindAmpersand>
 modules can help you find uses of these
@@ -870,9 +874,9 @@ The string following whatever was matched by the last successful
 pattern match (not counting any matches hidden within a BLOCK or C<eval()>
 enclosed by the current BLOCK).  Example:
 
-       local $_ = 'abcdefghi';
-       /def/;
-       print "$`:$&:$'\n";     # prints abc:def:ghi
+    local $_ = 'abcdefghi';
+    /def/;
+    print "$`:$&:$'\n";        # prints abc:def:ghi
 
 The use of this variable anywhere in a program imposes a considerable
 performance penalty on all regular expression matches.
@@ -906,7 +910,7 @@ The text matched by the last bracket of the last successful search pattern.
 This is useful if you don't know which one of a set of alternative patterns
 matched.  For example:
 
-       /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+    /Version: (.*)|Revision: (.*)/ && ($rev = $+);
 
 This variable is read-only and dynamically-scoped.
 
@@ -925,7 +929,7 @@ This is primarily used inside C<(?{...})> blocks for examining text
 recently matched.  For example, to effectively capture text to a variable
 (in addition to C<$1>, C<$2>, etc.), replace C<(...)> with
 
-       (?:(...)(?{ $var = $^N }))
+    (?:(...)(?{ $var = $^N }))
 
 By setting and then using C<$var> in this way relieves you from having to
 worry about exactly which numbered set of parentheses they are.
@@ -963,7 +967,7 @@ currently active dynamic scope.
 
 For example, C<$+{foo}> is equivalent to C<$1> after the following match:
 
-       'foo' =~ /(?<foo>foo)/;
+    'foo' =~ /(?<foo>foo)/;
 
 The keys of the C<%+> hash list only the names of buffers that have
 captured (and that are thus associated to defined values).
@@ -1044,7 +1048,9 @@ Here's an example:
             my $ary = $-{$bufname};
             foreach my $idx (0..$#$ary) {
                 print "\$-{$bufname}[$idx] : ",
-                      (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
+                      (defined($ary->[$idx])
+                          ? "'$ary->[$idx]'"
+                          : "undef"),
                       "\n";
             }
         }
@@ -1052,10 +1058,10 @@ Here's an example:
 
 would print out:
 
-       $-{A}[0] : '1'
-       $-{A}[1] : '3'
-       $-{B}[0] : '2'
-       $-{B}[1] : '4'
+    $-{A}[0] : '1'
+    $-{A}[1] : '3'
+    $-{B}[0] : '2'
+    $-{B}[1] : '4'
 
 The keys of the C<%-> hash correspond to all buffer names found in
 the regular expression.
@@ -1115,15 +1121,15 @@ although this is less efficient than using the regular built-in
 variables.  (Summary lines below for this contain the word HANDLE.)
 First you must say
 
-       use IO::Handle;
+    use IO::Handle;
 
 after which you may use either
 
-       method HANDLE EXPR
+    method HANDLE EXPR
 
 or more safely,
 
-       HANDLE->method(EXPR)
+    HANDLE->method(EXPR)
 
 Each method returns the old value of the C<IO::Handle> attribute.  The
 methods each take an optional EXPR, which, if supplied, specifies the
@@ -1145,17 +1151,17 @@ the change may affect other modules which rely on the default values
 of the special variables that you have changed.  This is one of the
 correct ways to read the whole file at once:
 
-       open my $fh, "<", "foo" or die $!;
-       local $/; # enable localized slurp mode
-       my $content = <$fh>;
-       close $fh;
+    open my $fh, "<", "foo" or die $!;
+    local $/; # enable localized slurp mode
+    my $content = <$fh>;
+    close $fh;
 
 But the following code is quite bad:
 
-       open my $fh, "<", "foo" or die $!;
-       undef $/; # enable slurp mode
-       my $content = <$fh>;
-       close $fh;
+    open my $fh, "<", "foo" or die $!;
+    undef $/; # enable slurp mode
+    my $content = <$fh>;
+    close $fh;
 
 since some other module, may want to read data from some file in the
 default "line mode", so if the code we have just presented has been
@@ -1167,26 +1173,26 @@ change affects the shortest scope possible.  So unless you are already
 inside some short C<{}> block, you should create one yourself.  For
 example:
 
-       my $content = '';
-       open my $fh, "<", "foo" or die $!;
-       {
-               local $/;
-               $content = <$fh>;
-       }
-       close $fh;
+    my $content = '';
+    open my $fh, "<", "foo" or die $!;
+    {
+       local $/;
+       $content = <$fh>;
+    }
+    close $fh;
 
 Here is an example of how your own code can go broken:
 
-       for ( 1..3 ){
-               $\ = "\r\n";
-               nasty_break();
-               print "$_";
-       }
+    for ( 1..3 ){
+       $\ = "\r\n";
+       nasty_break();
+       print "$_";
+    }
 
-       sub nasty_break {
+    sub nasty_break {
        $\ = "\f";
        # do something with $_
-       }
+    }
 
 You probably expect this code to print the equivalent of
 
@@ -1201,7 +1207,7 @@ first.  The value you set in  C<nasty_break()> is still there when you
 return.  The fix is to add C<local()> so the value doesn't leak out of
 C<nasty_break()>:
 
-        local $\ = "\f";
+    local $\ = "\f";
 
 It's easy to notice the problem in such a short example, but in more
 complicated code you are looking for trouble if you don't localize
@@ -1507,11 +1513,11 @@ following Perl expression, which uses a single-quoted string.  After
 execution of this statement, perl may have set all four special error
 variables:
 
-       eval q{
-               open my $pipe, "/cdrom/install |" or die $!;
-               my @res = <$pipe>;
-               close $pipe or die "bad pipe: $?, $!";
-           };
+    eval q{
+       open my $pipe, "/cdrom/install |" or die $!;
+       my @res = <$pipe>;
+       close $pipe or die "bad pipe: $?, $!";
+    };
 
 When perl executes the C<eval()> expression, it translates the
 C<open()>, C<< <PIPE> >>, and C<close> calls in the C run-time library
@@ -1906,12 +1912,12 @@ for instance, the C<use strict> pragma.
 The contents should be an integer; different bits of it are used for
 different pragmatic flags.  Here's an example:
 
-       sub add_100 { $^H |= 0x100 }
+    sub add_100 { $^H |= 0x100 }
 
-       sub foo {
-               BEGIN { add_100() }
-               bar->baz($boon);
-       }
+    sub foo {
+       BEGIN { add_100() }
+       bar->baz($boon);
+    }
 
 Consider what happens during execution of the BEGIN block.  At this point
 the BEGIN block has already been compiled, but the body of C<foo()> is still
@@ -1921,12 +1927,14 @@ the body of C<foo()> is being compiled.
 
 Substitution of C<BEGIN { add_100() }> block with:
 
-       BEGIN { require strict; strict->import('vars') }
+    BEGIN { require strict; strict->import('vars') }
 
 demonstrates how C<use strict 'vars'> is implemented.  Here's a conditional
 version of the same lexical pragma:
 
-       BEGIN { require strict; strict->import('vars') if $condition }
+    BEGIN {
+       require strict; strict->import('vars') if $condition
+    }
 
 This variable was added in Perl 5.003.