[inseparable changes from match from perl-5.003_93 to perl-5.003_94]

 BUILD PROCESS

Subject: Don't use db 2.x, we're not yet ready for it
From: Paul Marquess <pmarquess@bfsec.bt.co.uk>
Files: Configure

Subject: Warn if #! command is longer than 32 chars
From: Chip Salzenberg <chip@perl.com>
Files: Configure

Subject: patches re perl -wc install{perl,man}
Date: Tue, 11 Mar 97 13:13:16 GMT
From: Robin Barker <rmb1@cise.npl.co.uk>
Files: installman installperl

    I got the new installhtml from CPAN
    (TOMC/scripts/pod2html-v2.0beta.shar.gz)
    
    I had problems getting the system call to splitpod at line 376 to work.
    
    1. splitroot was not being found
    2. splitroot was not finding its library
    3. I changed htmlroot to podroot at line 175 to match the documentation.
    
    p5p-msgid: 3180.9703270906@tempest.cise.npl.co.uk
    private-msgid: 21544.9703111313@tempest.cise.npl.co.uk

Subject: 3_93 doesn't install pods
Date: Sun, 16 Mar 1997 02:21:35 -0500
From: Spider Boardman <spider@orb.nashua.nh.us>
Files: installperl
Msg-ID: 199703160721.CAA08339@Orb.Nashua.NH.US

    (applied based on p5p patch as commit 43506a616735d616e03d277d64fbae1e864024bf)

Subject: When installing, use File::Copy instead of `cp`
From: Chip Salzenberg <chip@perl.com>
Files: installperl

Subject: Make hint files' warnings more visible
Date: Thu, 20 Mar 1997 23:18:03 +0100 (MET)
From: Hallvard B Furuseth <h.b.furuseth@usit.uio.no>
Files: hints/3b1.sh hints/apollo.sh hints/cxux.sh hints/dcosx.sh hints/dgux.sh hints/esix4.sh hints/freebsd.sh hints/hpux.sh hints/irix_4.sh hints/mips.sh hints/next_3_0.sh hints/os2.sh hints/qnx.sh hints/sco_2_3_3.sh hints/sco_2_3_4.sh hints/solaris_2.sh hints/ultrix_4.sh hints/utekv.sh

    private-msgid: 199703202218.XAA09041@bombur2.uio.no

 CORE LANGUAGE CHANGES

Subject: Defer creation of array and hash elements as parameters
From: Chip Salzenberg <chip@perl.com>
Files: dump.c global.sym mg.c op.c op.h perl.h pp.c pp_hot.c proto.h sv.c

Subject: New special literal: __PACKAGE__
From: Chip Salzenberg <chip@perl.com>
Files: keywords.pl pod/perldata.pod toke.c

Subject: Abort compilation at C<BEGIN{}> or C<use> after errors
From: Chip Salzenberg <chip@perl.com>
Files: op.c pod/perldiag.pod t/pragma/subs.t

Subject: allow C<substr 'hello', -10>
Date: Mon, 10 Mar 1997 15:55:44 -0800
From: David Dyck <dcd@tc.fluke.com>
Files: pp.c
Msg-ID: 97Mar10.155517pst.35716-2@gateway.fluke.com

    (applied based on p5p patch as commit 77f720bf92f3d0100352416caeedd57936807ff2)

Subject: Regularize C<x % y>, esp. when y is negative
From: Chip Salzenberg <chip@perl.com>
Files: pp.c

Subject: Flush before C<flock(FOO, LOCK_UN)>
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod pod/perlfunc.pod pp_sys.c

Subject: Close loopholes in prototype mismatch warning
From: Chip Salzenberg <chip@perl.com>
Files: op.c sv.c toke.c

Subject: Warn on C<while ($x = each %y) {}>
From: Chip Salzenberg <chip@perl.com>
Files: op.c pod/perldiag.pod

Subject: Don't warn on C<print $fh func()>
From: Chip Salzenberg <chip@perl.com>
Files: toke.c

 CORE PORTABILITY

Subject: Don't say 'static var = 1'
Date: Sun, 9 Mar 1997 15:19:57 +0200 (EET)
From: Jarkko Hietaniemi <jhi@iki.fi>
Files: malloc.c

    private-msgid: 199703091319.PAA24714@alpha.hut.fi

Subject: HP/UX hint comments
Date: Fri, 21 Mar 1997 15:43:07 -0500 (EST)
From: Andy Dougherty <doughera@fractal.phys.lafayette.edu>
Files: hints/hpux.sh

    private-msgid: Pine.SOL.3.95q.970321153918.28770B-100000@fractal.lafayette.

Subject: VMS update
Date: Tue, 11 Mar 1997 22:00:55 -0500 (EST)
From: Charles Bailey <bailey@hmivax.humgen.upenn.edu>
Files: lib/ExtUtils/MM_VMS.pm lib/Test/Harness.pm t/op/taint.t utils/perlbug.PL vms/descrip.mms
Msg-ID: 1997Mar11.220056.1873182@hmivax.humgen.upenn.edu

    (applied based on p5p patch as commit 2b5725676da60b49978f38b85bb7f8ee20b4cb55)

Subject: vmsish.t and related patches
Date: Fri, 21 Mar 1997 01:32:47 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: MANIFEST perl.h vms/descrip.mms vms/ext/vmsish.t vms/vms.c

    private-msgid: 01IGQW3IP1KK005VFB@hmivax.humgen.upenn.edu

Subject: Win32 update (four patches)
From: Gurusamy Sarathy <gsar@engin.umich.edu>
Files: MANIFEST README.win32 lib/AutoSplit.pm lib/Cwd.pm lib/ExtUtils/Command.pm lib/ExtUtils/Install.pm lib/ExtUtils/MM_OS2.pm lib/ExtUtils/MM_Unix.pm lib/ExtUtils/MM_Win32.pm lib/ExtUtils/MakeMaker.pm lib/ExtUtils/Mksymlists.pm lib/File/Basename.pm lib/File/Path.pm mg.c t/comp/cpp.t t/comp/script.t t/harness t/io/argv.t t/io/dup.t t/io/fs.t t/io/inplace.t t/lib/filehand.t t/lib/io_dup.t t/lib/io_sel.t t/lib/io_taint.t t/op/closure.t t/op/exec.t t/op/glob.t t/op/goto.t t/op/magic.t t/op/misc.t t/op/rand.t t/op/split.t t/op/stat.t t/op/sysio.t t/op/taint.t t/pragma/strict.t t/pragma/subs.t t/pragma/warning.t util.c win32/*

 DOCUMENTATION

Subject: perlfaq.pod
Date: Mon, 17 Mar 1997 16:01:40 -0700
From: Tom Christiansen <tchrist@jhereg.perl.com>
Files: MANIFEST pod/Makefile pod/buildtoc pod/perl.pod pod/perlfaq*.pod pod/roffitall

    private-msgid: 199703172301.QAA12566@jhereg.perl.com

Subject: *.pod changes based on the FAQ
Date: Mon, 17 Mar 1997 09:50:14 -0700 (MST)
From: Nat Torkington <gnat@frii.com>
Files: pod/perldata.pod pod/perlfunc.pod pod/perlipc.pod pod/perlop.pod pod/perlre.pod pod/perlrun.pod pod/perlsec.pod pod/perlvar.pod
Msg-ID: 199703171650.JAA02655@elara.frii.com

    (applied based on p5p patch as commit 3c10ad8e31f7d77e71c048b1746912f41cb540f0)

Subject: Document that $. is not reset on implicit open
From: Chip Salzenberg <chip@perl.com>
Files: pod/perldelta.pod

Subject: Re: Embedding success with _93 
Date: Tue, 11 Mar 1997 17:55:05 -0500
From: Doug MacEachern <dougm@opengroup.org>
Files: pod/perldelta.pod
Msg-ID: 199703112255.RAA22775@postman.osf.org

    (applied based on p5p patch as commit 63a6ff3a1dc8d86edb4d8a7ec1548205e32a7114)

Subject: Patch to document illegal characters
Date: Fri, 14 Mar 1997 09:08:10 -0800 (PST)
From: Tom Phoenix <rootbeer@teleport.com>
Files: pod/perldiag.pod pod/perltrap.pod

    private-msgid: Pine.GSO.3.96.970314090558.15346J-100000@kelly.teleport.com

Subject: Document trap with //o and closures
Date: Mon, 10 Mar 1997 18:08:08 -0500 (EST)
From: Charles Bailey <bailey@HMIVAX.HUMGEN.UPENN.EDU>
Files: pod/perltrap.pod
Msg-ID: 01IGCHWRNSEU00661G@hmivax.humgen.upenn.edu

    (applied based on p5p patch as commit a54cb1465fdb400848f23705a6f130bb5c34ab70)

Subject: Illegal character in input
Date: Mon, 10 Mar 1997 15:21:21 -0800 (PST)
From: Tom Phoenix <rootbeer@teleport.com>
Files: pod/perldiag.pod

    private-msgid: Pine.GSO.3.95q.970310151512.22489a-100000@kelly.teleport.com

Subject: Patch for docs Re: Lost backslash
Date: Wed, 19 Mar 1997 07:28:57 -0800 (PST)
From: Tom Phoenix <rootbeer@teleport.com>
Files: pod/perlop.pod

    private-msgid: Pine.GSO.3.96.970319071438.24834G-100000@kelly.teleport.com

Subject: XSUB's doc fix
Date: Mon, 10 Mar 1997 11:42:06 -0500
From: Roderick Schertler <roderick@argon.org>
Files: pod/perlcall.pod pod/perlguts.pod pod/perlxstut.pod
Msg-ID: 28804.858012126@eeyore.ibcinc.com

    (applied based on p5p patch as commit 5f43237038ea7a4151d3bf65aeeecd56ceb78a6a)

Subject: Document return from do FILE
Date: Tue, 18 Mar 1997 14:50:10 +0000
From: "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
Files: pod/perlfunc.pod
Msg-ID: E0w70DK-0001yJ-00@ursa.cus.cam.ac.uk

    (applied based on p5p patch as commit ba8d5fb439878113de8abc9b52d2af237d30fb3c)

Subject: Document $^M in perlvar
Date: Thu, 20 Mar 97 21:08:33 GMT
From: Robin Barker <rmb1@cise.npl.co.uk>
Files: pod/perlvar.pod

    private-msgid: 6153.9703202108@tempest.cise.npl.co.uk

Subject: typos in pods of 5.003_93
Date: 19 Mar 1997 10:39:38 -0600
From: Jim Meyering <meyering@asic.sc.ti.com>
Files: pod/perlfunc.pod pod/perlguts.pod pod/perlre.pod pod/perltoot.pod pod/perlxs.pod
Msg-ID: wpgendbzvhx.fsf@asic.sc.ti.com

    (applied based on p5p patch as commit 76a9873e006cf8f48f57062b2a0dd40b5ed45a95)

Subject: Re: Updates to pod punctuations
Date: Fri, 14 Mar 1997 17:00:12 -0500
From: Larry W. Virden <lvirden@cas.org>
Files: pod/*.pod

    private-msgid: 9703141700.AA22911@cas.org

Subject: clarify example in perlfunc
Date: Thu, 20 Mar 1997 19:46:01 +0200 (EET)
From: Jarkko Hietaniemi <jhi@iki.fi>
Files: pod/perlfunc.pod

    private-msgid: 199703201746.TAA25195@alpha.hut.fi

Subject: Regularize headings in DB_File documentation
From: Chip Salzenberg <chip@perl.com>
Files: ext/DB_File/DB_File.pm

 LIBRARY AND EXTENSIONS

Subject: New module: autouse.pm
Date: Thu, 20 Mar 1997 19:34:30 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: MANIFEST lib/autouse.pm
Msg-ID: 199703210034.TAA13469@monk.mps.ohio-state.edu

    (applied based on p5p patch as commit 6757905eccb6dd0440ef65e8128a277a20f7d943)

Subject: Refresh DB_File to 1.12
Date: Wed, 12 Mar 97 15:51:14 GMT
From: Paul Marquess <pmarquess@bfsec.bt.co.uk>
Files: ext/DB_File/DB_File.pm ext/DB_File/DB_File.xs
Msg-ID: 9703121551.AA07435@claudius.bfsec.bt.co.uk

    (applied based on p5p patch as commit b3deed9189f963e9994815307931f9084f60d1d9)

Subject: In File::Path, some systems can't remove read-only files
From: Chip Salzenberg <chip@perl.com>
Files: lib/File/Path.pm

Subject: Fix bugs revealed by prototype warnings
From: Chip Salzenberg <chip@perl.com>
Files: ext/Opcode/Opcode.pm lib/ExtUtils/MakeMaker.pm lib/Getopt/Long.pm

Subject: Problems with SKIP in makemaker
Date: Thu, 20 Mar 1997 23:13:31 -0500 (EST)
From: Ilya Zakharevich <ilya@math.ohio-state.edu>
Files: lib/ExtUtils/MM_Unix.pm
Msg-ID: 199703210413.XAA21601@monk.mps.ohio-state.edu

    (applied based on p5p patch as commit 970322a2e8024294ada6e8d1a027cb98f1f48ee3)

Subject: In Exporter, don't C<require Carp> at file scope
From: Chip Salzenberg <chip@perl.com>
Files: lib/Exporter.pm

Subject: fix for Exporter's $SIG{__WARN__} handler
Date: Thu, 13 Mar 1997 18:40:51 -0500
From: Roderick Schertler <roderick@argon.org>
Files: lib/Exporter.pm
Msg-ID: 2282.858296451@eeyore.ibcinc.com

    (applied based on p5p patch as commit 2768ea1aeef34f42d096f198fbe629c8374ca429)

Subject: Don't try to substr() refs in Carp
From: Chip Salzenberg <chip@perl.com>
Files: lib/Carp.pm

Subject: Re: NUL in die and other messages
Date: Fri, 21 Mar 1997 09:58:17 +0000
From: "M.J.T. Guy" <mjtg@cus.cam.ac.uk>
Files: lib/Carp.pm
Msg-ID: E0w815V-0005xs-00@ursa.cus.cam.ac.uk

    (applied based on p5p patch as commit 52a267c574cb66c4bc35601dcf148a1d7a3bc557)

 OTHER CORE CHANGES

Subject: Guard against buffer overflow in yyerror() and related funcs
From: Chip Salzenberg <chip@perl.com>
Files: toke.c

Subject: For bin compat, rename calllist() and he_{,delay}free
From: Chip Salzenberg <chip@perl.com>
Files: global.sym hv.c op.c perl.c pod/perlguts.pod proto.h

Subject: Fix C<print> on tied default handle
From: Chip Salzenberg <chip@perl.com>
Files: pp_hot.c

Subject: Fix C<local($a, undef, $b) = (1,2,3)>
From: Chip Salzenberg <chip@perl.com>
Files: op.c

Subject: Improve diagnostic on C<@a++>, C<--%a>, @a =~ s/a/b/
From: Chip Salzenberg <chip@perl.com>
Files: pp.c pp_hot.c

Subject: Don't warn on C<$x{y} .= "z"> when %x is tied
From: Chip Salzenberg <chip@perl.com>
Files: pp_hot.c

Subject: Eliminate 'unreachable code' warnings
From: Chip Salzenberg <chip@perl.com>
Files: ext/POSIX/POSIX.xs mg.c pp_ctl.c toke.c

Subject: printf format corrections for -DDEBUGGING
Date: Wed, 19 Mar 1997 12:42:50 -0500
From: Roderick Schertler <roderick@argon.org>
Files: doop.c malloc.c op.c pp_ctl.c regexec.c sv.c x2p/str.c x2p/util.c
Msg-ID: 26592.858793370@eeyore.ibcinc.com

    (applied based on p5p patch as commit e125f273e351a19a92b69d6244af55abbbf0a26d)

Subject: Warn about missing -DMULTIPLICITY if likely a problem
Date: Wed, 19 Mar 1997 18:45:53 -0500
From: Doug MacEachern <dougm@opengroup.org>
Files: perl.c
Msg-ID: 199703192345.SAA15070@postman.osf.org

    (applied based on p5p patch as commit 71aeea1753924e6e19c2461e241e3f7d8a570e90)

1 files changed, 675 insertions, 0 deletions

diff --git a/pod/perlfaq7.pod b/pod/perlfaq7.pod
new file mode 100644
index 0000000000..14bfc678fc
--- /dev/null
+++ b/pod/perlfaq7.pod
@@ -0,0 +1,675 @@
+=head1 NAME
+
+perlfaq7 - Perl Language Issues ($Revision: 1.15 $)
+
+=head1 DESCRIPTION
+
+This section deals with general Perl language issues that don't
+clearly fit into any of the other sections.
+
+=head2 Can I get a BNF/yacc/RE for the Perl language?
+
+No, in the words of Chaim Frenkel: "Perl's grammar can not be reduced
+to BNF.  The work of parsing perl is distributed between yacc, the
+lexer, smoke and mirrors."
+
+=head2 What are all these $@%* punctuation signs, and how do I know when to use them?
+
+They are type specifiers, as detailed in L<perldata>:
+
+    $ for scalar values (number, string or reference)
+    @ for arrays
+    % for hashes (associative arrays)
+    * for all types of that symbol name.  In version 4 you used them like
+      pointers, but in modern perls you can just use references.
+
+While there are a few places where you don't actually need these type
+specifiers, you should always use them.
+
+A couple of others that you're likely to encounter that aren't
+really type specifiers are:
+
+    <> are used for inputting a record from a filehandle.
+    \  takes a reference to something.
+
+Note that E<lt>FILEE<gt> is I<neither> the type specifier for files
+nor the name of the handle.  It is the C<E<lt>E<gt>> operator applied
+to the handle FILE.  It reads one line (well, record - see
+L<perlvar/$/>) from the handle FILE in scalar context, or I<all> lines
+in list context.  When performing open, close, or any other operation
+besides C<E<lt>E<gt>> on files, or even talking about the handle, do
+I<not> use the brackets.  These are correct: C<eof(FH)>, C<seek(FH, 0,
+2)> and "copying from STDIN to FILE".
+
+=head2 Do I always/never have to quote my strings or use semicolons and commas?
+
+Normally, a bareword doesn't need to be quoted, but in most cases
+probably should be (and must be under C<use strict>).  But a hash key
+consisting of a simple word (that isn't the name of a defined
+subroutine) and the left-hand operand to the C<=E<gt>> operator both
+count as though they were quoted:
+
+    This                    is like this
+    ------------            ---------------
+    $foo{line}              $foo{"line"}
+    bar => stuff            "bar" => stuff
+
+The final semicolon in a block is optional, as is the final comma in a
+list.  Good style (see L<perlstyle>) says to put them in except for
+one-liners:
+
+    if ($whoops) { exit 1 }
+    @nums = (1, 2, 3);
+
+    if ($whoops) {
+        exit 1;
+    }
+    @lines = (
+	"There Beren came from mountains cold",
+	"And lost he wandered under leaves",
+    );
+
+=head2 How do I skip some return values?
+
+One way is to treat the return values as a list and index into it:
+
+        $dir = (getpwnam($user))[7];
+
+Another way is to use undef as an element on the left-hand-side:
+
+    ($dev, $ino, undef, undef, $uid, $gid) = stat($file);
+
+=head2 How do I temporarily block warnings?
+
+The C<$^W> variable (documented in L<perlvar>) controls
+runtime warnings for a block:
+
+    {
+	local $^W = 0;        # temporarily turn off warnings
+	$a = $b + $c;         # I know these might be undef
+    }
+
+Note that like all the punctuation variables, you cannot currently
+use my() on C<$^W>, only local().
+
+A new C<use warnings> pragma is in the works to provide finer control
+over all this.  The curious should check the perl5-porters mailing list
+archives for details.
+
+=head2 What's an extension?
+
+A way of calling compiled C code from Perl.  Reading L<perlxstut>
+is a good place to learn more about extensions.
+
+=head2 Why do Perl operators have different precedence than C operators?
+
+Actually, they don't.  All C operators that Perl copies have the same
+precedence in Perl as they do in C.  The problem is with operators that C
+doesn't have, especially functions that give a list context to everything
+on their right, eg print, chmod, exec, and so on.  Such functions are
+called "list operators" and appear as such in the precedence table in
+L<perlop>.
+
+A common mistake is to write:
+
+    unlink $file || die "snafu";
+
+This gets interpreted as:
+
+    unlink ($file || die "snafu");
+
+To avoid this problem, either put in extra parentheses or use the
+super low precedence C<or> operator:
+
+    (unlink $file) || die "snafu";
+    unlink $file or die "snafu";
+
+The "English" operators (C<and>, C<or>, C<xor>, and C<not>)
+deliberately have precedence lower than that of list operators for
+just such situations as the one above.
+
+Another operator with surprising precedence is exponentiation.  It
+binds more tightly even than unary minus, making C<-2**2> product a
+negative not a positive four.  It is also right-associating, meaning
+that C<2**3**2> is two raised to the ninth power, not eight squared.
+
+=head2 How do I declare/create a structure?
+
+In general, you don't "declare" a structure.  Just use a (probably
+anonymous) hash reference.  See L<perlref> and L<perldsc> for details.
+Here's an example:
+
+    $person = {};                   # new anonymous hash
+    $person->{AGE}  = 24;           # set field AGE to 24
+    $person->{NAME} = "Nat";        # set field NAME to "Nat"
+
+If you're looking for something a bit more rigorous, try L<perltoot>.
+
+=head2 How do I create a module?
+
+A module is a package that lives in a file of the same name.  For
+example, the Hello::There module would live in Hello/There.pm.  For
+details, read L<perlmod>.  You'll also find L<Exporter> helpful.  If
+you're writing a C or mixed-language module with both C and Perl, then
+you should study L<perlxstut>.
+
+Here's a convenient template you might wish you use when starting your
+own module.  Make sure to change the names appropriately.
+
+    package Some::Module;  # assumes Some/Module.pm
+
+    use strict;
+
+    BEGIN {
+	use Exporter   ();
+	use vars       qw($VERSION @ISA @EXPORT @EXPORT_OK %EXPORT_TAGS);
+
+	## set the version for version checking; uncomment to use
+	## $VERSION     = 1.00;
+
+	# if using RCS/CVS, this next line may be preferred,
+	# but beware two-digit versions.
+	$VERSION = do{my@r=q$Revision: 1.15 $=~/\d+/g;sprintf '%d.'.'%02d'x$#r,@r};
+
+	@ISA         = qw(Exporter);
+	@EXPORT      = qw(&func1 &func2 &func3);
+	%EXPORT_TAGS = ( );  	# eg: TAG => [ qw!name1 name2! ],
+
+	# your exported package globals go here,
+	# as well as any optionally exported functions
+	@EXPORT_OK   = qw($Var1 %Hashit);
+    }
+    use vars      @EXPORT_OK;
+
+    # non-exported package globals go here
+    use vars      qw( @more $stuff );
+
+    # initialize package globals, first exported ones
+    $Var1   = '';
+    %Hashit = ();
+
+    # then the others (which are still accessible as $Some::Module::stuff)
+    $stuff  = '';
+    @more   = ();
+
+    # all file-scoped lexicals must be created before
+    # the functions below that use them.
+
+    # file-private lexicals go here
+    my $priv_var    = '';
+    my %secret_hash = ();
+
+    # here's a file-private function as a closure,
+    # callable as &$priv_func;  it cannot be prototyped.
+    my $priv_func = sub {
+        # stuff goes here.
+    };
+
+    # make all your functions, whether exported or not;
+    # remember to put something interesting in the {} stubs
+    sub func1      {}	 # no prototype
+    sub func2()    {}	 # proto'd void
+    sub func3($$)  {}	 # proto'd to 2 scalars
+
+    # this one isn't exported, but could be called!
+    sub func4(\%)  {}    # proto'd to 1 hash ref
+
+    END { }       # module clean-up code here (global destructor)
+
+    1;            # modules must return true
+
+=head2 How do I create a class?
+
+See L<perltoot> for an introduction to classes and objects, as well as
+L<perlobj> and L<perlbot>.
+
+=head2 How can I tell if a variable is tainted?
+
+See L<perlsec/"Laundering and Detecting Tainted Data">.  Here's an
+example (which doesn't use any system calls, because the kill()
+is given no processes to signal):
+
+    sub is_tainted {
+	return ! eval { join('',@_), kill 0; 1; };
+    }
+
+This is not C<-w> clean, however.  There is no C<-w> clean way to
+detect taintedness - take this as a hint that you should untaint
+all possibly-tainted data.
+
+=head2 What's a closure?
+
+Closures are documented in L<perlref>.
+
+I<Closure> is a computer science term with a precise but
+hard-to-explain meaning. Closures are implemented in Perl as anonymous
+subroutines with lasting references to lexical variables outside their
+own scopes.  These lexicals magically refer to the variables that were
+around when the subroutine was defined (deep binding).
+
+Closures make sense in any programming language where you can have the
+return value of a function be itself a function, as you can in Perl.
+Note that some languages provide anonymous functions but are not
+capable of providing proper closures; the Python language, for
+example.  For more information on closures, check out any textbook on
+functional programming.  Scheme is a language that not only supports
+but encourages closures.
+
+Here's a classic function-generating function:
+
+    sub add_function_generator {
+      return sub { shift + shift };
+    }
+
+    $add_sub = add_function_generator();
+    $sum = &$add_sub(4,5);                # $sum is 9 now.
+
+The closure works as a I<function template> with some customization
+slots left out to be filled later.  The anonymous subroutine returned
+by add_function_generator() isn't technically a closure because it
+refers to no lexicals outside its own scope.
+
+Contrast this with the following make_adder() function, in which the
+returned anonymous function contains a reference to a lexical variable
+outside the scope of that function itself.  Such a reference requires
+that Perl return a proper closure, thus locking in for all time the
+value that the lexical had when the function was created.
+
+    sub make_adder {
+        my $addpiece = shift;
+        return sub { shift + $addpiece };
+    }
+
+    $f1 = make_adder(20);
+    $f2 = make_adder(555);
+
+Now C<&$f1($n)> is always 20 plus whatever $n you pass in, whereas
+C<&$f2($n)> is always 555 plus whatever $n you pass in.  The $addpiece
+in the closure sticks around.
+
+Closures are often used for less esoteric purposes.  For example, when
+you want to pass in a bit of code into a function:
+
+    my $line;
+    timeout( 30, sub { $line = <STDIN> } );
+
+If the code to execute had been passed in as a string, C<'$line =
+E<lt>STDINE<gt>'>, there would have been no way for the hypothetical
+timeout() function to access the lexical variable $line back in its
+caller's scope.
+
+=head2 How can I pass/return a {Function, FileHandle, Array, Hash, Method, Regexp}?
+
+With the exception of regexps, you need to pass references to these
+objects.  See L<perlsub/"Pass by Reference"> for this particular
+question, and L<perlref> for information on references.
+
+=over 4
+
+=item Passing Variables and Functions
+
+Regular variables and functions are quite easy: just pass in a
+reference to an existing or anonymous variable or function:
+
+    func( \$some_scalar );
+
+    func( \$some_array );
+    func( [ 1 .. 10 ]   );
+
+    func( \%some_hash   );
+    func( { this => 10, that => 20 }   );
+
+    func( \&some_func   );
+    func( sub { $_[0] ** $_[1] }   );
+
+=item Passing Filehandles
+
+To create filehandles you can pass to subroutines, you can use C<*FH>
+or C<\*FH> notation ("typeglobs" - see L<perldata> for more information),
+or create filehandles dynamically using the old FileHandle or the new
+IO::File modules, both part of the standard Perl distribution.
+
+    use Fcntl;
+    use IO::File;
+    my $fh = new IO::File $filename, O_WRONLY|O_APPEND;
+		or die "Can't append to $filename: $!";
+    func($fh);
+
+=item Passing Regexps
+
+To pass regexps around, you'll need to either use one of the highly
+experimental regular expression modules from CPAN (Nick Ing-Simmons's
+Regexp or Ilya Zakharevich's Devel::Regexp), pass around strings
+and use an exception-trapping eval, or else be be very, very clever.
+Here's an example of how to pass in a string to be regexp compared:
+
+    sub compare($$) {
+        my ($val1, $regexp) = @_;
+        my $retval = eval { $val =~ /$regexp/ };
+	die if $@;
+	return $retval;
+    }
+
+    $match = compare("old McDonald", q/d.*D/);
+
+Make sure you never say something like this:
+
+    return eval "\$val =~ /$regexp/";   # WRONG
+
+or someone can sneak shell escapes into the regexp due to the double
+interpolation of the eval and the double-quoted string.  For example:
+
+    $pattern_of_evil = 'danger ${ system("rm -rf * &") } danger';
+
+    eval "\$string =~ /$pattern_of_evil/";
+
+Those preferring to be very, very clever might see the O'Reilly book,
+I<Mastering Regular Expressions>, by Jeffrey Friedl.  Page 273's
+Build_MatchMany_Function() is particularly interesting.  A complete
+citation of this book is given in L<perlfaq2>.
+
+=item Passing Methods
+
+To pass an object method into a subroutine, you can do this:
+
+    call_a_lot(10, $some_obj, "methname")
+    sub call_a_lot {
+        my ($count, $widget, $trick) = @_;
+        for (my $i = 0; $i < $count; $i++) {
+            $widget->$trick();
+        }
+    }
+
+or you can use a closure to bundle up the object and its method call
+and arguments:
+
+    my $whatnot =  sub { $some_obj->obfuscate(@args) };
+    func($whatnot);
+    sub func {
+        my $code = shift;
+        &$code();
+    }
+
+You could also investigate the can() method in the UNIVERSAL class
+(part of the standard perl distribution).
+
+=back
+
+=head2 How do I create a static variable?
+
+As with most things in Perl, TMTOWTDI.  What is a "static variable" in
+other languages could be either a function-private variable (visible
+only within a single function, retaining its value between calls to
+that function), or a file-private variable (visible only to functions
+within the file it was declared in) in Perl.
+
+Here's code to implement a function-private variable:
+
+    BEGIN {
+        my $counter = 42;
+        sub prev_counter { return --$counter }
+        sub next_counter { return $counter++ }
+    }
+
+Now prev_counter() and next_counter() share a private variable $counter
+that was initialized at compile time.
+
+To declare a file-private variable, you'll still use a my(), putting
+it at the outer scope level at the top of the file.  Assume this is in
+file Pax.pm:
+
+    package Pax;
+    my $started = scalar(localtime(time()));
+
+    sub begun { return $started }
+
+When C<use Pax> or C<require Pax> loads this module, the variable will
+be initialized.  It won't get garbage-collected the way most variables
+going out of scope do, because the begun() function cares about it,
+but no one else can get it.  It is not called $Pax::started because
+its scope is unrelated to the package.  It's scoped to the file.  You
+could conceivably have several packages in that same file all
+accessing the same private variable, but another file with the same
+package couldn't get to it.
+
+=head2 What's the difference between dynamic and lexical (static) scoping?  Between local() and my()?
+
+C<local($x)> saves away the old value of the global variable C<$x>,
+and assigns a new value for the duration of the subroutine, I<which is
+visible in other functions called from that subroutine>.  This is done
+at run-time, so is called dynamic scoping.  local() always affects global
+variables, also called package variables or dynamic variables.
+
+C<my($x)> creates a new variable that is only visible in the current
+subroutine.  This is done at compile-time, so is called lexical or
+static scoping.  my() always affects private variables, also called
+lexical variables or (improperly) static(ly scoped) variables.
+
+For instance:
+
+    sub visible {
+	print "var has value $var\n";
+    }
+
+    sub dynamic {
+	local $var = 'local';	# new temporary value for the still-global
+	visible();              #   variable called $var
+    }
+
+    sub lexical {
+	my $var = 'private';    # new private variable, $var
+	visible();              # (invisible outside of sub scope)
+    }
+
+    $var = 'global';
+
+    visible();      		# prints global
+    dynamic();      		# prints local
+    lexical();      		# prints global
+
+Notice how at no point does the value "private" get printed.  That's
+because $var only has that value within the block of the lexical()
+function, and it is hidden from called subroutine.
+
+In summary, local() doesn't make what you think of as private, local
+variables.  It gives a global variable a temporary value.  my() is
+what you're looking for if you want private variables.
+
+See also L<perlsub>, which explains this all in more detail.
+
+=head2 How can I access a dynamic variable while a similarly named lexical is in scope?
+
+You can do this via symbolic references, provided you haven't set
+C<use strict "refs">.  So instead of $var, use C<${'var'}>.
+
+    local $var = "global";
+    my    $var = "lexical";
+
+    print "lexical is $var\n";
+
+    no strict 'refs';
+    print "global  is ${'var'}\n";
+
+If you know your package, you can just mention it explicitly, as in
+$Some_Pack::var.  Note that the notation $::var is I<not> the dynamic
+$var in the current package, but rather the one in the C<main>
+package, as though you had written $main::var.  Specifying the package
+directly makes you hard-code its name, but it executes faster and
+avoids running afoul of C<use strict "refs">.
+
+=head2 What's the difference between deep and shallow binding?
+
+In deep binding, lexical variables mentioned in anonymous subroutines
+are the same ones that were in scope when the subroutine was created.
+In shallow binding, they are whichever variables with the same names
+happen to be in scope when the subroutine is called.  Perl always uses
+deep binding of lexical variables (i.e., those created with my()).
+However, dynamic variables (aka global, local, or package variables)
+are effectively shallowly bound.  Consider this just one more reason
+not to use them.  See the answer to L<"What's a closure?">.
+
+=head2 Why doesn't "local($foo) = <FILE>;" work right?
+
+C<local()> gives list context to the right hand side of C<=>.  The
+E<lt>FHE<gt> read operation, like so many of Perl's functions and
+operators, can tell which context it was called in and behaves
+appropriately.  In general, the scalar() function can help.  This
+function does nothing to the data itself (contrary to popular myth)
+but rather tells its argument to behave in whatever its scalar fashion
+is.  If that function doesn't have a defined scalar behavior, this of
+course doesn't help you (such as with sort()).
+
+To enforce scalar context in this particular case, however, you need
+merely omit the parentheses:
+
+    local($foo) = <FILE>;	    # WRONG
+    local($foo) = scalar(<FILE>);   # ok
+    local $foo  = <FILE>;	    # right
+
+You should probably be using lexical variables anyway, although the
+issue is the same here:
+
+    my($foo) = <FILE>;	# WRONG
+    my $foo  = <FILE>;	# right
+
+=head2 How do I redefine a built-in function, operator, or method?
+
+Why do you want to do that? :-)
+
+If you want to override a predefined function, such as open(),
+then you'll have to import the new definition from a different
+module.  See L<perlsub/"Overriding Builtin Functions">.  There's
+also an example in L<perltoot/"Class::Template">.
+
+If you want to overload a Perl operator, such as C<+> or C<**>,
+then you'll want to use the C<use overload> pragma, documented
+in L<overload>.
+
+If you're talking about obscuring method calls in parent classes,
+see L<perltoot/"Overridden Methods">.
+
+=head2 What's the difference between calling a function as &foo and foo()?
+
+When you call a function as C<&foo>, you allow that function access to
+your current @_ values, and you by-pass prototypes.  That means that
+the function doesn't get an empty @_, it gets yours!  While not
+strictly speaking a bug (it's documented that way in L<perlsub>), it
+would be hard to consider this a feature in most cases.
+
+When you call your function as C<&foo()>, then you do get a new @_,
+but prototyping is still circumvented.
+
+Normally, you want to call a function using C<foo()>.  You may only
+omit the parentheses if the function is already known to the compiler
+because it already saw the definition (C<use> but not C<require>),
+or via a forward reference or C<use subs> declaration.  Even in this
+case, you get a clean @_ without any of the old values leaking through
+where they don't belong.
+
+=head2 How do I create a switch or case statement?
+
+This is explained in more depth in the L<perlsyn>.  Briefly, there's
+no official case statement, because of the variety of tests possible
+in Perl (numeric comparison, string comparison, glob comparison,
+regexp matching, overloaded comparisons, ...).  Larry couldn't decide
+how best to do this, so he left it out, even though it's been on the
+wish list since perl1.
+
+Here's a simple example of a switch based on pattern matching.  We'll
+do a multi-way conditional based on the type of reference stored in
+$whatchamacallit:
+
+    SWITCH:
+      for (ref $whatchamacallit) {
+
+	/^$/		&& die "not a reference";
+
+	/SCALAR/	&& do {
+				print_scalar($$ref);
+				last SWITCH;
+			};
+
+	/ARRAY/		&& do {
+				print_array(@$ref);
+				last SWITCH;
+			};
+
+	/HASH/		&& do {
+				print_hash(%$ref);
+				last SWITCH;
+			};
+
+	/CODE/		&& do {
+				warn "can't print function ref";
+				last SWITCH;
+			};
+
+	# DEFAULT
+
+	warn "User defined type skipped";
+
+    }
+
+=head2 How can I catch accesses to undefined variables/functions/methods?
+
+The AUTOLOAD method, discussed in L<perlsub/"Autoloading"> and
+L<perltoot/"AUTOLOAD: Proxy Methods">, lets you capture calls to
+undefined functions and methods.
+
+When it comes to undefined variables that would trigger a warning
+under C<-w>, you can use a handler to trap the pseudo-signal
+C<__WARN__> like this:
+
+    $SIG{__WARN__} = sub {
+
+	for ( $_[0] ) {
+
+	    /Use of uninitialized value/  && do {
+		# promote warning to a fatal
+		die $_;
+	    };
+
+	    # other warning cases to catch could go here;
+
+	    warn $_;
+	}
+
+    };
+
+=head2 Why can't a method included in this same file be found?
+
+Some possible reasons: your inheritance is getting confused, you've
+misspelled the method name, or the object is of the wrong type.  Check
+out L<perltoot> for details on these.  You may also use C<print
+ref($object)> to find out the class C<$object> was blessed into.
+
+Another possible reason for problems is because you've used the
+indirect object syntax (eg, C<find Guru "Samy">) on a class name
+before Perl has seen that such a package exists.  It's wisest to make
+sure your packages are all defined before you start using them, which
+will be taken care of if you use the C<use> statement instead of
+C<require>.  If not, make sure to use arrow notation (eg,
+C<Guru->find("Samy")>) instead.  Object notation is explained in
+L<perlobj>.
+
+=head2 How can I find out my current package?
+
+If you're just a random program, you can do this to find
+out what the currently compiled package is:
+
+    my $packname = ref bless [];
+
+But if you're a method and you want to print an error message
+that includes the kind of object you were called on (which is
+not necessarily the same as the one in which you were compiled):
+
+    sub amethod {
+	my $self = shift;
+	my $class = ref($self) || $self;
+	warn "called me from a $class object";
+    }
+
+=head1 AUTHOR AND COPYRIGHT
+
+Copyright (c) 1997 Tom Christiansen and Nathan Torkington.
+All rights reserved.  See L<perlfaq> for distribution information.