Import of Perl 5.003 into the tree. Makefile.bsd-wrapper and

config.sh.OpenBSD are the only local changes.

1 files changed, 464 insertions, 0 deletions

diff --git a/gnu/usr.bin/perl/pod/perlref.pod b/gnu/usr.bin/perl/pod/perlref.pod
new file mode 100644
index 00000000000..d528bc87974
--- /dev/null
+++ b/gnu/usr.bin/perl/pod/perlref.pod
@@ -0,0 +1,464 @@
+=head1 NAME
+
+perlref - Perl references and nested data structures
+
+=head1 DESCRIPTION
+
+Before release 5 of Perl it was difficult to represent complex data
+structures, because all references had to be symbolic, and even that was
+difficult to do when you wanted to refer to a variable rather than a
+symbol table entry.  Perl 5 not only makes it easier to use symbolic
+references to variables, but lets you have "hard" references to any piece
+of data.  Any scalar may hold a hard reference.  Since arrays and hashes
+contain scalars, you can now easily build arrays of arrays, arrays of
+hashes, hashes of arrays, arrays of hashes of functions, and so on.
+
+Hard references are smart--they keep track of reference counts for you,
+automatically freeing the thing referred to when its reference count
+goes to zero.  If that thing happens to be an object, the object is
+destructed.  See L<perlobj> for more about objects.  (In a sense,
+everything in Perl is an object, but we usually reserve the word for
+references to objects that have been officially "blessed" into a class package.)
+
+A symbolic reference contains the name of a variable, just as a
+symbolic link in the filesystem merely contains the name of a file.  
+The C<*glob> notation is a kind of symbolic reference.  Hard references
+are more like hard links in the file system: merely another way
+at getting at the same underlying object, irrespective of its name.
+
+"Hard" references are easy to use in Perl.  There is just one
+overriding principle:  Perl does no implicit referencing or
+dereferencing.  When a scalar is holding a reference, it always behaves
+as a scalar.  It doesn't magically start being an array or a hash
+unless you tell it so explicitly by dereferencing it.
+
+References can be constructed several ways.
+
+=over 4
+
+=item 1.
+
+By using the backslash operator on a variable, subroutine, or value.
+(This works much like the & (address-of) operator works in C.)  Note
+that this typically creates I<ANOTHER> reference to a variable, since
+there's already a reference to the variable in the symbol table.  But
+the symbol table reference might go away, and you'll still have the
+reference that the backslash returned.  Here are some examples:
+
+    $scalarref = \$foo;
+    $arrayref  = \@ARGV;
+    $hashref   = \%ENV;
+    $coderef   = \&handler;
+    $globref   = \*STDOUT;
+
+
+=item 2.
+
+A reference to an anonymous array can be constructed using square
+brackets:
+
+    $arrayref = [1, 2, ['a', 'b', 'c']];
+
+Here we've constructed a reference to an anonymous array of three elements
+whose final element is itself reference to another anonymous array of three
+elements.  (The multidimensional syntax described later can be used to
+access this.  For example, after the above, $arrayref-E<gt>[2][1] would have
+the value "b".)
+
+Note that taking a reference to an enumerated list is not the same
+as using square brackets--instead it's the same as creating
+a list of references!
+
+    @list = (\$a, \$b, \$c);  
+    @list = \($a, $b, $c);	# same thing!
+
+=item 3.
+
+A reference to an anonymous hash can be constructed using curly
+brackets:
+
+    $hashref = {
+	'Adam'  => 'Eve',
+	'Clyde' => 'Bonnie',
+    };
+
+Anonymous hash and array constructors can be intermixed freely to
+produce as complicated a structure as you want.  The multidimensional
+syntax described below works for these too.  The values above are
+literals, but variables and expressions would work just as well, because
+assignment operators in Perl (even within local() or my()) are executable
+statements, not compile-time declarations.
+
+Because curly brackets (braces) are used for several other things
+including BLOCKs, you may occasionally have to disambiguate braces at the
+beginning of a statement by putting a C<+> or a C<return> in front so
+that Perl realizes the opening brace isn't starting a BLOCK.  The economy and
+mnemonic value of using curlies is deemed worth this occasional extra
+hassle.
+
+For example, if you wanted a function to make a new hash and return a
+reference to it, you have these options:
+
+    sub hashem {        { @_ } }   # silently wrong
+    sub hashem {       +{ @_ } }   # ok
+    sub hashem { return { @_ } }   # ok
+
+=item 4.
+
+A reference to an anonymous subroutine can be constructed by using
+C<sub> without a subname:
+
+    $coderef = sub { print "Boink!\n" };
+
+Note the presence of the semicolon.  Except for the fact that the code
+inside isn't executed immediately, a C<sub {}> is not so much a
+declaration as it is an operator, like C<do{}> or C<eval{}>.  (However, no
+matter how many times you execute that line (unless you're in an
+C<eval("...")>), C<$coderef> will still have a reference to the I<SAME>
+anonymous subroutine.)
+
+Anonymous subroutines act as closures with respect to my() variables,
+that is, variables visible lexically within the current scope.  Closure
+is a notion out of the Lisp world that says if you define an anonymous
+function in a particular lexical context, it pretends to run in that
+context even when it's called outside of the context.
+
+In human terms, it's a funny way of passing arguments to a subroutine when
+you define it as well as when you call it.  It's useful for setting up
+little bits of code to run later, such as callbacks.  You can even
+do object-oriented stuff with it, though Perl provides a different
+mechanism to do that already--see L<perlobj>.
+
+You can also think of closure as a way to write a subroutine template without
+using eval.  (In fact, in version 5.000, eval was the I<only> way to get
+closures.  You may wish to use "require 5.001" if you use closures.)
+
+Here's a small example of how closures works:
+
+    sub newprint {
+	my $x = shift;
+	return sub { my $y = shift; print "$x, $y!\n"; };
+    }
+    $h = newprint("Howdy");
+    $g = newprint("Greetings");
+
+    # Time passes...
+
+    &$h("world");
+    &$g("earthlings");
+
+This prints
+
+    Howdy, world!
+    Greetings, earthlings!
+
+Note particularly that $x continues to refer to the value passed into
+newprint() I<despite> the fact that the "my $x" has seemingly gone out of
+scope by the time the anonymous subroutine runs.  That's what closure
+is all about.
+
+This only applies to lexical variables, by the way.  Dynamic variables
+continue to work as they have always worked.  Closure is not something
+that most Perl programmers need trouble themselves about to begin with.
+
+=item 5.
+
+References are often returned by special subroutines called constructors.
+Perl objects are just references to a special kind of object that happens to know
+which package it's associated with.  Constructors are just special
+subroutines that know how to create that association.  They do so by
+starting with an ordinary reference, and it remains an ordinary reference
+even while it's also being an object.  Constructors are customarily
+named new(), but don't have to be:
+
+    $objref = new Doggie (Tail => 'short', Ears => 'long');
+
+=item 6.
+
+References of the appropriate type can spring into existence if you
+dereference them in a context that assumes they exist.  Since we haven't
+talked about dereferencing yet, we can't show you any examples yet.
+
+=item 7.
+
+References to filehandles can be created by taking a reference to 
+a typeglob.  This is currently the best way to pass filehandles into or
+out of subroutines, or to store them in larger data structures.
+
+    splutter(\*STDOUT);
+    sub splutter {
+	my $fh = shift;
+	print $fh "her um well a hmmm\n";
+    }
+
+    $rec = get_rec(\*STDIN);
+    sub get_rec {
+	my $fh = shift;
+	return scalar <$fh>;
+    }
+
+=back
+
+That's it for creating references.  By now you're probably dying to
+know how to use references to get back to your long-lost data.  There
+are several basic methods.
+
+=over 4
+
+=item 1.
+
+Anywhere you'd put an identifier as part of a variable or subroutine
+name, you can replace the identifier with a simple scalar variable
+containing a reference of the correct type:
+
+    $bar = $$scalarref;
+    push(@$arrayref, $filename);
+    $$arrayref[0] = "January";
+    $$hashref{"KEY"} = "VALUE";
+    &$coderef(1,2,3);
+    print $globref "output\n";
+
+It's important to understand that we are specifically I<NOT> dereferencing
+C<$arrayref[0]> or C<$hashref{"KEY"}> there.  The dereference of the
+scalar variable happens I<BEFORE> it does any key lookups.  Anything more
+complicated than a simple scalar variable must use methods 2 or 3 below.
+However, a "simple scalar" includes an identifier that itself uses method
+1 recursively.  Therefore, the following prints "howdy".
+
+    $refrefref = \\\"howdy";
+    print $$$$refrefref;
+
+=item 2.
+
+Anywhere you'd put an identifier as part of a variable or subroutine
+name, you can replace the identifier with a BLOCK returning a reference
+of the correct type.  In other words, the previous examples could be
+written like this:
+
+    $bar = ${$scalarref};
+    push(@{$arrayref}, $filename);
+    ${$arrayref}[0] = "January";
+    ${$hashref}{"KEY"} = "VALUE";
+    &{$coderef}(1,2,3);
+    $globref->print("output\n");  # iff you use FileHandle
+
+Admittedly, it's a little silly to use the curlies in this case, but
+the BLOCK can contain any arbitrary expression, in particular,
+subscripted expressions:
+
+    &{ $dispatch{$index} }(1,2,3);	# call correct routine 
+
+Because of being able to omit the curlies for the simple case of C<$$x>,
+people often make the mistake of viewing the dereferencing symbols as
+proper operators, and wonder about their precedence.  If they were,
+though, you could use parens instead of braces.  That's not the case.
+Consider the difference below; case 0 is a short-hand version of case 1,
+I<NOT> case 2:
+
+    $$hashref{"KEY"}   = "VALUE";	# CASE 0
+    ${$hashref}{"KEY"} = "VALUE";	# CASE 1
+    ${$hashref{"KEY"}} = "VALUE";	# CASE 2
+    ${$hashref->{"KEY"}} = "VALUE";	# CASE 3
+
+Case 2 is also deceptive in that you're accessing a variable
+called %hashref, not dereferencing through $hashref to the hash
+it's presumably referencing.  That would be case 3.
+
+=item 3.
+
+The case of individual array elements arises often enough that it gets
+cumbersome to use method 2.  As a form of syntactic sugar, the two
+lines like that above can be written:
+
+    $arrayref->[0] = "January";
+    $hashref->{"KEY"} = "VALUE";
+
+The left side of the array can be any expression returning a reference,
+including a previous dereference.  Note that C<$array[$x]> is I<NOT> the
+same thing as C<$array-E<gt>[$x]> here:
+
+    $array[$x]->{"foo"}->[0] = "January";
+
+This is one of the cases we mentioned earlier in which references could
+spring into existence when in an lvalue context.  Before this
+statement, C<$array[$x]> may have been undefined.  If so, it's
+automatically defined with a hash reference so that we can look up
+C<{"foo"}> in it.  Likewise C<$array[$x]-E<gt>{"foo"}> will automatically get
+defined with an array reference so that we can look up C<[0]> in it.
+
+One more thing here.  The arrow is optional I<BETWEEN> brackets
+subscripts, so you can shrink the above down to
+
+    $array[$x]{"foo"}[0] = "January";
+
+Which, in the degenerate case of using only ordinary arrays, gives you
+multidimensional arrays just like C's:
+
+    $score[$x][$y][$z] += 42;
+
+Well, okay, not entirely like C's arrays, actually.  C doesn't know how
+to grow its arrays on demand.  Perl does.
+
+=item 4.
+
+If a reference happens to be a reference to an object, then there are
+probably methods to access the things referred to, and you should probably
+stick to those methods unless you're in the class package that defines the
+object's methods.  In other words, be nice, and don't violate the object's
+encapsulation without a very good reason.  Perl does not enforce
+encapsulation.  We are not totalitarians here.  We do expect some basic
+civility though.
+
+=back
+
+The ref() operator may be used to determine what type of thing the
+reference is pointing to.  See L<perlfunc>.
+
+The bless() operator may be used to associate a reference with a package
+functioning as an object class.  See L<perlobj>.
+
+A typeglob may be dereferenced the same way a reference can, since
+the dereference syntax always indicates the kind of reference desired.
+So C<${*foo}> and C<${\$foo}> both indicate the same scalar variable.
+
+Here's a trick for interpolating a subroutine call into a string:
+
+    print "My sub returned @{[mysub(1,2,3)]} that time.\n";
+
+The way it works is that when the C<@{...}> is seen in the double-quoted
+string, it's evaluated as a block.  The block creates a reference to an
+anonymous array containing the results of the call to C<mysub(1,2,3)>.  So
+the whole block returns a reference to an array, which is then
+dereferenced by C<@{...}> and stuck into the double-quoted string. This
+chicanery is also useful for arbitrary expressions:
+
+    print "That yeilds @{[$n + 5]} widgets\n";
+
+=head2 Symbolic references
+
+We said that references spring into existence as necessary if they are
+undefined, but we didn't say what happens if a value used as a
+reference is already defined, but I<ISN'T> a hard reference.  If you
+use it as a reference in this case, it'll be treated as a symbolic
+reference.  That is, the value of the scalar is taken to be the I<NAME>
+of a variable, rather than a direct link to a (possibly) anonymous
+value.
+
+People frequently expect it to work like this.  So it does.
+
+    $name = "foo";
+    $$name = 1;			# Sets $foo
+    ${$name} = 2;		# Sets $foo
+    ${$name x 2} = 3;		# Sets $foofoo
+    $name->[0] = 4;		# Sets $foo[0]
+    @$name = ();		# Clears @foo
+    &$name();			# Calls &foo() (as in Perl 4)
+    $pack = "THAT";
+    ${"${pack}::$name"} = 5;	# Sets $THAT::foo without eval
+
+This is very powerful, and slightly dangerous, in that it's possible
+to intend (with the utmost sincerity) to use a hard reference, and
+accidentally use a symbolic reference instead.  To protect against
+that, you can say
+
+    use strict 'refs';
+
+and then only hard references will be allowed for the rest of the enclosing
+block.  An inner block may countermand that with 
+
+    no strict 'refs';
+
+Only package variables are visible to symbolic references.  Lexical
+variables (declared with my()) aren't in a symbol table, and thus are
+invisible to this mechanism.  For example:
+
+    local($value) = 10;
+    $ref = \$value;
+    {
+	my $value = 20;
+	print $$ref;
+    } 
+
+This will still print 10, not 20.  Remember that local() affects package
+variables, which are all "global" to the package.
+
+=head2 Not-so-symbolic references
+
+A new feature contributing to readability in 5.001 is that the brackets
+around a symbolic reference behave more like quotes, just as they
+always have within a string.  That is,
+
+    $push = "pop on ";
+    print "${push}over";
+
+has always meant to print "pop on over", despite the fact that push is
+a reserved word.  This has been generalized to work the same outside
+of quotes, so that
+
+    print ${push} . "over";
+
+and even
+
+    print ${ push } . "over";
+
+will have the same effect.  (This would have been a syntax error in
+5.000, though Perl 4 allowed it in the spaceless form.)  Note that this
+construct is I<not> considered to be a symbolic reference when you're
+using strict refs:
+
+    use strict 'refs';
+    ${ bareword };	# Okay, means $bareword.
+    ${ "bareword" };	# Error, symbolic reference.
+
+Similarly, because of all the subscripting that is done using single
+words, we've applied the same rule to any bareword that is used for
+subscripting a hash.  So now, instead of writing
+
+    $array{ "aaa" }{ "bbb" }{ "ccc" }
+
+you can just write
+
+    $array{ aaa }{ bbb }{ ccc }
+
+and not worry about whether the subscripts are reserved words.  In the
+rare event that you do wish to do something like
+
+    $array{ shift }
+
+you can force interpretation as a reserved word by adding anything that
+makes it more than a bareword:
+
+    $array{ shift() }
+    $array{ +shift }
+    $array{ shift @_ }
+
+The B<-w> switch will warn you if it interprets a reserved word as a string.
+But it will no longer warn you about using lowercase words, since the
+string is effectively quoted.
+
+=head1 WARNING
+
+You may not (usefully) use a reference as the key to a hash.  It will be
+converted into a string:
+
+    $x{ \$a } = $a;
+
+If you try to dereference the key, it won't do a hard dereference, and 
+you won't accomplish what you're attemping.  You might want to do something
+more like
+
+    $r = \@a;
+    $x{ $r } = $r;
+
+And then at least you can use the values(), which will be
+real refs, instead of the keys(), which won't.
+
+=head1 SEE ALSO
+
+Besides the obvious documents, source code can be instructive.
+Some rather pathological examples of the use of references can be found
+in the F<t/op/ref.t> regression test in the Perl source directory.
+
+See also L<perldsc> and L<perllol> for how to use references to create
+complex data structures, and L<perlobj> for how to use them to create
+objects.