virgin perl 5.6.0

3 files changed, 194 insertions, 68 deletions

diff --git a/gnu/usr.bin/perl/pod/perlcompile.pod b/gnu/usr.bin/perl/pod/perlcompile.pod
index 505ce68384f..697cb80d409 100644
--- a/gnu/usr.bin/perl/pod/perlcompile.pod
+++ b/gnu/usr.bin/perl/pod/perlcompile.pod
@@ -9,16 +9,17 @@ internal form (a parse tree) which is then optimized before being
 run.  Since version 5.005, Perl has shipped with a module
 capable of inspecting the optimized parse tree (C<B>), and this has
 been used to write many useful utilities, including a module that lets
-you turn your Perl into C source code that can be compiled into a
+you turn your Perl into C source code that can be compiled into an
 native executable.
 
 The C<B> module provides access to the parse tree, and other modules
 ("back ends") do things with the tree.  Some write it out as
-semi-human-readable text.  Another traverses the parse tree to build a
-cross-reference of which subroutines, formats, and variables are used
-where.  Another checks your code for dubious constructs.  Yet another back
-end dumps the parse tree back out as Perl source, acting as a source code
-beautifier or deobfuscator.
+bytecode, C source code, or a semi-human-readable text.  Another
+traverses the parse tree to build a cross-reference of which
+subroutines, formats, and variables are used where.  Another checks
+your code for dubious constructs.  Yet another back end dumps the
+parse tree back out as Perl source, acting as a source code beautifier
+or deobfuscator.
 
 Because its original purpose was to be a way to produce C code
 corresponding to a Perl program, and in turn a native executable, the
@@ -36,7 +37,8 @@ what problems there are, and how to work around them.
 
 The compiler back ends are in the C<B::> hierarchy, and the front-end
 (the module that you, the user of the compiler, will sometimes
-interact with) is the O module.
+interact with) is the O module.  Some back ends (e.g., C<B::C>) have
+programs (e.g., I<perlcc>) to hide the modules' complexity.
 
 Here are the important back ends to know about, with their status
 expressed as a number from 0 (outline for later implementation) to
@@ -44,6 +46,30 @@ expressed as a number from 0 (outline for later implementation) to
 
 =over 4
 
+=item B::Bytecode
+
+Stores the parse tree in a machine-independent format, suitable
+for later reloading through the ByteLoader module.  Status: 5 (some
+things work, some things don't, some things are untested).
+
+=item B::C
+
+Creates a C source file containing code to rebuild the parse tree
+and resume the interpreter.  Status: 6 (many things work adequately,
+including programs using Tk).
+
+=item B::CC
+
+Creates a C source file corresponding to the run time code path in
+the parse tree.  This is the closest to a Perl-to-C translator there
+is, but the code it generates is almost incomprehensible because it
+translates the parse tree into a giant switch structure that
+manipulates Perl structures.  Eventual goal is to reduce (given
+sufficient type information in the Perl program) some of the
+Perl data structure manipulations into manipulations of C-level
+ints, floats, etc.  Status: 5 (some things work, including
+uncomplicated Tk examples).
+
 =item B::Lint
 
 Complains if it finds dubious constructs in your source code.  Status:
@@ -134,7 +160,7 @@ I<myperlprogram> to the file I<report>:
 =head2 The Decompiling Back End
 
 The Deparse back end turns your Perl source back into Perl source.  It
-can reformat along the way, making it useful as a deobfuscator.  The
+can reformat along the way, making it useful as a de-obfuscator.  The
 most basic way to use it is:
 
   $ perl -MO=Deparse myperlprogram
@@ -157,6 +183,9 @@ one-liners:
       rename $was, $_ unless $was eq $_;
   }
 
+(this is the I<rename> program that comes in the I<eg/> directory
+of the Perl source distribution).
+
 The decompiler has several options for the code it generates.  For
 instance, you can set the size of each indent from 4 (as above) to
 2 with:
@@ -190,7 +219,57 @@ To disable context checks and undefined subroutines:
 
 See L<B::Lint> for information on the options.
 
-=head1 Module List for the Compiler Suite
+=head2 The Simple C Back End
+
+This module saves the internal compiled state of your Perl program
+to a C source file, which can be turned into a native executable
+for that particular platform using a C compiler.  The resulting
+program links against the Perl interpreter library, so it
+will not save you disk space (unless you build Perl with a shared
+library) or program size.  It may, however, save you startup time.
+
+The C<perlcc> tool generates such executables by default.
+
+  perlcc myperlprogram.pl
+
+=head2 The Bytecode Back End
+
+This back end is only useful if you also have a way to load and
+execute the bytecode that it produces.  The ByteLoader module provides
+this functionality.
+
+To turn a Perl program into executable byte code, you can use C<perlcc>
+with the C<-b> switch:
+
+  perlcc -b myperlprogram.pl
+
+The byte code is machine independent, so once you have a compiled
+module or program, it is as portable as Perl source (assuming that
+the user of the module or program has a modern-enough Perl interpreter
+to decode the byte code).
+
+See B<B::Bytecode> for information on options to control the
+optimization and nature of the code generated by the Bytecode module.
+
+=head2 The Optimized C Back End
+
+The optimized C back end will turn your Perl program's run time
+code-path into an equivalent (but optimized) C program that manipulates
+the Perl data structures directly.  The program will still link against
+the Perl interpreter library, to allow for eval(), C<s///e>,
+C<require>, etc.
+
+The C<perlcc> tool generates such executables when using the -opt
+switch.  To compile a Perl program (ending in C<.pl>
+or C<.p>):
+
+  perlcc -opt myperlprogram.pl
+
+To produce a shared library from a Perl module (ending in C<.pm>):
+
+  perlcc -opt Myperlmodule.pm
+
+For more information, see L<perlcc> and L<B::CC>.
 
 =over 4
 
@@ -211,13 +290,53 @@ called something like this:
 
 This is like saying C<use O 'Deparse'> in your Perl program.
 
-=item B::Concise
+=item B::Asmdata
+
+This module is used by the B::Assembler module, which is in turn used
+by the B::Bytecode module, which stores a parse-tree as
+bytecode for later loading.  It's not a back end itself, but rather a
+component of a back end.
+
+=item B::Assembler
+
+This module turns a parse-tree into data suitable for storing
+and later decoding back into a parse-tree.  It's not a back end
+itself, but rather a component of a back end.  It's used by the
+I<assemble> program that produces bytecode.
+
+=item B::Bblock
+
+This module is used by the B::CC back end.  It walks "basic blocks".
+A basic block is a series of operations which is known to execute from
+start to finish, with no possiblity of branching or halting.
+
+=item B::Bytecode
+
+This module is a back end that generates bytecode from a
+program's parse tree.  This bytecode is written to a file, from where
+it can later be reconstructed back into a parse tree.  The goal is to
+do the expensive program compilation once, save the interpreter's
+state into a file, and then restore the state from the file when the
+program is to be executed.  See L</"The Bytecode Back End">
+for details about usage.
 
-This module prints a concise (but complete) version of the Perl parse
-tree.  Its output is more customizable than the one of B::Terse or
-B::Debug (and it can emulate them). This module useful for people who
-are writing their own back end, or who are learning about the Perl
-internals.  It's not useful to the average programmer.
+=item B::C
+
+This module writes out C code corresponding to the parse tree and
+other interpreter internal structures.  You compile the corresponding
+C file, and get an executable file that will restore the internal
+structures and the Perl interpreter will begin running the
+program.  See L</"The Simple C Back End"> for details about usage.
+
+=item B::CC
+
+This module writes out C code corresponding to your program's
+operations.  Unlike the B::C module, which merely stores the
+interpreter and its state in a C program, the B::CC module makes a
+C program that does not involve the interpreter.  As a consequence,
+programs translated into C by B::CC can execute faster than normal
+interpreted programs.  See L</"The Optimized C Back End"> for
+details about usage.
 
 =item B::Debug
 
@@ -233,6 +352,12 @@ It is useful in debugging and deconstructing other people's code,
 also as a pretty-printer for your own source.  See
 L</"The Decompiling Back End"> for details about usage.
 
+=item B::Disassembler
+
+This module turns bytecode back into a parse tree.  It's not a back
+end itself, but rather a component of a back end.  It's used by the
+I<disassemble> program that comes with the bytecode.
+
 =item B::Lint
 
 This module inspects the compiled form of your source code for things
@@ -244,17 +369,30 @@ can identify.  See L</"The Lint Back End"> for details about usage.
 =item B::Showlex
 
 This module prints out the my() variables used in a function or a
-file.  To get a list of the my() variables used in the subroutine
+file.  To gt a list of the my() variables used in the subroutine
 mysub() defined in the file myperlprogram:
 
   $ perl -MO=Showlex,mysub myperlprogram
 
-To get a list of the my() variables used in the file myperlprogram:
+To gt a list of the my() variables used in the file myperlprogram:
 
   $ perl -MO=Showlex myperlprogram
 
 [BROKEN]
 
+=item B::Stackobj
+
+This module is used by the B::CC module.  It's not a back end itself,
+but rather a component of a back end.
+
+=item B::Stash
+
+This module is used by the L<perlcc> program, which compiles a module
+into an executable.  B::Stash prints the symbol tables in use by a
+program, and is used to prevent B::CC from producing C code for the
+B::* and O modules.  It's not a back end itself, but rather a
+component of a back end.
+
 =item B::Terse
 
 This module prints the contents of the parse tree, but without as much
@@ -276,6 +414,19 @@ usage.
 
 =head1 KNOWN PROBLEMS
 
+The simple C backend currently only saves typeglobs with alphanumeric
+names.
+
+The optimized C backend outputs code for more modules than it should
+(e.g., DirHandle).  It also has little hope of properly handling
+C<goto LABEL> outside the running subroutine (C<goto &sub> is ok).
+C<goto LABEL> currently does not work at all in this backend.
+It also creates a huge initialization function that gives
+C compilers headaches.  Splitting the initialization function gives
+better results.  Other problems include: unsigned math does not
+work correctly; some opcodes are handled incorrectly by default
+opcode handling mechanism.
+
 BEGIN{} blocks are executed while compiling your code.  Any external
 state that is initialized in BEGIN{}, such as opening files, initiating
 database connections etc., do not behave properly.  To work around
diff --git a/gnu/usr.bin/perl/pod/podchecker.PL b/gnu/usr.bin/perl/pod/podchecker.PL
index 75c316d26ed..a7f96434ca6 100644
--- a/gnu/usr.bin/perl/pod/podchecker.PL
+++ b/gnu/usr.bin/perl/pod/podchecker.PL
@@ -39,7 +39,7 @@ print OUT <<'!NO!SUBS!';
 #############################################################################
 # podchecker -- command to invoke the podchecker function in Pod::Checker
 #
-# Copyright (c) 1998-2000 by Bradford Appleton. All rights reserved.
+# Copyright (c) 1998-1999 by Bradford Appleton. All rights reserved.
 # This file is part of "PodParser". PodParser is free software;
 # you can redistribute it and/or modify it under the same terms
 # as Perl itself.
@@ -70,9 +70,7 @@ Print the manual page and exit.
 
 =item B<-warnings> B<-nowarnings>
 
-Turn on/off printing of warnings. Repeating B<-warnings> increases the
-warning level, i.e. more warnings are printed. Currently increasing to
-level two causes flagging of unescaped "E<lt>,E<gt>" characters.
+Turn on/off printing of warnings.
 
 =item I<file>
 
@@ -87,8 +85,6 @@ syntax errors in the POD documentation and will print any errors
 it find to STDERR. At the end, it will print a status message
 indicating the number of errors found.
 
-Directories are ignored, an appropriate warning message is printed.
-
 B<podchecker> invokes the B<podchecker()> function exported by B<Pod::Checker>
 Please see L<Pod::Checker/podchecker()> for more details.
 
@@ -105,7 +101,7 @@ the given POD files has syntax errors.
 The status 2 indicates that at least one of the specified 
 files does not contain I<any> POD commands.
 
-Status 1 overrides status 2. If you want unambiguous
+Status 1 overrides status 2. If you want unambigouus
 results, call B<podchecker> with one single argument only.
 
 =head1 SEE ALSO
@@ -114,10 +110,8 @@ L<Pod::Parser> and L<Pod::Checker>
 
 =head1 AUTHORS
 
-Please report bugs using L<http://rt.cpan.org>.
-
 Brad Appleton E<lt>bradapp@enteract.comE<gt>,
-Marek Rouchal E<lt>marekr@cpan.orgE<gt>
+Marek Rouchal E<lt>marek@saftsack.fs.uni-bayreuth.deE<gt>
 
 Based on code for B<Pod::Text::pod2text(1)> written by
 Tom Christiansen E<lt>tchrist@mox.perl.comE<gt>
@@ -130,50 +124,32 @@ use Pod::Usage;
 use Getopt::Long;
 
 ## Define options
-my %options;
+my %options = (
+        "help"     => 0,
+        "man"      => 0,
+        "warnings" => 1,
+);
 
 ## Parse options
-GetOptions(\%options, qw(help man warnings+ nowarnings))  ||  pod2usage(2);
+GetOptions(\%options, "help", "man", "warnings!")  ||  pod2usage(2);
 pod2usage(1)  if ($options{help});
 pod2usage(-verbose => 2)  if ($options{man});
 
-if($options{nowarnings}) {
-  $options{warnings} = 0;
-}
-elsif(!defined $options{warnings}) {
-  $options{warnings} = 1; # default is warnings on
-}
-
 ## Dont default to STDIN if connected to a terminal
 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 
 ## Invoke podchecker()
 my $status = 0;
-@ARGV = qw(-) unless(@ARGV);
-for my $podfile (@ARGV) {
-    if($podfile eq '-') {
-      $podfile = '<&STDIN';
-    }
-    elsif(-d $podfile) {
-      warn "podchecker: Warning: Ignoring directory '$podfile'\n";
-      next;
-    }
-    my $errors =
-      podchecker($podfile, undef, '-warnings' => $options{warnings});
-    if($errors > 0) {
+@ARGV = ("<&STDIN") unless(@ARGV);
+for (@ARGV) {
+    my $s = podchecker($_, undef, '-warnings' => $options{warnings});
+    if($s > 0) {
         # errors occurred
         $status = 1;
-        printf STDERR ("%s has %d pod syntax %s.\n",
-          $podfile, $errors,
-          ($errors == 1) ? 'error' : 'errors');
     }
-    elsif($errors < 0) {
+    elsif($s < 0) {
         # no pod found
         $status = 2 unless($status);
-        print STDERR "$podfile does not contain any pod commands.\n";
-    }
-    else {
-        print STDERR "$podfile pod syntax OK.\n";
     }
 }
 exit $status;
diff --git a/gnu/usr.bin/perl/pod/podselect.PL b/gnu/usr.bin/perl/pod/podselect.PL
index 7fadd7366cb..f2ba80a73b5 100644
--- a/gnu/usr.bin/perl/pod/podselect.PL
+++ b/gnu/usr.bin/perl/pod/podselect.PL
@@ -15,8 +15,9 @@ use Cwd;
 # This is so that make depend always knows where to find PL derivatives.
 $origdir = cwd;
 chdir(dirname($0));
-$file = basename($0, '.PL');
-$file .= '.com' if $^O eq 'VMS';
+($file = basename($0)) =~ s/\.PL$//;
+$file =~ s/\.pl$// if ($^O eq 'os2' or $^O eq 'dos');  # "case-forgiving"
+$file =~ s/\.pl$/.com/ if ($^O eq 'VMS');              # "case-forgiving"
 
 open OUT,">$file" or die "Can't create $file: $!";
 
@@ -38,14 +39,14 @@ print OUT <<'!NO!SUBS!';
 #############################################################################
 # podselect -- command to invoke the podselect function in Pod::Select
 #
-# Copyright (c) 1996-2000 by Bradford Appleton. All rights reserved.
+# Copyright (c) 1996-1999 by Bradford Appleton. All rights reserved.
 # This file is part of "PodParser". PodParser is free software;
 # you can redistribute it and/or modify it under the same terms
 # as Perl itself.
 #############################################################################
 
 use strict;
-#use diagnostics;
+use diagnostics;
 
 =head1 NAME
 
@@ -98,8 +99,6 @@ L<Pod::Parser> and L<Pod::Select>
 
 =head1 AUTHOR
 
-Please report bugs using L<http://rt.cpan.org>.
-
 Brad Appleton E<lt>bradapp@enteract.comE<gt>
 
 Based on code for B<Pod::Text::pod2text(1)> written by
@@ -113,13 +112,13 @@ use Getopt::Long;
 
 ## Define options
 my %options = (
-        'help'     => 0,
-        'man'      => 0,
-        'sections' => [],
+        "help"     => 0,
+        "man"      => 0,
+        "sections" => [],
 );
 
 ## Parse options
-GetOptions(\%options, 'help', 'man', 'sections|select=s@')  ||  pod2usage(2);
+GetOptions(\%options, "help", "man", "sections|select=s@")  ||  pod2usage(2);
 pod2usage(1)  if ($options{help});
 pod2usage(-verbose => 2)  if ($options{man});
 
@@ -127,8 +126,8 @@ pod2usage(-verbose => 2)  if ($options{man});
 pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
 
 ## Invoke podselect().
-if (@{ $options{'sections'} } > 0) {
-    podselect({ -sections => $options{'sections'} }, @ARGV);
+if (@{ $options{"sections"} } > 0) {
+    podselect({ -sections => $options{"sections"} }, @ARGV);
 }
 else {
     podselect(@ARGV);