[Midnightbsd-cvs] src [6441] U trunk/contrib/perl/pod: perl 5.18.1 merge
laffer1 at midnightbsd.org
laffer1 at midnightbsd.org
Mon Dec 2 16:27:51 EST 2013
Revision: 6441
http://svnweb.midnightbsd.org/src/?rev=6441
Author: laffer1
Date: 2013-12-02 16:27:48 -0500 (Mon, 02 Dec 2013)
Log Message:
-----------
perl 5.18.1 merge
Modified Paths:
--------------
trunk/contrib/perl/pod/Makefile.SH
trunk/contrib/perl/pod/buildtoc
trunk/contrib/perl/pod/perl.pod
trunk/contrib/perl/pod/perl5004delta.pod
trunk/contrib/perl/pod/perl5005delta.pod
trunk/contrib/perl/pod/perl5100delta.pod
trunk/contrib/perl/pod/perl5101delta.pod
trunk/contrib/perl/pod/perl5120delta.pod
trunk/contrib/perl/pod/perl5121delta.pod
trunk/contrib/perl/pod/perl5122delta.pod
trunk/contrib/perl/pod/perl5123delta.pod
trunk/contrib/perl/pod/perl5140delta.pod
trunk/contrib/perl/pod/perl561delta.pod
trunk/contrib/perl/pod/perl56delta.pod
trunk/contrib/perl/pod/perl589delta.pod
trunk/contrib/perl/pod/perl58delta.pod
trunk/contrib/perl/pod/perlapio.pod
trunk/contrib/perl/pod/perlbook.pod
trunk/contrib/perl/pod/perlboot.pod
trunk/contrib/perl/pod/perlbot.pod
trunk/contrib/perl/pod/perlcall.pod
trunk/contrib/perl/pod/perlcheat.pod
trunk/contrib/perl/pod/perlclib.pod
trunk/contrib/perl/pod/perlcommunity.pod
trunk/contrib/perl/pod/perldata.pod
trunk/contrib/perl/pod/perldbmfilter.pod
trunk/contrib/perl/pod/perldebguts.pod
trunk/contrib/perl/pod/perldebtut.pod
trunk/contrib/perl/pod/perldebug.pod
trunk/contrib/perl/pod/perldelta.pod
trunk/contrib/perl/pod/perldiag.pod
trunk/contrib/perl/pod/perldsc.pod
trunk/contrib/perl/pod/perlebcdic.pod
trunk/contrib/perl/pod/perlembed.pod
trunk/contrib/perl/pod/perlfork.pod
trunk/contrib/perl/pod/perlform.pod
trunk/contrib/perl/pod/perlfunc.pod
trunk/contrib/perl/pod/perlgit.pod
trunk/contrib/perl/pod/perlgpl.pod
trunk/contrib/perl/pod/perlguts.pod
trunk/contrib/perl/pod/perlhack.pod
trunk/contrib/perl/pod/perlhacktips.pod
trunk/contrib/perl/pod/perlhacktut.pod
trunk/contrib/perl/pod/perlhist.pod
trunk/contrib/perl/pod/perlinterp.pod
trunk/contrib/perl/pod/perlintro.pod
trunk/contrib/perl/pod/perliol.pod
trunk/contrib/perl/pod/perlipc.pod
trunk/contrib/perl/pod/perllexwarn.pod
trunk/contrib/perl/pod/perllocale.pod
trunk/contrib/perl/pod/perllol.pod
trunk/contrib/perl/pod/perlmod.pod
trunk/contrib/perl/pod/perlmodinstall.pod
trunk/contrib/perl/pod/perlmodlib.PL
trunk/contrib/perl/pod/perlmodstyle.pod
trunk/contrib/perl/pod/perlmroapi.pod
trunk/contrib/perl/pod/perlobj.pod
trunk/contrib/perl/pod/perlop.pod
trunk/contrib/perl/pod/perlpacktut.pod
trunk/contrib/perl/pod/perlperf.pod
trunk/contrib/perl/pod/perlpod.pod
trunk/contrib/perl/pod/perlpodspec.pod
trunk/contrib/perl/pod/perlpolicy.pod
trunk/contrib/perl/pod/perlport.pod
trunk/contrib/perl/pod/perlpragma.pod
trunk/contrib/perl/pod/perlre.pod
trunk/contrib/perl/pod/perlreapi.pod
trunk/contrib/perl/pod/perlrebackslash.pod
trunk/contrib/perl/pod/perlrecharclass.pod
trunk/contrib/perl/pod/perlref.pod
trunk/contrib/perl/pod/perlreftut.pod
trunk/contrib/perl/pod/perlreguts.pod
trunk/contrib/perl/pod/perlrequick.pod
trunk/contrib/perl/pod/perlreref.pod
trunk/contrib/perl/pod/perlretut.pod
trunk/contrib/perl/pod/perlrun.pod
trunk/contrib/perl/pod/perlsec.pod
trunk/contrib/perl/pod/perlsource.pod
trunk/contrib/perl/pod/perlsub.pod
trunk/contrib/perl/pod/perlsyn.pod
trunk/contrib/perl/pod/perlthrtut.pod
trunk/contrib/perl/pod/perltie.pod
trunk/contrib/perl/pod/perltodo.pod
trunk/contrib/perl/pod/perltooc.pod
trunk/contrib/perl/pod/perltoot.pod
trunk/contrib/perl/pod/perltrap.pod
trunk/contrib/perl/pod/perlunicode.pod
trunk/contrib/perl/pod/perlunifaq.pod
trunk/contrib/perl/pod/perluniintro.pod
trunk/contrib/perl/pod/perlutil.pod
trunk/contrib/perl/pod/perlvar.pod
trunk/contrib/perl/pod/perlvms.pod
trunk/contrib/perl/pod/rofftoc
Added Paths:
-----------
trunk/contrib/perl/pod/checkpods.PL
trunk/contrib/perl/pod/perl5124delta.pod
trunk/contrib/perl/pod/perl5125delta.pod
trunk/contrib/perl/pod/perl5142delta.pod
trunk/contrib/perl/pod/perl5143delta.pod
trunk/contrib/perl/pod/perl5144delta.pod
trunk/contrib/perl/pod/perl5160delta.pod
trunk/contrib/perl/pod/perl5161delta.pod
trunk/contrib/perl/pod/perl5162delta.pod
trunk/contrib/perl/pod/perl5163delta.pod
trunk/contrib/perl/pod/perl5180delta.pod
trunk/contrib/perl/pod/perlapi.pod
trunk/contrib/perl/pod/perldtrace.pod
trunk/contrib/perl/pod/perlexperiment.pod
trunk/contrib/perl/pod/perlintern.pod
trunk/contrib/perl/pod/perlmodlib.pod
trunk/contrib/perl/pod/perlootut.pod
trunk/contrib/perl/pod/perlothrtut.pod
trunk/contrib/perl/pod/perlrepository.pod
trunk/contrib/perl/pod/perltoc.pod
trunk/contrib/perl/pod/pod2html.PL
trunk/contrib/perl/pod/pod2latex.PL
trunk/contrib/perl/pod/pod2man.PL
trunk/contrib/perl/pod/pod2text.PL
trunk/contrib/perl/pod/pod2usage.PL
trunk/contrib/perl/pod/podchecker.PL
trunk/contrib/perl/pod/podselect.PL
Property Changed:
----------------
trunk/contrib/perl/pod/Makefile.SH
trunk/contrib/perl/pod/buildtoc
trunk/contrib/perl/pod/perl.pod
trunk/contrib/perl/pod/perl5004delta.pod
trunk/contrib/perl/pod/perl5005delta.pod
trunk/contrib/perl/pod/perl5100delta.pod
trunk/contrib/perl/pod/perl5101delta.pod
trunk/contrib/perl/pod/perl5110delta.pod
trunk/contrib/perl/pod/perl5111delta.pod
trunk/contrib/perl/pod/perl5112delta.pod
trunk/contrib/perl/pod/perl5113delta.pod
trunk/contrib/perl/pod/perl5114delta.pod
trunk/contrib/perl/pod/perl5115delta.pod
trunk/contrib/perl/pod/perl5120delta.pod
trunk/contrib/perl/pod/perl5121delta.pod
trunk/contrib/perl/pod/perl5122delta.pod
trunk/contrib/perl/pod/perl5123delta.pod
trunk/contrib/perl/pod/perl5130delta.pod
trunk/contrib/perl/pod/perl51310delta.pod
trunk/contrib/perl/pod/perl51311delta.pod
trunk/contrib/perl/pod/perl5131delta.pod
trunk/contrib/perl/pod/perl5132delta.pod
trunk/contrib/perl/pod/perl5133delta.pod
trunk/contrib/perl/pod/perl5134delta.pod
trunk/contrib/perl/pod/perl5135delta.pod
trunk/contrib/perl/pod/perl5136delta.pod
trunk/contrib/perl/pod/perl5137delta.pod
trunk/contrib/perl/pod/perl5138delta.pod
trunk/contrib/perl/pod/perl5139delta.pod
trunk/contrib/perl/pod/perl5140delta.pod
trunk/contrib/perl/pod/perl5141delta.pod
trunk/contrib/perl/pod/perl561delta.pod
trunk/contrib/perl/pod/perl56delta.pod
trunk/contrib/perl/pod/perl570delta.pod
trunk/contrib/perl/pod/perl571delta.pod
trunk/contrib/perl/pod/perl572delta.pod
trunk/contrib/perl/pod/perl573delta.pod
trunk/contrib/perl/pod/perl581delta.pod
trunk/contrib/perl/pod/perl582delta.pod
trunk/contrib/perl/pod/perl583delta.pod
trunk/contrib/perl/pod/perl584delta.pod
trunk/contrib/perl/pod/perl585delta.pod
trunk/contrib/perl/pod/perl586delta.pod
trunk/contrib/perl/pod/perl587delta.pod
trunk/contrib/perl/pod/perl588delta.pod
trunk/contrib/perl/pod/perl589delta.pod
trunk/contrib/perl/pod/perl58delta.pod
trunk/contrib/perl/pod/perl590delta.pod
trunk/contrib/perl/pod/perl591delta.pod
trunk/contrib/perl/pod/perl592delta.pod
trunk/contrib/perl/pod/perl593delta.pod
trunk/contrib/perl/pod/perl594delta.pod
trunk/contrib/perl/pod/perl595delta.pod
trunk/contrib/perl/pod/perlapio.pod
trunk/contrib/perl/pod/perlartistic.pod
trunk/contrib/perl/pod/perlbook.pod
trunk/contrib/perl/pod/perlboot.pod
trunk/contrib/perl/pod/perlbot.pod
trunk/contrib/perl/pod/perlcall.pod
trunk/contrib/perl/pod/perlcheat.pod
trunk/contrib/perl/pod/perlclib.pod
trunk/contrib/perl/pod/perlcommunity.pod
trunk/contrib/perl/pod/perlcompile.pod
trunk/contrib/perl/pod/perldata.pod
trunk/contrib/perl/pod/perldbmfilter.pod
trunk/contrib/perl/pod/perldebguts.pod
trunk/contrib/perl/pod/perldebtut.pod
trunk/contrib/perl/pod/perldebug.pod
trunk/contrib/perl/pod/perldelta.pod
trunk/contrib/perl/pod/perldiag.pod
trunk/contrib/perl/pod/perldoc.pod
trunk/contrib/perl/pod/perldsc.pod
trunk/contrib/perl/pod/perlebcdic.pod
trunk/contrib/perl/pod/perlembed.pod
trunk/contrib/perl/pod/perlfaq.pod
trunk/contrib/perl/pod/perlfaq1.pod
trunk/contrib/perl/pod/perlfaq2.pod
trunk/contrib/perl/pod/perlfaq3.pod
trunk/contrib/perl/pod/perlfaq4.pod
trunk/contrib/perl/pod/perlfaq5.pod
trunk/contrib/perl/pod/perlfaq6.pod
trunk/contrib/perl/pod/perlfaq7.pod
trunk/contrib/perl/pod/perlfaq8.pod
trunk/contrib/perl/pod/perlfaq9.pod
trunk/contrib/perl/pod/perlfilter.pod
trunk/contrib/perl/pod/perlfork.pod
trunk/contrib/perl/pod/perlform.pod
trunk/contrib/perl/pod/perlfunc.pod
trunk/contrib/perl/pod/perlgit.pod
trunk/contrib/perl/pod/perlglossary.pod
trunk/contrib/perl/pod/perlgpl.pod
trunk/contrib/perl/pod/perlguts.pod
trunk/contrib/perl/pod/perlhack.pod
trunk/contrib/perl/pod/perlhacktips.pod
trunk/contrib/perl/pod/perlhacktut.pod
trunk/contrib/perl/pod/perlhist.pod
trunk/contrib/perl/pod/perlinterp.pod
trunk/contrib/perl/pod/perlintro.pod
trunk/contrib/perl/pod/perliol.pod
trunk/contrib/perl/pod/perlipc.pod
trunk/contrib/perl/pod/perllexwarn.pod
trunk/contrib/perl/pod/perllocale.pod
trunk/contrib/perl/pod/perllol.pod
trunk/contrib/perl/pod/perlmod.pod
trunk/contrib/perl/pod/perlmodinstall.pod
trunk/contrib/perl/pod/perlmodlib.PL
trunk/contrib/perl/pod/perlmodstyle.pod
trunk/contrib/perl/pod/perlmroapi.pod
trunk/contrib/perl/pod/perlnewmod.pod
trunk/contrib/perl/pod/perlnumber.pod
trunk/contrib/perl/pod/perlobj.pod
trunk/contrib/perl/pod/perlop.pod
trunk/contrib/perl/pod/perlopentut.pod
trunk/contrib/perl/pod/perlpacktut.pod
trunk/contrib/perl/pod/perlperf.pod
trunk/contrib/perl/pod/perlpod.pod
trunk/contrib/perl/pod/perlpodspec.pod
trunk/contrib/perl/pod/perlpodstyle.pod
trunk/contrib/perl/pod/perlpolicy.pod
trunk/contrib/perl/pod/perlport.pod
trunk/contrib/perl/pod/perlpragma.pod
trunk/contrib/perl/pod/perlre.pod
trunk/contrib/perl/pod/perlreapi.pod
trunk/contrib/perl/pod/perlrebackslash.pod
trunk/contrib/perl/pod/perlrecharclass.pod
trunk/contrib/perl/pod/perlref.pod
trunk/contrib/perl/pod/perlreftut.pod
trunk/contrib/perl/pod/perlreguts.pod
trunk/contrib/perl/pod/perlrequick.pod
trunk/contrib/perl/pod/perlreref.pod
trunk/contrib/perl/pod/perlretut.pod
trunk/contrib/perl/pod/perlrun.pod
trunk/contrib/perl/pod/perlsec.pod
trunk/contrib/perl/pod/perlsource.pod
trunk/contrib/perl/pod/perlstyle.pod
trunk/contrib/perl/pod/perlsub.pod
trunk/contrib/perl/pod/perlsyn.pod
trunk/contrib/perl/pod/perlthrtut.pod
trunk/contrib/perl/pod/perltie.pod
trunk/contrib/perl/pod/perltodo.pod
trunk/contrib/perl/pod/perltooc.pod
trunk/contrib/perl/pod/perltoot.pod
trunk/contrib/perl/pod/perltrap.pod
trunk/contrib/perl/pod/perlunicode.pod
trunk/contrib/perl/pod/perlunifaq.pod
trunk/contrib/perl/pod/perluniintro.pod
trunk/contrib/perl/pod/perlunitut.pod
trunk/contrib/perl/pod/perlutil.pod
trunk/contrib/perl/pod/perlvar.pod
trunk/contrib/perl/pod/perlvms.pod
trunk/contrib/perl/pod/perlxs.pod
trunk/contrib/perl/pod/perlxstut.pod
trunk/contrib/perl/pod/roffitall
trunk/contrib/perl/pod/rofftoc
trunk/contrib/perl/pod/splitman
trunk/contrib/perl/pod/splitpod
Modified: trunk/contrib/perl/pod/Makefile.SH
===================================================================
--- trunk/contrib/perl/pod/Makefile.SH 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/Makefile.SH 2013-12-02 21:27:48 UTC (rev 6441)
@@ -55,9 +55,7 @@
$spitshell >>Makefile <<'!NO!SUBS!'
HTMLROOT = / # Change this to fix cross-references in HTML
-POD2HTML_ARGS = --htmlroot=$(HTMLROOT) \
- --podroot=.. --podpath=pod:lib:ext:vms \
- --libpods=perlfunc:perlguts:perlvar:perlrun:perlop
+POD2HTML_ARGS = --htmlroot=$(HTMLROOT) --podroot=.. --podpath=pod:lib:ext:vms
POD2HTML = ../ext/Pod-Html/pod2html
POD2MAN = ../cpan/podlators/pod2man
POD2LATEX = ../cpan/Pod-LaTeX/pod2latex
@@ -76,7 +74,7 @@
tex: $(POD2LATEX) $(TEX)
toc perltoc.pod: buildtoc
- $(PERLILIB) buildtoc --build-toc
+ $(PERLILIB) buildtoc
.SUFFIXES: .pm .pod
Property changes on: trunk/contrib/perl/pod/Makefile.SH
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/buildtoc
===================================================================
--- trunk/contrib/perl/pod/buildtoc 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/buildtoc 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,338 +1,45 @@
#!/usr/bin/perl -w
use strict;
-use vars qw($masterpodfile %Build %Targets $Verbose $Quiet %Ignore
- @Master %Readmes %Pods %Aux %Readmepods %Pragmata %Modules
- %Copies %Generated $Test);
+use vars qw($Quiet);
use File::Spec;
-use File::Find;
use FindBin;
-use Text::Tabs;
use Text::Wrap;
use Getopt::Long;
-use Carp;
no locale;
-require 5.010;
-{
+# Assumption is that we're either already being run from the top level (*nix,
+# VMS), or have absolute paths in @INC (Win32, pod/Makefile)
+BEGIN {
my $Top = File::Spec->catdir($FindBin::Bin, File::Spec->updir);
-
- sub abs_from_top {
- my $path = shift;
- return File::Spec->catdir($Top, split /\//, $path) if $path =~ s!/\z!!;
- return File::Spec->catfile($Top, split /\//, $path);
- }
+ chdir $Top or die "Can't chdir to $Top: $!";
+ require 'Porting/pod_lib.pl';
}
-$masterpodfile = abs_from_top('pod.lst');
+die "$0: Usage: $0 [--quiet]\n"
+ unless GetOptions (quiet => \$Quiet) && !@ARGV;
-# Generate any/all of these files
-# --verbose gives slightly more output
-# --quiet suppresses routine warnings
-# --build-all tries to build everything
-# --build-foo updates foo as follows
-# --showfiles shows the files to be changed
-# --test exit if perl.pod, pod.lst, MANIFEST are consistent, and regenerated
-# files are up to date, die otherwise.
+my $state = get_pod_metadata(0, sub { warn @_ if @_ }, 'pod/perltoc.pod');
-%Targets
- = (
- toc => 'pod/perltoc.pod',
- manifest => 'MANIFEST',
- perlpod => 'pod/perl.pod',
- vms => 'vms/descrip_mms.template',
- nmake => 'win32/Makefile',
- dmake => 'win32/makefile.mk',
- podmak => 'win32/pod.mak',
- # plan9 => 'plan9/mkfile'),
- unix => 'Makefile.SH',
- # TODO: add roffitall
- );
+my $found = pods_to_install();
-foreach (values %Targets) {
- $_ = abs_from_top($_);
-}
+my_die "Can't find any pods!\n" unless %$found;
-{
- my @files = keys %Targets;
- my $filesopts = join(" | ", map { "--build-$_" } "all", sort @files);
- my $showfiles;
- my %build_these;
- die <<__USAGE__
-$0: Usage: $0 [--verbose] [--showfiles] $filesopts
-__USAGE__
- unless @ARGV
- && GetOptions (verbose => \$Verbose,
- quiet => \$Quiet,
- showfiles => \$showfiles,
- test => \$Test,
- map {+"build-$_", \$build_these{$_}} @files, 'all');
- if ($build_these{all}) {
- %Build = %Targets;
- } else {
- while (my ($file, $want) = each %build_these) {
- $Build{$file} = $Targets{$file} if $want;
- }
- }
- if ($showfiles) {
- print
- join(" ",
- sort { lc $a cmp lc $b }
- map {
- my ($v, $d, $f) = File::Spec->splitpath($_);
- my @d;
- @d = defined $d ? File::Spec->splitdir($d) : ();
- shift @d if @d;
- File::Spec->catfile(@d ?
- (@d == 1 && $d[0] eq '' ? () : @d)
- : "pod", $f);
- } @Targets{@files}),
- "\n";
- exit(0);
- }
-}
+# Accumulating everything into a lexical before writing to disk dates from the
+# time when this script also provided the functionality of regen/pod_rules.pl
+# and this code was in a subroutine do_toc(). In turn, the use of a file scoped
+# lexical instead of a parameter or return value is because the code dates back
+# further still, and used *only* to create pod/perltoc.pod by printing direct
-# Don't copy these top level READMEs
-%Ignore
- = (
- micro => 1,
-# vms => 1,
- );
-
-if ($Verbose) {
- print "I'm building $_\n" foreach keys %Build;
-}
-
-open my $master, '<', $masterpodfile or die "$0: Can't open $masterpodfile: $!";
-
-my ($delta_source, $delta_target);
-
-foreach (<$master>) {
- next if /^\#/;
-
- # At least one upper case letter somewhere in the first group
- if (/^(\S+)\s(.*)/ && $1 =~ tr/h//) {
- # it's a heading
- my $flags = $1;
- $flags =~ tr/h//d;
- my %flags = (header => 1);
- $flags{toc_omit} = 1 if $flags =~ tr/o//d;
- $flags{aux} = 1 if $flags =~ tr/a//d;
- die "$0: Unknown flag found in heading line: $_" if length $flags;
- push @Master, [\%flags, $2];
-
- } elsif (/^(\S*)\s+(\S+)\s+(.*)/) {
- # it's a section
- my ($flags, $filename, $desc) = ($1, $2, $3);
-
- my %flags = (indent => 0);
- $flags{indent} = $1 if $flags =~ s/(\d+)//;
- $flags{toc_omit} = 1 if $flags =~ tr/o//d;
- $flags{aux} = 1 if $flags =~ tr/a//d;
-
- if ($flags =~ tr/D//d) {
- $flags{manifest_omit} = 1;
- $delta_source = "$filename.pod";
- }
- if ($flags =~ tr/d//d) {
- $flags{perlpod_omit} = 1;
- $delta_target = "$filename.pod";
- }
- $Generated{"$filename.pod"}++ if $flags =~ tr/g//d;
-
- if ($flags =~ tr/r//d) {
- my $readme = $filename;
- $readme =~ s/^perl//;
- $Readmepods{$filename} = $Readmes{$readme} = $desc;
- $flags{readme} = 1;
- } elsif ($flags{aux}) {
- $Aux{$filename} = $desc;
- } else {
- $Pods{$filename} = $desc;
- }
- die "$0: Unknown flag found in section line: $_" if length $flags;
- push @Master, [\%flags, $filename, $desc];
- } elsif (/^$/) {
- push @Master, undef;
- } else {
- die "$0: Malformed line: $_" if $1 =~ tr/A-Z//;
- }
-}
-if (defined $delta_source) {
- if (defined $delta_target) {
- # This way round so that keys can act as a MANIFEST skip list
- # Targets will aways be in the pod directory. Currently we can only cope
- # with sources being in the same directory.
- $Copies{$delta_target} = $delta_source;
- } else {
- die "$0: delta source defined but not target";
- }
-} elsif (defined $delta_target) {
- die "$0: delta target defined but not source";
-}
-
-close $master;
-
-# Sanity cross check
-{
- my (%disk_pods, @disk_pods);
- my (@manipods, %manipods);
- my (@manireadmes, %manireadmes);
- my (@perlpods, %perlpods);
- my (%our_pods);
-
- # Convert these to a list of filenames.
- foreach (keys %Pods, keys %Readmepods) {
- $our_pods{"$_.pod"}++;
- }
-
- opendir my $dh, abs_from_top('pod/');
- while (readdir $dh) {
- next unless /\.pod\z/;
- push @disk_pods, $_;
- ++$disk_pods{$_};
- }
-
- # Things we copy from won't be in perl.pod
- # Things we copy to won't be in MANIFEST
-
- my $filename = abs_from_top('MANIFEST');
- open my $mani, '<', $filename or die "$0: opening $filename failed: $!";
- while (<$mani>) {
- if (m!^pod/([^.]+\.pod)\s+!i) {
- push @manipods, $1;
- } elsif (m!^README\.(\S+)\s+!i) {
- next if $Ignore{$1};
- push @manireadmes, "perl$1.pod";
- }
- }
- close $mani or die $!;
- @manipods{@manipods} = @manipods;
- @manireadmes{@manireadmes} = @manireadmes;
-
- $filename = abs_from_top('pod/perl.pod');
- open my $perlpod, '<', $filename or die "$0: opening $filename failed: $!\n";
- while (<$perlpod>) {
- if (/^For ease of access, /../^\(If you're intending /) {
- if (/^\s+(perl\S*)\s+\w/) {
- push @perlpods, "$1.pod";
- }
- }
- }
- close $perlpod or die $!;
- die "$0: could not find the pod listing of perl.pod\n"
- unless @perlpods;
- @perlpods{@perlpods} = @perlpods;
-
- my @inconsistent;
- foreach my $i (sort keys %disk_pods) {
- push @inconsistent, "$0: $i exists but is unknown by buildtoc\n"
- unless $our_pods{$i};
- push @inconsistent, "$0: $i exists but is unknown by ../MANIFEST\n"
- if !$manipods{$i} && !$manireadmes{$i} && !$Copies{$i} && !$Generated{$i};
- push @inconsistent, "$0: $i exists but is unknown by perl.pod\n"
- if !$perlpods{$i} && !exists $Copies{$i};
- }
- my %BuildFiles;
- foreach my $path (values %Build) {
- (undef, undef, my $file) = File::Spec->splitpath($path);
- ++$BuildFiles{$file}
- }
-
- foreach my $i (sort keys %our_pods) {
- push @inconsistent, "$0: $i is known by buildtoc but does not exist\n"
- unless $disk_pods{$i} or $BuildFiles{$i};
- }
- foreach my $i (sort keys %manipods) {
- push @inconsistent, "$0: $i is known by ../MANIFEST but does not exist\n"
- unless $disk_pods{$i};
- push @inconsistent, "$0: $i is known by ../MANIFEST but is marked as generated\n"
- if $Generated{$i};
- }
- foreach my $i (sort keys %perlpods) {
- push @inconsistent, "$0: $i is known by perl.pod but does not exist\n"
- unless $disk_pods{$i} or $BuildFiles{$i};
- }
- if ($Test) {
- delete $Build{toc};
- printf "1..%d\n", 1 + scalar keys %Build;
- if (@inconsistent) {
- print "not ok 1\n";
- die @inconsistent
- }
- print "ok 1\n";
- }
- else {
- warn @inconsistent if @inconsistent;
- }
-}
-
-# Find all the modules
-if ($Build{toc}) {
- my @modpods;
- find \&getpods => abs_from_top('lib/');
-
- sub getpods {
- if (/\.p(od|m)$/) {
- my $file = $File::Find::name;
- return if $file =~ qr!/lib/Pod/Functions.pm\z!; # Used only by pod itself
- return if $file =~ m!(?:^|/)t/!;
- return if $file =~ m!lib/Attribute/Handlers/demo/!;
- return if $file =~ m!lib/Net/FTP/.+\.pm!; # Hi, Graham! :-)
- return if $file =~ m!lib/Math/BigInt/t/!;
- return if $file =~ m!/Devel/PPPort/[Hh]arness|lib/Devel/Harness!i;
- return if $file =~ m!XS/(?:APItest|Typemap)!;
- my $pod = $file;
- return if $pod =~ s/pm$/pod/ && -e $pod;
- unless (open my $f, '<', $_) {
- warn "$0: bogus <$file>: $!";
- system "ls", "-l", $file;
- }
- else {
- my $line;
- while ($line = <$f>) {
- if ($line =~ /^=head1\s+NAME\b/) {
- push @modpods, $file;
- return;
- }
- }
- warn "$0: $file: cannot find =head1 NAME\n" unless $Quiet;
- }
- }
- }
-
- die "$0: no pods" unless @modpods;
-
- my %done;
- for (@modpods) {
- my $name = $_;
- $name =~ s/\.p(m|od)$//;
- $name =~ s-.*?/lib/--;
- $name =~ s-/-::-g;
- next if $done{$name}++;
-
- if ($name =~ /^[a-z]/) {
- $Pragmata{$name} = $_;
- } else {
- $Modules{$name} = $_;
- }
- }
-}
-
-# OK. Now a lot of ancillary function definitions follow
-# Main program returns at "Do stuff"
-
my $OUT;
+my $roffitall;
-sub do_toc {
- my $filename = shift;
+($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
- ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
-
# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
# This file is autogenerated by buildtoc from all the other pods.
- # Edit those files and run buildtoc --build-toc to effect changes.
+ # Edit those files and run $0 to effect changes.
=head1 NAME
@@ -347,41 +54,31 @@
=head1 BASIC DOCUMENTATION
EOPOD2B
-#' make emacs happy
- # All the things in the master list that happen to be pod filenames
- foreach (grep {defined $_ && @$_ == 3 && !$_->[0]{toc_omit}} @Master) {
- podset($_->[1], abs_from_top("pod/$_->[1].pod"));
- }
+# All the things in the master list that happen to be pod filenames
+foreach (grep {!$_->[2]{toc_omit}} @{$state->{master}}) {
+ $roffitall .= " \$mandir/$_->[0].1 \\\n";
+ podset($_->[0], $_->[1]);
+}
+foreach my $type (qw(PRAGMA MODULE)) {
+ ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
- ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
+ =head1 $type DOCUMENTATION
- =head1 PRAGMA DOCUMENTATION
-
EOPOD2B
- foreach (sort keys %Pragmata) {
- podset($_, $Pragmata{$_});
- }
+ foreach my $name (sort keys %{$found->{$type}}) {
+ $roffitall .= " \$libdir/$name.3 \\\n";
+ podset($name, $found->{$type}{$name});
+ }
+}
- ($_= <<"EOPOD2B") =~ s/^\t//gm and $OUT .= $_;
+$_= <<"EOPOD2B";
-
- =head1 MODULE DOCUMENTATION
-
-EOPOD2B
-
- foreach (sort keys %Modules) {
- podset($_, $Modules{$_});
- }
-
- $_= <<"EOPOD2B";
-
-
=head1 AUXILIARY DOCUMENTATION
Here should be listed all the extra programs' documentation, but they
@@ -391,8 +88,8 @@
EOPOD2B
- $_ .= join "\n", map {"\t=item $_\n"} sort keys %Aux;
- $_ .= <<"EOPOD2B" ;
+$_ .= join "\n", map {"\t=item $_\n"} @{$state->{aux}};
+$_ .= <<"EOPOD2B" ;
=back
@@ -404,17 +101,82 @@
EOPOD2B
- s/^\t//gm;
- $OUT .= "$_\n";
+s/^\t//gm;
+$OUT .= "$_\n";
- $OUT =~ s/\n\s+\n/\n\n/gs;
- $OUT =~ s/\n{3,}/\n\n/g;
+$OUT =~ s/\n\s+\n/\n\n/gs;
+$OUT =~ s/\n{3,}/\n\n/g;
- $OUT =~ s/([^\n]+)/wrap('', '', $1)/ge;
+$OUT =~ s/([^\n]+)/wrap('', '', $1)/ge;
- return $OUT;
-}
+write_or_die('pod/perltoc.pod', $OUT);
+write_or_die('pod/roffitall', <<'EOH' . $roffitall . <<'EOT');
+#!/bin/sh
+#
+# Usage: roffitall [-nroff|-psroff|-groff]
+#
+# Authors: Tom Christiansen, Raphael Manfredi
+
+me=roffitall
+tmp=.
+
+if test -f ../config.sh; then
+ . ../config.sh
+fi
+
+mandir=$installman1dir
+libdir=$installman3dir
+
+test -d $mandir || mandir=/usr/new/man/man1
+test -d $libdir || libdir=/usr/new/man/man3
+
+case "$1" in
+-nroff) cmd="nroff -man"; ext='txt';;
+-psroff) cmd="psroff -t"; ext='ps';;
+-groff) cmd="groff -man"; ext='ps';;
+*)
+ echo "Usage: roffitall [-nroff|-psroff|-groff]" >&2
+ exit 1
+ ;;
+esac
+
+toroff=`
+ echo \
+EOH
+ | perl -ne 'map { -r && print "$_ " } split'`
+
+ # Bypass internal shell buffer limit -- can't use case
+ if perl -e '$a = shift; exit($a =~ m|/|)' $toroff; then
+ echo "$me: empty file list -- did you run install?" >&2
+ exit 1
+ fi
+
+ #psroff -t -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.ps 2>$tmp/PerlTOC.raw
+ #nroff -man -rC1 -rD1 -rF1 > $tmp/PerlDoc.txt 2>$tmp/PerlTOC.nr.raw
+
+ # First, create the raw data
+ run="$cmd -rC1 -rD1 -rF1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
+ echo "$me: running $run"
+ eval $run $toroff
+
+ #Now create the TOC
+ echo "$me: parsing TOC"
+ perl rofftoc $tmp/PerlTOC.$ext.raw > $tmp/PerlTOC.tmp.man
+ run="$cmd $tmp/PerlTOC.tmp.man >$tmp/PerlTOC.$ext"
+ echo "$me: running $run"
+ eval $run
+
+ # Finally, recreate the Doc, without the blank page 0
+ run="$cmd -rC1 -rD1 >$tmp/PerlDoc.$ext 2>$tmp/PerlTOC.$ext.raw"
+ echo "$me: running $run"
+ eval $run $toroff
+ rm -f $tmp/PerlTOC.tmp.man $tmp/PerlTOC.$ext.raw
+ echo "$me: leaving you with $tmp/PerlDoc.$ext and $tmp/PerlTOC.$ext"
+EOT
+
+exit(0);
+
# Below are all the auxiliary routines for generating perltoc.pod
my ($inhead1, $inhead2, $initem);
@@ -422,10 +184,25 @@
sub podset {
my ($pod, $file) = @_;
+ open my $fh, '<', $file or my_die "Can't open file '$file' for $pod: $!";
+
+ local *_;
+ my $found_pod;
+ while (<$fh>) {
+ if (/^=head1\s+NAME\b/) {
+ ++$found_pod;
+ last;
+ }
+ }
+
+ unless ($found_pod) {
+ warn "$0: NOTE: cannot find '=head1 NAME' in:\n $file\n" unless $Quiet;
+ return;
+ }
+
+ seek $fh, 0, 0 or my_die "Can't rewind file '$file': $!";
local $/ = '';
- open my $fh, '<', $file or die "Can't open file '$file' for $pod: $!";
-
while(<$fh>) {
tr/\015//d;
if (s/^=head1 (NAME)\s*/=head2 /) {
@@ -433,7 +210,7 @@
$OUT .= "\n\n=head2 ";
$_ = <$fh>;
# Remove svn keyword expansions from the Perl FAQ
- s/ \(\$Revision: 1.1.1.3 $\)//g;
+ s/ \(\$Revision: \d+ \$\)//g;
if ( /^\s*\Q$pod\E\b/ ) {
s/$pod\.pm/$pod/; # '.pm' in NAME !?
} else {
@@ -496,283 +273,9 @@
$initem = 0;
}
-# End of original buildtoc. From here on are routines to generate new sections
-# for and inplace edit other files
-
-sub generate_perlpod {
- my @output;
- my $maxlength = 0;
- foreach (@Master) {
- my $flags = $_->[0];
- next if $flags->{aux};
- next if $flags->{perlpod_omit};
-
- if (@$_ == 2) {
- # Heading
- push @output, "=head2 $_->[1]\n";
- } elsif (@$_ == 3) {
- # Section
- my $start = " " x (4 + $flags->{indent}) . $_->[1];
- $maxlength = length $start if length ($start) > $maxlength;
- push @output, [$start, $_->[2]];
- } elsif (@$_ == 0) {
- # blank line
- push @output, "\n";
- } else {
- die "$0: Illegal length " . scalar @$_;
- }
- }
- # want at least 2 spaces padding
- $maxlength += 2;
- $maxlength = ($maxlength + 3) & ~3;
- # sprintf gives $1.....$2 where ... are spaces:
- return unexpand (map {ref $_ ? sprintf "%-${maxlength}s%s\n", @$_ : $_}
- @output);
-}
-
-
-sub generate_manifest {
- # Annoyingly, unexpand doesn't consider it good form to replace a single
- # space before a tab with a tab
- # Annoyingly (2) it returns read only values.
- my @temp = unexpand (map {sprintf "%-32s%s", @$_} @_);
- map {s/ \t/\t\t/g; $_} @temp;
-}
-sub generate_manifest_pod {
- generate_manifest map {["pod/$_.pod", $Pods{$_}]}
- sort grep {!$Copies{"$_.pod"}} grep {!$Generated{"$_.pod"}} keys %Pods;
-}
-sub generate_manifest_readme {
- generate_manifest sort {$a->[0] cmp $b->[0]}
- ["README.vms", "Notes about installing the VMS port"],
- map {["README.$_", $Readmes{$_}]} keys %Readmes;
-}
-
-sub generate_roffitall {
- (map ({"\t\$maindir/$_.1\t\\"}sort keys %Pods),
- "\t\t\\",
- map ({"\t\$maindir/$_.1\t\\"}sort keys %Aux),
- "\t\t\\",
- map ({"\t\$libdir/$_.3\t\\"}sort keys %Pragmata),
- "\t\t\\",
- map ({"\t\$libdir/$_.3\t\\"}sort keys %Modules),
- )
-}
-
-sub generate_descrip_mms_1 {
- local $Text::Wrap::columns = 150;
- my $count = 0;
- my @lines = map {"pod" . $count++ . " = $_"}
- split /\n/, wrap('', '', join " ", map "[.lib.pods]$_.pod",
- sort keys %Pods, keys %Readmepods);
- @lines, "pod = " . join ' ', map {"\$(pod$_)"} 0 .. $count - 1;
-}
-
-sub generate_descrip_mms_2 {
- map {<<"SNIP"}
-[.lib.pods]$_.pod : [.pod]$_.pod
- \@ If F\$Search("[.lib]pods.dir").eqs."" Then Create/Directory [.lib.pods]
- Copy/NoConfirm/Log \$(MMS\$SOURCE) [.lib.pods]
-SNIP
- sort keys %Pods, keys %Readmepods;
-}
-
-sub generate_nmake_1 {
- # XXX Fix this with File::Spec
- (map {sprintf "\tcopy ..\\README.%-8s ..\\pod\\perl$_.pod\n", $_}
- sort keys %Readmes),
- (map {"\tcopy ..\\pod\\$Copies{$_} ..\\pod\\$_\n"} sort keys %Copies);
-}
-
-# This doesn't have a trailing newline
-sub generate_nmake_2 {
- # Spot the special case
- local $Text::Wrap::columns = 76;
- my $line = wrap ("\t ", "\t ",
- join " ", sort keys %Copies, keys %Generated,
- map {"perl$_.pod"} keys %Readmes);
- $line =~ s/$/ \\/mg;
- $line =~ s/ \\$//;
- $line;
-}
-
-sub generate_pod_mak {
- my $variable = shift;
- my @lines;
- my $line = join "\\\n", "\U$variable = ",
- map {"\t$_.$variable\t"} sort keys %Pods;
- # Special case
- $line =~ s/.*perltoc.html.*\n//m;
- $line;
-}
-
-sub verify_contiguous {
- my ($name, $content, $what) = @_;
- my $sections = () = $content =~ m/\0+/g;
- croak("$0: $name contains no $what") if $sections < 1;
- croak("$0: $name contains discontiguous $what") if $sections > 1;
-}
-
-sub do_manifest {
- my ($name, $prev) = @_;
- my @manifest =
- grep {! m!^pod/[^.]+\.pod.*!}
- grep {! m!^README\.(\S+)! || $Ignore{$1}} split "\n", $prev;
- join "\n", (
- # Dictionary order - fold and handle non-word chars as nothing
- map { $_->[0] }
- sort { $a->[1] cmp $b->[1] || $a->[0] cmp $b->[0] }
- map { my $f = lc $_; $f =~ s/[^a-z0-9\s]//g; [ $_, $f ] }
- @manifest,
- &generate_manifest_pod(),
- &generate_manifest_readme()), '';
-}
-
-sub do_nmake {
- my ($name, $makefile) = @_;
- $makefile =~ s/^\tcopy \.\.\\README.*\n/\0/gm;
- verify_contiguous($name, $makefile, 'README copies');
- # Now remove the other copies that follow
- 1 while $makefile =~ s/\0\tcopy .*\n/\0/gm;
- $makefile =~ s/\0+/join ("", &generate_nmake_1)/se;
-
- $makefile =~ s{(-cd \$\(PODDIR\) && del /f[^\n]+).*?(-cd \.\.\\utils && del /f)}
- {"$1\n" . &generate_nmake_2."\n\t$2"}se;
- $makefile;
-}
-
-# shut up used only once warning
-*do_dmake = *do_dmake = \&do_nmake;
-
-sub do_perlpod {
- my ($name, $pod) = @_;
-
- unless ($pod =~ s{(For\ ease\ of\ access,\ .*\n)
- (?:\s+[a-z]{4,}.*\n # fooo
- |=head.*\n # =head foo
- |\s*\n # blank line
- )+
- }
- {$1 . join "", &generate_perlpod}mxe) {
- die "$0: Failed to insert amendments in do_perlpod";
- }
- $pod;
-}
-
-sub do_podmak {
- my ($name, $body) = @_;
- foreach my $variable (qw(pod man html tex)) {
- die "$0: could not find $variable in $name"
- unless $body =~ s{\n\U$variable\E = (?:[^\n]*\\\n)*[^\n]*}
- {"\n" . generate_pod_mak ($variable)}se;
- }
- $body;
-}
-
-sub do_vms {
- my ($name, $makefile) = @_;
- $makefile =~ s/\npod\d* =[^\n]*/\0/gs;
- verify_contiguous($name, $makefile, 'pod assignments');
- $makefile =~ s/\0+/join "\n", '', &generate_descrip_mms_1/se;
-
- die "$0: $name contains NUL bytes" if $makefile =~ /\0/;
-
-# Looking for the macro defining the current perldelta:
-#PERLDELTA_CURRENT = [.pod]perl5139delta.pod
-
- $makefile =~ s/\nPERLDELTA_CURRENT\s+=\s+\Q[.pod]perl\E\d+delta\.pod\n
- /\0/sx;
- verify_contiguous($name, $makefile, 'current perldelta macro');
- $makefile =~ s/\0+/join "\n", '', "PERLDELTA_CURRENT = [.pod]$delta_target", ''/se;
-
-# Looking for rules like this
-# [.lib.pods]perl.pod : [.pod]perl.pod
-# @ If F$Search("[.lib]pods.dir").eqs."" Then Create/Directory [.lib.pods]
-# Copy/NoConfirm/Log $(MMS$SOURCE) [.lib.pods]
-
- $makefile =~ s/\n\Q[.lib.pods]\Eperl[^\n\.]*\.pod[^\n]+\n
- [^\n]+\n # Another line
- [^\n]+\Q[.lib.pods]\E\n # ends [.lib.pods]
- /\0/gsx;
- verify_contiguous($name, $makefile, 'copy rules');
- $makefile =~ s/\0+/join "\n", '', &generate_descrip_mms_2/se;
-
- $makefile;
-}
-
-sub do_unix {
- my ($name, $makefile_SH) = @_;
-
- $makefile_SH =~ s{^(perltoc_pod_prereqs = extra.pods).*}
- {join ' ', $1, map "pod/$_",
- sort keys %Copies, grep {!/perltoc/} keys %Generated
- }mge;
-
-# pod/perl511delta.pod: pod/perldelta.pod
-# cd pod && $(LNS) perldelta.pod perl511delta.pod
-
- $makefile_SH =~ s!(
-pod/perl[a-z0-9_]+\.pod: pod/perl[a-z0-9_]+\.pod
- \$\(LNS\) perl[a-z0-9_]+\.pod pod/perl[a-z0-9_]+\.pod
-)+!\0!gm;
-
- verify_contiguous($name, $makefile_SH, 'copy rules');
-
- my @copy_rules = map "
-pod/$_: pod/$Copies{$_}
- \$(LNS) $Copies{$_} pod/$_
-", keys %Copies;
-
- $makefile_SH =~ s/\0+/join '', @copy_rules/se;
- $makefile_SH;
-
-}
-
-# Do stuff
-
-my $built;
-while (my ($target, $name) = each %Targets) {
- print "Working on target $target\n" if $Verbose;
- next unless $Build{$target};
- $built++;
- my ($orig, $mode);
- print "Now processing $name\n" if $Verbose;
- if ($target ne "toc") {
- local $/;
- open my $thing, '<', $name or die "Can't open $name: $!";
- binmode $thing;
- $orig = <$thing>;
- die "$0: $name contains NUL bytes" if $orig =~ /\0/;
- }
-
- my $new = do {
- no strict 'refs';
- &{"do_$target"}($target, $orig);
- };
-
- if (defined $orig) {
- if ($new eq $orig) {
- if ($Test) {
- printf "ok %d # $name is up to date\n", $built + 1;
- } elsif ($Verbose) {
- print "Was not modified\n";
- }
- next;
- } elsif ($Test) {
- printf "not ok %d # $name is up to date\n", $built + 1;
- next;
- }
- $mode = (stat $name)[2] // die "$0: Can't stat $name: $!";
- rename $name, "$name.old" or die "$0: Can't rename $name to $name.old: $!";
- }
-
- open my $thing, '>', $name or die "$0: Can't open $name for writing: $!";
- binmode $thing;
- print $thing $new or die "$0: print to $name failed: $!";
- close $thing or die "$0: close $name failed: $!";
- if (defined $mode) {
- chmod $mode & 0777, $name or die "$0: can't chmod $mode $name: $!";
- }
-}
-
-warn "$0: was not instructed to build anything\n" unless $built || $Test;
+# Local variables:
+# cperl-indent-level: 4
+# indent-tabs-mode: nil
+# End:
+#
+# ex: set ts=8 sts=4 sw=4 et:
Property changes on: trunk/contrib/perl/pod/buildtoc
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/checkpods.PL (from rev 6437, vendor/perl/5.18.1/pod/checkpods.PL)
===================================================================
--- trunk/contrib/perl/pod/checkpods.PL (rev 0)
+++ trunk/contrib/perl/pod/checkpods.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,85 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+ eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+ if \$running_under_some_shell;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+# From roderick at gate.netThu Sep 5 17:19:30 1996
+# Date: Thu, 05 Sep 1996 00:11:22 -0400
+# From: Roderick Schertler <roderick at gate.net>
+# To: perl5-porters at africa.nicoh.com
+# Subject: POD lines with only spaces
+#
+# There are some places in the documentation where a POD directive is
+# ignored because the line before it contains whitespace (and so the
+# directive doesn't start a paragraph). This patch adds a way to check
+# for these to the pod Makefile (though it isn't made part of the build
+# process, which would be a good idea), and fixes those places where the
+# problem currently exists.
+#
+# Version 1.00 Original.
+# Version 1.01 Andy Dougherty <doughera at lafayette.edu>
+# Trivial modifications to output format for easier auto-parsing
+# Broke it out as a separate function to avoid nasty
+# Make/Shell/Perl quoting problems, and also to make it easier
+# to grow. Someone will probably want to rewrite in terms of
+# some sort of Pod::Checker module. Or something. Consider this
+# a placeholder for the future.
+# Version 1.02 Roderick Schertler <roderick at argon.org>
+# Check for pod directives following any kind of unempty line, not
+# just lines of whitespace.
+
+ at directive = qw(head1 head2 item over back cut pod for begin end);
+ at directive{@directive} = (1) x @directive;
+
+$exit = $last_unempty = 0;
+while (<>) {
+ s/(\012|\015\012|\015)$//;
+ if (/^=(\S+)/ && $directive{$1} && $last_unempty) {
+ printf "%s: line %5d, no blank line preceding directive =%s\n",
+ $ARGV, $., $1;
+ $exit = 1;
+ }
+ $last_unempty = ($_ ne '');
+ if (eof) {
+ close(ARGV);
+ $last_unempty = 0;
+ }
+}
+exit $exit
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Modified: trunk/contrib/perl/pod/perl.pod
===================================================================
--- trunk/contrib/perl/pod/perl.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -15,6 +15,8 @@
S<[ B<-i>[I<extension>] ]>
S<[ [B<-e>|B<-E>] I<'command'> ] [ B<--> ] [ I<programfile> ] [ I<argument> ]...>
+For more information on these options, you can run C<perldoc perlrun>.
+
=head1 GETTING HELP
The F<perldoc> program gives you access to all the documentation that comes
@@ -28,10 +30,29 @@
For ease of access, the Perl manual has been split up into several sections.
+=begin buildtoc
+
+# This section is parsed by Porting/pod_lib.pl for use by pod/buildtoc etc
+
+flag =g perluniprops perlmodlib perlapi perlintern
+flag =go perltoc
+flag =ro perlcn perljp perlko perltw
+flag = perlvms
+
+path perlfaq.* cpan/perlfaq/lib/
+path perlglossary cpan/perlfaq/lib/
+path perlxs(?:tut|typemap)? dist/ExtUtils-ParseXS/lib/
+path perldoc cpan/Pod-Perldoc/lib/
+
+aux a2p c2ph h2ph h2xs perlbug pl2pm pod2html pod2man s2p splain xsubpp
+
+=end buildtoc
+
=head2 Overview
perl Perl overview (this section)
perlintro Perl introduction for beginners
+ perlrun Perl execution and options
perltoc Perl documentation table of contents
=head2 Tutorials
@@ -43,10 +64,7 @@
perlrequick Perl regular expressions quick start
perlretut Perl regular expressions tutorial
- perlboot Perl OO tutorial for beginners
- perltoot Perl OO tutorial, part 1
- perltooc Perl OO tutorial, part 2
- perlbot Perl OO tricks and examples
+ perlootut Perl OO tutorial for beginners
perlperf Perl Performance and Optimization Techniques
@@ -79,7 +97,6 @@
perlpod Perl plain old documentation
perlpodspec Perl plain old documentation format specification
perlpodstyle Perl POD style guide
- perlrun Perl execution and options
perldiag Perl diagnostic messages
perllexwarn Perl warnings and their control
perldebug Perl debugging
@@ -105,7 +122,7 @@
perluniintro Perl Unicode introduction
perlunicode Perl Unicode support
perlunifaq Perl Unicode FAQ
- perluniprops Index of Unicode Version 6.0.0 properties in Perl
+ perluniprops Index of Unicode properties in Perl
perlunitut Perl Unicode tutorial
perlebcdic Considerations for running Perl on EBCDIC platforms
@@ -120,10 +137,10 @@
perlutil utilities packaged with the Perl distribution
- perlcompile Perl compiler suite intro
-
perlfilter Perl source filters
+ perldtrace Perl's support for DTrace
+
perlglossary Perl Glossary
=head2 Internals and C Language Interface
@@ -132,6 +149,7 @@
perldebguts Perl debugging guts and tips
perlxstut Perl XS tutorial
perlxs Perl XS application programming interface
+ perlxstypemap Perl XS C/Perl type conversion tools
perlclib Internal replacements for standard C library functions
perlguts Perl internal functions for those doing extensions
perlcall Perl calling conventions from C
@@ -146,7 +164,7 @@
perlhack Perl hackers guide
perlsource Guide to the Perl source tree
- perlinterp Overview of the Perl intepreter source and how it works
+ perlinterp Overview of the Perl interpreter source and how it works
perlhacktut Walk through the creation of a simple C code patch
perlhacktips Tips for Perl core C code hacking
perlpolicy Perl development policies
@@ -156,44 +174,29 @@
perlbook Perl book information
perlcommunity Perl community information
- perltodo Perl things to do
perldoc Look up Perl documentation in Pod format
perlhist Perl history records
perldelta Perl changes since previous version
+ perl5180delta Perl changes in version 5.18.0
+ perl5161delta Perl changes in version 5.16.1
+ perl5162delta Perl changes in version 5.16.2
+ perl5163delta Perl changes in version 5.16.3
+ perl5160delta Perl changes in version 5.16.0
+ perl5144delta Perl changes in version 5.14.4
+ perl5143delta Perl changes in version 5.14.3
+ perl5142delta Perl changes in version 5.14.2
perl5141delta Perl changes in version 5.14.1
perl5140delta Perl changes in version 5.14.0
- perl51311delta Perl changes in version 5.13.11
- perl51310delta Perl changes in version 5.13.10
- perl5139delta Perl changes in version 5.13.9
- perl5138delta Perl changes in version 5.13.8
- perl5137delta Perl changes in version 5.13.7
- perl5136delta Perl changes in version 5.13.6
- perl5135delta Perl changes in version 5.13.5
- perl5134delta Perl changes in version 5.13.4
- perl5133delta Perl changes in version 5.13.3
- perl5132delta Perl changes in version 5.13.2
- perl5131delta Perl changes in version 5.13.1
- perl5130delta Perl changes in version 5.13.0
+ perl5125delta Perl changes in version 5.12.5
+ perl5124delta Perl changes in version 5.12.4
perl5123delta Perl changes in version 5.12.3
perl5122delta Perl changes in version 5.12.2
perl5121delta Perl changes in version 5.12.1
perl5120delta Perl changes in version 5.12.0
- perl5115delta Perl changes in version 5.11.5
- perl5114delta Perl changes in version 5.11.4
- perl5113delta Perl changes in version 5.11.3
- perl5112delta Perl changes in version 5.11.2
- perl5111delta Perl changes in version 5.11.1
- perl5110delta Perl changes in version 5.11.0
perl5101delta Perl changes in version 5.10.1
perl5100delta Perl changes in version 5.10.0
- perl595delta Perl changes in version 5.9.5
- perl594delta Perl changes in version 5.9.4
- perl593delta Perl changes in version 5.9.3
- perl592delta Perl changes in version 5.9.2
- perl591delta Perl changes in version 5.9.1
- perl590delta Perl changes in version 5.9.0
perl589delta Perl changes in version 5.8.9
perl588delta Perl changes in version 5.8.8
perl587delta Perl changes in version 5.8.7
@@ -204,20 +207,20 @@
perl582delta Perl changes in version 5.8.2
perl581delta Perl changes in version 5.8.1
perl58delta Perl changes in version 5.8.0
- perl573delta Perl changes in version 5.7.3
- perl572delta Perl changes in version 5.7.2
- perl571delta Perl changes in version 5.7.1
- perl570delta Perl changes in version 5.7.0
perl561delta Perl changes in version 5.6.1
perl56delta Perl changes in version 5.6
perl5005delta Perl changes in version 5.005
perl5004delta Perl changes in version 5.004
+ perlexperiment A listing of experimental features in Perl
+
perlartistic Perl Artistic License
perlgpl GNU General Public License
=head2 Language-Specific
+=for buildtoc flag +r
+
perlcn Perl for Simplified Chinese (in EUC-CN)
perljp Perl for Japanese (in EUC-JP)
perlko Perl for Korean (in EUC-KR)
@@ -227,13 +230,11 @@
perlaix Perl notes for AIX
perlamiga Perl notes for AmigaOS
- perlbeos Perl notes for BeOS
perlbs2000 Perl notes for POSIX-BC BS2000
perlce Perl notes for WinCE
perlcygwin Perl notes for Cygwin
perldgux Perl notes for DG/UX
perldos Perl notes for DOS
- perlepoc Perl notes for EPOC
perlfreebsd Perl notes for FreeBSD
perlhaiku Perl notes for Haiku
perlhpux Perl notes for HP-UX
@@ -242,7 +243,6 @@
perllinux Perl notes for Linux
perlmacos Perl notes for Mac OS (Classic)
perlmacosx Perl notes for Mac OS X
- perlmpeix Perl notes for MPE/iX
perlnetware Perl notes for NetWare
perlopenbsd Perl notes for OpenBSD
perlos2 Perl notes for OS/2
@@ -254,19 +254,35 @@
perlsolaris Perl notes for Solaris
perlsymbian Perl notes for Symbian
perltru64 Perl notes for Tru64
- perluts Perl notes for UTS
- perlvmesa Perl notes for VM/ESA
perlvms Perl notes for VMS
perlvos Perl notes for Stratus VOS
perlwin32 Perl notes for Windows
+=for buildtoc flag -r
+=head2 Stubs for Deleted Documents
+
+ perlboot
+ perlbot
+ perltodo
+ perltooc
+ perltoot
+
+=for buildtoc __END__
+
On a Unix-like system, these documentation files will usually also be
available as manpages for use with the F<man> program.
+Some documentation is not available as man pages, so if a
+cross-reference is not found by man, try it with L<perldoc>. Perldoc can
+also take you directly to documentation for functions (with the B<-f>
+switch). See C<perldoc --help> (or C<perldoc perldoc> or C<man perldoc>)
+for other helpful options L<perldoc> has to offer.
+
In general, if something strange has gone wrong with your program and you're
-not sure where you should look for help, try the B<-w> switch first. It will
-often point out exactly where the trouble is.
+not sure where you should look for help, try making your code comply with
+B<use strict> and B<use warnings>. These will often point out exactly
+where the trouble is.
=head1 DESCRIPTION
@@ -281,110 +297,23 @@
from quick "one-liners" to full-scale application development.
The language is intended to be practical (easy to use, efficient,
-complete) rather than beautiful (tiny, elegant, minimal).
+complete) rather than beautiful (tiny, elegant, minimal). It combines
+(in the author's opinion, anyway) some of the best features of B<sed>,
+B<awk>, and B<sh>, making it familiar and easy to use for Unix users to
+whip up quick solutions to annoying problems. Its general-purpose
+programming facilities support procedural, functional, and
+object-oriented programming paradigms, making Perl a comfortable
+language for the long haul on major projects, whatever your bent.
-Perl combines (in the author's opinion, anyway) some of the best
-features of C, B<sed>, B<awk>, and B<sh>, so people familiar with
-those languages should have little difficulty with it. (Language
-historians will also note some vestiges of B<csh>, Pascal, and even
-BASIC-PLUS.) Expression syntax corresponds closely to C
-expression syntax. Unlike most Unix utilities, Perl does not
-arbitrarily limit the size of your data--if you've got the memory,
-Perl can slurp in your whole file as a single string. Recursion is of
-unlimited depth. And the tables used by hashes (sometimes called
-"associative arrays") grow as necessary to prevent degraded
-performance. Perl can use sophisticated pattern matching techniques to
-scan large amounts of data quickly. Although optimized for
-scanning text, Perl also has many excellent tools for slicing
-and dicing binary data.
+Perl's roots in text processing haven't been forgotten over the years.
+It still boasts some of the most powerful regular expressions to be
+found anywhere, and its support for Unicode text is world-class. It
+handles all kinds of structured text, too, through an extensive
+collection of extensions. Those libraries, collected in the CPAN,
+provide ready-made solutions to an astounding array of problems. When
+they haven't set the standard themselves, they steal from the best
+-- just like Perl itself.
-But wait, there's more...
-
-Begun in 1993 (see L<perlhist>), Perl version 5 is nearly a complete
-rewrite that provides the following additional benefits:
-
-=over 4
-
-=item *
-
-modularity and reusability using innumerable modules
-
-Described in L<perlmod>, L<perlmodlib>, and L<perlmodinstall>.
-
-=item *
-
-embeddable and extensible
-
-Described in L<perlembed>, L<perlxstut>, L<perlxs>, L<perlcall>,
-L<perlguts>, and L<xsubpp>.
-
-=item *
-
-roll-your-own magic variables (including multiple simultaneous DBM
-implementations)
-
-Described in L<perltie> and L<AnyDBM_File>.
-
-=item *
-
-subroutines can now be overridden, autoloaded, and prototyped
-
-Described in L<perlsub>.
-
-=item *
-
-arbitrarily nested data structures and anonymous functions
-
-Described in L<perlreftut>, L<perlref>, L<perldsc>, and L<perllol>.
-
-=item *
-
-object-oriented programming
-
-Described in L<perlobj>, L<perlboot>, L<perltoot>, L<perltooc>,
-and L<perlbot>.
-
-=item *
-
-support for light-weight processes (threads)
-
-Described in L<perlthrtut> and L<threads>.
-
-=item *
-
-support for Unicode, internationalization, and localization
-
-Described in L<perluniintro>, L<perllocale> and L<Locale::Maketext>.
-
-=item *
-
-lexical scoping
-
-Described in L<perlsub>.
-
-=item *
-
-regular expression enhancements
-
-Described in L<perlre>, with additional examples in L<perlop>.
-
-=item *
-
-enhanced debugger and interactive Perl environment,
-with integrated editor support
-
-Described in L<perldebtut>, L<perldebug> and L<perldebguts>.
-
-=item *
-
-POSIX 1003.1 compliant library
-
-Described in L<POSIX>.
-
-=back
-
-Okay, that's I<definitely> enough hype.
-
=head1 AVAILABILITY
Perl is available for most operating systems, including virtually
@@ -417,9 +346,14 @@
=head1 DIAGNOSTICS
-The C<use warnings> pragma (and the B<-w> switch) produces some
-lovely diagnostics.
+Using the C<use strict> pragma ensures that all variables are properly
+declared and prevents other misuses of legacy Perl features.
+The C<use warnings> pragma produces some lovely diagnostics. One can
+also use the B<-w> flag, but its use is normally discouraged, because
+it gets applied to all executed Perl code, including that not under
+your control.
+
See L<perldiag> for explanations of all Perl's diagnostics. The C<use
diagnostics> pragma automatically turns Perl's normally terse warnings
and errors into these longer forms.
@@ -432,12 +366,12 @@
Setuid scripts have additional constraints that can produce error
messages such as "Insecure dependency". See L<perlsec>.
-Did we mention that you should definitely consider using the B<-w>
-switch?
+Did we mention that you should definitely consider using the B<use warnings>
+pragma?
=head1 BUGS
-The B<-w> switch is not mandatory.
+The behavior implied by the B<use warnings> pragma is not mandatory.
Perl is at the mercy of your machine's definitions of various
operations such as type casting, atof(), and floating-point
Property changes on: trunk/contrib/perl/pod/perl.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5004delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5004delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5004delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -753,7 +753,7 @@
The resulting perl can be used under Windows 95 (if it
is installed in the same directory locations as it got installed
in Windows NT). This port includes support for perl extension
-building tools like L<MakeMaker> and L<h2xs>, so that many extensions
+building tools like L<ExtUtils::MakeMaker> and L<h2xs>, so that many extensions
available on the Comprehensive Perl Archive Network (CPAN) can now be
readily built under Windows NT. See http://www.perl.com/ for more
information on CPAN and F<README.win32> in the perl distribution for more
Property changes on: trunk/contrib/perl/pod/perl5004delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5005delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5005delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5005delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -509,7 +509,7 @@
MiNT is now supported. See F<README.mint>.
-MPE/iX is now supported. See F<README.mpeix>.
+MPE/iX is now supported. See README.mpeix.
MVS (aka OS390, aka Open Edition) is now supported. See F<README.os390>
(installed as L<perlos390> on some systems).
@@ -523,7 +523,7 @@
See F<README.win32>, aka L<perlwin32>.
VMS configuration system has been rewritten. See F<README.vms> (installed
-as L<README_vms> on some systems).
+as F<README_vms> on some systems).
The hints files for most Unix platforms have seen incremental improvements.
@@ -722,7 +722,7 @@
To silently interpret it as the Perl operator, use the C<CORE::> prefix
on the operator (e.g. C<CORE::log($x)>) or by declaring the subroutine
-to be an object method (see L<attrs>).
+to be an object method (see L</attrs>).
=item Bad index while coercing array into hash
Property changes on: trunk/contrib/perl/pod/perl5005delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5100delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5100delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5100delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -844,7 +844,7 @@
=item *
C<Archive::Extract> is a generic archive extraction mechanism
-for F<.tar> (plain, gziped or bzipped) or F<.zip> files.
+for F<.tar> (plain, gzipped or bzipped) or F<.zip> files.
=item *
Property changes on: trunk/contrib/perl/pod/perl5100delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5101delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5101delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5101delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1751,7 +1751,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for
Property changes on: trunk/contrib/perl/pod/perl5101delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5110delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5110delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5110delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5110delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5111delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5111delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5111delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5111delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5112delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5112delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5112delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5112delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5113delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5113delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5113delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5113delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5114delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5114delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5114delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5114delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5115delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5115delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5115delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5115delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5120delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5120delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5120delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -116,7 +116,7 @@
Extension modules can now cleanly hook into the Perl parser to define
new kinds of keyword-headed expression and compound statement. The
syntax following the keyword is defined entirely by the extension. This
-allow a completely non-Perl sublanguage to be parsed inline, with the
+allows a completely non-Perl sublanguage to be parsed inline, with the
correct ops cleanly generated.
See L<perlapi/PL_keyword_plugin> for the mechanism. The Perl core
@@ -456,7 +456,6 @@
C<Module::CoreList> no longer contains the C<%:patchlevel> hash.
-
=item *
C<length undef> now returns undef.
@@ -529,7 +528,6 @@
C<suidperl> is no longer part of Perl. It used to provide a mechanism to
emulate setuid permission bits on systems that don't support it properly.
-
=item Use of C<:=> to mean an empty attribute list
An accident of Perl's parser meant that these constructions were all
@@ -561,7 +559,6 @@
pass import arguments to a C<use UNIVERSAL> statement will result in a
deprecation warning.
-
=item Use of "goto" to jump into a construct
Using C<goto> to jump from an outer scope into an inner scope is now
@@ -1433,7 +1430,6 @@
=over
-
=item *
The various large F<Changes*> files (which listed every change made
@@ -1447,7 +1443,6 @@
interacting with the old Perforce-based repository, which is now obsolete.
Information still relevant has been moved to L<perlrepository>.
-
=item *
The syntax C<unless (EXPR) BLOCK else BLOCK> is now documented as valid,
@@ -1455,7 +1450,6 @@
BLOCK>, although actually using the latter may not be the best idea for
the readability of your source code.
-
=item *
Documented -X overloading.
@@ -2106,7 +2100,6 @@
could be caused by buggy XS code, and at this point recovery is not
possible.
-
=item *
The fatal error C<Malformed UTF-8 returned by \N> is now produced if the
@@ -3176,7 +3169,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for
Property changes on: trunk/contrib/perl/pod/perl5120delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5121delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5121delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5121delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -210,12 +210,10 @@
See also: L<http://rt.cpan.org/Public/Bug/Display.html?id=55049>
-
=item *
utf8::is_utf8 now respects GMAGIC (e.g. $1)
-
=item *
XS code using C<fputc()> or C<fputs()>: on Windows could cause an error
@@ -390,7 +388,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for
Property changes on: trunk/contrib/perl/pod/perl5121delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5122delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5122delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5122delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -325,7 +325,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for
Property changes on: trunk/contrib/perl/pod/perl5122delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5123delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5123delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5123delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -96,7 +96,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for
Property changes on: trunk/contrib/perl/pod/perl5123delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perl5124delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5124delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5124delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5124delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,108 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5124delta - what is new for perl v5.12.4
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.12.3 release and
+the 5.12.4 release.
+
+If you are upgrading from an earlier release such as 5.12.2, first read
+L<perl5123delta>, which describes differences between 5.12.2
+and 5.12.3. The major changes made in 5.12.0 are described in L<perl5120delta>.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.12.3. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Selected Bug Fixes
+
+When strict "refs" mode is off, C<%{...}> in rvalue context returns
+C<undef> if its argument is undefined. An optimisation introduced in Perl
+5.12.0 to make C<keys %{...}> faster when used as a boolean did not take
+this into account, causing C<keys %{+undef}> (and C<keys %$foo> when
+C<$foo> is undefined) to be an error, which it should be so in strict
+mode only [perl #81750].
+
+C<lc>, C<uc>, C<lcfirst>, and C<ucfirst> no longer return untainted strings
+when the argument is tainted. This has been broken since perl 5.8.9
+[perl #87336].
+
+Fixed a case where it was possible that a freed buffer may have been read
+from when parsing a here document.
+
+=head1 Modules and Pragmata
+
+L<Module::CoreList> has been upgraded from version 2.43 to 2.50.
+
+=head1 Testing
+
+The F<cpan/CGI/t/http.t> test script has been fixed to work when the
+environment has HTTPS_* environment variables, such as HTTPS_PROXY.
+
+=head1 Documentation
+
+Updated the documentation for rand() in L<perlfunc> to note that it is not
+cryptographically secure.
+
+=head1 Platform Specific Notes
+
+=over 4
+
+=item Linux
+
+Support Ubuntu 11.04's new multi-arch library layout.
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.12.4 represents approximately 5 months of development since
+Perl 5.12.3 and contains approximately 200 lines of changes across
+11 files from 8 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.12.4:
+
+Andy Dougherty, David Golden, David Leadbeater, Father Chrysostomos,
+Florian Ragwitz, Jesse Vincent, Leon Brocard, Zsbán Ambrus.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the B<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5125delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5125delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5125delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5125delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,241 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5125delta - what is new for perl v5.12.5
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.12.4 release and
+the 5.12.5 release.
+
+If you are upgrading from an earlier release such as 5.12.3, first read
+L<perl5124delta>, which describes differences between 5.12.3 and
+5.12.4.
+
+=head1 Security
+
+=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939)
+
+A bug in C<Encode> could, on certain inputs, cause the heap to overflow.
+This problem has been corrected. Bug reported by Robert Zacek.
+
+=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
+
+Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would
+cause an access violation / segfault. A Perl program that accepts a flags value from
+an external source could expose itself to denial of service or arbitrary code
+execution attacks. There are no known exploits in the wild. The problem has been
+corrected by explicitly disabling all unsupported flags and setting unused function
+pointers to null. Bug reported by Clément Lecigne.
+
+=head2 Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)
+
+Poorly written perl code that allows an attacker to specify the count to
+perl's 'x' string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before 5.15.5 can
+escalate that into a heap buffer overrun; coupled with versions of glibc
+before 2.16, it possibly allows the execution of arbitrary code.
+
+This problem has been fixed.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.12.4. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules
+
+=head3 L<B::Concise>
+
+L<B::Concise> no longer produces mangled output with the B<-tree> option
+[perl #80632].
+
+=head3 L<charnames>
+
+A regression introduced in Perl 5.8.8 has been fixed, that caused
+C<charnames::viacode(0)> to return C<undef> instead of the string "NULL"
+[perl #72624].
+
+=head3 L<Encode> has been upgraded from version 2.39 to version 2.39_01.
+
+See L</Security>.
+
+=head3 L<File::Glob> has been upgraded from version 1.07 to version 1.07_01.
+
+See L</Security>.
+
+=head3 L<Unicode::UCD>
+
+The documentation for the C<upper> function now actually says "upper", not
+"lower".
+
+=head3 L<Module::CoreList>
+
+L<Module::CoreList> has been updated to version 2.50_02 to add data for
+this release.
+
+=head1 Changes to Existing Documentation
+
+=head2 L<perlebcdic>
+
+The L<perlebcdic> document contains a helpful table to use in C<tr///> to
+convert between EBCDIC and Latin1/ASCII. Unfortunately, the table was the
+inverse of the one it describes. This has been corrected.
+
+=head2 L<perlunicode>
+
+The section on
+L<User-Defined Case Mappings|perlunicode/User-Defined Case Mappings> had
+some bad markup and unclear sentences, making parts of it unreadable. This
+has been rectified.
+
+=head2 L<perluniprops>
+
+This document has been corrected to take non-ASCII platforms into account.
+
+=head1 Installation and Configuration Improvements
+
+=head2 Platform Specific Changes
+
+=over 4
+
+=item Mac OS X
+
+There have been configuration and test fixes to make Perl build cleanly on
+Lion and Mountain Lion.
+
+=item NetBSD
+
+The NetBSD hints file was corrected to be compatible with NetBSD 6.*
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+C<chop> now correctly handles characters above "\x{7fffffff}"
+[perl #73246].
+
+=item *
+
+C<< ($<,$>) = (...) >> stopped working properly in 5.12.0. It is supposed
+to make a single C<setreuid()> call, rather than calling C<setruid()> and
+C<seteuid()> separately. Consequently it did not work properly. This has
+been fixed [perl #75212].
+
+=item *
+
+Fixed a regression of kill() when a match variable is used for the
+process ID to kill [perl #75812].
+
+=item *
+
+C<UNIVERSAL::VERSION> no longer leaks memory. It started leaking in Perl
+5.10.0.
+
+=item *
+
+The C-level C<my_strftime> functions no longer leaks memory. This fixes a
+memory leak in C<POSIX::strftime> [perl #73520].
+
+=item *
+
+C<caller> no longer leaks memory when called from the DB package if
+C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
+was triggering this bug [perl #97010].
+
+=item *
+
+Passing to C<index> an offset beyond the end of the string when the string
+is encoded internally in UTF8 no longer causes panics [perl #75898].
+
+=item *
+
+Syntax errors in C<< (?{...}) >> blocks in regular expressions no longer
+cause panic messages [perl #2353].
+
+=item *
+
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty. This has
+been fixed [perl #90160].
+
+=back
+
+=head1 Errata
+
+=head2 split() and C<@_>
+
+split() no longer modifies C<@_> when called in scalar or void context.
+In void context it now produces a "Useless use of split" warning.
+This is actually a change introduced in perl 5.12.0, but it was missed from
+that release's L<perl5120delta>.
+
+=head1 Acknowledgements
+
+Perl 5.12.5 represents approximately 17 months of development since Perl 5.12.4
+and contains approximately 1,900 lines of changes across 64 files from 18
+authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.12.5:
+
+Andy Dougherty, Chris 'BinGOs' Williams, Craig A. Berry, David Mitchell,
+Dominic Hargreaves, Father Chrysostomos, Florian Ragwitz, George Greer, Goro
+Fuji, Jesse Vincent, Karl Williamson, Leon Brocard, Nicholas Clark, Rafael
+Garcia-Suarez, Reini Urban, Ricardo Signes, Steve Hay, Tony Cook.
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the B<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Index: trunk/contrib/perl/pod/perl5130delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5130delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5130delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5130delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl51310delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl51310delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl51310delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl51310delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl51311delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl51311delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl51311delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl51311delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5131delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5131delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5131delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5131delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5132delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5132delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5132delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5132delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5133delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5133delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5133delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5133delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5134delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5134delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5134delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5134delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5135delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5135delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5135delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5135delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5136delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5136delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5136delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5136delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5137delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5137delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5137delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5137delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5138delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5138delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5138delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5138delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5139delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5139delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5139delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5139delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl5140delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5140delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5140delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1108,7 +1108,7 @@
=head2 Freeing weak references
When there are many weak references to an object, freeing that object
-can under some circumstances take O(I<NE<0xB2>>) time to free, where
+can under some circumstances take O(I<N*N>) time to free, where
I<N> is the number of references. The circumstances in which this can happen
have been reduced [perl #75254]
@@ -1210,7 +1210,7 @@
L<CPAN::Meta> version 2.110440 has been added as a dual-life module. It
provides a standard library to read, interpret and write CPAN distribution
-metadata files (like F<META.json> and F<META.yml)> that describe a
+metadata files (like F<META.json> and F<META.yml>) that describe a
distribution, its contents, and the requirements for building it and
installing it. The latest CPAN distribution metadata specification is
included as L<CPAN::Meta::Spec> and notes on changes in the specification
@@ -1547,9 +1547,9 @@
L<Digest::SHA> has been upgraded from version 5.47 to 5.61.
-L<shasum> now more closely mimics L<sha1sum(1)>/L<md5sum(1)>.
+C<shasum> now more closely mimics L<sha1sum(1)>/L<md5sum(1)>.
-L<Addfile> accepts all POSIX filenames.
+C<addfile> accepts all POSIX filenames.
New SHA-512/224 and SHA-512/256 transforms (ref. NIST Draft FIPS 180-4
[February 2011])
@@ -2125,7 +2125,7 @@
A new function, Unicode::UCD::num(), has been added. This function
returns the numeric value of the string passed it or C<undef> if the string
in its entirety has no "safe" numeric value. (For more detail, and for the
-definition of "safe", see L<Unicode::UCD/num>.)
+definition of "safe", see L<Unicode::UCD/num()>.)
This upgrade also includes several bug fixes:
@@ -2888,7 +2888,7 @@
the most common path for creating files from Perl became C<PerlIOUnix_open>,
which has always explicitly used C<0666> as the permission mask. This prevents
inheriting permissions from RMS defaults and ACLs, so to avoid that problem,
-we now pass C<0777> to open(). In theVMS CRTL, C<0777> has a special
+we now pass C<0777> to open(). In the VMS CRTL, C<0777> has a special
meaning over and above intersecting with the current umask; specifically, it
allows Unix syscalls to preserve native default permissions (5.12.3).
@@ -4445,8 +4445,8 @@
=item *
-readline() returns an empty string instead of undef when it is
-interrupted by a signal.
+readline() returns an empty string instead of a cached previous value
+when it is interrupted by a signal
=item *
@@ -4569,7 +4569,7 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes all the core committers, who are able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please use this address for
Property changes on: trunk/contrib/perl/pod/perl5140delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl5141delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl5141delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl5141delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl5141delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perl5142delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5142delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5142delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5142delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,242 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5142delta - what is new for perl v5.14.2
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.14.1 release and
+the 5.14.2 release.
+
+If you are upgrading from an earlier release such as 5.14.0, first read
+L<perl5141delta>, which describes differences between 5.14.0 and
+5.14.1.
+
+=head1 Core Enhancements
+
+No changes since 5.14.0.
+
+=head1 Security
+
+=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
+
+Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would
+cause an access violation / segfault. A Perl program that accepts a flags value from
+an external source could expose itself to denial of service or arbitrary code
+execution attacks. There are no known exploits in the wild. The problem has been
+corrected by explicitly disabling all unsupported flags and setting unused function
+pointers to null. Bug reported by Clément Lecigne.
+
+=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939)
+
+A bug in C<Encode> could, on certain inputs, cause the heap to overflow.
+This problem has been corrected. Bug reported by Robert Zacek.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Deprecations
+
+There have been no deprecations since 5.14.0.
+
+=head1 Modules and Pragmata
+
+=head2 New Modules and Pragmata
+
+None
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<CPAN> has been upgraded from version 1.9600 to version 1.9600_01.
+
+L<CPAN::Distribution> has been upgraded from version 1.9602 to 1.9602_01.
+
+Backported bugfixes from CPAN version 1.9800. Ensures proper
+detection of C<configure_requires> prerequisites from CPAN Meta files
+in the case where C<dynamic_config> is true. [rt.cpan.org #68835]
+
+Also ensures that C<configure_requires> is only checked in META files,
+not MYMETA files, so protect against MYMETA generation that drops
+C<configure_requires>.
+
+=item *
+
+L<Encode> has been upgraded from version 2.42 to 2.42_01.
+
+See L</Security>.
+
+=item *
+
+L<File::Glob> has been upgraded from version 1.12 to version 1.13.
+
+See L</Security>.
+
+=item *
+
+L<PerlIO::scalar> has been upgraded from version 0.11 to 0.11_01.
+
+It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
+C<$scalar> is a copy-on-write scalar.
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+None
+
+=head1 Platform Support
+
+=head2 New Platforms
+
+None
+
+=head2 Discontinued Platforms
+
+None
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item HP-UX PA-RISC/64 now supports gcc-4.x
+
+A fix to correct the socketsize now makes the test suite pass on HP-UX
+PA-RISC for 64bitall builds.
+
+=item Building on OS X 10.7 Lion and Xcode 4 works again
+
+The build system has been updated to work with the build tools under Mac OS X
+10.7.
+
+=back
+
+=head1 Bug Fixes
+
+=over 4
+
+=item *
+
+In @INC filters (subroutines returned by subroutines in @INC), $_ used to
+misbehave: If returned from a subroutine, it would not be copied, but the
+variable itself would be returned; and freeing $_ (e.g., with C<undef *_>)
+would cause perl to crash. This has been fixed [perl #91880].
+
+=item *
+
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty. This has
+been fixed [perl #90160].
+
+=item *
+
+C<caller> no longer leaks memory when called from the DB package if
+C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
+was triggering this bug [perl #97010].
+
+=item *
+
+C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
+string buffers in place (i.e., skipping the copy). This could result in
+hashes having two elements with the same key [perl #91834].
+
+=item *
+
+Localising a tied variable used to make it read-only if it contained a
+copy-on-write string.
+
+=item *
+
+Elements of restricted hashes (see the L<fields> pragma) containing
+copy-on-write values couldn't be deleted, nor could such hashes be cleared
+(C<%hash = ()>).
+
+=item *
+
+Locking a hash element that is a glob copy no longer causes subsequent
+assignment to it to corrupt the glob.
+
+=item *
+
+A panic involving the combination of the regular expression modifiers
+C</aa> introduced in 5.14.0 and the C<\b> escape sequence has been
+fixed [perl #95964].
+
+=back
+
+=head1 Known Problems
+
+This is a list of some significant unfixed bugs, which are regressions
+from 5.12.0.
+
+=over 4
+
+=item *
+
+C<PERL_GLOBAL_STRUCT> is broken.
+
+Since perl 5.14.0, building with C<-DPERL_GLOBAL_STRUCT> hasn't been
+possible. This means that perl currently doesn't work on any platforms that
+require it to be built this way, including Symbian.
+
+While C<PERL_GLOBAL_STRUCT> now works again on recent development versions of
+perl, it actually working on Symbian again hasn't been verified.
+
+We'd be very interested in hearing from anyone working with Perl on Symbian.
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.14.2 represents approximately three months of development since
+Perl 5.14.1 and contains approximately 1200 lines of changes
+across 61 files from 9 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.14.2:
+
+Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn
+Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5143delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5143delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5143delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5143delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,291 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5143delta - what is new for perl v5.14.3
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.14.2 release and
+the 5.14.3 release.
+
+If you are upgrading from an earlier release such as 5.12.0, first read
+L<perl5140delta>, which describes differences between 5.12.0 and
+5.14.0.
+
+=head1 Core Enhancements
+
+No changes since 5.14.0.
+
+=head1 Security
+
+=head2 C<Digest> unsafe use of eval (CVE-2011-3597)
+
+The C<Digest-E<gt>new()> function did not properly sanitize input before
+using it in an eval() call, which could lead to the injection of arbitrary
+Perl code.
+
+In order to exploit this flaw, the attacker would need to be able to set
+the algorithm name used, or be able to execute arbitrary Perl code already.
+
+This problem has been fixed.
+
+=head2 Heap buffer overrun in 'x' string repeat operator (CVE-2012-5195)
+
+Poorly written perl code that allows an attacker to specify the count to
+perl's 'x' string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before 5.15.5 can
+escalate that into a heap buffer overrun; coupled with versions of glibc
+before 2.16, it possibly allows the execution of arbitrary code.
+
+This problem has been fixed.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Deprecations
+
+There have been no deprecations since 5.14.0.
+
+=head1 Modules and Pragmata
+
+=head2 New Modules and Pragmata
+
+None
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<PerlIO::scalar> was updated to fix a bug in which opening a filehandle to
+a glob copy caused assertion failures (under debugging) or hangs or other
+erratic behaviour without debugging.
+
+=item *
+
+L<ODBM_File> and L<NDBM_File> were updated to allow building on GNU/Hurd.
+
+=item *
+
+L<IPC::Open3> has been updated to fix a regression introduced in perl
+5.12, which broke C<IPC::Open3::open3($in, $out, $err, '-')>.
+[perl #95748]
+
+=item *
+
+L<Digest> has been upgraded from version 1.16 to 1.16_01.
+
+See L</Security>.
+
+=item *
+
+L<Module::CoreList> has been updated to version 2.49_04 to add data for
+this release.
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+None
+
+=head1 Documentation
+
+=head2 New Documentation
+
+None
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlcheat>
+
+=over 4
+
+=item *
+
+L<perlcheat> was updated to 5.14.
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+h2ph was updated to search correctly gcc include directories on platforms
+such as Debian with multi-architecture support.
+
+=item *
+
+In Configure, the test for procselfexe was refactored into a loop.
+
+=back
+
+=head1 Platform Support
+
+=head2 New Platforms
+
+None
+
+=head2 Discontinued Platforms
+
+None
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item FreeBSD
+
+The FreeBSD hints file was corrected to be compatible with FreeBSD 10.0.
+
+=item Solaris and NetBSD
+
+Configure was updated for "procselfexe" support on Solaris and NetBSD.
+
+=item HP-UX
+
+README.hpux was updated to note the existence of a broken header in
+HP-UX 11.00.
+
+=item Linux
+
+libutil is no longer used when compiling on Linux platforms, which avoids
+warnings being emitted.
+
+The system gcc (rather than any other gcc which might be in the compiling
+user's path) is now used when searching for libraries such as C<-lm>.
+
+=item Mac OS X
+
+The locale tests were updated to reflect the behaviour of locales in
+Mountain Lion.
+
+=item GNU/Hurd
+
+Various build and test fixes were included for GNU/Hurd.
+
+LFS support was enabled in GNU/Hurd.
+
+=item NetBSD
+
+The NetBSD hints file was corrected to be compatible with NetBSD 6.*
+
+=back
+
+=head1 Bug Fixes
+
+=over 4
+
+=item *
+
+A regression has been fixed that was introduced in 5.14, in C</i>
+regular expression matching, in which a match improperly fails if the
+pattern is in UTF-8, the target string is not, and a Latin-1 character
+precedes a character in the string that should match the pattern. [perl
+#101710]
+
+=item *
+
+In case-insensitive regular expression pattern matching, no longer on
+UTF-8 encoded strings does the scan for the start of match only look at
+the first possible position. This caused matches such as
+C<"f\x{FB00}" =~ /ff/i> to fail.
+
+=item *
+
+The sitecustomize support was made relocatableinc aware, so that
+-Dusesitecustomize and -Duserelocatableinc may be used together.
+
+=item *
+
+The smartmatch operator (C<~~>) was changed so that the right-hand side
+takes precedence during C<Any ~~ Object> operations.
+
+=item *
+
+A bug has been fixed in the tainting support, in which an C<index()>
+operation on a tainted constant would cause all other constants to become
+tainted. [perl #64804]
+
+=item *
+
+A regression has been fixed that was introduced in perl 5.12, whereby
+tainting errors were not correctly propagated through C<die()>.
+[perl #111654]
+
+=item *
+
+A regression has been fixed that was introduced in perl 5.14, in which
+C</[[:lower:]]/i> and C</[[:upper:]]/i> no longer matched the opposite case.
+[perl #101970]
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.14.3 represents approximately 12 months of development since Perl 5.14.2
+and contains approximately 2,300 lines of changes across 64 files from 22
+authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.14.3:
+
+Abigail, Andy Dougherty, Carl Hayter, Chris 'BinGOs' Williams, Dave Rolsky,
+David Mitchell, Dominic Hargreaves, Father Chrysostomos, Florian Ragwitz,
+H.Merijn Brand, Jilles Tjoelker, Karl Williamson, Leon Timmermans, Michael G
+Schwern, Nicholas Clark, Niko Tyni, Pino Toscano, Ricardo Signes, Salvador
+Fandiño, Samuel Thibault, Steve Hay, Tony Cook.
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5144delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5144delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5144delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5144delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,240 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5144delta - what is new for perl v5.14.4
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.14.3 release and
+the 5.14.4 release.
+
+If you are upgrading from an earlier release such as 5.12.0, first read
+L<perl5140delta>, which describes differences between 5.12.0 and
+5.14.0.
+
+=head1 Core Enhancements
+
+No changes since 5.14.0.
+
+=head1 Security
+
+This release contains one major, and medium, and a number of minor
+security fixes. The latter are included mainly to allow the test suite to
+pass cleanly with the clang compiler's address sanitizer facility.
+
+=head2 CVE-2013-1667: memory exhaustion with arbitrary hash keys
+
+With a carefully crafted set of hash keys (for example arguments on a
+URL), it is possible to cause a hash to consume a large amount of memory
+and CPU, and thus possibly to achieve a Denial-of-Service.
+
+This problem has been fixed.
+
+=head2 memory leak in Encode
+
+The UTF-8 encoding implementation in Encode.xs had a memory leak which has been
+fixed.
+
+=head2 [perl #111594] Socket::unpack_sockaddr_un heap-buffer-overflow
+
+A read buffer overflow could occur when copying C<sockaddr> buffers.
+Fairly harmless.
+
+This problem has been fixed.
+
+=head2 [perl #111586] SDBM_File: fix off-by-one access to global ".dir"
+
+An extra byte was being copied for some string literals. Fairly harmless.
+
+This problem has been fixed.
+
+=head2 off-by-two error in List::Util
+
+A string literal was being used that included two bytes beyond the
+end of the string. Fairly harmless.
+
+This problem has been fixed.
+
+=head2 [perl #115994] fix segv in regcomp.c:S_join_exact()
+
+Under debugging builds, while marking optimised-out regex nodes as type
+C<OPTIMIZED>, it could treat blocks of exact text as if they were nodes,
+and thus SEGV. Fairly harmless.
+
+This problem has been fixed.
+
+=head2 [perl #115992] PL_eval_start use-after-free
+
+The statement C<local $[;>, when preceded by an C<eval>, and when not part
+of an assignment, could crash. Fairly harmless.
+
+This problem has been fixed.
+
+=head2 wrap-around with IO on long strings
+
+Reading or writing strings greater than 2**31 bytes in size could segfault
+due to integer wraparound.
+
+This problem has been fixed.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.14.0. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Deprecations
+
+There have been no deprecations since 5.14.0.
+
+=head1 Modules and Pragmata
+
+=head2 New Modules and Pragmata
+
+None
+
+=head2 Updated Modules and Pragmata
+
+The following modules have just the minor code fixes as listed above in
+L</Security> (version numbers have not changed):
+
+=over 4
+
+=item Socket
+
+=item SDBM_File
+
+=item List::Util
+
+=back
+
+L<Encode> has been upgraded from version 2.42_01 to version 2.42_02.
+
+L<Module::CoreList> has been updated to version 2.49_06 to add data for
+this release.
+
+=head2 Removed Modules and Pragmata
+
+None.
+
+=head1 Documentation
+
+=head2 New Documentation
+
+None.
+
+=head2 Changes to Existing Documentation
+
+None.
+
+=head1 Diagnostics
+
+No new or changed diagnostics.
+
+=head1 Utility Changes
+
+None
+
+=head1 Configuration and Compilation
+
+No changes.
+
+=head1 Platform Support
+
+=head2 New Platforms
+
+None.
+
+=head2 Discontinued Platforms
+
+None.
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item VMS
+
+5.14.3 failed to compile on VMS due to incomplete application of a patch
+series that allowed C<userelocatableinc> and C<usesitecustomize> to be
+used simultaneously. Other platforms were not affected and the problem
+has now been corrected.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+In Perl 5.14.0, C<$tainted ~~ @array> stopped working properly. Sometimes
+it would erroneously fail (when C<$tainted> contained a string that occurs
+in the array I<after> the first element) or erroneously succeed (when
+C<undef> occurred after the first element) [perl #93590].
+
+=back
+
+=head1 Known Problems
+
+None.
+
+=head1 Acknowledgements
+
+Perl 5.14.4 represents approximately 5 months of development since Perl 5.14.3
+and contains approximately 1,700 lines of changes across 49 files from 12
+authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.14.4:
+
+Andy Dougherty, Chris 'BinGOs' Williams, Christian Hansen, Craig A. Berry,
+Dave Rolsky, David Mitchell, Dominic Hargreaves, Father Chrysostomos,
+Florian Ragwitz, Reini Urban, Ricardo Signes, Yves Orton.
+
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send
+it to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who be able
+to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently
+distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5160delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5160delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5160delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5160delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,4314 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5160delta - what is new for perl v5.16.0
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.14.0 release and
+the 5.16.0 release.
+
+If you are upgrading from an earlier release such as 5.12.0, first read
+L<perl5140delta>, which describes differences between 5.12.0 and
+5.14.0.
+
+Some bug fixes in this release have been backported to later
+releases of 5.14.x. Those are indicated with the 5.14.x version in
+parentheses.
+
+=head1 Notice
+
+With the release of Perl 5.16.0, the 5.12.x series of releases is now out of
+its support period. There may be future 5.12.x releases, but only in the
+event of a critical security issue. Users of Perl 5.12 or earlier should
+consider upgrading to a more recent release of Perl.
+
+This policy is described in greater detail in
+L<perlpolicy|perlpolicy/MAINTENANCE AND SUPPORT>.
+
+=head1 Core Enhancements
+
+=head2 C<use I<VERSION>>
+
+As of this release, version declarations like C<use v5.16> now disable
+all features before enabling the new feature bundle. This means that
+the following holds true:
+
+ use 5.016;
+ # only 5.16 features enabled here
+ use 5.014;
+ # only 5.14 features enabled here (not 5.16)
+
+C<use v5.12> and higher continue to enable strict, but explicit C<use
+strict> and C<no strict> now override the version declaration, even
+when they come first:
+
+ no strict;
+ use 5.012;
+ # no strict here
+
+There is a new ":default" feature bundle that represents the set of
+features enabled before any version declaration or C<use feature> has
+been seen. Version declarations below 5.10 now enable the ":default"
+feature set. This does not actually change the behavior of C<use
+v5.8>, because features added to the ":default" set are those that were
+traditionally enabled by default, before they could be turned off.
+
+C<< no feature >> now resets to the default feature set. To disable all
+features (which is likely to be a pretty special-purpose request, since
+it presumably won't match any named set of semantics) you can now
+write C<< no feature ':all' >>.
+
+C<$[> is now disabled under C<use v5.16>. It is part of the default
+feature set and can be turned on or off explicitly with C<use feature
+'array_base'>.
+
+=head2 C<__SUB__>
+
+The new C<__SUB__> token, available under the C<current_sub> feature
+(see L<feature>) or C<use v5.16>, returns a reference to the current
+subroutine, making it easier to write recursive closures.
+
+=head2 New and Improved Built-ins
+
+=head3 More consistent C<eval>
+
+The C<eval> operator sometimes treats a string argument as a sequence of
+characters and sometimes as a sequence of bytes, depending on the
+internal encoding. The internal encoding is not supposed to make any
+difference, but there is code that relies on this inconsistency.
+
+The new C<unicode_eval> and C<evalbytes> features (enabled under C<use
+5.16.0>) resolve this. The C<unicode_eval> feature causes C<eval
+$string> to treat the string always as Unicode. The C<evalbytes>
+features provides a function, itself called C<evalbytes>, which
+evaluates its argument always as a string of bytes.
+
+These features also fix oddities with source filters leaking to outer
+dynamic scopes.
+
+See L<feature> for more detail.
+
+=head3 C<substr> lvalue revamp
+
+=for comment Does this belong here, or under Incompatible Changes?
+
+When C<substr> is called in lvalue or potential lvalue context with two
+or three arguments, a special lvalue scalar is returned that modifies
+the original string (the first argument) when assigned to.
+
+Previously, the offsets (the second and third arguments) passed to
+C<substr> would be converted immediately to match the string, negative
+offsets being translated to positive and offsets beyond the end of the
+string being truncated.
+
+Now, the offsets are recorded without modification in the special
+lvalue scalar that is returned, and the original string is not even
+looked at by C<substr> itself, but only when the returned lvalue is
+read or modified.
+
+These changes result in an incompatible change:
+
+If the original string changes length after the call to C<substr> but
+before assignment to its return value, negative offsets will remember
+their position from the end of the string, affecting code like this:
+
+ my $string = "string";
+ my $lvalue = \substr $string, -4, 2;
+ print $$lvalue, "\n"; # prints "ri"
+ $string = "bailing twine";
+ print $$lvalue, "\n"; # prints "wi"; used to print "il"
+
+The same thing happens with an omitted third argument. The returned
+lvalue will always extend to the end of the string, even if the string
+becomes longer.
+
+Since this change also allowed many bugs to be fixed (see
+L</The C<substr> operator>), and since the behavior
+of negative offsets has never been specified, the
+change was deemed acceptable.
+
+=head3 Return value of C<tied>
+
+The value returned by C<tied> on a tied variable is now the actual
+scalar that holds the object to which the variable is tied. This
+lets ties be weakened with C<Scalar::Util::weaken(tied
+$tied_variable)>.
+
+=head2 Unicode Support
+
+=head3 Supports (I<almost>) Unicode 6.1
+
+Besides the addition of whole new scripts, and new characters in
+existing scripts, this new version of Unicode, as always, makes some
+changes to existing characters. One change that may trip up some
+applications is that the General Category of two characters in the
+Latin-1 range, PILCROW SIGN and SECTION SIGN, has been changed from
+Other_Symbol to Other_Punctuation. The same change has been made for
+a character in each of Tibetan, Ethiopic, and Aegean.
+The code points U+3248..U+324F (CIRCLED NUMBER TEN ON BLACK SQUARE
+through CIRCLED NUMBER EIGHTY ON BLACK SQUARE) have had their General
+Category changed from Other_Symbol to Other_Numeric. The Line Break
+property has changes for Hebrew and Japanese; and because of
+other changes in 6.1, the Perl regular expression construct C<\X> now
+works differently for some characters in Thai and Lao.
+
+New aliases (synonyms) have been defined for many property values;
+these, along with the previously existing ones, are all cross-indexed in
+L<perluniprops>.
+
+The return value of C<charnames::viacode()> is affected by other
+changes:
+
+ Code point Old Name New Name
+ U+000A LINE FEED (LF) LINE FEED
+ U+000C FORM FEED (FF) FORM FEED
+ U+000D CARRIAGE RETURN (CR) CARRIAGE RETURN
+ U+0085 NEXT LINE (NEL) NEXT LINE
+ U+008E SINGLE-SHIFT 2 SINGLE-SHIFT-2
+ U+008F SINGLE-SHIFT 3 SINGLE-SHIFT-3
+ U+0091 PRIVATE USE 1 PRIVATE USE-1
+ U+0092 PRIVATE USE 2 PRIVATE USE-2
+ U+2118 SCRIPT CAPITAL P WEIERSTRASS ELLIPTIC FUNCTION
+
+Perl will accept any of these names as input, but
+C<charnames::viacode()> now returns the new name of each pair. The
+change for U+2118 is considered by Unicode to be a correction, that is
+the original name was a mistake (but again, it will remain forever valid
+to use it to refer to U+2118). But most of these changes are the
+fallout of the mistake Unicode 6.0 made in naming a character used in
+Japanese cell phones to be "BELL", which conflicts with the longstanding
+industry use of (and Unicode's recommendation to use) that name
+to mean the ASCII control character at U+0007. Therefore, that name
+has been deprecated in Perl since v5.14, and any use of it will raise a
+warning message (unless turned off). The name "ALERT" is now the
+preferred name for this code point, with "BEL" an acceptable short
+form. The name for the new cell phone character, at code point U+1F514,
+remains undefined in this version of Perl (hence we don't
+implement quite all of Unicode 6.1), but starting in v5.18, BELL will mean
+this character, and not U+0007.
+
+Unicode has taken steps to make sure that this sort of mistake does not
+happen again. The Standard now includes all generally accepted
+names and abbreviations for control characters, whereas previously it
+didn't (though there were recommended names for most of them, which Perl
+used). This means that most of those recommended names are now
+officially in the Standard. Unicode did not recommend names for the
+four code points listed above between U+008E and U+008F, and in
+standardizing them Unicode subtly changed the names that Perl had
+previously given them, by replacing the final blank in each name by a
+hyphen. Unicode also officially accepts names that Perl had deprecated,
+such as FILE SEPARATOR. Now the only deprecated name is BELL.
+Finally, Perl now uses the new official names instead of the old
+(now considered obsolete) names for the first four code points in the
+list above (the ones which have the parentheses in them).
+
+Now that the names have been placed in the Unicode standard, these kinds
+of changes should not happen again, though corrections, such as to
+U+2118, are still possible.
+
+Unicode also added some name abbreviations, which Perl now accepts:
+SP for SPACE;
+TAB for CHARACTER TABULATION;
+NEW LINE, END OF LINE, NL, and EOL for LINE FEED;
+LOCKING-SHIFT ONE for SHIFT OUT;
+LOCKING-SHIFT ZERO for SHIFT IN;
+and ZWNBSP for ZERO WIDTH NO-BREAK SPACE.
+
+More details on this version of Unicode are provided in
+L<http://www.unicode.org/versions/Unicode6.1.0/>.
+
+=head3 C<use charnames> is no longer needed for C<\N{I<name>}>
+
+When C<\N{I<name>}> is encountered, the C<charnames> module is now
+automatically loaded when needed as if the C<:full> and C<:short>
+options had been specified. See L<charnames> for more information.
+
+=head3 C<\N{...}> can now have Unicode loose name matching
+
+This is described in the C<charnames> item in
+L</Updated Modules and Pragmata> below.
+
+=head3 Unicode Symbol Names
+
+Perl now has proper support for Unicode in symbol names. It used to be
+that C<*{$foo}> would ignore the internal UTF8 flag and use the bytes of
+the underlying representation to look up the symbol. That meant that
+C<*{"\x{100}"}> and C<*{"\xc4\x80"}> would return the same thing. All
+these parts of Perl have been fixed to account for Unicode:
+
+=over
+
+=item *
+
+Method names (including those passed to C<use overload>)
+
+=item *
+
+Typeglob names (including names of variables, subroutines, and filehandles)
+
+=item *
+
+Package names
+
+=item *
+
+C<goto>
+
+=item *
+
+Symbolic dereferencing
+
+=item *
+
+Second argument to C<bless()> and C<tie()>
+
+=item *
+
+Return value of C<ref()>
+
+=item *
+
+Subroutine prototypes
+
+=item *
+
+Attributes
+
+=item *
+
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+
+=back
+
+In addition, a parsing bug has been fixed that prevented C<*{é}> from
+implicitly quoting the name, but instead interpreted it as C<*{+é}>, which
+would cause a strict violation.
+
+C<*{"*a::b"}> automatically strips off the * if it is followed by an ASCII
+letter. That has been extended to all Unicode identifier characters.
+
+One-character non-ASCII non-punctuation variables (like C<$é>) are now
+subject to "Used only once" warnings. They used to be exempt, as they
+were treated as punctuation variables.
+
+Also, single-character Unicode punctuation variables (like C<$‰>) are now
+supported [perl #69032].
+
+=head3 Improved ability to mix locales and Unicode, including UTF-8 locales
+
+An optional parameter has been added to C<use locale>
+
+ use locale ':not_characters';
+
+which tells Perl to use all but the C<LC_CTYPE> and C<LC_COLLATE>
+portions of the current locale. Instead, the character set is assumed
+to be Unicode. This lets locales and Unicode be seamlessly mixed,
+including the increasingly frequent UTF-8 locales. When using this
+hybrid form of locales, the C<:locale> layer to the L<open> pragma can
+be used to interface with the file system, and there are CPAN modules
+available for ARGV and environment variable conversions.
+
+Full details are in L<perllocale>.
+
+=head3 New function C<fc> and corresponding escape sequence C<\F> for Unicode foldcase
+
+Unicode foldcase is an extension to lowercase that gives better results
+when comparing two strings case-insensitively. It has long been used
+internally in regular expression C</i> matching. Now it is available
+explicitly through the new C<fc> function call (enabled by
+S<C<"use feature 'fc'">>, or C<use v5.16>, or explicitly callable via
+C<CORE::fc>) or through the new C<\F> sequence in double-quotish
+strings.
+
+Full details are in L<perlfunc/fc>.
+
+=head3 The Unicode C<Script_Extensions> property is now supported.
+
+New in Unicode 6.0, this is an improved C<Script> property. Details
+are in L<perlunicode/Scripts>.
+
+=head2 XS Changes
+
+=head3 Improved typemaps for Some Builtin Types
+
+Most XS authors will know there is a longstanding bug in the
+OUTPUT typemap for T_AVREF (C<AV*>), T_HVREF (C<HV*>), T_CVREF (C<CV*>),
+and T_SVREF (C<SVREF> or C<\$foo>) that requires manually decrementing
+the reference count of the return value instead of the typemap taking
+care of this. For backwards-compatibility, this cannot be changed in the
+default typemaps. But we now provide additional typemaps
+C<T_AVREF_REFCOUNT_FIXED>, etc. that do not exhibit this bug. Using
+them in your extension is as simple as having one line in your
+C<TYPEMAP> section:
+
+ HV* T_HVREF_REFCOUNT_FIXED
+
+=head3 C<is_utf8_char()>
+
+The XS-callable function C<is_utf8_char()>, when presented with
+malformed UTF-8 input, can read up to 12 bytes beyond the end of the
+string. This cannot be fixed without changing its API, and so its
+use is now deprecated. Use C<is_utf8_char_buf()> (described just below)
+instead.
+
+=head3 Added C<is_utf8_char_buf()>
+
+This function is designed to replace the deprecated L</is_utf8_char()>
+function. It includes an extra parameter to make sure it doesn't read
+past the end of the input buffer.
+
+=head3 Other C<is_utf8_foo()> functions, as well as C<utf8_to_foo()>, etc.
+
+Most other XS-callable functions that take UTF-8 encoded input
+implicitly assume that the UTF-8 is valid (not malformed) with respect to
+buffer length. Do not do things such as change a character's case or
+see if it is alphanumeric without first being sure that it is valid
+UTF-8. This can be safely done for a whole string by using one of the
+functions C<is_utf8_string()>, C<is_utf8_string_loc()>, and
+C<is_utf8_string_loclen()>.
+
+=head3 New Pad API
+
+Many new functions have been added to the API for manipulating lexical
+pads. See L<perlapi/Pad Data Structures> for more information.
+
+=head2 Changes to Special Variables
+
+=head3 C<$$> can be assigned to
+
+C<$$> was made read-only in Perl 5.8.0. But only sometimes: C<local $$>
+would make it writable again. Some CPAN modules were using C<local $$> or
+XS code to bypass the read-only check, so there is no reason to keep C<$$>
+read-only. (This change also allowed a bug to be fixed while maintaining
+backward compatibility.)
+
+=head3 C<$^X> converted to an absolute path on FreeBSD, OS X and Solaris
+
+C<$^X> is now converted to an absolute path on OS X, FreeBSD (without
+needing F</proc> mounted) and Solaris 10 and 11. This augments the
+previous approach of using F</proc> on Linux, FreeBSD, and NetBSD
+(in all cases, where mounted).
+
+This makes relocatable perl installations more useful on these platforms.
+(See "Relocatable @INC" in F<INSTALL>)
+
+=head2 Debugger Changes
+
+=head3 Features inside the debugger
+
+The current Perl's L<feature> bundle is now enabled for commands entered
+in the interactive debugger.
+
+=head3 New option for the debugger's B<t> command
+
+The B<t> command in the debugger, which toggles tracing mode, now
+accepts a numeric argument that determines how many levels of subroutine
+calls to trace.
+
+=head3 C<enable> and C<disable>
+
+The debugger now has C<disable> and C<enable> commands for disabling
+existing breakpoints and re-enabling them. See L<perldebug>.
+
+=head3 Breakpoints with file names
+
+The debugger's "b" command for setting breakpoints now lets a line
+number be prefixed with a file name. See
+L<perldebug/"b [file]:[line] [condition]">.
+
+=head2 The C<CORE> Namespace
+
+=head3 The C<CORE::> prefix
+
+The C<CORE::> prefix can now be used on keywords enabled by
+L<feature.pm|feature>, even outside the scope of C<use feature>.
+
+=head3 Subroutines in the C<CORE> namespace
+
+Many Perl keywords are now available as subroutines in the CORE namespace.
+This lets them be aliased:
+
+ BEGIN { *entangle = \&CORE::tie }
+ entangle $variable, $package, @args;
+
+And for prototypes to be bypassed:
+
+ sub mytie(\[%$*@]$@) {
+ my ($ref, $pack, @args) = @_;
+ ... do something ...
+ goto &CORE::tie;
+ }
+
+Some of these cannot be called through references or via C<&foo> syntax,
+but must be called as barewords.
+
+See L<CORE> for details.
+
+=head2 Other Changes
+
+=head3 Anonymous handles
+
+Automatically generated file handles are now named __ANONIO__ when the
+variable name cannot be determined, rather than $__ANONIO__.
+
+=head3 Autoloaded sort Subroutines
+
+Custom sort subroutines can now be autoloaded [perl #30661]:
+
+ sub AUTOLOAD { ... }
+ @sorted = sort foo @list; # uses AUTOLOAD
+
+=head3 C<continue> no longer requires the "switch" feature
+
+The C<continue> keyword has two meanings. It can introduce a C<continue>
+block after a loop, or it can exit the current C<when> block. Up to now,
+the latter meaning was valid only with the "switch" feature enabled, and
+was a syntax error otherwise. Since the main purpose of feature.pm is to
+avoid conflicts with user-defined subroutines, there is no reason for
+C<continue> to depend on it.
+
+=head3 DTrace probes for interpreter phase change
+
+The C<phase-change> probes will fire when the interpreter's phase
+changes, which tracks the C<${^GLOBAL_PHASE}> variable. C<arg0> is
+the new phase name; C<arg1> is the old one. This is useful
+for limiting your instrumentation to one or more of: compile time,
+run time, or destruct time.
+
+=head3 C<__FILE__()> Syntax
+
+The C<__FILE__>, C<__LINE__> and C<__PACKAGE__> tokens can now be written
+with an empty pair of parentheses after them. This makes them parse the
+same way as C<time>, C<fork> and other built-in functions.
+
+=head3 The C<\$> prototype accepts any scalar lvalue
+
+The C<\$> and C<\[$]> subroutine prototypes now accept any scalar lvalue
+argument. Previously they accepted only scalars beginning with C<$> and
+hash and array elements. This change makes them consistent with the way
+the built-in C<read> and C<recv> functions (among others) parse their
+arguments. This means that one can override the built-in functions with
+custom subroutines that parse their arguments the same way.
+
+=head3 C<_> in subroutine prototypes
+
+The C<_> character in subroutine prototypes is now allowed before C<@> or
+C<%>.
+
+=head1 Security
+
+=head2 Use C<is_utf8_char_buf()> and not C<is_utf8_char()>
+
+The latter function is now deprecated because its API is insufficient to
+guarantee that it doesn't read (up to 12 bytes in the worst case) beyond
+the end of its input string. See
+L<is_utf8_char_buf()|/Added is_utf8_char_buf()>.
+
+=head2 Malformed UTF-8 input could cause attempts to read beyond the end of the buffer
+
+Two new XS-accessible functions, C<utf8_to_uvchr_buf()> and
+C<utf8_to_uvuni_buf()> are now available to prevent this, and the Perl
+core has been converted to use them.
+See L</Internal Changes>.
+
+=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
+
+Calling C<File::Glob::bsd_glob> with the unsupported flag
+GLOB_ALTDIRFUNC would cause an access violation / segfault. A Perl
+program that accepts a flags value from an external source could expose
+itself to denial of service or arbitrary code execution attacks. There
+are no known exploits in the wild. The problem has been corrected by
+explicitly disabling all unsupported flags and setting unused function
+pointers to null. Bug reported by Clément Lecigne. (5.14.2)
+
+=head2 Privileges are now set correctly when assigning to C<$(>
+
+A hypothetical bug (probably unexploitable in practice) because the
+incorrect setting of the effective group ID while setting C<$(> has been
+fixed. The bug would have affected only systems that have C<setresgid()>
+but not C<setregid()>, but no such systems are known to exist.
+
+=head1 Deprecations
+
+=head2 Don't read the Unicode data base files in F<lib/unicore>
+
+It is now deprecated to directly read the Unicode data base files.
+These are stored in the F<lib/unicore> directory. Instead, you should
+use the new functions in L<Unicode::UCD>. These provide a stable API,
+and give complete information.
+
+Perl may at some point in the future change or remove these files. The
+file which applications were most likely to have used is
+F<lib/unicore/ToDigit.pl>. L<Unicode::UCD/prop_invmap()> can be used to
+get at its data instead.
+
+=head2 XS functions C<is_utf8_char()>, C<utf8_to_uvchr()> and
+C<utf8_to_uvuni()>
+
+This function is deprecated because it could read beyond the end of the
+input string. Use the new L<is_utf8_char_buf()|/Added is_utf8_char_buf()>,
+C<utf8_to_uvchr_buf()> and C<utf8_to_uvuni_buf()> instead.
+
+=head1 Future Deprecations
+
+This section serves as a notice of features that are I<likely> to be
+removed or L<deprecated|perlpolicy/deprecated> in the next release of
+perl (5.18.0). If your code depends on these features, you should
+contact the Perl 5 Porters via the L<mailing
+list|http://lists.perl.org/list/perl5-porters.html> or L<perlbug> to
+explain your use case and inform the deprecation process.
+
+=head2 Core Modules
+
+These modules may be marked as deprecated I<from the core>. This only
+means that they will no longer be installed by default with the core
+distribution, but will remain available on the CPAN.
+
+=over
+
+=item *
+
+CPANPLUS
+
+=item *
+
+Filter::Simple
+
+=item *
+
+PerlIO::mmap
+
+=item *
+
+Pod::LaTeX
+
+=item *
+
+Pod::Parser
+
+=item *
+
+SelfLoader
+
+=item *
+
+Text::Soundex
+
+=item *
+
+Thread.pm
+
+=back
+
+=head2 Platforms with no supporting programmers
+
+These platforms will probably have their
+special build support removed during the
+5.17.0 development series.
+
+=over
+
+=item *
+
+BeOS
+
+=item *
+
+djgpp
+
+=item *
+
+dgux
+
+=item *
+
+EPOC
+
+=item *
+
+MPE/iX
+
+=item *
+
+Rhapsody
+
+=item *
+
+UTS
+
+=item *
+
+VM/ESA
+
+=back
+
+=head2 Other Future Deprecations
+
+=over
+
+=item *
+
+Swapping of $< and $>
+
+For more information about this future deprecation, see L<the relevant RT
+ticket|https://rt.perl.org/rt3/Ticket/Display.html?id=96212>.
+
+=item *
+
+sfio, stdio
+
+Perl supports being built without PerlIO proper, using a stdio or sfio
+wrapper instead. A perl build like this will not support IO layers and
+thus Unicode IO, making it rather handicapped.
+
+PerlIO supports a C<stdio> layer if stdio use is desired, and similarly a
+sfio layer could be produced.
+
+=item *
+
+Unescaped literal C<< "{" >> in regular expressions.
+
+Starting with v5.20, it is planned to require a literal C<"{"> to be
+escaped, for example by preceding it with a backslash. In v5.18, a
+deprecated warning message will be emitted for all such uses.
+This affects only patterns that are to match a literal C<"{">. Other
+uses of this character, such as part of a quantifier or sequence as in
+those below, are completely unaffected:
+
+ /foo{3,5}/
+ /\p{Alphabetic}/
+ /\N{DIGIT ZERO}
+
+Removing this will permit extensions to Perl's pattern syntax and better
+error checking for existing syntax. See L<perlre/Quantifiers> for an
+example.
+
+=item *
+
+Revamping C<< "\Q" >> semantics in double-quotish strings when combined with other escapes.
+
+There are several bugs and inconsistencies involving combinations
+of C<\Q> and escapes like C<\x>, C<\L>, etc., within a C<\Q...\E> pair.
+These need to be fixed, and doing so will necessarily change current
+behavior. The changes have not yet been settled.
+
+=back
+
+=head1 Incompatible Changes
+
+=head2 Special blocks called in void context
+
+Special blocks (C<BEGIN>, C<CHECK>, C<INIT>, C<UNITCHECK>, C<END>) are now
+called in void context. This avoids wasteful copying of the result of the
+last statement [perl #108794].
+
+=head2 The C<overloading> pragma and regexp objects
+
+With C<no overloading>, regular expression objects returned by C<qr//> are
+now stringified as "Regexp=REGEXP(0xbe600d)" instead of the regular
+expression itself [perl #108780].
+
+=head2 Two XS typemap Entries removed
+
+Two presumably unused XS typemap entries have been removed from the
+core typemap: T_DATAUNIT and T_CALLBACK. If you are, against all odds,
+a user of these, please see the instructions on how to restore them
+in L<perlxstypemap>.
+
+=head2 Unicode 6.1 has incompatibilities with Unicode 6.0
+
+These are detailed in L</Supports (almost) Unicode 6.1> above.
+You can compile this version of Perl to use Unicode 6.0. See
+L<perlunicode/Hacking Perl to work on earlier Unicode versions (for very serious hackers only)>.
+
+=head2 Borland compiler
+
+All support for the Borland compiler has been dropped. The code had not
+worked for a long time anyway.
+
+=head2 Certain deprecated Unicode properties are no longer supported by default
+
+Perl should never have exposed certain Unicode properties that are used
+by Unicode internally and not meant to be publicly available. Use of
+these has generated deprecated warning messages since Perl 5.12. The
+removed properties are Other_Alphabetic,
+Other_Default_Ignorable_Code_Point, Other_Grapheme_Extend,
+Other_ID_Continue, Other_ID_Start, Other_Lowercase, Other_Math, and
+Other_Uppercase.
+
+Perl may be recompiled to include any or all of them; instructions are
+given in
+L<perluniprops/Unicode character properties that are NOT accepted by Perl>.
+
+=head2 Dereferencing IO thingies as typeglobs
+
+The C<*{...}> operator, when passed a reference to an IO thingy (as in
+C<*{*STDIN{IO}}>), creates a new typeglob containing just that IO object.
+Previously, it would stringify as an empty string, but some operators would
+treat it as undefined, producing an "uninitialized" warning.
+Now it stringifies as __ANONIO__ [perl #96326].
+
+=head2 User-defined case-changing operations
+
+This feature was deprecated in Perl 5.14, and has now been removed.
+The CPAN module L<Unicode::Casing> provides better functionality without
+the drawbacks that this feature had, as are detailed in the 5.14
+documentation:
+L<http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29>
+
+=head2 XSUBs are now 'static'
+
+XSUB C functions are now 'static', that is, they are not visible from
+outside the compilation unit. Users can use the new C<XS_EXTERNAL(name)>
+and C<XS_INTERNAL(name)> macros to pick the desired linking behavior.
+The ordinary C<XS(name)> declaration for XSUBs will continue to declare
+non-'static' XSUBs for compatibility, but the XS compiler,
+L<ExtUtils::ParseXS> (C<xsubpp>) will emit 'static' XSUBs by default.
+L<ExtUtils::ParseXS>'s behavior can be reconfigured from XS using the
+C<EXPORT_XSUB_SYMBOLS> keyword. See L<perlxs> for details.
+
+=head2 Weakening read-only references
+
+Weakening read-only references is no longer permitted. It should never
+have worked anyway, and could sometimes result in crashes.
+
+=head2 Tying scalars that hold typeglobs
+
+Attempting to tie a scalar after a typeglob was assigned to it would
+instead tie the handle in the typeglob's IO slot. This meant that it was
+impossible to tie the scalar itself. Similar problems affected C<tied> and
+C<untie>: C<tied $scalar> would return false on a tied scalar if the last
+thing returned was a typeglob, and C<untie $scalar> on such a tied scalar
+would do nothing.
+
+We fixed this problem before Perl 5.14.0, but it caused problems with some
+CPAN modules, so we put in a deprecation cycle instead.
+
+Now the deprecation has been removed and this bug has been fixed. So
+C<tie $scalar> will always tie the scalar, not the handle it holds. To tie
+the handle, use C<tie *$scalar> (with an explicit asterisk). The same
+applies to C<tied *$scalar> and C<untie *$scalar>.
+
+=head2 IPC::Open3 no longer provides C<xfork()>, C<xclose_on_exec()>
+and C<xpipe_anon()>
+
+All three functions were private, undocumented, and unexported. They do
+not appear to be used by any code on CPAN. Two have been inlined and one
+deleted entirely.
+
+=head2 C<$$> no longer caches PID
+
+Previously, if one called fork(3) from C, Perl's
+notion of C<$$> could go out of sync with what getpid() returns. By always
+fetching the value of C<$$> via getpid(), this potential bug is eliminated.
+Code that depends on the caching behavior will break. As described in
+L<Core Enhancements|/C<$$> can be assigned to>,
+C<$$> is now writable, but it will be reset during a
+fork.
+
+=head2 C<$$> and C<getppid()> no longer emulate POSIX semantics under LinuxThreads
+
+The POSIX emulation of C<$$> and C<getppid()> under the obsolete
+LinuxThreads implementation has been removed.
+This only impacts users of Linux 2.4 and
+users of Debian GNU/kFreeBSD up to and including 6.0, not the vast
+majority of Linux installations that use NPTL threads.
+
+This means that C<getppid()>, like C<$$>, is now always guaranteed to
+return the OS's idea of the current state of the process, not perl's
+cached version of it.
+
+See the documentation for L<$$|perlvar/$$> for details.
+
+=head2 C<< $< >>, C<< $> >>, C<$(> and C<$)> are no longer cached
+
+Similarly to the changes to C<$$> and C<getppid()>, the internal
+caching of C<< $< >>, C<< $> >>, C<$(> and C<$)> has been removed.
+
+When we cached these values our idea of what they were would drift out
+of sync with reality if someone (e.g., someone embedding perl) called
+C<sete?[ug]id()> without updating C<PL_e?[ug]id>. Having to deal with
+this complexity wasn't worth it given how cheap the C<gete?[ug]id()>
+system call is.
+
+This change will break a handful of CPAN modules that use the XS-level
+C<PL_uid>, C<PL_gid>, C<PL_euid> or C<PL_egid> variables.
+
+The fix for those breakages is to use C<PerlProc_gete?[ug]id()> to
+retrieve them (e.g., C<PerlProc_getuid()>), and not to assign to
+C<PL_e?[ug]id> if you change the UID/GID/EUID/EGID. There is no longer
+any need to do so since perl will always retrieve the up-to-date
+version of those values from the OS.
+
+=head2 Which Non-ASCII characters get quoted by C<quotemeta> and C<\Q> has changed
+
+This is unlikely to result in a real problem, as Perl does not attach
+special meaning to any non-ASCII character, so it is currently
+irrelevant which are quoted or not. This change fixes bug [perl #77654] and
+brings Perl's behavior more into line with Unicode's recommendations.
+See L<perlfunc/quotemeta>.
+
+=head1 Performance Enhancements
+
+=over
+
+=item *
+
+Improved performance for Unicode properties in regular expressions
+
+=for comment Can this be compacted some? -- rjbs, 2012-02-20
+
+Matching a code point against a Unicode property is now done via a
+binary search instead of linear. This means for example that the worst
+case for a 1000 item property is 10 probes instead of 1000. This
+inefficiency has been compensated for in the past by permanently storing
+in a hash the results of a given probe plus the results for the adjacent
+64 code points, under the theory that near-by code points are likely to
+be searched for. A separate hash was used for each mention of a Unicode
+property in each regular expression. Thus, C<qr/\p{foo}abc\p{foo}/>
+would generate two hashes. Any probes in one instance would be unknown
+to the other, and the hashes could expand separately to be quite large
+if the regular expression were used on many different widely-separated
+code points.
+Now, however, there is just one hash shared by all instances of a given
+property. This means that if C<\p{foo}> is matched against "A" in one
+regular expression in a thread, the result will be known immediately to
+all regular expressions, and the relentless march of using up memory is
+slowed considerably.
+
+=item *
+
+Version declarations with the C<use> keyword (e.g., C<use 5.012>) are now
+faster, as they enable features without loading F<feature.pm>.
+
+=item *
+
+C<local $_> is faster now, as it no longer iterates through magic that it
+is not going to copy anyway.
+
+=item *
+
+Perl 5.12.0 sped up the destruction of objects whose classes define
+empty C<DESTROY> methods (to prevent autoloading), by simply not
+calling such empty methods. This release takes this optimization a
+step further, by not calling any C<DESTROY> method that begins with a
+C<return> statement. This can be useful for destructors that are only
+used for debugging:
+
+ use constant DEBUG => 1;
+ sub DESTROY { return unless DEBUG; ... }
+
+Constant-folding will reduce the first statement to C<return;> if DEBUG
+is set to 0, triggering this optimization.
+
+=item *
+
+Assigning to a variable that holds a typeglob or copy-on-write scalar
+is now much faster. Previously the typeglob would be stringified or
+the copy-on-write scalar would be copied before being clobbered.
+
+=item *
+
+Assignment to C<substr> in void context is now more than twice its
+previous speed. Instead of creating and returning a special lvalue
+scalar that is then assigned to, C<substr> modifies the original string
+itself.
+
+=item *
+
+C<substr> no longer calculates a value to return when called in void
+context.
+
+=item *
+
+Due to changes in L<File::Glob>, Perl's C<glob> function and its C<<
+<...> >> equivalent are now much faster. The splitting of the pattern
+into words has been rewritten in C, resulting in speed-ups of 20% for
+some cases.
+
+This does not affect C<glob> on VMS, as it does not use File::Glob.
+
+=item *
+
+The short-circuiting operators C<&&>, C<||>, and C<//>, when chained
+(such as C<$a || $b || $c>), are now considerably faster to short-circuit,
+due to reduced optree traversal.
+
+=item *
+
+The implementation of C<s///r> makes one fewer copy of the scalar's value.
+
+=item *
+
+Recursive calls to lvalue subroutines in lvalue scalar context use less
+memory.
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 Deprecated Modules
+
+=over
+
+=item L<Version::Requirements>
+
+Version::Requirements is now DEPRECATED, use L<CPAN::Meta::Requirements>,
+which is a drop-in replacement. It will be deleted from perl.git blead
+in v5.17.0.
+
+=back
+
+=head2 New Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<arybase> -- this new module implements the C<$[> variable.
+
+=item *
+
+L<PerlIO::mmap> 0.010 has been added to the Perl core.
+
+The C<mmap> PerlIO layer is no longer implemented by perl itself, but has
+been moved out into the new L<PerlIO::mmap> module.
+
+=back
+
+=head2 Updated Modules and Pragmata
+
+This is only an overview of selected module updates. For a complete list of
+updates, run:
+
+ $ corelist --diff 5.14.0 5.16.0
+
+You can substitute your favorite version in place of 5.14.0, too.
+
+=over 4
+
+=item *
+
+L<Archive::Extract> has been upgraded from version 0.48 to 0.58.
+
+Includes a fix for FreeBSD to only use C<unzip> if it is located in
+C</usr/local/bin>, as FreeBSD 9.0 will ship with a limited C<unzip> in
+C</usr/bin>.
+
+=item *
+
+L<Archive::Tar> has been upgraded from version 1.76 to 1.82.
+
+Adjustments to handle files >8gb (>0777777777777 octal) and a feature
+to return the MD5SUM of files in the archive.
+
+=item *
+
+L<base> has been upgraded from version 2.16 to 2.18.
+
+C<base> no longer sets a module's C<$VERSION> to "-1" when a module it
+loads does not define a C<$VERSION>. This change has been made because
+"-1" is not a valid version number under the new "lax" criteria used
+internally by C<UNIVERSAL::VERSION>. (See L<version> for more on "lax"
+version criteria.)
+
+C<base> no longer internally skips loading modules it has already loaded
+and instead relies on C<require> to inspect C<%INC>. This fixes a bug
+when C<base> is used with code that clear C<%INC> to force a module to
+be reloaded.
+
+=item *
+
+L<Carp> has been upgraded from version 1.20 to 1.26.
+
+It now includes last read filehandle info and puts a dot after the file
+and line number, just like errors from C<die> [perl #106538].
+
+=item *
+
+L<charnames> has been updated from version 1.18 to 1.30.
+
+C<charnames> can now be invoked with a new option, C<:loose>,
+which is like the existing C<:full> option, but enables Unicode loose
+name matching. Details are in L<charnames/LOOSE MATCHES>.
+
+=item *
+
+L<B::Deparse> has been upgraded from version 1.03 to 1.14. This fixes
+numerous deparsing bugs.
+
+=item *
+
+L<CGI> has been upgraded from version 3.52 to 3.59.
+
+It uses the public and documented FCGI.pm API in CGI::Fast. CGI::Fast was
+using an FCGI API that was deprecated and removed from documentation
+more than ten years ago. Usage of this deprecated API with FCGI E<gt>=
+0.70 or FCGI E<lt>= 0.73 introduces a security issue.
+L<https://rt.cpan.org/Public/Bug/Display.html?id=68380>
+L<http://web.nvd.nist.gov/view/vuln/detail?vulnId=CVE-2011-2766>
+
+Things that may break your code:
+
+C<url()> was fixed to return C<PATH_INFO> when it is explicitly requested
+with either the C<path=E<gt>1> or C<path_info=E<gt>1> flag.
+
+If your code is running under mod_rewrite (or compatible) and you are
+calling C<self_url()> or you are calling C<url()> and passing
+C<path_info=E<gt>1>, these methods will actually be returning
+C<PATH_INFO> now, as you have explicitly requested or C<self_url()>
+has requested on your behalf.
+
+The C<PATH_INFO> has been omitted in such URLs since the issue was
+introduced in the 3.12 release in December, 2005.
+
+This bug is so old your application may have come to depend on it or
+workaround it. Check for application before upgrading to this release.
+
+Examples of affected method calls:
+
+ $q->url(-absolute => 1, -query => 1, -path_info => 1);
+ $q->url(-path=>1);
+ $q->url(-full=>1,-path=>1);
+ $q->url(-rewrite=>1,-path=>1);
+ $q->self_url();
+
+We no longer read from STDIN when the Content-Length is not set,
+preventing requests with no Content-Length from sometimes freezing.
+This is consistent with the CGI RFC 3875, and is also consistent with
+CGI::Simple. However, the old behavior may have been expected by some
+command-line uses of CGI.pm.
+
+In addition, the DELETE HTTP verb is now supported.
+
+=item *
+
+L<Compress::Zlib> has been upgraded from version 2.035 to 2.048.
+
+IO::Compress::Zip and IO::Uncompress::Unzip now have support for LZMA
+(method 14). There is a fix for a CRC issue in IO::Compress::Unzip and
+it supports Streamed Stored context now. And fixed a Zip64 issue in
+IO::Compress::Zip when the content size was exactly 0xFFFFFFFF.
+
+=item *
+
+L<Digest::SHA> has been upgraded from version 5.61 to 5.71.
+
+Added BITS mode to the addfile method and shasum. This makes
+partial-byte inputs possible via files/STDIN and lets shasum check
+all 8074 NIST Msg vectors, where previously special programming was
+required to do this.
+
+=item *
+
+L<Encode> has been upgraded from version 2.42 to 2.44.
+
+Missing aliases added, a deep recursion error fixed and various
+documentation updates.
+
+Addressed 'decode_xs n-byte heap-overflow' security bug in Unicode.xs
+(CVE-2011-2939). (5.14.2)
+
+=item *
+
+L<ExtUtils::CBuilder> updated from version 0.280203 to 0.280206.
+
+The new version appends CFLAGS and LDFLAGS to their Config.pm
+counterparts.
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded from version 2.2210 to 3.16.
+
+Much of L<ExtUtils::ParseXS>, the module behind the XS compiler C<xsubpp>,
+was rewritten and cleaned up. It has been made somewhat more extensible
+and now finally uses strictures.
+
+The typemap logic has been moved into a separate module,
+L<ExtUtils::Typemaps>. See L</New Modules and Pragmata>, above.
+
+For a complete set of changes, please see the ExtUtils::ParseXS
+changelog, available on the CPAN.
+
+=item *
+
+L<File::Glob> has been upgraded from version 1.12 to 1.17.
+
+On Windows, tilde (~) expansion now checks the C<USERPROFILE> environment
+variable, after checking C<HOME>.
+
+It has a new C<:bsd_glob> export tag, intended to replace C<:glob>. Like
+C<:glob> it overrides C<glob> with a function that does not split the glob
+pattern into words, but, unlike C<:glob>, it iterates properly in scalar
+context, instead of returning the last file.
+
+There are other changes affecting Perl's own C<glob> operator (which uses
+File::Glob internally, except on VMS). See L</Performance Enhancements>
+and L</Selected Bug Fixes>.
+
+=item *
+
+L<FindBin> updated from version 1.50 to 1.51.
+
+It no longer returns a wrong result if a script of the same name as the
+current one exists in the path and is executable.
+
+=item *
+
+L<HTTP::Tiny> has been upgraded from version 0.012 to 0.017.
+
+Added support for using C<$ENV{http_proxy}> to set the default proxy host.
+
+Adds additional shorthand methods for all common HTTP verbs,
+a C<post_form()> method for POST-ing x-www-form-urlencoded data and
+a C<www_form_urlencode()> utility method.
+
+=item *
+
+L<IO> has been upgraded from version 1.25_04 to 1.25_06, and L<IO::Handle>
+from version 1.31 to 1.33.
+
+Together, these upgrades fix a problem with IO::Handle's C<getline> and
+C<getlines> methods. When these methods are called on the special ARGV
+handle, the next file is automatically opened, as happens with the built-in
+C<E<lt>E<gt>> and C<readline> functions. But, unlike the built-ins, these
+methods were not respecting the caller's use of the L<open> pragma and
+applying the appropriate I/O layers to the newly-opened file
+[rt.cpan.org #66474].
+
+=item *
+
+L<IPC::Cmd> has been upgraded from version 0.70 to 0.76.
+
+Capturing of command output (both C<STDOUT> and C<STDERR>) is now supported
+using L<IPC::Open3> on MSWin32 without requiring L<IPC::Run>.
+
+=item *
+
+L<IPC::Open3> has been upgraded from version 1.09 to 1.12.
+
+Fixes a bug which prevented use of C<open3> on Windows when C<*STDIN>,
+C<*STDOUT> or C<*STDERR> had been localized.
+
+Fixes a bug which prevented duplicating numeric file descriptors on Windows.
+
+C<open3> with "-" for the program name works once more. This was broken in
+version 1.06 (and hence in Perl 5.14.0) [perl #95748].
+
+=item *
+
+L<Locale::Codes> has been upgraded from version 3.16 to 3.21.
+
+Added Language Extension codes (langext) and Language Variation codes (langvar)
+as defined in the IANA language registry.
+
+Added language codes from ISO 639-5
+
+Added language/script codes from the IANA language subtag registry
+
+Fixed an uninitialized value warning [rt.cpan.org #67438].
+
+Fixed the return value for the all_XXX_codes and all_XXX_names functions
+[rt.cpan.org #69100].
+
+Reorganized modules to move Locale::MODULE to Locale::Codes::MODULE to allow
+for cleaner future additions. The original four modules (Locale::Language,
+Locale::Currency, Locale::Country, Locale::Script) will continue to work, but
+all new sets of codes will be added in the Locale::Codes namespace.
+
+The code2XXX, XXX2code, all_XXX_codes, and all_XXX_names functions now
+support retired codes. All codesets may be specified by a constant or
+by their name now. Previously, they were specified only by a constant.
+
+The alias_code function exists for backward compatibility. It has been
+replaced by rename_country_code. The alias_code function will be
+removed some time after September, 2013.
+
+All work is now done in the central module (Locale::Codes). Previously,
+some was still done in the wrapper modules (Locale::Codes::*). Added
+Language Family codes (langfam) as defined in ISO 639-5.
+
+=item *
+
+L<Math::BigFloat> has been upgraded from version 1.993 to 1.997.
+
+The C<numify> method has been corrected to return a normalized Perl number
+(the result of C<0 + $thing>), instead of a string [rt.cpan.org #66732].
+
+=item *
+
+L<Math::BigInt> has been upgraded from version 1.994 to 1.998.
+
+It provides a new C<bsgn> method that complements the C<babs> method.
+
+It fixes the internal C<objectify> function's handling of "foreign objects"
+so they are converted to the appropriate class (Math::BigInt or
+Math::BigFloat).
+
+=item *
+
+L<Math::BigRat> has been upgraded from version 0.2602 to 0.2603.
+
+C<int()> on a Math::BigRat object containing -1/2 now creates a
+Math::BigInt containing 0, rather than -0. L<Math::BigInt> does not even
+support negative zero, so the resulting object was actually malformed
+[perl #95530].
+
+=item *
+
+L<Math::Complex> has been upgraded from version 1.56 to 1.59
+and L<Math::Trig> from version 1.2 to 1.22.
+
+Fixes include: correct copy constructor usage; fix polarwise formatting with
+numeric format specifier; and more stable C<great_circle_direction> algorithm.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.51 to 2.66.
+
+The C<corelist> utility now understands the C<-r> option for displaying
+Perl release dates and the C<--diff> option to print the set of modlib
+changes between two perl distributions.
+
+=item *
+
+L<Module::Metadata> has been upgraded from version 1.000004 to 1.000009.
+
+Adds C<provides> method to generate a CPAN META provides data structure
+correctly; use of C<package_versions_from_directory> is discouraged.
+
+=item *
+
+L<ODBM_File> has been upgraded from version 1.10 to 1.12.
+
+The XS code is now compiled with C<PERL_NO_GET_CONTEXT>, which will aid
+performance under ithreads.
+
+=item *
+
+L<open> has been upgraded from version 1.08 to 1.10.
+
+It no longer turns off layers on standard handles when invoked without the
+":std" directive. Similarly, when invoked I<with> the ":std" directive, it
+now clears layers on STDERR before applying the new ones, and not just on
+STDIN and STDOUT [perl #92728].
+
+=item *
+
+L<overload> has been upgraded from version 1.13 to 1.18.
+
+C<overload::Overloaded> no longer calls C<can> on the class, but uses
+another means to determine whether the object has overloading. It was
+never correct for it to call C<can>, as overloading does not respect
+AUTOLOAD. So classes that autoload methods and implement C<can> no longer
+have to account for overloading [perl #40333].
+
+A warning is now produced for invalid arguments. See L</New Diagnostics>.
+
+=item *
+
+L<PerlIO::scalar> has been upgraded from version 0.11 to 0.14.
+
+(This is the module that implements C<< open $fh, '>', \$scalar >>.)
+
+It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
+C<$scalar> is a copy-on-write scalar. (5.14.2)
+
+It also fixes a hang that occurs with C<readline> or C<< <$fh> >> if a
+typeglob has been assigned to $scalar [perl #92258].
+
+It no longer assumes during C<seek> that $scalar is a string internally.
+If it didn't crash, it was close to doing so [perl #92706]. Also, the
+internal print routine no longer assumes that the position set by C<seek>
+is valid, but extends the string to that position, filling the intervening
+bytes (between the old length and the seek position) with nulls
+[perl #78980].
+
+Printing to an in-memory handle now works if the $scalar holds a reference,
+stringifying the reference before modifying it. References used to be
+treated as empty strings.
+
+Printing to an in-memory handle no longer crashes if the $scalar happens to
+hold a number internally, but no string buffer.
+
+Printing to an in-memory handle no longer creates scalars that confuse
+the regular expression engine [perl #108398].
+
+=item *
+
+L<Pod::Functions> has been upgraded from version 1.04 to 1.05.
+
+F<Functions.pm> is now generated at perl build time from annotations in
+F<perlfunc.pod>. This will ensure that L<Pod::Functions> and L<perlfunc>
+remain in synchronisation.
+
+=item *
+
+L<Pod::Html> has been upgraded from version 1.11 to 1.1502.
+
+This is an extensive rewrite of Pod::Html to use L<Pod::Simple> under
+the hood. The output has changed significantly.
+
+=item *
+
+L<Pod::Perldoc> has been upgraded from version 3.15_03 to 3.17.
+
+It corrects the search paths on VMS [perl #90640]. (5.14.1)
+
+The B<-v> option now fetches the right section for C<$0>.
+
+This upgrade has numerous significant fixes. Consult its changelog on
+the CPAN for more information.
+
+=item *
+
+L<POSIX> has been upgraded from version 1.24 to 1.30.
+
+L<POSIX> no longer uses L<AutoLoader>. Any code which was relying on this
+implementation detail was buggy, and may fail because of this change.
+The module's Perl code has been considerably simplified, roughly halving
+the number of lines, with no change in functionality. The XS code has
+been refactored to reduce the size of the shared object by about 12%,
+with no change in functionality. More POSIX functions now have tests.
+
+C<sigsuspend> and C<pause> now run signal handlers before returning, as the
+whole point of these two functions is to wait until a signal has
+arrived, and then return I<after> it has been triggered. Delayed, or
+"safe", signals were preventing that from happening, possibly resulting in
+race conditions [perl #107216].
+
+C<POSIX::sleep> is now a direct call into the underlying OS C<sleep>
+function, instead of being a Perl wrapper on C<CORE::sleep>.
+C<POSIX::dup2> now returns the correct value on Win32 (I<i.e.>, the file
+descriptor). C<POSIX::SigSet> C<sigsuspend> and C<sigpending> and
+C<POSIX::pause> now dispatch safe signals immediately before returning to
+their caller.
+
+C<POSIX::Termios::setattr> now defaults the third argument to C<TCSANOW>,
+instead of 0. On most platforms C<TCSANOW> is defined to be 0, but on some
+0 is not a valid parameter, which caused a call with defaults to fail.
+
+=item *
+
+L<Socket> has been upgraded from version 1.94 to 2.001.
+
+It has new functions and constants for handling IPv6 sockets:
+
+ pack_ipv6_mreq
+ unpack_ipv6_mreq
+ IPV6_ADD_MEMBERSHIP
+ IPV6_DROP_MEMBERSHIP
+ IPV6_MTU
+ IPV6_MTU_DISCOVER
+ IPV6_MULTICAST_HOPS
+ IPV6_MULTICAST_IF
+ IPV6_MULTICAST_LOOP
+ IPV6_UNICAST_HOPS
+ IPV6_V6ONLY
+
+=item *
+
+L<Storable> has been upgraded from version 2.27 to 2.34.
+
+It no longer turns copy-on-write scalars into read-only scalars when
+freezing and thawing.
+
+=item *
+
+L<Sys::Syslog> has been upgraded from version 0.27 to 0.29.
+
+This upgrade closes many outstanding bugs.
+
+=item *
+
+L<Term::ANSIColor> has been upgraded from version 3.00 to 3.01.
+
+Only interpret an initial array reference as a list of colors, not any initial
+reference, allowing the colored function to work properly on objects with
+stringification defined.
+
+=item *
+
+L<Term::ReadLine> has been upgraded from version 1.07 to 1.09.
+
+Term::ReadLine now supports any event loop, including unpublished ones and
+simple L<IO::Select>, loops without the need to rewrite existing code for
+any particular framework [perl #108470].
+
+=item *
+
+L<threads::shared> has been upgraded from version 1.37 to 1.40.
+
+Destructors on shared objects used to be ignored sometimes if the objects
+were referenced only by shared data structures. This has been mostly
+fixed, but destructors may still be ignored if the objects still exist at
+global destruction time [perl #98204].
+
+=item *
+
+L<Unicode::Collate> has been upgraded from version 0.73 to 0.89.
+
+Updated to CLDR 1.9.1
+
+Locales updated to CLDR 2.0: mk, mt, nb, nn, ro, ru, sk, sr, sv, uk,
+zh__pinyin, zh__stroke
+
+Newly supported locales: bn, fa, ml, mr, or, pa, sa, si, si__dictionary,
+sr_Latn, sv__reformed, ta, te, th, ur, wae.
+
+Tailored compatibility ideographs as well as unified ideographs for the
+locales: ja, ko, zh__big5han, zh__gb2312han, zh__pinyin, zh__stroke.
+
+Locale/*.pl files are now searched for in @INC.
+
+=item *
+
+L<Unicode::Normalize> has been upgraded from version 1.10 to 1.14.
+
+Fixes for the removal of F<unicore/CompositionExclusions.txt> from core.
+
+=item *
+
+L<Unicode::UCD> has been upgraded from version 0.32 to 0.43.
+
+This adds four new functions: C<prop_aliases()> and
+C<prop_value_aliases()>, which are used to find all Unicode-approved
+synonyms for property names, or to convert from one name to another;
+C<prop_invlist> which returns all code points matching a given
+Unicode binary property; and C<prop_invmap> which returns the complete
+specification of a given Unicode property.
+
+=item *
+
+L<Win32API::File> has been upgraded from version 0.1101 to 0.1200.
+
+Added SetStdHandle and GetStdHandle functions
+
+=back
+
+=head2 Removed Modules and Pragmata
+
+As promised in Perl 5.14.0's release notes, the following modules have
+been removed from the core distribution, and if needed should be installed
+from CPAN instead.
+
+=over
+
+=item *
+
+L<Devel::DProf> has been removed from the Perl core. Prior version was
+20110228.00.
+
+=item *
+
+L<Shell> has been removed from the Perl core. Prior version was 0.72_01.
+
+=item *
+
+Several old perl4-style libraries which have been deprecated with 5.14
+are now removed:
+
+ abbrev.pl assert.pl bigfloat.pl bigint.pl bigrat.pl cacheout.pl
+ complete.pl ctime.pl dotsh.pl exceptions.pl fastcwd.pl flush.pl
+ getcwd.pl getopt.pl getopts.pl hostname.pl importenv.pl
+ lib/find{,depth}.pl look.pl newgetopt.pl open2.pl open3.pl
+ pwd.pl shellwords.pl stat.pl tainted.pl termcap.pl timelocal.pl
+
+They can be found on CPAN as L<Perl4::CoreLibs>.
+
+=back
+
+=head1 Documentation
+
+=head2 New Documentation
+
+=head3 L<perldtrace>
+
+L<perldtrace> describes Perl's DTrace support, listing the provided probes
+and gives examples of their use.
+
+=head3 L<perlexperiment>
+
+This document is intended to provide a list of experimental features in
+Perl. It is still a work in progress.
+
+=head3 L<perlootut>
+
+This a new OO tutorial. It focuses on basic OO concepts, and then recommends
+that readers choose an OO framework from CPAN.
+
+=head3 L<perlxstypemap>
+
+The new manual describes the XS typemapping mechanism in unprecedented
+detail and combines new documentation with information extracted from
+L<perlxs> and the previously unofficial list of all core typemaps.
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlapi>
+
+=over 4
+
+=item *
+
+The HV API has long accepted negative lengths to show that the key is
+in UTF8. This is now documented.
+
+=item *
+
+The C<boolSV()> macro is now documented.
+
+=back
+
+=head3 L<perlfunc>
+
+=over 4
+
+=item *
+
+C<dbmopen> treats a 0 mode as a special case, that prevents a nonexistent
+file from being created. This has been the case since Perl 5.000, but was
+never documented anywhere. Now the perlfunc entry mentions it
+[perl #90064].
+
+=item *
+
+As an accident of history, C<open $fh, '<:', ...> applies the default
+layers for the platform (C<:raw> on Unix, C<:crlf> on Windows), ignoring
+whatever is declared by L<open.pm|open>. This seems such a useful feature
+it has been documented in L<perlfunc|perlfunc/open> and L<open>.
+
+=item *
+
+The entry for C<split> has been rewritten. It is now far clearer than
+before.
+
+=back
+
+=head3 L<perlguts>
+
+=over 4
+
+=item *
+
+A new section, L<Autoloading with XSUBs|perlguts/Autoloading with XSUBs>,
+has been added, which explains the two APIs for accessing the name of the
+autoloaded sub.
+
+=item *
+
+Some function descriptions in L<perlguts> were confusing, as it was
+not clear whether they referred to the function above or below the
+description. This has been clarified [perl #91790].
+
+=back
+
+=head3 L<perlobj>
+
+=over 4
+
+=item *
+
+This document has been rewritten from scratch, and its coverage of various OO
+concepts has been expanded.
+
+=back
+
+=head3 L<perlop>
+
+=over 4
+
+=item *
+
+Documentation of the smartmatch operator has been reworked and moved from
+perlsyn to perlop where it belongs.
+
+It has also been corrected for the case of C<undef> on the left-hand
+side. The list of different smart match behaviors had an item in the
+wrong place.
+
+=item *
+
+Documentation of the ellipsis statement (C<...>) has been reworked and
+moved from perlop to perlsyn.
+
+=item *
+
+The explanation of bitwise operators has been expanded to explain how they
+work on Unicode strings (5.14.1).
+
+=item *
+
+More examples for C<m//g> have been added (5.14.1).
+
+=item *
+
+The C<<< <<\FOO >>> here-doc syntax has been documented (5.14.1).
+
+=back
+
+=head3 L<perlpragma>
+
+=over 4
+
+=item *
+
+There is now a standard convention for naming keys in the C<%^H>,
+documented under L<Key naming|perlpragma/Key naming>.
+
+=back
+
+=head3 L<perlsec/Laundering and Detecting Tainted Data>
+
+=over 4
+
+=item *
+
+The example function for checking for taintedness contained a subtle
+error. C<$@> needs to be localized to prevent its changing this
+global's value outside the function. The preferred method to check for
+this remains L<Scalar::Util/tainted>.
+
+=back
+
+=head3 L<perllol>
+
+=over
+
+=item *
+
+L<perllol> has been expanded with examples using the new C<push $scalar>
+syntax introduced in Perl 5.14.0 (5.14.1).
+
+=back
+
+=head3 L<perlmod>
+
+=over
+
+=item *
+
+L<perlmod> now states explicitly that some types of explicit symbol table
+manipulation are not supported. This codifies what was effectively already
+the case [perl #78074].
+
+=back
+
+=head3 L<perlpodstyle>
+
+=over 4
+
+=item *
+
+The tips on which formatting codes to use have been corrected and greatly
+expanded.
+
+=item *
+
+There are now a couple of example one-liners for previewing POD files after
+they have been edited.
+
+=back
+
+=head3 L<perlre>
+
+=over
+
+=item *
+
+The C<(*COMMIT)> directive is now listed in the right section
+(L<Verbs without an argument|perlre/Verbs without an argument>).
+
+=back
+
+=head3 L<perlrun>
+
+=over
+
+=item *
+
+L<perlrun> has undergone a significant clean-up. Most notably, the
+B<-0x...> form of the B<-0> flag has been clarified, and the final section
+on environment variables has been corrected and expanded (5.14.1).
+
+=back
+
+=head3 L<perlsub>
+
+=over
+
+=item *
+
+The ($;) prototype syntax, which has existed for rather a long time, is now
+documented in L<perlsub>. It lets a unary function have the same
+precedence as a list operator.
+
+=back
+
+=head3 L<perltie>
+
+=over
+
+=item *
+
+The required syntax for tying handles has been documented.
+
+=back
+
+=head3 L<perlvar>
+
+=over
+
+=item *
+
+The documentation for L<$!|perlvar/$!> has been corrected and clarified.
+It used to state that $! could be C<undef>, which is not the case. It was
+also unclear whether system calls set C's C<errno> or Perl's C<$!>
+[perl #91614].
+
+=item *
+
+Documentation for L<$$|perlvar/$$> has been amended with additional
+cautions regarding changing the process ID.
+
+=back
+
+=head3 Other Changes
+
+=over 4
+
+=item *
+
+L<perlxs> was extended with documentation on inline typemaps.
+
+=item *
+
+L<perlref> has a new L<Circular References|perlref/Circular References>
+section explaining how circularities may not be freed and how to solve that
+with weak references.
+
+=item *
+
+Parts of L<perlapi> were clarified, and Perl equivalents of some C
+functions have been added as an additional mode of exposition.
+
+=item *
+
+A few parts of L<perlre> and L<perlrecharclass> were clarified.
+
+=back
+
+=head2 Removed Documentation
+
+=head3 Old OO Documentation
+
+The old OO tutorials, perltoot, perltooc, and perlboot, have been
+removed. The perlbot (bag of object tricks) document has been removed
+as well.
+
+=head3 Development Deltas
+
+The perldelta files for development releases are no longer packaged with
+perl. These can still be found in the perl source code repository.
+
+=head1 Diagnostics
+
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages. For the complete list of
+diagnostic messages, see L<perldiag>.
+
+=head2 New Diagnostics
+
+=head3 New Errors
+
+=over 4
+
+=item *
+
+L<Cannot set tied @DB::args|perldiag/"Cannot set tied @DB::args">
+
+This error occurs when C<caller> tries to set C<@DB::args> but finds it
+tied. Before this error was added, it used to crash instead.
+
+=item *
+
+L<Cannot tie unreifiable array|perldiag/"Cannot tie unreifiable array">
+
+This error is part of a safety check that the C<tie> operator does before
+tying a special array like C<@_>. You should never see this message.
+
+=item *
+
+L<&CORE::%s cannot be called directly|perldiag/"&CORE::%s cannot be called directly">
+
+This occurs when a subroutine in the C<CORE::> namespace is called
+with C<&foo> syntax or through a reference. Some subroutines
+in this package cannot yet be called that way, but must be
+called as barewords. See L</Subroutines in the C<CORE> namespace>, above.
+
+=item *
+
+L<Source filters apply only to byte streams|perldiag/"Source filters apply only to byte streams">
+
+This new error occurs when you try to activate a source filter (usually by
+loading a source filter module) within a string passed to C<eval> under the
+C<unicode_eval> feature.
+
+=back
+
+=head3 New Warnings
+
+=over 4
+
+=item *
+
+L<defined(@array) is deprecated|perldiag/"defined(@array) is deprecated">
+
+The long-deprecated C<defined(@array)> now also warns for package variables.
+Previously it issued a warning for lexical variables only.
+
+=item *
+
+L<length() used on %s|perldiag/length() used on %s>
+
+This new warning occurs when C<length> is used on an array or hash, instead
+of C<scalar(@array)> or C<scalar(keys %hash)>.
+
+=item *
+
+L<lvalue attribute %s already-defined subroutine|perldiag/"lvalue attribute %s already-defined subroutine">
+
+L<attributes.pm|attributes> now emits this warning when the :lvalue
+attribute is applied to a Perl subroutine that has already been defined, as
+doing so can have unexpected side-effects.
+
+=item *
+
+L<overload arg '%s' is invalid|perldiag/"overload arg '%s' is invalid">
+
+This warning, in the "overload" category, is produced when the overload
+pragma is given an argument it doesn't recognize, presumably a mistyped
+operator.
+
+=item *
+
+L<$[ used in %s (did you mean $] ?)|perldiag/"$[ used in %s (did you mean $] ?)">
+
+This new warning exists to catch the mistaken use of C<$[> in version
+checks. C<$]>, not C<$[>, contains the version number.
+
+=item *
+
+L<Useless assignment to a temporary|perldiag/"Useless assignment to a temporary">
+
+Assigning to a temporary scalar returned
+from an lvalue subroutine now produces this
+warning [perl #31946].
+
+=item *
+
+L<Useless use of \E|perldiag/"Useless use of \E">
+
+C<\E> does nothing unless preceded by C<\Q>, C<\L> or C<\U>.
+
+=back
+
+=head2 Removed Errors
+
+=over
+
+=item *
+
+"sort is now a reserved word"
+
+This error used to occur when C<sort> was called without arguments,
+followed by C<;> or C<)>. (E.g., C<sort;> would die, but C<{sort}> was
+OK.) This error message was added in Perl 3 to catch code like
+C<close(sort)> which would no longer work. More than two decades later,
+this message is no longer appropriate. Now C<sort> without arguments is
+always allowed, and returns an empty list, as it did in those cases
+where it was already allowed [perl #90030].
+
+=back
+
+=head2 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+The "Applying pattern match..." or similar warning produced when an
+array or hash is on the left-hand side of the C<=~> operator now
+mentions the name of the variable.
+
+=item *
+
+The "Attempt to free non-existent shared string" has had the spelling
+of "non-existent" corrected to "nonexistent". It was already listed
+with the correct spelling in L<perldiag>.
+
+=item *
+
+The error messages for using C<default> and C<when> outside a
+topicalizer have been standardized to match the messages for C<continue>
+and loop controls. They now read 'Can't "default" outside a
+topicalizer' and 'Can't "when" outside a topicalizer'. They both used
+to be 'Can't use when() outside a topicalizer' [perl #91514].
+
+=item *
+
+The message, "Code point 0x%X is not Unicode, no properties match it;
+all inverse properties do" has been changed to "Code point 0x%X is not
+Unicode, all \p{} matches fail; all \P{} matches succeed".
+
+=item *
+
+Redefinition warnings for constant subroutines used to be mandatory,
+even occurring under C<no warnings>. Now they respect the L<warnings>
+pragma.
+
+=item *
+
+The "glob failed" warning message is now suppressible via C<no warnings>
+[perl #111656].
+
+=item *
+
+The L<Invalid version format|perldiag/"Invalid version format (%s)">
+error message now says "negative version number" within the parentheses,
+rather than "non-numeric data", for negative numbers.
+
+=item *
+
+The two warnings
+L<Possible attempt to put comments in qw() list|perldiag/"Possible attempt to put comments in qw() list">
+and
+L<Possible attempt to separate words with commas|perldiag/"Possible attempt to separate words with commas">
+are no longer mutually exclusive: the same C<qw> construct may produce
+both.
+
+=item *
+
+The uninitialized warning for C<y///r> when C<$_> is implicit and
+undefined now mentions the variable name, just like the non-/r variation
+of the operator.
+
+=item *
+
+The 'Use of "foo" without parentheses is ambiguous' warning has been
+extended to apply also to user-defined subroutines with a (;$)
+prototype, and not just to built-in functions.
+
+=item *
+
+Warnings that mention the names of lexical (C<my>) variables with
+Unicode characters in them now respect the presence or absence of the
+C<:utf8> layer on the output handle, instead of outputting UTF8
+regardless. Also, the correct names are included in the strings passed
+to C<$SIG{__WARN__}> handlers, rather than the raw UTF8 bytes.
+
+=back
+
+=head1 Utility Changes
+
+=head3 L<h2ph>
+
+=over 4
+
+=item *
+
+L<h2ph> used to generate code of the form
+
+ unless(defined(&FOO)) {
+ sub FOO () {42;}
+ }
+
+But the subroutine is a compile-time declaration, and is hence unaffected
+by the condition. It has now been corrected to emit a string C<eval>
+around the subroutine [perl #99368].
+
+=back
+
+=head3 L<splain>
+
+=over 4
+
+=item *
+
+F<splain> no longer emits backtraces with the first line number repeated.
+
+This:
+
+ Uncaught exception from user code:
+ Cannot fwiddle the fwuddle at -e line 1.
+ at -e line 1
+ main::baz() called at -e line 1
+ main::bar() called at -e line 1
+ main::foo() called at -e line 1
+
+has become this:
+
+ Uncaught exception from user code:
+ Cannot fwiddle the fwuddle at -e line 1.
+ main::baz() called at -e line 1
+ main::bar() called at -e line 1
+ main::foo() called at -e line 1
+
+=item *
+
+Some error messages consist of multiple lines that are listed as separate
+entries in L<perldiag>. splain has been taught to find the separate
+entries in these cases, instead of simply failing to find the message.
+
+=back
+
+=head3 L<zipdetails>
+
+=over 4
+
+=item *
+
+This is a new utility, included as part of an
+L<IO::Compress::Base> upgrade.
+
+L<zipdetails> displays information about the internal record structure
+of the zip file. It is not concerned with displaying any details of
+the compressed data stored in the zip file.
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+F<regexp.h> has been modified for compatibility with GCC's B<-Werror>
+option, as used by some projects that include perl's header files (5.14.1).
+
+=item *
+
+C<USE_LOCALE{,_COLLATE,_CTYPE,_NUMERIC}> have been added the output of perl -V
+as they have affect the behavior of the interpreter binary (albeit
+in only a small area).
+
+=item *
+
+The code and tests for L<IPC::Open2> have been moved from F<ext/IPC-Open2>
+into F<ext/IPC-Open3>, as C<IPC::Open2::open2()> is implemented as a thin
+wrapper around C<IPC::Open3::_open3()>, and hence is very tightly coupled to
+it.
+
+=item *
+
+The magic types and magic vtables are now generated from data in a new script
+F<regen/mg_vtable.pl>, instead of being maintained by hand. As different
+EBCDIC variants can't agree on the code point for '~', the character to code
+point conversion is done at build time by F<generate_uudmap> to a new generated
+header F<mg_data.h>. C<PL_vtbl_bm> and C<PL_vtbl_fm> are now defined by the
+pre-processor as C<PL_vtbl_regexp>, instead of being distinct C variables.
+C<PL_vtbl_sig> has been removed.
+
+=item *
+
+Building with C<-DPERL_GLOBAL_STRUCT> works again. This configuration is not
+generally used.
+
+=item *
+
+Perl configured with I<MAD> now correctly frees C<MADPROP> structures when
+OPs are freed. C<MADPROP>s are now allocated with C<PerlMemShared_malloc()>
+
+=item *
+
+F<makedef.pl> has been refactored. This should have no noticeable affect on
+any of the platforms that use it as part of their build (AIX, VMS, Win32).
+
+=item *
+
+C<useperlio> can no longer be disabled.
+
+=item *
+
+The file F<global.sym> is no longer needed, and has been removed. It
+contained a list of all exported functions, one of the files generated by
+F<regen/embed.pl> from data in F<embed.fnc> and F<regen/opcodes>. The code
+has been refactored so that the only user of F<global.sym>, F<makedef.pl>,
+now reads F<embed.fnc> and F<regen/opcodes> directly, removing the need to
+store the list of exported functions in an intermediate file.
+
+As F<global.sym> was never installed, this change should not be visible
+outside the build process.
+
+=item *
+
+F<pod/buildtoc>, used by the build process to build L<perltoc>, has been
+refactored and simplified. It now contains only code to build L<perltoc>;
+the code to regenerate Makefiles has been moved to F<Porting/pod_rules.pl>.
+It's a bug if this change has any material effect on the build process.
+
+=item *
+
+F<pod/roffitall> is now built by F<pod/buildtoc>, instead of being
+shipped with the distribution. Its list of manpages is now generated
+(and therefore current). See also RT #103202 for an unresolved related
+issue.
+
+=item *
+
+The man page for C<XS::Typemap> is no longer installed. C<XS::Typemap>
+is a test module which is not installed, hence installing its
+documentation makes no sense.
+
+=item *
+
+The -Dusesitecustomize and -Duserelocatableinc options now work
+together properly.
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=head3 Cygwin
+
+=over 4
+
+=item *
+
+Since version 1.7, Cygwin supports native UTF-8 paths. If Perl is built
+under that environment, directory and filenames will be UTF-8 encoded.
+
+=item *
+
+Cygwin does not initialize all original Win32 environment variables. See
+F<README.cygwin> for a discussion of the newly-added
+C<Cygwin::sync_winenv()> function [perl #110190] and for
+further links.
+
+=back
+
+=head3 HP-UX
+
+=over 4
+
+=item *
+
+HP-UX PA-RISC/64 now supports gcc-4.x
+
+A fix to correct the socketsize now makes the test suite pass on HP-UX
+PA-RISC for 64bitall builds. (5.14.2)
+
+=back
+
+=head3 VMS
+
+=over 4
+
+=item *
+
+Remove unnecessary includes, fix miscellaneous compiler warnings and
+close some unclosed comments on F<vms/vms.c>.
+
+=item *
+
+Remove sockadapt layer from the VMS build.
+
+=item *
+
+Explicit support for VMS versions before v7.0 and DEC C versions
+before v6.0 has been removed.
+
+=item *
+
+Since Perl 5.10.1, the home-grown C<stat> wrapper has been unable to
+distinguish between a directory name containing an underscore and an
+otherwise-identical filename containing a dot in the same position
+(e.g., t/test_pl as a directory and t/test.pl as a file). This problem
+has been corrected.
+
+=item *
+
+The build on VMS now permits names of the resulting symbols in C code for
+Perl longer than 31 characters. Symbols like
+C<Perl__it_was_the_best_of_times_it_was_the_worst_of_times> can now be
+created freely without causing the VMS linker to seize up.
+
+=back
+
+=head3 GNU/Hurd
+
+=over 4
+
+=item *
+
+Numerous build and test failures on GNU/Hurd have been resolved with hints
+for building DBM modules, detection of the library search path, and enabling
+of large file support.
+
+=back
+
+=head3 OpenVOS
+
+=over 4
+
+=item *
+
+Perl is now built with dynamic linking on OpenVOS, the minimum supported
+version of which is now Release 17.1.0.
+
+=back
+
+=head3 SunOS
+
+The CC workshop C++ compiler is now detected and used on systems that ship
+without cc.
+
+=head1 Internal Changes
+
+=over 4
+
+=item *
+
+The compiled representation of formats is now stored via the C<mg_ptr> of
+their C<PERL_MAGIC_fm>. Previously it was stored in the string buffer,
+beyond C<SvLEN()>, the regular end of the string. C<SvCOMPILED()> and
+C<SvCOMPILED_{on,off}()> now exist solely for compatibility for XS code.
+The first is always 0, the other two now no-ops. (5.14.1)
+
+=item *
+
+Some global variables have been marked C<const>, members in the interpreter
+structure have been re-ordered, and the opcodes have been re-ordered. The
+op C<OP_AELEMFAST> has been split into C<OP_AELEMFAST> and C<OP_AELEMFAST_LEX>.
+
+=item *
+
+When empting a hash of its elements (e.g., via undef(%h), or %h=()), HvARRAY
+field is no longer temporarily zeroed. Any destructors called on the freed
+elements see the remaining elements. Thus, %h=() becomes more like
+C<delete $h{$_} for keys %h>.
+
+=item *
+
+Boyer-Moore compiled scalars are now PVMGs, and the Boyer-Moore tables are now
+stored via the mg_ptr of their C<PERL_MAGIC_bm>.
+Previously they were PVGVs, with the tables stored in
+the string buffer, beyond C<SvLEN()>. This eliminates
+the last place where the core stores data beyond C<SvLEN()>.
+
+=item *
+
+Simplified logic in C<Perl_sv_magic()> introduces a small change of
+behavior for error cases involving unknown magic types. Previously, if
+C<Perl_sv_magic()> was passed a magic type unknown to it, it would
+
+=over
+
+=item 1.
+
+Croak "Modification of a read-only value attempted" if read only
+
+=item 2.
+
+Return without error if the SV happened to already have this magic
+
+=item 3.
+
+otherwise croak "Don't know how to handle magic of type \\%o"
+
+=back
+
+Now it will always croak "Don't know how to handle magic of type \\%o", even
+on read-only values, or SVs which already have the unknown magic type.
+
+=item *
+
+The experimental C<fetch_cop_label> function has been renamed to
+C<cop_fetch_label>.
+
+=item *
+
+The C<cop_store_label> function has been added to the API, but is
+experimental.
+
+=item *
+
+F<embedvar.h> has been simplified, and one level of macro indirection for
+PL_* variables has been removed for the default (non-multiplicity)
+configuration. PERLVAR*() macros now directly expand their arguments to
+tokens such as C<PL_defgv>, instead of expanding to C<PL_Idefgv>, with
+F<embedvar.h> defining a macro to map C<PL_Idefgv> to C<PL_defgv>. XS code
+which has unwarranted chumminess with the implementation may need updating.
+
+=item *
+
+An API has been added to explicitly choose whether to export XSUB
+symbols. More detail can be found in the comments for commit e64345f8.
+
+=item *
+
+The C<is_gv_magical_sv> function has been eliminated and merged with
+C<gv_fetchpvn_flags>. It used to be called to determine whether a GV
+should be autovivified in rvalue context. Now it has been replaced with a
+new C<GV_ADDMG> flag (not part of the API).
+
+=item *
+
+The returned code point from the function C<utf8n_to_uvuni()>
+when the input is malformed UTF-8, malformations are allowed, and
+C<utf8> warnings are off is now the Unicode REPLACEMENT CHARACTER
+whenever the malformation is such that no well-defined code point can be
+computed. Previously the returned value was essentially garbage. The
+only malformations that have well-defined values are a zero-length
+string (0 is the return), and overlong UTF-8 sequences.
+
+=item *
+
+Padlists are now marked C<AvREAL>; i.e., reference-counted. They have
+always been reference-counted, but were not marked real, because F<pad.c>
+did its own clean-up, instead of using the usual clean-up code in F<sv.c>.
+That caused problems in thread cloning, so now the C<AvREAL> flag is on,
+but is turned off in F<pad.c> right before the padlist is freed (after
+F<pad.c> has done its custom freeing of the pads).
+
+=item *
+
+All C files that make up the Perl core have been converted to UTF-8.
+
+=item *
+
+These new functions have been added as part of the work on Unicode symbols:
+
+ HvNAMELEN
+ HvNAMEUTF8
+ HvENAMELEN
+ HvENAMEUTF8
+ gv_init_pv
+ gv_init_pvn
+ gv_init_pvsv
+ gv_fetchmeth_pv
+ gv_fetchmeth_pvn
+ gv_fetchmeth_sv
+ gv_fetchmeth_pv_autoload
+ gv_fetchmeth_pvn_autoload
+ gv_fetchmeth_sv_autoload
+ gv_fetchmethod_pv_flags
+ gv_fetchmethod_pvn_flags
+ gv_fetchmethod_sv_flags
+ gv_autoload_pv
+ gv_autoload_pvn
+ gv_autoload_sv
+ newGVgen_flags
+ sv_derived_from_pv
+ sv_derived_from_pvn
+ sv_derived_from_sv
+ sv_does_pv
+ sv_does_pvn
+ sv_does_sv
+ whichsig_pv
+ whichsig_pvn
+ whichsig_sv
+ newCONSTSUB_flags
+
+The gv_fetchmethod_*_flags functions, like gv_fetchmethod_flags, are
+experimental and may change in a future release.
+
+=item *
+
+The following functions were added. These are I<not> part of the API:
+
+ GvNAMEUTF8
+ GvENAMELEN
+ GvENAME_HEK
+ CopSTASH_flags
+ CopSTASH_flags_set
+ PmopSTASH_flags
+ PmopSTASH_flags_set
+ sv_sethek
+ HEKfARG
+
+There is also a C<HEKf> macro corresponding to C<SVf>, for
+interpolating HEKs in formatted strings.
+
+=item *
+
+C<sv_catpvn_flags> takes a couple of new internal-only flags,
+C<SV_CATBYTES> and C<SV_CATUTF8>, which tell it whether the char array to
+be concatenated is UTF8. This allows for more efficient concatenation than
+creating temporary SVs to pass to C<sv_catsv>.
+
+=item *
+
+For XS AUTOLOAD subs, $AUTOLOAD is set once more, as it was in 5.6.0. This
+is in addition to setting C<SvPVX(cv)>, for compatibility with 5.8 to 5.14.
+See L<perlguts/Autoloading with XSUBs>.
+
+=item *
+
+Perl now checks whether the array (the linearized isa) returned by a MRO
+plugin begins with the name of the class itself, for which the array was
+created, instead of assuming that it does. This prevents the first element
+from being skipped during method lookup. It also means that
+C<mro::get_linear_isa> may return an array with one more element than the
+MRO plugin provided [perl #94306].
+
+=item *
+
+C<PL_curstash> is now reference-counted.
+
+=item *
+
+There are now feature bundle hints in C<PL_hints> (C<$^H>) that version
+declarations use, to avoid having to load F<feature.pm>. One setting of
+the hint bits indicates a "custom" feature bundle, which means that the
+entries in C<%^H> still apply. F<feature.pm> uses that.
+
+The C<HINT_FEATURE_MASK> macro is defined in F<perl.h> along with other
+hints. Other macros for setting and testing features and bundles are in
+the new F<feature.h>. C<FEATURE_IS_ENABLED> (which has moved to
+F<feature.h>) is no longer used throughout the codebase, but more specific
+macros, e.g., C<FEATURE_SAY_IS_ENABLED>, that are defined in F<feature.h>.
+
+=item *
+
+F<lib/feature.pm> is now a generated file, created by the new
+F<regen/feature.pl> script, which also generates F<feature.h>.
+
+=item *
+
+Tied arrays are now always C<AvREAL>. If C<@_> or C<DB::args> is tied, it
+is reified first, to make sure this is always the case.
+
+=item *
+
+Two new functions C<utf8_to_uvchr_buf()> and C<utf8_to_uvuni_buf()> have
+been added. These are the same as C<utf8_to_uvchr> and
+C<utf8_to_uvuni> (which are now deprecated), but take an extra parameter
+that is used to guard against reading beyond the end of the input
+string.
+See L<perlapi/utf8_to_uvchr_buf> and L<perlapi/utf8_to_uvuni_buf>.
+
+=item *
+
+The regular expression engine now does TRIE case insensitive matches
+under Unicode. This may change the output of C<< use re 'debug'; >>,
+and will speed up various things.
+
+=item *
+
+There is a new C<wrap_op_checker()> function, which provides a thread-safe
+alternative to writing to C<PL_check> directly.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=head2 Array and hash
+
+=over
+
+=item *
+
+A bug has been fixed that would cause a "Use of freed value in iteration"
+error if the next two hash elements that would be iterated over are
+deleted [perl #85026]. (5.14.1)
+
+=item *
+
+Deleting the current hash iterator (the hash element that would be returned
+by the next call to C<each>) in void context used not to free it
+[perl #85026].
+
+=item *
+
+Deletion of methods via C<delete $Class::{method}> syntax used to update
+method caches if called in void context, but not scalar or list context.
+
+=item *
+
+When hash elements are deleted in void context, the internal hash entry is
+now freed before the value is freed, to prevent destructors called by that
+latter freeing from seeing the hash in an inconsistent state. It was
+possible to cause double-frees if the destructor freed the hash itself
+[perl #100340].
+
+=item *
+
+A C<keys> optimization in Perl 5.12.0 to make it faster on empty hashes
+caused C<each> not to reset the iterator if called after the last element
+was deleted.
+
+=item *
+
+Freeing deeply nested hashes no longer crashes [perl #44225].
+
+=item *
+
+It is possible from XS code to create hashes with elements that have no
+values. The hash element and slice operators used to crash
+when handling these in lvalue context. They now
+produce a "Modification of non-creatable hash value attempted" error
+message.
+
+=item *
+
+If list assignment to a hash or array triggered destructors that freed the
+hash or array itself, a crash would ensue. This is no longer the case
+[perl #107440].
+
+=item *
+
+It used to be possible to free the typeglob of a localized array or hash
+(e.g., C<local @{"x"}; delete $::{x}>), resulting in a crash on scope exit.
+
+=item *
+
+Some core bugs affecting L<Hash::Util> have been fixed: locking a hash
+element that is a glob copy no longer causes the next assignment to it to
+corrupt the glob (5.14.2), and unlocking a hash element that holds a
+copy-on-write scalar no longer causes modifications to that scalar to
+modify other scalars that were sharing the same string buffer.
+
+=back
+
+=head2 C API fixes
+
+=over
+
+=item *
+
+The C<newHVhv> XS function now works on tied hashes, instead of crashing or
+returning an empty hash.
+
+=item *
+
+The C<SvIsCOW> C macro now returns false for read-only copies of typeglobs,
+such as those created by:
+
+ $hash{elem} = *foo;
+ Hash::Util::lock_value %hash, 'elem';
+
+It used to return true.
+
+=item *
+
+The C<SvPVutf8> C function no longer tries to modify its argument,
+resulting in errors [perl #108994].
+
+=item *
+
+C<SvPVutf8> now works properly with magical variables.
+
+=item *
+
+C<SvPVbyte> now works properly non-PVs.
+
+=item *
+
+When presented with malformed UTF-8 input, the XS-callable functions
+C<is_utf8_string()>, C<is_utf8_string_loc()>, and
+C<is_utf8_string_loclen()> could read beyond the end of the input
+string by up to 12 bytes. This no longer happens. [perl #32080].
+However, currently, C<is_utf8_char()> still has this defect, see
+L</is_utf8_char()> above.
+
+=item *
+
+The C-level C<pregcomp> function could become confused about whether the
+pattern was in UTF8 if the pattern was an overloaded, tied, or otherwise
+magical scalar [perl #101940].
+
+=back
+
+=head2 Compile-time hints
+
+=over
+
+=item *
+
+Tying C<%^H> no longer causes perl to crash or ignore the contents of
+C<%^H> when entering a compilation scope [perl #106282].
+
+=item *
+
+C<eval $string> and C<require> used not to
+localize C<%^H> during compilation if it
+was empty at the time the C<eval> call itself was compiled. This could
+lead to scary side effects, like C<use re "/m"> enabling other flags that
+the surrounding code was trying to enable for its caller [perl #68750].
+
+=item *
+
+C<eval $string> and C<require> no longer localize hints (C<$^H> and C<%^H>)
+at run time, but only during compilation of the $string or required file.
+This makes C<BEGIN { $^H{foo}=7 }> equivalent to
+C<BEGIN { eval '$^H{foo}=7' }> [perl #70151].
+
+=item *
+
+Creating a BEGIN block from XS code (via C<newXS> or C<newATTRSUB>) would,
+on completion, make the hints of the current compiling code the current
+hints. This could cause warnings to occur in a non-warning scope.
+
+=back
+
+=head2 Copy-on-write scalars
+
+Copy-on-write or shared hash key scalars
+were introduced in 5.8.0, but most Perl code
+did not encounter them (they were used mostly internally). Perl
+5.10.0 extended them, such that assigning C<__PACKAGE__> or a
+hash key to a scalar would make it copy-on-write. Several parts
+of Perl were not updated to account for them, but have now been fixed.
+
+=over
+
+=item *
+
+C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
+string buffers in place (i.e., skipping the copy). This could result in
+hashes having two elements with the same key [perl #91834]. (5.14.2)
+
+=item *
+
+Lvalue subroutines were not allowing COW scalars to be returned. This was
+fixed for lvalue scalar context in Perl 5.12.3 and 5.14.0, but list context
+was not fixed until this release.
+
+=item *
+
+Elements of restricted hashes (see the L<fields> pragma) containing
+copy-on-write values couldn't be deleted, nor could such hashes be cleared
+(C<%hash = ()>). (5.14.2)
+
+=item *
+
+Localizing a tied variable used to make it read-only if it contained a
+copy-on-write string. (5.14.2)
+
+=item *
+
+Assigning a copy-on-write string to a stash
+element no longer causes a double free. Regardless of this change, the
+results of such assignments are still undefined.
+
+=item *
+
+Assigning a copy-on-write string to a tied variable no longer stops that
+variable from being tied if it happens to be a PVMG or PVLV internally.
+
+=item *
+
+Doing a substitution on a tied variable returning a copy-on-write
+scalar used to cause an assertion failure or an "Attempt to free
+nonexistent shared string" warning.
+
+=item *
+
+This one is a regression from 5.12: In 5.14.0, the bitwise assignment
+operators C<|=>, C<^=> and C<&=> started leaving the left-hand side
+undefined if it happened to be a copy-on-write string [perl #108480].
+
+=item *
+
+L<Storable>, L<Devel::Peek> and L<PerlIO::scalar> had similar problems.
+See L</Updated Modules and Pragmata>, above.
+
+=back
+
+=head2 The debugger
+
+=over
+
+=item *
+
+F<dumpvar.pl>, and therefore the C<x> command in the debugger, have been
+fixed to handle objects blessed into classes whose names contain "=". The
+contents of such objects used not to be dumped [perl #101814].
+
+=item *
+
+The "R" command for restarting a debugger session has been fixed to work on
+Windows, or any other system lacking a C<POSIX::_SC_OPEN_MAX> constant
+[perl #87740].
+
+=item *
+
+The C<#line 42 foo> directive used not to update the arrays of lines used
+by the debugger if it occurred in a string eval. This was partially fixed
+in 5.14, but it worked only for a single C<#line 42 foo> in each eval. Now
+it works for multiple.
+
+=item *
+
+When subroutine calls are intercepted by the debugger, the name of the
+subroutine or a reference to it is stored in C<$DB::sub>, for the debugger
+to access. Sometimes (such as C<$foo = *bar; undef *bar; &$foo>)
+C<$DB::sub> would be set to a name that could not be used to find the
+subroutine, and so the debugger's attempt to call it would fail. Now the
+check to see whether a reference is needed is more robust, so those
+problems should not happen anymore [rt.cpan.org #69862].
+
+=item *
+
+Every subroutine has a filename associated with it that the debugger uses.
+The one associated with constant subroutines used to be misallocated when
+cloned under threads. Consequently, debugging threaded applications could
+result in memory corruption [perl #96126].
+
+=back
+
+=head2 Dereferencing operators
+
+=over
+
+=item *
+
+C<defined(${"..."})>, C<defined(*{"..."})>, etc., used to
+return true for most, but not all built-in variables, if
+they had not been used yet. This bug affected C<${^GLOBAL_PHASE}> and
+C<${^UTF8CACHE}>, among others. It also used to return false if the
+package name was given as well (C<${"::!"}>) [perl #97978, #97492].
+
+=item *
+
+Perl 5.10.0 introduced a similar bug: C<defined(*{"foo"})> where "foo"
+represents the name of a built-in global variable used to return false if
+the variable had never been used before, but only on the I<first> call.
+This, too, has been fixed.
+
+=item *
+
+Since 5.6.0, C<*{ ... }> has been inconsistent in how it treats undefined
+values. It would die in strict mode or lvalue context for most undefined
+values, but would be treated as the empty string (with a warning) for the
+specific scalar return by C<undef()> (C<&PL_sv_undef> internally). This
+has been corrected. C<undef()> is now treated like other undefined
+scalars, as in Perl 5.005.
+
+=back
+
+=head2 Filehandle, last-accessed
+
+Perl has an internal variable that stores the last filehandle to be
+accessed. It is used by C<$.> and by C<tell> and C<eof> without
+arguments.
+
+=over
+
+=item *
+
+It used to be possible to set this internal variable to a glob copy and
+then modify that glob copy to be something other than a glob, and still
+have the last-accessed filehandle associated with the variable after
+assigning a glob to it again:
+
+ my $foo = *STDOUT; # $foo is a glob copy
+ <$foo>; # $foo is now the last-accessed handle
+ $foo = 3; # no longer a glob
+ $foo = *STDERR; # still the last-accessed handle
+
+Now the C<$foo = 3> assignment unsets that internal variable, so there
+is no last-accessed filehandle, just as if C<< <$foo> >> had never
+happened.
+
+This also prevents some unrelated handle from becoming the last-accessed
+handle if $foo falls out of scope and the same internal SV gets used for
+another handle [perl #97988].
+
+=item *
+
+A regression in 5.14 caused these statements not to set that internal
+variable:
+
+ my $fh = *STDOUT;
+ tell $fh;
+ eof $fh;
+ seek $fh, 0,0;
+ tell *$fh;
+ eof *$fh;
+ seek *$fh, 0,0;
+ readline *$fh;
+
+This is now fixed, but C<tell *{ *$fh }> still has the problem, and it
+is not clear how to fix it [perl #106536].
+
+=back
+
+=head2 Filetests and C<stat>
+
+The term "filetests" refers to the operators that consist of a hyphen
+followed by a single letter: C<-r>, C<-x>, C<-M>, etc. The term "stacked"
+when applied to filetests means followed by another filetest operator
+sharing the same operand, as in C<-r -x -w $fooo>.
+
+=over
+
+=item *
+
+C<stat> produces more consistent warnings. It no longer warns for "_"
+[perl #71002] and no longer skips the warning at times for other unopened
+handles. It no longer warns about an unopened handle when the operating
+system's C<fstat> function fails.
+
+=item *
+
+C<stat> would sometimes return negative numbers for large inode numbers,
+because it was using the wrong internal C type. [perl #84590]
+
+=item *
+
+C<lstat> is documented to fall back to C<stat> (with a warning) when given
+a filehandle. When passed an IO reference, it was actually doing the
+equivalent of S<C<stat _>> and ignoring the handle.
+
+=item *
+
+C<-T _> with no preceding C<stat> used to produce a
+confusing "uninitialized" warning, even though there
+is no visible uninitialized value to speak of.
+
+=item *
+
+C<-T>, C<-B>, C<-l> and C<-t> now work
+when stacked with other filetest operators
+[perl #77388].
+
+=item *
+
+In 5.14.0, filetest ops (C<-r>, C<-x>, etc.) started calling FETCH on a
+tied argument belonging to the previous argument to a list operator, if
+called with a bareword argument or no argument at all. This has been
+fixed, so C<push @foo, $tied, -r> no longer calls FETCH on C<$tied>.
+
+=item *
+
+In Perl 5.6, C<-l> followed by anything other than a bareword would treat
+its argument as a file name. That was changed in 5.8 for glob references
+(C<\*foo>), but not for globs themselves (C<*foo>). C<-l> started
+returning C<undef> for glob references without setting the last
+stat buffer that the "_" handle uses, but only if warnings
+were turned on. With warnings off, it was the same as 5.6.
+In other words, it was simply buggy and inconsistent. Now the 5.6
+behavior has been restored.
+
+=item *
+
+C<-l> followed by a bareword no longer "eats" the previous argument to
+the list operator in whose argument list it resides. Hence,
+C<print "bar", -l foo> now actually prints "bar", because C<-l>
+on longer eats it.
+
+=item *
+
+Perl keeps several internal variables to keep track of the last stat
+buffer, from which file(handle) it originated, what type it was, and
+whether the last stat succeeded.
+
+There were various cases where these could get out of synch, resulting in
+inconsistent or erratic behavior in edge cases (every mention of C<-T>
+applies to C<-B> as well):
+
+=over
+
+=item *
+
+C<-T I<HANDLE>>, even though it does a C<stat>, was not resetting the last
+stat type, so an C<lstat _> following it would merrily return the wrong
+results. Also, it was not setting the success status.
+
+=item *
+
+Freeing the handle last used by C<stat> or a filetest could result in
+S<C<-T _>> using an unrelated handle.
+
+=item *
+
+C<stat> with an IO reference would not reset the stat type or record the
+filehandle for S<C<-T _>> to use.
+
+=item *
+
+Fatal warnings could cause the stat buffer not to be reset
+for a filetest operator on an unopened filehandle or C<-l> on any handle.
+Fatal warnings also stopped C<-T> from setting C<$!>.
+
+=item *
+
+When the last stat was on an unreadable file, C<-T _> is supposed to
+return C<undef>, leaving the last stat buffer unchanged. But it was
+setting the stat type, causing C<lstat _> to stop working.
+
+=item *
+
+C<-T I<FILENAME>> was not resetting the internal stat buffers for
+unreadable files.
+
+=back
+
+These have all been fixed.
+
+=back
+
+=head2 Formats
+
+=over
+
+=item *
+
+Several edge cases have been fixed with formats and C<formline>;
+in particular, where the format itself is potentially variable (such as
+with ties and overloading), and where the format and data differ in their
+encoding. In both these cases, it used to possible for the output to be
+corrupted [perl #91032].
+
+=item *
+
+C<formline> no longer converts its argument into a string in-place. So
+passing a reference to C<formline> no longer destroys the reference
+[perl #79532].
+
+=item *
+
+Assignment to C<$^A> (the format output accumulator) now recalculates
+the number of lines output.
+
+=back
+
+=head2 C<given> and C<when>
+
+=over
+
+=item *
+
+C<given> was not scoping its implicit $_ properly, resulting in memory
+leaks or "Variable is not available" warnings [perl #94682].
+
+=item *
+
+C<given> was not calling set-magic on the implicit lexical C<$_> that it
+uses. This meant, for example, that C<pos> would be remembered from one
+execution of the same C<given> block to the next, even if the input were a
+different variable [perl #84526].
+
+=item *
+
+C<when> blocks are now capable of returning variables declared inside the
+enclosing C<given> block [perl #93548].
+
+=back
+
+=head2 The C<glob> operator
+
+=over
+
+=item *
+
+On OSes other than VMS, Perl's C<glob> operator (and the C<< <...> >> form)
+use L<File::Glob> underneath. L<File::Glob> splits the pattern into words,
+before feeding each word to its C<bsd_glob> function.
+
+There were several inconsistencies in the way the split was done. Now
+quotation marks (' and ") are always treated as shell-style word delimiters
+(that allow whitespace as part of a word) and backslashes are always
+preserved, unless they exist to escape quotation marks. Before, those
+would only sometimes be the case, depending on whether the pattern
+contained whitespace. Also, escaped whitespace at the end of the pattern
+is no longer stripped [perl #40470].
+
+=item *
+
+C<CORE::glob> now works as a way to call the default globbing function. It
+used to respect overrides, despite the C<CORE::> prefix.
+
+=item *
+
+Under miniperl (used to configure modules when perl itself is built),
+C<glob> now clears %ENV before calling csh, since the latter croaks on some
+systems if it does not like the contents of the LS_COLORS environment
+variable [perl #98662].
+
+=back
+
+=head2 Lvalue subroutines
+
+=over
+
+=item *
+
+Explicit return now returns the actual argument passed to return, instead
+of copying it [perl #72724, #72706].
+
+=item *
+
+Lvalue subroutines used to enforce lvalue syntax (i.e., whatever can go on
+the left-hand side of C<=>) for the last statement and the arguments to
+return. Since lvalue subroutines are not always called in lvalue context,
+this restriction has been lifted.
+
+=item *
+
+Lvalue subroutines are less restrictive about what values can be returned.
+It used to croak on values returned by C<shift> and C<delete> and from
+other subroutines, but no longer does so [perl #71172].
+
+=item *
+
+Empty lvalue subroutines (C<sub :lvalue {}>) used to return C<@_> in list
+context. All subroutines used to do this, but regular subs were fixed in
+Perl 5.8.2. Now lvalue subroutines have been likewise fixed.
+
+=item *
+
+Autovivification now works on values returned from lvalue subroutines
+[perl #7946], as does returning C<keys> in lvalue context.
+
+=item *
+
+Lvalue subroutines used to copy their return values in rvalue context. Not
+only was this a waste of CPU cycles, but it also caused bugs. A C<($)>
+prototype would cause an lvalue sub to copy its return value [perl #51408],
+and C<while(lvalue_sub() =~ m/.../g) { ... }> would loop endlessly
+[perl #78680].
+
+=item *
+
+When called in potential lvalue context
+(e.g., subroutine arguments or a list
+passed to C<for>), lvalue subroutines used to copy
+any read-only value that was returned. E.g., C< sub :lvalue { $] } >
+would not return C<$]>, but a copy of it.
+
+=item *
+
+When called in potential lvalue context, an lvalue subroutine returning
+arrays or hashes used to bind the arrays or hashes to scalar variables,
+resulting in bugs. This was fixed in 5.14.0 if an array were the first
+thing returned from the subroutine (but not for C<$scalar, @array> or
+hashes being returned). Now a more general fix has been applied
+[perl #23790].
+
+=item *
+
+Method calls whose arguments were all surrounded with C<my()> or C<our()>
+(as in C<< $object->method(my($a,$b)) >>) used to force lvalue context on
+the subroutine. This would prevent lvalue methods from returning certain
+values.
+
+=item *
+
+Lvalue sub calls that are not determined to be such at compile time
+(C<&$name> or &{"name"}) are no longer exempt from strict refs if they
+occur in the last statement of an lvalue subroutine [perl #102486].
+
+=item *
+
+Sub calls whose subs are not visible at compile time, if
+they occurred in the last statement of an lvalue subroutine,
+would reject non-lvalue subroutines and die with "Can't modify non-lvalue
+subroutine call" [perl #102486].
+
+Non-lvalue sub calls whose subs I<are> visible at compile time exhibited
+the opposite bug. If the call occurred in the last statement of an lvalue
+subroutine, there would be no error when the lvalue sub was called in
+lvalue context. Perl would blindly assign to the temporary value returned
+by the non-lvalue subroutine.
+
+=item *
+
+C<AUTOLOAD> routines used to take precedence over the actual sub being
+called (i.e., when autoloading wasn't needed), for sub calls in lvalue or
+potential lvalue context, if the subroutine was not visible at compile
+time.
+
+=item *
+
+Applying the C<:lvalue> attribute to an XSUB or to an aliased subroutine
+stub with C<< sub foo :lvalue; >> syntax stopped working in Perl 5.12.
+This has been fixed.
+
+=item *
+
+Applying the :lvalue attribute to subroutine that is already defined does
+not work properly, as the attribute changes the way the sub is compiled.
+Hence, Perl 5.12 began warning when an attempt is made to apply the
+attribute to an already defined sub. In such cases, the attribute is
+discarded.
+
+But the change in 5.12 missed the case where custom attributes are also
+present: that case still silently and ineffectively applied the attribute.
+That omission has now been corrected. C<sub foo :lvalue :Whatever> (when
+C<foo> is already defined) now warns about the :lvalue attribute, and does
+not apply it.
+
+=item *
+
+A bug affecting lvalue context propagation through nested lvalue subroutine
+calls has been fixed. Previously, returning a value in nested rvalue
+context would be treated as lvalue context by the inner subroutine call,
+resulting in some values (such as read-only values) being rejected.
+
+=back
+
+=head2 Overloading
+
+=over
+
+=item *
+
+Arithmetic assignment (C<$left += $right>) involving overloaded objects
+that rely on the 'nomethod' override no longer segfault when the left
+operand is not overloaded.
+
+=item *
+
+Errors that occur when methods cannot be found during overloading now
+mention the correct package name, as they did in 5.8.x, instead of
+erroneously mentioning the "overload" package, as they have since 5.10.0.
+
+=item *
+
+Undefining C<%overload::> no longer causes a crash.
+
+=back
+
+=head2 Prototypes of built-in keywords
+
+=over
+
+=item *
+
+The C<prototype> function no longer dies for the C<__FILE__>, C<__LINE__>
+and C<__PACKAGE__> directives. It now returns an empty-string prototype
+for them, because they are syntactically indistinguishable from nullary
+functions like C<time>.
+
+=item *
+
+C<prototype> now returns C<undef> for all overridable infix operators,
+such as C<eq>, which are not callable in any way resembling functions.
+It used to return incorrect prototypes for some and die for others
+[perl #94984].
+
+=item *
+
+The prototypes of several built-in functions--C<getprotobynumber>, C<lock>,
+C<not> and C<select>--have been corrected, or at least are now closer to
+reality than before.
+
+=back
+
+=head2 Regular expressions
+
+=for comment Is it possible to merge some of these items?
+
+=over 4
+
+=item *
+
+C</[[:ascii:]]/> and C</[[:blank:]]/> now use locale rules under
+C<use locale> when the platform supports that. Previously, they used
+the platform's native character set.
+
+=item *
+
+C<m/[[:ascii:]]/i> and C</\p{ASCII}/i> now match identically (when not
+under a differing locale). This fixes a regression introduced in 5.14
+in which the first expression could match characters outside of ASCII,
+such as the KELVIN SIGN.
+
+=item *
+
+C</.*/g> would sometimes refuse to match at the end of a string that ends
+with "\n". This has been fixed [perl #109206].
+
+=item *
+
+Starting with 5.12.0, Perl used to get its internal bookkeeping muddled up
+after assigning C<${ qr// }> to a hash element and locking it with
+L<Hash::Util>. This could result in double frees, crashes, or erratic
+behavior.
+
+=item *
+
+The new (in 5.14.0) regular expression modifier C</a> when repeated like
+C</aa> forbids the characters outside the ASCII range that match
+characters inside that range from matching under C</i>. This did not
+work under some circumstances, all involving alternation, such as:
+
+ "\N{KELVIN SIGN}" =~ /k|foo/iaa;
+
+succeeded inappropriately. This is now fixed.
+
+=item *
+
+5.14.0 introduced some memory leaks in regular expression character
+classes such as C<[\w\s]>, which have now been fixed. (5.14.1)
+
+=item *
+
+An edge case in regular expression matching could potentially loop.
+This happened only under C</i> in bracketed character classes that have
+characters with multi-character folds, and the target string to match
+against includes the first portion of the fold, followed by another
+character that has a multi-character fold that begins with the remaining
+portion of the fold, plus some more.
+
+ "s\N{U+DF}" =~ /[\x{DF}foo]/i
+
+is one such case. C<\xDF> folds to C<"ss">. (5.14.1)
+
+=item *
+
+A few characters in regular expression pattern matches did not
+match correctly in some circumstances, all involving C</i>. The
+affected characters are:
+COMBINING GREEK YPOGEGRAMMENI,
+GREEK CAPITAL LETTER IOTA,
+GREEK CAPITAL LETTER UPSILON,
+GREEK PROSGEGRAMMENI,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND OXIA,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND OXIA,
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
+LATIN SMALL LETTER LONG S,
+LATIN SMALL LIGATURE LONG S T,
+and
+LATIN SMALL LIGATURE ST.
+
+=item *
+
+A memory leak regression in regular expression compilation
+under threading has been fixed.
+
+=item *
+
+A regression introduced in 5.14.0 has
+been fixed. This involved an inverted
+bracketed character class in a regular expression that consisted solely
+of a Unicode property. That property wasn't getting inverted outside the
+Latin1 range.
+
+=item *
+
+Three problematic Unicode characters now work better in regex pattern matching under C</i>.
+
+In the past, three Unicode characters:
+LATIN SMALL LETTER SHARP S,
+GREEK SMALL LETTER IOTA WITH DIALYTIKA AND TONOS,
+and
+GREEK SMALL LETTER UPSILON WITH DIALYTIKA AND TONOS,
+along with the sequences that they fold to
+(including "ss" for LATIN SMALL LETTER SHARP S),
+did not properly match under C</i>. 5.14.0 fixed some of these cases,
+but introduced others, including a panic when one of the characters or
+sequences was used in the C<(?(DEFINE)> regular expression predicate.
+The known bugs that were introduced in 5.14 have now been fixed; as well
+as some other edge cases that have never worked until now. These all
+involve using the characters and sequences outside bracketed character
+classes under C</i>. This closes [perl #98546].
+
+There remain known problems when using certain characters with
+multi-character folds inside bracketed character classes, including such
+constructs as C<qr/[\N{LATIN SMALL LETTER SHARP}a-z]/i>. These
+remaining bugs are addressed in [perl #89774].
+
+=item *
+
+RT #78266: The regex engine has been leaking memory when accessing
+named captures that weren't matched as part of a regex ever since 5.10
+when they were introduced; e.g., this would consume over a hundred MB of
+memory:
+
+ for (1..10_000_000) {
+ if ("foo" =~ /(foo|(?<capture>bar))?/) {
+ my $capture = $+{capture}
+ }
+ }
+ system "ps -o rss $$"'
+
+=item *
+
+In 5.14, C</[[:lower:]]/i> and C</[[:upper:]]/i> no longer matched the
+opposite case. This has been fixed [perl #101970].
+
+=item *
+
+A regular expression match with an overloaded object on the right-hand side
+would sometimes stringify the object too many times.
+
+=item *
+
+A regression has been fixed that was introduced in 5.14, in C</i>
+regular expression matching, in which a match improperly fails if the
+pattern is in UTF-8, the target string is not, and a Latin-1 character
+precedes a character in the string that should match the pattern.
+[perl #101710]
+
+=item *
+
+In case-insensitive regular expression pattern matching, no longer on
+UTF-8 encoded strings does the scan for the start of match look only at
+the first possible position. This caused matches such as
+C<"f\x{FB00}" =~ /ff/i> to fail.
+
+=item *
+
+The regexp optimizer no longer crashes on debugging builds when merging
+fixed-string nodes with inconvenient contents.
+
+=item *
+
+A panic involving the combination of the regular expression modifiers
+C</aa> and the C<\b> escape sequence introduced in 5.14.0 has been
+fixed [perl #95964]. (5.14.2)
+
+=item *
+
+The combination of the regular expression modifiers C</aa> and the C<\b>
+and C<\B> escape sequences did not work properly on UTF-8 encoded
+strings. All non-ASCII characters under C</aa> should be treated as
+non-word characters, but what was happening was that Unicode rules were
+used to determine wordness/non-wordness for non-ASCII characters. This
+is now fixed [perl #95968].
+
+=item *
+
+C<< (?foo: ...) >> no longer loses passed in character set.
+
+=item *
+
+The trie optimization used to have problems with alternations containing
+an empty C<(?:)>, causing C<< "x" =~ /\A(?>(?:(?:)A|B|C?x))\z/ >> not to
+match, whereas it should [perl #111842].
+
+=item *
+
+Use of lexical (C<my>) variables in code blocks embedded in regular
+expressions will no longer result in memory corruption or crashes.
+
+Nevertheless, these code blocks are still experimental, as there are still
+problems with the wrong variables being closed over (in loops for instance)
+and with abnormal exiting (e.g., C<die>) causing memory corruption.
+
+=item *
+
+The C<\h>, C<\H>, C<\v> and C<\V> regular expression metacharacters used to
+cause a panic error message when trying to match at the end of the
+string [perl #96354].
+
+=item *
+
+The abbreviations for four C1 control characters C<MW> C<PM>, C<RI>, and
+C<ST> were previously unrecognized by C<\N{}>, vianame(), and
+string_vianame().
+
+=item *
+
+Mentioning a variable named "&" other than C<$&> (i.e., C<@&> or C<%&>) no
+longer stops C<$&> from working. The same applies to variables named "'"
+and "`" [perl #24237].
+
+=item *
+
+Creating a C<UNIVERSAL::AUTOLOAD> sub no longer stops C<%+>, C<%-> and
+C<%!> from working some of the time [perl #105024].
+
+=back
+
+=head2 Smartmatching
+
+=over
+
+=item *
+
+C<~~> now correctly handles the precedence of Any~~Object, and is not tricked
+by an overloaded object on the left-hand side.
+
+=item *
+
+In Perl 5.14.0, C<$tainted ~~ @array> stopped working properly. Sometimes
+it would erroneously fail (when C<$tainted> contained a string that occurs
+in the array I<after> the first element) or erroneously succeed (when
+C<undef> occurred after the first element) [perl #93590].
+
+=back
+
+=head2 The C<sort> operator
+
+=over
+
+=item *
+
+C<sort> was not treating C<sub {}> and C<sub {()}> as equivalent when
+such a sub was provided as the comparison routine. It used to croak on
+C<sub {()}>.
+
+=item *
+
+C<sort> now works once more with custom sort routines that are XSUBs. It
+stopped working in 5.10.0.
+
+=item *
+
+C<sort> with a constant for a custom sort routine, although it produces
+unsorted results, no longer crashes. It started crashing in 5.10.0.
+
+=item *
+
+Warnings emitted by C<sort> when a custom comparison routine returns a
+non-numeric value now contain "in sort" and show the line number of the
+C<sort> operator, rather than the last line of the comparison routine. The
+warnings also now occur only if warnings are enabled in the scope where
+C<sort> occurs. Previously the warnings would occur if enabled in the
+comparison routine's scope.
+
+=item *
+
+C<< sort { $a <=> $b } >>, which is optimized internally, now produces
+"uninitialized" warnings for NaNs (not-a-number values), since C<< <=> >>
+returns C<undef> for those. This brings it in line with
+S<C<< sort { 1; $a <=> $b } >>> and other more complex cases, which are not
+optimized [perl #94390].
+
+=back
+
+=head2 The C<substr> operator
+
+=over
+
+=item *
+
+Tied (and otherwise magical) variables are no longer exempt from the
+"Attempt to use reference as lvalue in substr" warning.
+
+=item *
+
+That warning now occurs when the returned lvalue is assigned to, not
+when C<substr> itself is called. This makes a difference only if the
+return value of C<substr> is referenced and later assigned to.
+
+=item *
+
+Passing a substring of a read-only value or a typeglob to a function
+(potential lvalue context) no longer causes an immediate "Can't coerce"
+or "Modification of a read-only value" error. That error occurs only
+if the passed value is assigned to.
+
+The same thing happens with the "substr outside of string" error. If
+the lvalue is only read from, not written to, it is now just a warning, as
+with rvalue C<substr>.
+
+=item *
+
+C<substr> assignments no longer call FETCH twice if the first argument
+is a tied variable, just once.
+
+=back
+
+=head2 Support for embedded nulls
+
+Some parts of Perl did not work correctly with nulls (C<chr 0>) embedded in
+strings. That meant that, for instance, C<< $m = "a\0b"; foo->$m >> would
+call the "a" method, instead of the actual method name contained in $m.
+These parts of perl have been fixed to support nulls:
+
+=over
+
+=item *
+
+Method names
+
+=item *
+
+Typeglob names (including filehandle and subroutine names)
+
+=item *
+
+Package names, including the return value of C<ref()>
+
+=item *
+
+Typeglob elements (C<*foo{"THING\0stuff"}>)
+
+=item *
+
+Signal names
+
+=item *
+
+Various warnings and error messages that mention variable names or values,
+methods, etc.
+
+=back
+
+One side effect of these changes is that blessing into "\0" no longer
+causes C<ref()> to return false.
+
+=head2 Threading bugs
+
+=over
+
+=item *
+
+Typeglobs returned from threads are no longer cloned if the parent thread
+already has a glob with the same name. This means that returned
+subroutines will now assign to the right package variables [perl #107366].
+
+=item *
+
+Some cases of threads crashing due to memory allocation during cloning have
+been fixed [perl #90006].
+
+=item *
+
+Thread joining would sometimes emit "Attempt to free unreferenced scalar"
+warnings if C<caller> had been used from the C<DB> package before thread
+creation [perl #98092].
+
+=item *
+
+Locking a subroutine (via C<lock &sub>) is no longer a compile-time error
+for regular subs. For lvalue subroutines, it no longer tries to return the
+sub as a scalar, resulting in strange side effects like C<ref \$_>
+returning "CODE" in some instances.
+
+C<lock &sub> is now a run-time error if L<threads::shared> is loaded (a
+no-op otherwise), but that may be rectified in a future version.
+
+=back
+
+=head2 Tied variables
+
+=over
+
+=item *
+
+Various cases in which FETCH was being ignored or called too many times
+have been fixed:
+
+=over
+
+=item *
+
+C<PerlIO::get_layers> [perl #97956]
+
+=item *
+
+C<$tied =~ y/a/b/>, C<chop $tied> and C<chomp $tied> when $tied holds a
+reference.
+
+=item *
+
+When calling C<local $_> [perl #105912]
+
+=item *
+
+Four-argument C<select>
+
+=item *
+
+A tied buffer passed to C<sysread>
+
+=item *
+
+C<< $tied .= <> >>
+
+=item *
+
+Three-argument C<open>, the third being a tied file handle
+(as in C<< open $fh, ">&", $tied >>)
+
+=item *
+
+C<sort> with a reference to a tied glob for the comparison routine.
+
+=item *
+
+C<..> and C<...> in list context [perl #53554].
+
+=item *
+
+C<${$tied}>, C<@{$tied}>, C<%{$tied}> and C<*{$tied}> where the tied
+variable returns a string (C<&{}> was unaffected)
+
+=item *
+
+C<defined ${ $tied_variable }>
+
+=item *
+
+Various functions that take a filehandle argument in rvalue context
+(C<close>, C<readline>, etc.) [perl #97482]
+
+=item *
+
+Some cases of dereferencing a complex expression, such as
+C<${ (), $tied } = 1>, used to call C<FETCH> multiple times, but now call
+it once.
+
+=item *
+
+C<$tied-E<gt>method> where $tied returns a package name--even resulting in
+a failure to call the method, due to memory corruption
+
+=item *
+
+Assignments like C<*$tied = \&{"..."}> and C<*glob = $tied>
+
+=item *
+
+C<chdir>, C<chmod>, C<chown>, C<utime>, C<truncate>, C<stat>, C<lstat> and
+the filetest ops (C<-r>, C<-x>, etc.)
+
+=back
+
+=item *
+
+C<caller> sets C<@DB::args> to the subroutine arguments when called from
+the DB package. It used to crash when doing so if C<@DB::args> happened to
+be tied. Now it croaks instead.
+
+=item *
+
+Tying an element of %ENV or C<%^H> and then deleting that element would
+result in a call to the tie object's DELETE method, even though tying the
+element itself is supposed to be equivalent to tying a scalar (the element
+is, of course, a scalar) [perl #67490].
+
+=item *
+
+When Perl autovivifies an element of a tied array or hash (which entails
+calling STORE with a new reference), it now calls FETCH immediately after
+the STORE, instead of assuming that FETCH would have returned the same
+reference. This can make it easier to implement tied objects [perl #35865, #43011].
+
+=item *
+
+Four-argument C<select> no longer produces its "Non-string passed as
+bitmask" warning on tied or tainted variables that are strings.
+
+=item *
+
+Localizing a tied scalar that returns a typeglob no longer stops it from
+being tied till the end of the scope.
+
+=item *
+
+Attempting to C<goto> out of a tied handle method used to cause memory
+corruption or crashes. Now it produces an error message instead
+[perl #8611].
+
+=item *
+
+A bug has been fixed that occurs when a tied variable is used as a
+subroutine reference: if the last thing assigned to or returned from the
+variable was a reference or typeglob, the C<\&$tied> could either crash or
+return the wrong subroutine. The reference case is a regression introduced
+in Perl 5.10.0. For typeglobs, it has probably never worked till now.
+
+=back
+
+=head2 Version objects and vstrings
+
+=over
+
+=item *
+
+The bitwise complement operator (and possibly other operators, too) when
+passed a vstring would leave vstring magic attached to the return value,
+even though the string had changed. This meant that
+C<< version->new(~v1.2.3) >> would create a version looking like "v1.2.3"
+even though the string passed to C<< version->new >> was actually
+"\376\375\374". This also caused L<B::Deparse> to deparse C<~v1.2.3>
+incorrectly, without the C<~> [perl #29070].
+
+=item *
+
+Assigning a vstring to a magic (e.g., tied, C<$!>) variable and then
+assigning something else used to blow away all magic. This meant that
+tied variables would come undone, C<$!> would stop getting updated on
+failed system calls, C<$|> would stop setting autoflush, and other
+mischief would take place. This has been fixed.
+
+=item *
+
+C<< version->new("version") >> and C<printf "%vd", "version"> no longer
+crash [perl #102586].
+
+=item *
+
+Version comparisons, such as those that happen implicitly with C<use
+v5.43>, no longer cause locale settings to change [perl #105784].
+
+=item *
+
+Version objects no longer cause memory leaks in boolean context
+[perl #109762].
+
+=back
+
+=head2 Warnings, redefinition
+
+=over
+
+=item *
+
+Subroutines from the C<autouse> namespace are once more exempt from
+redefinition warnings. This used to work in 5.005, but was broken in
+5.6 for most subroutines. For subs created via XS that redefine
+subroutines from the C<autouse> package, this stopped working in 5.10.
+
+=item *
+
+New XSUBs now produce redefinition warnings if they overwrite existing
+subs, as they did in 5.8.x. (The C<autouse> logic was reversed in
+5.10-14. Only subroutines from the C<autouse> namespace would warn
+when clobbered.)
+
+=item *
+
+C<newCONSTSUB> used to use compile-time warning hints, instead of
+run-time hints. The following code should never produce a redefinition
+warning, but it used to, if C<newCONSTSUB> redefined an existing
+subroutine:
+
+ use warnings;
+ BEGIN {
+ no warnings;
+ some_XS_function_that_calls_new_CONSTSUB();
+ }
+
+=item *
+
+Redefinition warnings for constant subroutines are on by default (what
+are known as severe warnings in L<perldiag>). This occurred only
+when it was a glob assignment or declaration of a Perl subroutine that
+caused the warning. If the creation of XSUBs triggered the warning, it
+was not a default warning. This has been corrected.
+
+=item *
+
+The internal check to see whether a redefinition warning should occur
+used to emit "uninitialized" warnings in cases like this:
+
+ use warnings "uninitialized";
+ use constant {u => undef, v => undef};
+ sub foo(){u}
+ sub foo(){v}
+
+=back
+
+=head2 Warnings, "Uninitialized"
+
+=over
+
+=item *
+
+Various functions that take a filehandle argument in rvalue context
+(C<close>, C<readline>, etc.) used to warn twice for an undefined handle
+[perl #97482].
+
+=item *
+
+C<dbmopen> now only warns once, rather than three times, if the mode
+argument is C<undef> [perl #90064].
+
+=item *
+
+The C<+=> operator does not usually warn when the left-hand side is
+C<undef>, but it was doing so for tied variables. This has been fixed
+[perl #44895].
+
+=item *
+
+A bug fix in Perl 5.14 introduced a new bug, causing "uninitialized"
+warnings to report the wrong variable if the operator in question had
+two operands and one was C<%{...}> or C<@{...}>. This has been fixed
+[perl #103766].
+
+=item *
+
+C<..> and C<...> in list context now mention the name of the variable in
+"uninitialized" warnings for string (as opposed to numeric) ranges.
+
+=back
+
+=head2 Weak references
+
+=over
+
+=item *
+
+Weakening the first argument to an automatically-invoked C<DESTROY> method
+could result in erroneous "DESTROY created new reference" errors or
+crashes. Now it is an error to weaken a read-only reference.
+
+=item *
+
+Weak references to lexical hashes going out of scope were not going stale
+(becoming undefined), but continued to point to the hash.
+
+=item *
+
+Weak references to lexical variables going out of scope are now broken
+before any magical methods (e.g., DESTROY on a tie object) are called.
+This prevents such methods from modifying the variable that will be seen
+the next time the scope is entered.
+
+=item *
+
+Creating a weak reference to an @ISA array or accessing the array index
+(C<$#ISA>) could result in confused internal bookkeeping for elements
+later added to the @ISA array. For instance, creating a weak
+reference to the element itself could push that weak reference on to @ISA;
+and elements added after use of C<$#ISA> would be ignored by method lookup
+[perl #85670].
+
+=back
+
+=head2 Other notable fixes
+
+=over
+
+=item *
+
+C<quotemeta> now quotes consistently the same non-ASCII characters under
+C<use feature 'unicode_strings'>, regardless of whether the string is
+encoded in UTF-8 or not, hence fixing the last vestiges (we hope) of the
+notorious L<perlunicode/The "Unicode Bug">. [perl #77654].
+
+Which of these code points is quoted has changed, based on Unicode's
+recommendations. See L<perlfunc/quotemeta> for details.
+
+=item *
+
+C<study> is now a no-op, presumably fixing all outstanding bugs related to
+study causing regex matches to behave incorrectly!
+
+=item *
+
+When one writes C<open foo || die>, which used to work in Perl 4, a
+"Precedence problem" warning is produced. This warning used erroneously to
+apply to fully-qualified bareword handle names not followed by C<||>. This
+has been corrected.
+
+=item *
+
+After package aliasing (C<*foo:: = *bar::>), C<select> with 0 or 1 argument
+would sometimes return a name that could not be used to refer to the
+filehandle, or sometimes it would return C<undef> even when a filehandle
+was selected. Now it returns a typeglob reference in such cases.
+
+=item *
+
+C<PerlIO::get_layers> no longer ignores some arguments that it thinks are
+numeric, while treating others as filehandle names. It is now consistent
+for flat scalars (i.e., not references).
+
+=item *
+
+Unrecognized switches on C<#!> line
+
+If a switch, such as B<-x>, that cannot occur on the C<#!> line is used
+there, perl dies with "Can't emulate...".
+
+It used to produce the same message for switches that perl did not
+recognize at all, whether on the command line or the C<#!> line.
+
+Now it produces the "Unrecognized switch" error message [perl #104288].
+
+=item *
+
+C<system> now temporarily blocks the SIGCHLD signal handler, to prevent the
+signal handler from stealing the exit status [perl #105700].
+
+=item *
+
+The %n formatting code for C<printf> and C<sprintf>, which causes the number
+of characters to be assigned to the next argument, now actually
+assigns the number of characters, instead of the number of bytes.
+
+It also works now with special lvalue functions like C<substr> and with
+nonexistent hash and array elements [perl #3471, #103492].
+
+=item *
+
+Perl skips copying values returned from a subroutine, for the sake of
+speed, if doing so would make no observable difference. Because of faulty
+logic, this would happen with the
+result of C<delete>, C<shift> or C<splice>, even if the result was
+referenced elsewhere. It also did so with tied variables about to be freed
+[perl #91844, #95548].
+
+=item *
+
+C<utf8::decode> now refuses to modify read-only scalars [perl #91850].
+
+=item *
+
+Freeing $_ inside a C<grep> or C<map> block, a code block embedded in a
+regular expression, or an @INC filter (a subroutine returned by a
+subroutine in @INC) used to result in double frees or crashes
+[perl #91880, #92254, #92256].
+
+=item *
+
+C<eval> returns C<undef> in scalar context or an empty list in list
+context when there is a run-time error. When C<eval> was passed a
+string in list context and a syntax error occurred, it used to return a
+list containing a single undefined element. Now it returns an empty
+list in list context for all errors [perl #80630].
+
+=item *
+
+C<goto &func> no longer crashes, but produces an error message, when
+the unwinding of the current subroutine's scope fires a destructor that
+undefines the subroutine being "goneto" [perl #99850].
+
+=item *
+
+Perl now holds an extra reference count on the package that code is
+currently compiling in. This means that the following code no longer
+crashes [perl #101486]:
+
+ package Foo;
+ BEGIN {*Foo:: = *Bar::}
+ sub foo;
+
+=item *
+
+The C<x> repetition operator no longer crashes on 64-bit builds with large
+repeat counts [perl #94560].
+
+=item *
+
+Calling C<require> on an implicit C<$_> when C<*CORE::GLOBAL::require> has
+been overridden does not segfault anymore, and C<$_> is now passed to the
+overriding subroutine [perl #78260].
+
+=item *
+
+C<use> and C<require> are no longer affected by the I/O layers active in
+the caller's scope (enabled by L<open.pm|open>) [perl #96008].
+
+=item *
+
+C<our $::é; $é> (which is invalid) no longer produces the "Compilation
+error at lib/utf8_heavy.pl..." error message, which it started emitting in
+5.10.0 [perl #99984].
+
+=item *
+
+On 64-bit systems, C<read()> now understands large string offsets beyond
+the 32-bit range.
+
+=item *
+
+Errors that occur when processing subroutine attributes no longer cause the
+subroutine's op tree to leak.
+
+=item *
+
+Passing the same constant subroutine to both C<index> and C<formline> no
+longer causes one or the other to fail [perl #89218]. (5.14.1)
+
+=item *
+
+List assignment to lexical variables declared with attributes in the same
+statement (C<my ($x, at y) : blimp = (72,94)>) stopped working in Perl 5.8.0.
+It has now been fixed.
+
+=item *
+
+Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
+a pack template equivalent to "U0" if the input string was empty. This has
+been fixed [perl #90160]. (5.14.2)
+
+=item *
+
+Destructors on objects were not called during global destruction on objects
+that were not referenced by any scalars. This could happen if an array
+element were blessed (e.g., C<bless \$a[0]>) or if a closure referenced a
+blessed variable (C<bless \my @a; sub foo { @a }>).
+
+Now there is an extra pass during global destruction to fire destructors on
+any objects that might be left after the usual passes that check for
+objects referenced by scalars [perl #36347].
+
+=item *
+
+Fixed a case where it was possible that a freed buffer may have been read
+from when parsing a here document [perl #90128]. (5.14.1)
+
+=item *
+
+C<each(I<ARRAY>)> is now wrapped in C<defined(...)>, like C<each(I<HASH>)>,
+inside a C<while> condition [perl #90888].
+
+=item *
+
+A problem with context propagation when a C<do> block is an argument to
+C<return> has been fixed. It used to cause C<undef> to be returned in
+certain cases of a C<return> inside an C<if> block which itself is followed by
+another C<return>.
+
+=item *
+
+Calling C<index> with a tainted constant no longer causes constants in
+subsequently compiled code to become tainted [perl #64804].
+
+=item *
+
+Infinite loops like C<1 while 1> used to stop C<strict 'subs'> mode from
+working for the rest of the block.
+
+=item *
+
+For list assignments like C<($a,$b) = ($b,$a)>, Perl has to make a copy of
+the items on the right-hand side before assignment them to the left. For
+efficiency's sake, it assigns the values on the right straight to the items
+on the left if no one variable is mentioned on both sides, as in C<($a,$b) =
+($c,$d)>. The logic for determining when it can cheat was faulty, in that
+C<&&> and C<||> on the right-hand side could fool it. So C<($a,$b) =
+$some_true_value && ($b,$a)> would end up assigning the value of C<$b> to
+both scalars.
+
+=item *
+
+Perl no longer tries to apply lvalue context to the string in
+C<("string", $variable) ||= 1> (which used to be an error). Since the
+left-hand side of C<||=> is evaluated in scalar context, that's a scalar
+comma operator, which gives all but the last item void context. There is
+no such thing as void lvalue context, so it was a mistake for Perl to try
+to force it [perl #96942].
+
+=item *
+
+C<caller> no longer leaks memory when called from the DB package if
+C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
+was triggering this bug [perl #97010]. (5.14.2)
+
+=item *
+
+C<close> and similar filehandle functions, when called on built-in global
+variables (like C<$+>), used to die if the variable happened to hold the
+undefined value, instead of producing the usual "Use of uninitialized
+value" warning.
+
+=item *
+
+When autovivified file handles were introduced in Perl 5.6.0, C<readline>
+was inadvertently made to autovivify when called as C<readline($foo)> (but
+not as C<E<lt>$fooE<gt>>). It has now been fixed never to autovivify.
+
+=item *
+
+Calling an undefined anonymous subroutine (e.g., what $x holds after
+C<undef &{$x = sub{}}>) used to cause a "Not a CODE reference" error, which
+has been corrected to "Undefined subroutine called" [perl #71154].
+
+=item *
+
+Causing C<@DB::args> to be freed between uses of C<caller> no longer
+results in a crash [perl #93320].
+
+=item *
+
+C<setpgrp($foo)> used to be equivalent to C<($foo, setpgrp)>, because
+C<setpgrp> was ignoring its argument if there was just one. Now it is
+equivalent to C<setpgrp($foo,0)>.
+
+=item *
+
+C<shmread> was not setting the scalar flags correctly when reading from
+shared memory, causing the existing cached numeric representation in the
+scalar to persist [perl #98480].
+
+=item *
+
+C<++> and C<--> now work on copies of globs, instead of dying.
+
+=item *
+
+C<splice()> doesn't warn when truncating
+
+You can now limit the size of an array using C<splice(@a,MAX_LEN)> without
+worrying about warnings.
+
+=item *
+
+C<< $$ >> is no longer tainted. Since this value comes directly from
+C<< getpid() >>, it is always safe.
+
+=item *
+
+The parser no longer leaks a filehandle if STDIN was closed before parsing
+started [perl #37033].
+
+=item *
+
+C<< die; >> with a non-reference, non-string, or magical (e.g., tainted)
+value in $@ now properly propagates that value [perl #111654].
+
+=back
+
+=head1 Known Problems
+
+=over 4
+
+=item *
+
+On Solaris, we have two kinds of failure.
+
+If F<make> is Sun's F<make>, we get an error about a badly formed macro
+assignment in the F<Makefile>. That happens when F<./Configure> tries to
+make depends. F<Configure> then exits 0, but further F<make>-ing fails.
+
+If F<make> is F<gmake>, F<Configure> completes, then we get errors related
+to F</usr/include/stdbool.h>
+
+=item *
+
+On Win32, a number of tests hang unless STDERR is redirected. The cause of
+this is still under investigation.
+
+=item *
+
+When building as root with a umask that prevents files from being
+other-readable, F<t/op/filetest.t> will fail. This is a test bug, not a
+bug in perl's behavior.
+
+=item *
+
+Configuring with a recent gcc and link-time-optimization, such as
+C<Configure -Doptimize='-O2 -flto'> fails
+because the optimizer optimizes away some of Configure's tests. A
+workaround is to omit the C<-flto> flag when running Configure, but add
+it back in while actually building, something like
+
+ sh Configure -Doptimize=-O2
+ make OPTIMIZE='-O2 -flto'
+
+=item *
+
+The following CPAN modules have test failures with perl 5.16. Patches have
+been submitted for all of these, so hopefully there will be new releases
+soon:
+
+=over
+
+=item *
+
+L<Date::Pcalc> version 6.1
+
+=item *
+
+L<Module::CPANTS::Analyse> version 0.85
+
+This fails due to problems in L<Module::Find> 0.10 and L<File::MMagic>
+1.27.
+
+=item *
+
+L<PerlIO::Util> version 0.72
+
+=back
+
+=back
+
+=head1 Acknowledgements
+
+Perl 5.16.0 represents approximately 12 months of development since Perl
+5.14.0 and contains approximately 590,000 lines of changes across 2,500
+files from 139 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.16.0:
+
+Aaron Crane, Abhijit Menon-Sen, Abigail, Alan Haggai Alavi, Alberto
+Simões, Alexandr Ciornii, Andreas König, Andy Dougherty, Aristotle
+Pagaltzis, Bo Johansson, Bo Lindbergh, Breno G. de Oliveira, brian d
+foy, Brian Fraser, Brian Greenfield, Carl Hayter, Chas. Owens,
+Chia-liang Kao, Chip Salzenberg, Chris 'BinGOs' Williams, Christian
+Hansen, Christopher J. Madsen, chromatic, Claes Jacobsson, Claudio
+Ramirez, Craig A. Berry, Damian Conway, Daniel Kahn Gillmor, Darin
+McBride, Dave Rolsky, David Cantrell, David Golden, David Leadbeater,
+David Mitchell, Dee Newcum, Dennis Kaarsemaker, Dominic Hargreaves,
+Douglas Christopher Wilson, Eric Brine, Father Chrysostomos, Florian
+Ragwitz, Frederic Briere, George Greer, Gerard Goossen, Gisle Aas,
+H.Merijn Brand, Hojung Youn, Ian Goodacre, James E Keenan, Jan Dubois,
+Jerry D. Hedden, Jesse Luehrs, Jesse Vincent, Jilles Tjoelker, Jim
+Cromie, Jim Meyering, Joel Berger, Johan Vromans, Johannes Plunien, John
+Hawkinson, John P. Linderman, John Peacock, Joshua ben Jore, Juerd
+Waalboer, Karl Williamson, Karthik Rajagopalan, Keith Thompson, Kevin J.
+Woolley, Kevin Ryde, Laurent Dami, Leo Lapworth, Leon Brocard, Leon
+Timmermans, Louis Strous, Lukas Mai, Marc Green, Marcel Grünauer, Mark
+A. Stratman, Mark Dootson, Mark Jason Dominus, Martin Hasch, Matthew
+Horsfall, Max Maischein, Michael G Schwern, Michael Witten, Mike
+Sheldrake, Moritz Lenz, Nicholas Clark, Niko Tyni, Nuno Carvalho, Pau
+Amma, Paul Evans, Paul Green, Paul Johnson, Perlover, Peter John Acklam,
+Peter Martini, Peter Scott, Phil Monsen, Pino Toscano, Rafael
+Garcia-Suarez, Rainer Tammer, Reini Urban, Ricardo Signes, Robin Barker,
+Rodolfo Carvalho, Salvador Fandiño, Sam Kimbrel, Samuel Thibault, Shawn
+M Moore, Shigeya Suzuki, Shirakata Kentaro, Shlomi Fish, Sisyphus,
+Slaven Rezic, Spiros Denaxas, Steffen Müller, Steffen Schwigon, Stephen
+Bennett, Stephen Oberholtzer, Stevan Little, Steve Hay, Steve Peters,
+Thomas Sibley, Thorsten Glaser, Timothe Litt, Todd Rinaldo, Tom
+Christiansen, Tom Hukins, Tony Cook, Vadim Konovalov, Vincent Pit,
+Vladimir Timofeev, Walt Mankowski, Yves Orton, Zefram, Zsbán Ambrus,
+Ævar Arnfjörð Bjarmason.
+
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors,
+please see the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at L<http://rt.perl.org/perlbug/>. There may also be
+information at L<http://www.perl.org/>, the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5-security-report at perl.org. This points to a closed
+subscription unarchived mailing list, which includes all core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please use this address only for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5161delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5161delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5161delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5161delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,198 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5161delta - what is new for perl v5.16.1
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.16.0 release and
+the 5.16.1 release.
+
+If you are upgrading from an earlier release such as 5.14.0, first read
+L<perl5160delta>, which describes differences between 5.14.0 and
+5.16.0.
+
+=head1 Security
+
+=head2 an off-by-two error in Scalar-List-Util has been fixed
+
+The bugfix was in Scalar-List-Util 1.23_04, and perl 5.16.1 includes
+Scalar-List-Util 1.25.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.16.0 If any
+exist, they are bugs, and we request that you submit a report. See
+L</Reporting Bugs> below.
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Scalar::Util> and L<List::Util> have been upgraded from version 1.23 to
+version 1.25.
+
+=item *
+
+L<B::Deparse> has been updated from version 1.14 to 1.14_01. An
+"uninitialized" warning emitted by B::Deparse has been squashed
+[perl #113464].
+
+=back
+
+=head1 Configuration and Compilation
+
+=over
+
+=item *
+
+Building perl with some Windows compilers used to fail due to a problem
+with miniperl's C<glob> operator (which uses the C<perlglob> program)
+deleting the PATH environment variable [perl #113798].
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item VMS
+
+All C header files from the top-level directory of the distribution are now
+installed on VMS, providing consistency with a long-standing practice on other
+platforms. Previously only a subset were installed, which broke non-core extension
+builds for extensions that depended on the missing include files.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+A regression introduced in Perl v5.16.0 involving
+C<tr/I<SEARCHLIST>/I<REPLACEMENTLIST>/> has been fixed. Only the first
+instance is supposed to be meaningful if a character appears more than
+once in C<I<SEARCHLIST>>. Under some circumstances, the final instance
+was overriding all earlier ones. [perl #113584]
+
+=item *
+
+C<B::COP::stashlen> has been added. This provides access to an internal
+field added in perl 5.16 under threaded builds. It was broken at the last
+minute before 5.16 was released [perl #113034].
+
+=item *
+
+The L<re> pragma will no longer clobber C<$_>. [perl #113750]
+
+=item *
+
+Unicode 6.1 published an incorrect alias for one of the
+Canonical_Combining_Class property's values (which range between 0 and
+254). The alias C<CCC133> should have been C<CCC132>. Perl now
+overrides the data file furnished by Unicode to give the correct value.
+
+=item *
+
+Duplicating scalar filehandles works again. [perl #113764]
+
+=item *
+
+Under threaded perls, a runtime code block in a regular expression could
+corrupt the package name stored in the op tree, resulting in bad reads
+in C<caller>, and possibly crashes [perl #113060].
+
+=item *
+
+For efficiency's sake, many operators and built-in functions return the
+same scalar each time. Lvalue subroutines and subroutines in the CORE::
+namespace were allowing this implementation detail to leak through.
+C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
+would happen with an lvalue subroutine returning the return value of C<uc>.
+Now the value is copied in such cases [perl #113044].
+
+=item *
+
+C<__SUB__> now works in special blocks (C<BEGIN>, C<END>, etc.).
+
+=item *
+
+Formats that reference lexical variables from outside no longer result
+in crashes.
+
+=back
+
+=head1 Known Problems
+
+There are no new known problems, but consult L<perl5160delta/Known
+Problems> to see those identified in the 5.16.0 release.
+
+=head1 Acknowledgements
+
+Perl 5.16.1 represents approximately 2 months of development since Perl
+5.16.0 and contains approximately 14,000 lines of changes across 96
+files from 8 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.16.1:
+
+Chris 'BinGOs' Williams, Craig A. Berry, Father Chrysostomos, Karl
+Williamson, Paul Johnson, Reini Urban, Ricardo Signes, Tony Cook.
+
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+
+Many of the changes included in this version originated in the CPAN
+modules included in Perl's core. We're grateful to the entire CPAN
+community for helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors,
+please see the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5-security-report at perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5162delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5162delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5162delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5162delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,125 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5162delta - what is new for perl v5.16.2
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.16.1 release and
+the 5.16.2 release.
+
+If you are upgrading from an earlier release such as 5.16.0, first read
+L<perl5161delta>, which describes differences between 5.16.0 and
+5.16.1.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.16.0
+If any exist, they are bugs, and we request that you submit a
+report. See L</Reporting Bugs> below.
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.70 to version 2.76.
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item * configuration should no longer be confused by ls colorization
+
+=back
+
+=head1 Platform Support
+
+=head2 Platform-Specific Notes
+
+=over 4
+
+=item AIX
+
+Configure now always adds -qlanglvl=extc99 to the CC flags on AIX when
+using xlC. This will make it easier to compile a number of XS-based modules
+that assume C99 [perl #113778].
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item * fix /\h/ equivalence with /[\h]/
+
+see [perl #114220]
+
+=back
+
+=head1 Known Problems
+
+There are no new known problems.
+
+=head1 Acknowledgements
+
+Perl 5.16.2 represents approximately 2 months of development since Perl
+5.16.1 and contains approximately 740 lines of changes across 20 files
+from 9 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl 5.16.2:
+
+Andy Dougherty, Craig A. Berry, Darin McBride, Dominic Hargreaves, Karen
+Etheridge, Karl Williamson, Peter Martini, Ricardo Signes, Tony Cook.
+
+The list above is almost certainly incomplete as it is automatically
+generated from version control history. In particular, it does not
+include the names of the (very much appreciated) contributors who
+reported issues to the Perl bug tracker.
+
+For a more complete list of all of Perl's historical contributors,
+please see the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5-security-report at perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5163delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5163delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5163delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5163delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,133 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5163delta - what is new for perl v5.16.3
+
+=head1 DESCRIPTION
+
+This document describes differences between the 5.16.2 release and
+the 5.16.3 release.
+
+If you are upgrading from an earlier release such as 5.16.1, first read
+L<perl5162delta>, which describes differences between 5.16.1 and
+5.16.2.
+
+=head1 Core Enhancements
+
+No changes since 5.16.0.
+
+=head1 Security
+
+This release contains one major and a number of minor security fixes.
+These latter are included mainly to allow the test suite to pass cleanly
+with the clang compiler's address sanitizer facility.
+
+=head2 CVE-2013-1667: memory exhaustion with arbitrary hash keys
+
+With a carefully crafted set of hash keys (for example arguments on a
+URL), it is possible to cause a hash to consume a large amount of memory
+and CPU, and thus possibly to achieve a Denial-of-Service.
+
+This problem has been fixed.
+
+=head2 wrap-around with IO on long strings
+
+Reading or writing strings greater than 2**31 bytes in size could segfault
+due to integer wraparound.
+
+This problem has been fixed.
+
+=head2 memory leak in Encode
+
+The UTF-8 encoding implementation in Encode.xs had a memory leak which has been
+fixed.
+
+=head1 Incompatible Changes
+
+There are no changes intentionally incompatible with 5.16.0. If any
+exist, they are bugs and reports are welcome.
+
+=head1 Deprecations
+
+There have been no deprecations since 5.16.0.
+
+=head1 Modules and Pragmata
+
+=head2 Updated Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Encode> has been upgraded from version 2.44 to version 2.44_01.
+
+=item *
+
+L<Module::CoreList> has been upgraded from version 2.76 to version 2.76_02.
+
+=item *
+
+L<XS::APItest> has been upgraded from version 0.38 to version 0.39.
+
+=back
+
+=head1 Known Problems
+
+None.
+
+=head1 Acknowledgements
+
+Perl 5.16.3 represents approximately 4 months of development since Perl 5.16.2
+and contains approximately 870 lines of changes across 39 files from 7 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.16.3:
+
+Andy Dougherty, Chris 'BinGOs' Williams, Dave Rolsky, David Mitchell, Michael
+Schroeder, Ricardo Signes, Yves Orton.
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles
+recently posted to the comp.lang.perl.misc newsgroup and the perl
+bug database at http://rt.perl.org/perlbug/ . There may also be
+information at http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug>
+program included with your release. Be sure to trim your bug down
+to a tiny but sufficient test case. Your bug report, along with the
+output of C<perl -V>, will be sent off to perlbug at perl.org to be
+analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please
+send it to perl5-security-report at perl.org. This points to a closed
+subscription unarchived mailing list, which includes all the core
+committers, who will be able to help assess the impact of issues, figure
+out a resolution, and help co-ordinate the release of patches to
+mitigate or fix the problem across all platforms on which Perl is
+supported. Please only use this address for security issues in the Perl
+core, not for modules independently distributed on CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details
+on what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Copied: trunk/contrib/perl/pod/perl5180delta.pod (from rev 6437, vendor/perl/5.18.1/pod/perl5180delta.pod)
===================================================================
--- trunk/contrib/perl/pod/perl5180delta.pod (rev 0)
+++ trunk/contrib/perl/pod/perl5180delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,3781 @@
+=encoding utf8
+
+=head1 NAME
+
+perl5180delta - what is new for perl v5.18.0
+
+=head1 DESCRIPTION
+
+This document describes differences between the v5.16.0 release and the v5.18.0
+release.
+
+If you are upgrading from an earlier release such as v5.14.0, first read
+L<perl5160delta>, which describes differences between v5.14.0 and v5.16.0.
+
+=head1 Core Enhancements
+
+=head2 New mechanism for experimental features
+
+Newly-added experimental features will now require this incantation:
+
+ no warnings "experimental::feature_name";
+ use feature "feature_name"; # would warn without the prev line
+
+There is a new warnings category, called "experimental", containing
+warnings that the L<feature> pragma emits when enabling experimental
+features.
+
+Newly-added experimental features will also be given special warning IDs,
+which consist of "experimental::" followed by the name of the feature. (The
+plan is to extend this mechanism eventually to all warnings, to allow them
+to be enabled or disabled individually, and not just by category.)
+
+By saying
+
+ no warnings "experimental::feature_name";
+
+you are taking responsibility for any breakage that future changes to, or
+removal of, the feature may cause.
+
+Since some features (like C<~~> or C<my $_>) now emit experimental warnings,
+and you may want to disable them in code that is also run on perls that do not
+recognize these warning categories, consider using the C<if> pragma like this:
+
+ no if $] >= 5.018, warnings => "experimental::feature_name";
+
+Existing experimental features may begin emitting these warnings, too. Please
+consult L<perlexperiment> for information on which features are considered
+experimental.
+
+=head2 Hash overhaul
+
+Changes to the implementation of hashes in perl v5.18.0 will be one of the most
+visible changes to the behavior of existing code.
+
+By default, two distinct hash variables with identical keys and values may now
+provide their contents in a different order where it was previously identical.
+
+When encountering these changes, the key to cleaning up from them is to accept
+that B<hashes are unordered collections> and to act accordingly.
+
+=head3 Hash randomization
+
+The seed used by Perl's hash function is now random. This means that the
+order which keys/values will be returned from functions like C<keys()>,
+C<values()>, and C<each()> will differ from run to run.
+
+This change was introduced to make Perl's hashes more robust to algorithmic
+complexity attacks, and also because we discovered that it exposes hash
+ordering dependency bugs and makes them easier to track down.
+
+Toolchain maintainers might want to invest in additional infrastructure to
+test for things like this. Running tests several times in a row and then
+comparing results will make it easier to spot hash order dependencies in
+code. Authors are strongly encouraged not to expose the key order of
+Perl's hashes to insecure audiences.
+
+Further, every hash has its own iteration order, which should make it much
+more difficult to determine what the current hash seed is.
+
+=head3 New hash functions
+
+Perl v5.18 includes support for multiple hash functions, and changed
+the default (to ONE_AT_A_TIME_HARD), you can choose a different
+algorithm by defining a symbol at compile time. For a current list,
+consult the F<INSTALL> document. Note that as of Perl v5.18 we can
+only recommend use of the default or SIPHASH. All the others are
+known to have security issues and are for research purposes only.
+
+=head3 PERL_HASH_SEED environment variable now takes a hex value
+
+C<PERL_HASH_SEED> no longer accepts an integer as a parameter;
+instead the value is expected to be a binary value encoded in a hex
+string, such as "0xf5867c55039dc724". This is to make the
+infrastructure support hash seeds of arbitrary lengths, which might
+exceed that of an integer. (SipHash uses a 16 byte seed.)
+
+=head3 PERL_PERTURB_KEYS environment variable added
+
+The C<PERL_PERTURB_KEYS> environment variable allows one to control the level of
+randomization applied to C<keys> and friends.
+
+When C<PERL_PERTURB_KEYS> is 0, perl will not randomize the key order at all. The
+chance that C<keys> changes due to an insert will be the same as in previous
+perls, basically only when the bucket size is changed.
+
+When C<PERL_PERTURB_KEYS> is 1, perl will randomize keys in a non-repeatable
+way. The chance that C<keys> changes due to an insert will be very high. This
+is the most secure and default mode.
+
+When C<PERL_PERTURB_KEYS> is 2, perl will randomize keys in a repeatable way.
+Repeated runs of the same program should produce the same output every time.
+
+C<PERL_HASH_SEED> implies a non-default C<PERL_PERTURB_KEYS> setting. Setting
+C<PERL_HASH_SEED=0> (exactly one 0) implies C<PERL_PERTURB_KEYS=0> (hash key
+randomization disabled); settng C<PERL_HASH_SEED> to any other value implies
+C<PERL_PERTURB_KEYS=2> (deterministic and repeatable hash key randomization).
+Specifying C<PERL_PERTURB_KEYS> explicitly to a different level overrides this
+behavior.
+
+=head3 Hash::Util::hash_seed() now returns a string
+
+Hash::Util::hash_seed() now returns a string instead of an integer. This
+is to make the infrastructure support hash seeds of arbitrary lengths
+which might exceed that of an integer. (SipHash uses a 16 byte seed.)
+
+=head3 Output of PERL_HASH_SEED_DEBUG has been changed
+
+The environment variable PERL_HASH_SEED_DEBUG now makes perl show both the
+hash function perl was built with, I<and> the seed, in hex, in use for that
+process. Code parsing this output, should it exist, must change to accommodate
+the new format. Example of the new format:
+
+ $ PERL_HASH_SEED_DEBUG=1 ./perl -e1
+ HASH_FUNCTION = MURMUR3 HASH_SEED = 0x1476bb9f
+
+=head2 Upgrade to Unicode 6.2
+
+Perl now supports Unicode 6.2. A list of changes from Unicode
+6.1 is at L<http://www.unicode.org/versions/Unicode6.2.0>.
+
+=head2 Character name aliases may now include non-Latin1-range characters
+
+It is possible to define your own names for characters for use in
+C<\N{...}>, C<charnames::vianame()>, etc. These names can now be
+comprised of characters from the whole Unicode range. This allows for
+names to be in your native language, and not just English. Certain
+restrictions apply to the characters that may be used (you can't define
+a name that has punctuation in it, for example). See L<charnames/CUSTOM
+ALIASES>.
+
+=head2 New DTrace probes
+
+The following new DTrace probes have been added:
+
+=over 4
+
+=item *
+
+C<op-entry>
+
+=item *
+
+C<loading-file>
+
+=item *
+
+C<loaded-file>
+
+=back
+
+=head2 C<${^LAST_FH}>
+
+This new variable provides access to the filehandle that was last read.
+This is the handle used by C<$.> and by C<tell> and C<eof> without
+arguments.
+
+=head2 Regular Expression Set Operations
+
+This is an B<experimental> feature to allow matching against the union,
+intersection, etc., of sets of code points, similar to
+L<Unicode::Regex::Set>. It can also be used to extend C</x> processing
+to [bracketed] character classes, and as a replacement of user-defined
+properties, allowing more complex expressions than they do. See
+L<perlrecharclass/Extended Bracketed Character Classes>.
+
+=head2 Lexical subroutines
+
+This new feature is still considered B<experimental>. To enable it:
+
+ use 5.018;
+ no warnings "experimental::lexical_subs";
+ use feature "lexical_subs";
+
+You can now declare subroutines with C<state sub foo>, C<my sub foo>, and
+C<our sub foo>. (C<state sub> requires that the "state" feature be
+enabled, unless you write it as C<CORE::state sub foo>.)
+
+C<state sub> creates a subroutine visible within the lexical scope in which
+it is declared. The subroutine is shared between calls to the outer sub.
+
+C<my sub> declares a lexical subroutine that is created each time the
+enclosing block is entered. C<state sub> is generally slightly faster than
+C<my sub>.
+
+C<our sub> declares a lexical alias to the package subroutine of the same
+name.
+
+For more information, see L<perlsub/Lexical Subroutines>.
+
+=head2 Computed Labels
+
+The loop controls C<next>, C<last> and C<redo>, and the special C<dump>
+operator, now allow arbitrary expressions to be used to compute labels at run
+time. Previously, any argument that was not a constant was treated as the
+empty string.
+
+=head2 More CORE:: subs
+
+Several more built-in functions have been added as subroutines to the
+CORE:: namespace - namely, those non-overridable keywords that can be
+implemented without custom parsers: C<defined>, C<delete>, C<exists>,
+C<glob>, C<pos>, C<protoytpe>, C<scalar>, C<split>, C<study>, and C<undef>.
+
+As some of these have prototypes, C<prototype('CORE::...')> has been
+changed to not make a distinction between overridable and non-overridable
+keywords. This is to make C<prototype('CORE::pos')> consistent with
+C<prototype(&CORE::pos)>.
+
+=head2 C<kill> with negative signal names
+
+C<kill> has always allowed a negative signal number, which kills the
+process group instead of a single process. It has also allowed signal
+names. But it did not behave consistently, because negative signal names
+were treated as 0. Now negative signals names like C<-INT> are supported
+and treated the same way as -2 [perl #112990].
+
+=head1 Security
+
+=head2 See also: hash overhaul
+
+Some of the changes in the L<hash overhaul|/"Hash overhaul"> were made to
+enhance security. Please read that section.
+
+=head2 C<Storable> security warning in documentation
+
+The documentation for C<Storable> now includes a section which warns readers
+of the danger of accepting Storable documents from untrusted sources. The
+short version is that deserializing certain types of data can lead to loading
+modules and other code execution. This is documented behavior and wanted
+behavior, but this opens an attack vector for malicious entities.
+
+=head2 C<Locale::Maketext> allowed code injection via a malicious template
+
+If users could provide a translation string to Locale::Maketext, this could be
+used to invoke arbitrary Perl subroutines available in the current process.
+
+This has been fixed, but it is still possible to invoke any method provided by
+C<Locale::Maketext> itself or a subclass that you are using. One of these
+methods in turn will invoke the Perl core's C<sprintf> subroutine.
+
+In summary, allowing users to provide translation strings without auditing
+them is a bad idea.
+
+This vulnerability is documented in CVE-2012-6329.
+
+=head2 Avoid calling memset with a negative count
+
+Poorly written perl code that allows an attacker to specify the count to perl's
+C<x> string repeat operator can already cause a memory exhaustion
+denial-of-service attack. A flaw in versions of perl before v5.15.5 can escalate
+that into a heap buffer overrun; coupled with versions of glibc before 2.16, it
+possibly allows the execution of arbitrary code.
+
+The flaw addressed to this commit has been assigned identifier CVE-2012-5195
+and was researched by Tim Brown.
+
+=head1 Incompatible Changes
+
+=head2 See also: hash overhaul
+
+Some of the changes in the L<hash overhaul|/"Hash overhaul"> are not fully
+compatible with previous versions of perl. Please read that section.
+
+=head2 An unknown character name in C<\N{...}> is now a syntax error
+
+Previously, it warned, and the Unicode REPLACEMENT CHARACTER was
+substituted. Unicode now recommends that this situation be a syntax
+error. Also, the previous behavior led to some confusing warnings and
+behaviors, and since the REPLACEMENT CHARACTER has no use other than as
+a stand-in for some unknown character, any code that has this problem is
+buggy.
+
+=head2 Formerly deprecated characters in C<\N{}> character name aliases are now errors.
+
+Since v5.12.0, it has been deprecated to use certain characters in
+user-defined C<\N{...}> character names. These now cause a syntax
+error. For example, it is now an error to begin a name with a digit,
+such as in
+
+ my $undraftable = "\N{4F}"; # Syntax error!
+
+or to have commas anywhere in the name. See L<charnames/CUSTOM ALIASES>.
+
+=head2 C<\N{BELL}> now refers to U+1F514 instead of U+0007
+
+Unicode 6.0 reused the name "BELL" for a different code point than it
+traditionally had meant. Since Perl v5.14, use of this name still
+referred to U+0007, but would raise a deprecation warning. Now, "BELL"
+refers to U+1F514, and the name for U+0007 is "ALERT". All the
+functions in L<charnames> have been correspondingly updated.
+
+=head2 New Restrictions in Multi-Character Case-Insensitive Matching in Regular Expression Bracketed Character Classes
+
+Unicode has now withdrawn their previous recommendation for regular
+expressions to automatically handle cases where a single character can
+match multiple characters case-insensitively, for example, the letter
+LATIN SMALL LETTER SHARP S and the sequence C<ss>. This is because
+it turns out to be impracticable to do this correctly in all
+circumstances. Because Perl has tried to do this as best it can, it
+will continue to do so. (We are considering an option to turn it off.)
+However, a new restriction is being added on such matches when they
+occur in [bracketed] character classes. People were specifying
+things such as C</[\0-\xff]/i>, and being surprised that it matches the
+two character sequence C<ss> (since LATIN SMALL LETTER SHARP S occurs in
+this range). This behavior is also inconsistent with using a
+property instead of a range: C<\p{Block=Latin1}> also includes LATIN
+SMALL LETTER SHARP S, but C</[\p{Block=Latin1}]/i> does not match C<ss>.
+The new rule is that for there to be a multi-character case-insensitive
+match within a bracketed character class, the character must be
+explicitly listed, and not as an end point of a range. This more
+closely obeys the Principle of Least Astonishment. See
+L<perlrecharclass/Bracketed Character Classes>. Note that a bug [perl
+#89774], now fixed as part of this change, prevented the previous
+behavior from working fully.
+
+=head2 Explicit rules for variable names and identifiers
+
+Due to an oversight, single character variable names in v5.16 were
+completely unrestricted. This opened the door to several kinds of
+insanity. As of v5.18, these now follow the rules of other identifiers,
+in addition to accepting characters that match the C<\p{POSIX_Punct}>
+property.
+
+There is no longer any difference in the parsing of identifiers
+specified by using braces versus without braces. For instance, perl
+used to allow C<${foo:bar}> (with a single colon) but not C<$foo:bar>.
+Now that both are handled by a single code path, they are both treated
+the same way: both are forbidden. Note that this change is about the
+range of permissible literal identifiers, not other expressions.
+
+=head2 Vertical tabs are now whitespace
+
+No one could recall why C<\s> didn't match C<\cK>, the vertical tab.
+Now it does. Given the extreme rarity of that character, very little
+breakage is expected. That said, here's what it means:
+
+C<\s> in a regex now matches a vertical tab in all circumstances.
+
+Literal vertical tabs in a regex literal are ignored when the C</x>
+modifier is used.
+
+Leading vertical tabs, alone or mixed with other whitespace, are now
+ignored when interpreting a string as a number. For example:
+
+ $dec = " \cK \t 123";
+ $hex = " \cK \t 0xF";
+
+ say 0 + $dec; # was 0 with warning, now 123
+ say int $dec; # was 0, now 123
+ say oct $hex; # was 0, now 15
+
+=head2 C</(?{})/> and C</(??{})/> have been heavily reworked
+
+The implementation of this feature has been almost completely rewritten.
+Although its main intent is to fix bugs, some behaviors, especially
+related to the scope of lexical variables, will have changed. This is
+described more fully in the L</Selected Bug Fixes> section.
+
+=head2 Stricter parsing of substitution replacement
+
+It is no longer possible to abuse the way the parser parses C<s///e> like
+this:
+
+ %_=(_,"Just another ");
+ $_="Perl hacker,\n";
+ s//_}->{_/e;print
+
+=head2 C<given> now aliases the global C<$_>
+
+Instead of assigning to an implicit lexical C<$_>, C<given> now makes the
+global C<$_> an alias for its argument, just like C<foreach>. However, it
+still uses lexical C<$_> if there is lexical C<$_> in scope (again, just like
+C<foreach>) [perl #114020].
+
+=head2 The smartmatch family of features are now experimental
+
+Smart match, added in v5.10.0 and significantly revised in v5.10.1, has been
+a regular point of complaint. Although there are a number of ways in which
+it is useful, it has also proven problematic and confusing for both users and
+implementors of Perl. There have been a number of proposals on how to best
+address the problem. It is clear that smartmatch is almost certainly either
+going to change or go away in the future. Relying on its current behavior
+is not recommended.
+
+Warnings will now be issued when the parser sees C<~~>, C<given>, or C<when>.
+To disable these warnings, you can add this line to the appropriate scope:
+
+ no if $] >= 5.018, warnings => "experimental::smartmatch";
+
+Consider, though, replacing the use of these features, as they may change
+behavior again before becoming stable.
+
+=head2 Lexical C<$_> is now experimental
+
+Since it was introduced in Perl v5.10, it has caused much confusion with no
+obvious solution:
+
+=over
+
+=item *
+
+Various modules (e.g., List::Util) expect callback routines to use the
+global C<$_>. C<use List::Util 'first'; my $_; first { $_ == 1 } @list>
+does not work as one would expect.
+
+=item *
+
+A C<my $_> declaration earlier in the same file can cause confusing closure
+warnings.
+
+=item *
+
+The "_" subroutine prototype character allows called subroutines to access
+your lexical C<$_>, so it is not really private after all.
+
+=item *
+
+Nevertheless, subroutines with a "(@)" prototype and methods cannot access
+the caller's lexical C<$_>, unless they are written in XS.
+
+=item *
+
+But even XS routines cannot access a lexical C<$_> declared, not in the
+calling subroutine, but in an outer scope, iff that subroutine happened not
+to mention C<$_> or use any operators that default to C<$_>.
+
+=back
+
+It is our hope that lexical C<$_> can be rehabilitated, but this may
+cause changes in its behavior. Please use it with caution until it
+becomes stable.
+
+=head2 readline() with C<$/ = \N> now reads N characters, not N bytes
+
+Previously, when reading from a stream with I/O layers such as
+C<encoding>, the readline() function, otherwise known as the C<< <> >>
+operator, would read I<N> bytes from the top-most layer. [perl #79960]
+
+Now, I<N> characters are read instead.
+
+There is no change in behaviour when reading from streams with no
+extra layers, since bytes map exactly to characters.
+
+=head2 Overridden C<glob> is now passed one argument
+
+C<glob> overrides used to be passed a magical undocumented second argument
+that identified the caller. Nothing on CPAN was using this, and it got in
+the way of a bug fix, so it was removed. If you really need to identify
+the caller, see L<Devel::Callsite> on CPAN.
+
+=head2 Here doc parsing
+
+The body of a here document inside a quote-like operator now always begins
+on the line after the "<<foo" marker. Previously, it was documented to
+begin on the line following the containing quote-like operator, but that
+was only sometimes the case [perl #114040].
+
+=head2 Alphanumeric operators must now be separated from the closing
+delimiter of regular expressions
+
+You may no longer write something like:
+
+ m/a/and 1
+
+Instead you must write
+
+ m/a/ and 1
+
+with whitespace separating the operator from the closing delimiter of
+the regular expression. Not having whitespace has resulted in a
+deprecation warning since Perl v5.14.0.
+
+=head2 qw(...) can no longer be used as parentheses
+
+C<qw> lists used to fool the parser into thinking they were always
+surrounded by parentheses. This permitted some surprising constructions
+such as C<foreach $x qw(a b c) {...}>, which should really be written
+C<foreach $x (qw(a b c)) {...}>. These would sometimes get the lexer into
+the wrong state, so they didn't fully work, and the similar C<foreach qw(a
+b c) {...}> that one might expect to be permitted never worked at all.
+
+This side effect of C<qw> has now been abolished. It has been deprecated
+since Perl v5.13.11. It is now necessary to use real parentheses
+everywhere that the grammar calls for them.
+
+=head2 Interaction of lexical and default warnings
+
+Turning on any lexical warnings used first to disable all default warnings
+if lexical warnings were not already enabled:
+
+ $*; # deprecation warning
+ use warnings "void";
+ $#; # void warning; no deprecation warning
+
+Now, the C<debugging>, C<deprecated>, C<glob>, C<inplace> and C<malloc> warnings
+categories are left on when turning on lexical warnings (unless they are
+turned off by C<no warnings>, of course).
+
+This may cause deprecation warnings to occur in code that used to be free
+of warnings.
+
+Those are the only categories consisting only of default warnings. Default
+warnings in other categories are still disabled by C<< use warnings "category" >>,
+as we do not yet have the infrastructure for controlling
+individual warnings.
+
+=head2 C<state sub> and C<our sub>
+
+Due to an accident of history, C<state sub> and C<our sub> were equivalent
+to a plain C<sub>, so one could even create an anonymous sub with
+C<our sub { ... }>. These are now disallowed outside of the "lexical_subs"
+feature. Under the "lexical_subs" feature they have new meanings described
+in L<perlsub/Lexical Subroutines>.
+
+=head2 Defined values stored in environment are forced to byte strings
+
+A value stored in an environment variable has always been stringified. In this
+release, it is converted to be only a byte string. First, it is forced to be
+only a string. Then if the string is utf8 and the equivalent of
+C<utf8::downgrade()> works, that result is used; otherwise, the equivalent of
+C<utf8::encode()> is used, and a warning is issued about wide characters
+(L</Diagnostics>).
+
+=head2 C<require> dies for unreadable files
+
+When C<require> encounters an unreadable file, it now dies. It used to
+ignore the file and continue searching the directories in C<@INC>
+[perl #113422].
+
+=head2 C<gv_fetchmeth_*> and SUPER
+
+The various C<gv_fetchmeth_*> XS functions used to treat a package whose
+named ended with C<::SUPER> specially. A method lookup on the C<Foo::SUPER>
+package would be treated as a C<SUPER> method lookup on the C<Foo> package. This
+is no longer the case. To do a C<SUPER> lookup, pass the C<Foo> stash and the
+C<GV_SUPER> flag.
+
+=head2 C<split>'s first argument is more consistently interpreted
+
+After some changes earlier in v5.17, C<split>'s behavior has been
+simplified: if the PATTERN argument evaluates to a string
+containing one space, it is treated the way that a I<literal> string
+containing one space once was.
+
+=head1 Deprecations
+
+=head2 Module removals
+
+The following modules will be removed from the core distribution in a future
+release, and will at that time need to be installed from CPAN. Distributions
+on CPAN which require these modules will need to list them as prerequisites.
+
+The core versions of these modules will now issue C<"deprecated">-category
+warnings to alert you to this fact. To silence these deprecation warnings,
+install the modules in question from CPAN.
+
+Note that these are (with rare exceptions) fine modules that you are encouraged
+to continue to use. Their disinclusion from core primarily hinges on their
+necessity to bootstrapping a fully functional, CPAN-capable Perl installation,
+not usually on concerns over their design.
+
+=over
+
+=item L<encoding>
+
+The use of this pragma is now strongly discouraged. It conflates the encoding
+of source text with the encoding of I/O data, reinterprets escape sequences in
+source text (a questionable choice), and introduces the UTF-8 bug to all runtime
+handling of character strings. It is broken as designed and beyond repair.
+
+For using non-ASCII literal characters in source text, please refer to L<utf8>.
+For dealing with textual I/O data, please refer to L<Encode> and L<open>.
+
+=item L<Archive::Extract>
+
+=item L<B::Lint>
+
+=item L<B::Lint::Debug>
+
+=item L<CPANPLUS> and all included C<CPANPLUS::*> modules
+
+=item L<Devel::InnerPackage>
+
+=item L<Log::Message>
+
+=item L<Log::Message::Config>
+
+=item L<Log::Message::Handlers>
+
+=item L<Log::Message::Item>
+
+=item L<Log::Message::Simple>
+
+=item L<Module::Pluggable>
+
+=item L<Module::Pluggable::Object>
+
+=item L<Object::Accessor>
+
+=item L<Pod::LaTeX>
+
+=item L<Term::UI>
+
+=item L<Term::UI::History>
+
+=back
+
+=head2 Deprecated Utilities
+
+The following utilities will be removed from the core distribution in a
+future release as their associated modules have been deprecated. They
+will remain available with the applicable CPAN distribution.
+
+=over
+
+=item L<cpanp>
+
+=item C<cpanp-run-perl>
+
+=item L<cpan2dist>
+
+These items are part of the C<CPANPLUS> distribution.
+
+=item L<pod2latex>
+
+This item is part of the C<Pod::LaTeX> distribution.
+
+=back
+
+=head2 PL_sv_objcount
+
+This interpreter-global variable used to track the total number of
+Perl objects in the interpreter. It is no longer maintained and will
+be removed altogether in Perl v5.20.
+
+=head2 Five additional characters should be escaped in patterns with C</x>
+
+When a regular expression pattern is compiled with C</x>, Perl treats 6
+characters as white space to ignore, such as SPACE and TAB. However,
+Unicode recommends 11 characters be treated thusly. We will conform
+with this in a future Perl version. In the meantime, use of any of the
+missing characters will raise a deprecation warning, unless turned off.
+The five characters are:
+
+ U+0085 NEXT LINE
+ U+200E LEFT-TO-RIGHT MARK
+ U+200F RIGHT-TO-LEFT MARK
+ U+2028 LINE SEPARATOR
+ U+2029 PARAGRAPH SEPARATOR
+
+=head2 User-defined charnames with surprising whitespace
+
+A user-defined character name with trailing or multiple spaces in a row is
+likely a typo. This now generates a warning when defined, on the assumption
+that uses of it will be unlikely to include the excess whitespace.
+
+=head2 Various XS-callable functions are now deprecated
+
+All the functions used to classify characters will be removed from a
+future version of Perl, and should not be used. With participating C
+compilers (e.g., gcc), compiling any file that uses any of these will
+generate a warning. These were not intended for public use; there are
+equivalent, faster, macros for most of them.
+
+See L<perlapi/Character classes>. The complete list is:
+
+C<is_uni_alnum>, C<is_uni_alnumc>, C<is_uni_alnumc_lc>,
+C<is_uni_alnum_lc>, C<is_uni_alpha>, C<is_uni_alpha_lc>,
+C<is_uni_ascii>, C<is_uni_ascii_lc>, C<is_uni_blank>,
+C<is_uni_blank_lc>, C<is_uni_cntrl>, C<is_uni_cntrl_lc>,
+C<is_uni_digit>, C<is_uni_digit_lc>, C<is_uni_graph>,
+C<is_uni_graph_lc>, C<is_uni_idfirst>, C<is_uni_idfirst_lc>,
+C<is_uni_lower>, C<is_uni_lower_lc>, C<is_uni_print>,
+C<is_uni_print_lc>, C<is_uni_punct>, C<is_uni_punct_lc>,
+C<is_uni_space>, C<is_uni_space_lc>, C<is_uni_upper>,
+C<is_uni_upper_lc>, C<is_uni_xdigit>, C<is_uni_xdigit_lc>,
+C<is_utf8_alnum>, C<is_utf8_alnumc>, C<is_utf8_alpha>,
+C<is_utf8_ascii>, C<is_utf8_blank>, C<is_utf8_char>,
+C<is_utf8_cntrl>, C<is_utf8_digit>, C<is_utf8_graph>,
+C<is_utf8_idcont>, C<is_utf8_idfirst>, C<is_utf8_lower>,
+C<is_utf8_mark>, C<is_utf8_perl_space>, C<is_utf8_perl_word>,
+C<is_utf8_posix_digit>, C<is_utf8_print>, C<is_utf8_punct>,
+C<is_utf8_space>, C<is_utf8_upper>, C<is_utf8_xdigit>,
+C<is_utf8_xidcont>, C<is_utf8_xidfirst>.
+
+In addition these three functions that have never worked properly are
+deprecated:
+C<to_uni_lower_lc>, C<to_uni_title_lc>, and C<to_uni_upper_lc>.
+
+=head2 Certain rare uses of backslashes within regexes are now deprecated
+
+There are three pairs of characters that Perl recognizes as
+metacharacters in regular expression patterns: C<{}>, C<[]>, and C<()>.
+These can be used as well to delimit patterns, as in:
+
+ m{foo}
+ s(foo)(bar)
+
+Since they are metacharacters, they have special meaning to regular
+expression patterns, and it turns out that you can't turn off that
+special meaning by the normal means of preceding them with a backslash,
+if you use them, paired, within a pattern delimited by them. For
+example, in
+
+ m{foo\{1,3\}}
+
+the backslashes do not change the behavior, and this matches
+S<C<"f o">> followed by one to three more occurrences of C<"o">.
+
+Usages like this, where they are interpreted as metacharacters, are
+exceedingly rare; we think there are none, for example, in all of CPAN.
+Hence, this deprecation should affect very little code. It does give
+notice, however, that any such code needs to change, which will in turn
+allow us to change the behavior in future Perl versions so that the
+backslashes do have an effect, and without fear that we are silently
+breaking any existing code.
+
+=head2 Splitting the tokens C<(?> and C<(*> in regular expressions
+
+A deprecation warning is now raised if the C<(> and C<?> are separated
+by white space or comments in C<(?...)> regular expression constructs.
+Similarly, if the C<(> and C<*> are separated in C<(*VERB...)>
+constructs.
+
+=head2 Pre-PerlIO IO implementations
+
+In theory, you can currently build perl without PerlIO. Instead, you'd use a
+wrapper around stdio or sfio. In practice, this isn't very useful. It's not
+well tested, and without any support for IO layers or (thus) Unicode, it's not
+much of a perl. Building without PerlIO will most likely be removed in the
+next version of perl.
+
+PerlIO supports a C<stdio> layer if stdio use is desired. Similarly a
+sfio layer could be produced in the future, if needed.
+
+=head1 Future Deprecations
+
+=over
+
+=item *
+
+Platforms without support infrastructure
+
+Both Windows CE and z/OS have been historically under-maintained, and are
+currently neither successfully building nor regularly being smoke tested.
+Efforts are underway to change this situation, but it should not be taken for
+granted that the platforms are safe and supported. If they do not become
+buildable and regularly smoked, support for them may be actively removed in
+future releases. If you have an interest in these platforms and you can lend
+your time, expertise, or hardware to help support these platforms, please let
+the perl development effort know by emailing C<perl5-porters at perl.org>.
+
+Some platforms that appear otherwise entirely dead are also on the short list
+for removal between now and v5.20.0:
+
+=over
+
+=item DG/UX
+
+=item NeXT
+
+=back
+
+We also think it likely that current versions of Perl will no longer
+build AmigaOS, DJGPP, NetWare (natively), OS/2 and Plan 9. If you
+are using Perl on such a platform and have an interest in ensuring
+Perl's future on them, please contact us.
+
+We believe that Perl has long been unable to build on mixed endian
+architectures (such as PDP-11s), and intend to remove any remaining
+support code. Similarly, code supporting the long umaintained GNU
+dld will be removed soon if no-one makes themselves known as an
+active user.
+
+=item *
+
+Swapping of $< and $>
+
+Perl has supported the idiom of swapping $< and $> (and likewise $( and
+$)) to temporarily drop permissions since 5.0, like this:
+
+ ($<, $>) = ($>, $<);
+
+However, this idiom modifies the real user/group id, which can have
+undesirable side-effects, is no longer useful on any platform perl
+supports and complicates the implementation of these variables and list
+assignment in general.
+
+As an alternative, assignment only to C<< $> >> is recommended:
+
+ local $> = $<;
+
+See also: L<Setuid Demystified|http://www.cs.berkeley.edu/~daw/papers/setuid-usenix02.pdf>.
+
+=item *
+
+C<microperl>, long broken and of unclear present purpose, will be removed.
+
+=item *
+
+Revamping C<< "\Q" >> semantics in double-quotish strings when combined with
+other escapes.
+
+There are several bugs and inconsistencies involving combinations
+of C<\Q> and escapes like C<\x>, C<\L>, etc., within a C<\Q...\E> pair.
+These need to be fixed, and doing so will necessarily change current
+behavior. The changes have not yet been settled.
+
+=item *
+
+Use of C<$x>, where C<x> stands for any actual (non-printing) C0 control
+character will be disallowed in a future Perl version. Use C<${x}>
+instead (where again C<x> stands for a control character),
+or better, C<$^A> , where C<^> is a caret (CIRCUMFLEX ACCENT),
+and C<A> stands for any of the characters listed at the end of
+L<perlebcdic/OPERATOR DIFFERENCES>.
+
+=back
+
+=head1 Performance Enhancements
+
+=over 4
+
+=item *
+
+Lists of lexical variable declarations (C<my($x, $y)>) are now optimised
+down to a single op and are hence faster than before.
+
+=item *
+
+A new C preprocessor define C<NO_TAINT_SUPPORT> was added that, if set,
+disables Perl's taint support altogether. Using the -T or -t command
+line flags will cause a fatal error. Beware that both core tests as
+well as many a CPAN distribution's tests will fail with this change. On
+the upside, it provides a small performance benefit due to reduced
+branching.
+
+B<Do not enable this unless you know exactly what you are getting yourself
+into.>
+
+=item *
+
+C<pack> with constant arguments is now constant folded in most cases
+[perl #113470].
+
+=item *
+
+Speed up in regular expression matching against Unicode properties. The
+largest gain is for C<\X>, the Unicode "extended grapheme cluster." The
+gain for it is about 35% - 40%. Bracketed character classes, e.g.,
+C<[0-9\x{100}]> containing code points above 255 are also now faster.
+
+=item *
+
+On platforms supporting it, several former macros are now implemented as static
+inline functions. This should speed things up slightly on non-GCC platforms.
+
+=item *
+
+The optimisation of hashes in boolean context has been extended to
+affect C<scalar(%hash)>, C<%hash ? ... : ...>, and C<sub { %hash || ... }>.
+
+=item *
+
+Filetest operators manage the stack in a fractionally more efficient manner.
+
+=item *
+
+Globs used in a numeric context are now numified directly in most cases,
+rather than being numified via stringification.
+
+=item *
+
+The C<x> repetition operator is now folded to a single constant at compile
+time if called in scalar context with constant operands and no parentheses
+around the left operand.
+
+=back
+
+=head1 Modules and Pragmata
+
+=head2 New Modules and Pragmata
+
+=over 4
+
+=item *
+
+L<Config::Perl::V> version 0.16 has been added as a dual-lifed module.
+It provides structured data retrieval of C<perl -V> output including
+information only known to the C<perl> binary and not available via L<Config>.
+
+=back
+
+=head2 Updated Modules and Pragmata
+
+For a complete list of updates, run:
+
+ $ corelist --diff 5.16.0 5.18.0
+
+You can substitute your favorite version in place of C<5.16.0>, too.
+
+=over
+
+=item *
+
+L<Archive::Extract> has been upgraded to 0.68.
+
+Work around an edge case on Linux with Busybox's unzip.
+
+=item *
+
+L<Archive::Tar> has been upgraded to 1.90.
+
+ptar now supports the -T option as well as dashless options
+[rt.cpan.org #75473], [rt.cpan.org #75475].
+
+Auto-encode filenames marked as UTF-8 [rt.cpan.org #75474].
+
+Don't use C<tell> on L<IO::Zlib> handles [rt.cpan.org #64339].
+
+Don't try to C<chown> on symlinks.
+
+=item *
+
+L<autodie> has been upgraded to 2.13.
+
+C<autodie> now plays nicely with the 'open' pragma.
+
+=item *
+
+L<B> has been upgraded to 1.42.
+
+The C<stashoff> method of COPs has been added. This provides access to an
+internal field added in perl 5.16 under threaded builds [perl #113034].
+
+C<B::COP::stashpv> now supports UTF-8 package names and embedded NULs.
+
+All C<CVf_*> and C<GVf_*>
+and more SV-related flag values are now provided as constants in the C<B::>
+namespace and available for export. The default export list has not changed.
+
+This makes the module work with the new pad API.
+
+=item *
+
+L<B::Concise> has been upgraded to 0.95.
+
+The C<-nobanner> option has been fixed, and C<format>s can now be dumped.
+When passed a sub name to dump, it will check also to see whether it
+is the name of a format. If a sub and a format share the same name,
+it will dump both.
+
+This adds support for the new C<OpMAYBE_TRUEBOOL> and C<OPpTRUEBOOL> flags.
+
+=item *
+
+L<B::Debug> has been upgraded to 1.18.
+
+This adds support (experimentally) for C<B::PADLIST>, which was
+added in Perl 5.17.4.
+
+=item *
+
+L<B::Deparse> has been upgraded to 1.20.
+
+Avoid warning when run under C<perl -w>.
+
+It now deparses
+loop controls with the correct precedence, and multiple statements in a
+C<format> line are also now deparsed correctly.
+
+This release suppresses trailing semicolons in formats.
+
+This release adds stub deparsing for lexical subroutines.
+
+It no longer dies when deparsing C<sort> without arguments. It now
+correctly omits the comma for C<system $prog @args> and C<exec $prog
+ at args>.
+
+=item *
+
+L<bignum>, L<bigint> and L<bigrat> have been upgraded to 0.33.
+
+The overrides for C<hex> and C<oct> have been rewritten, eliminating
+several problems, and making one incompatible change:
+
+=over
+
+=item *
+
+Formerly, whichever of C<use bigint> or C<use bigrat> was compiled later
+would take precedence over the other, causing C<hex> and C<oct> not to
+respect the other pragma when in scope.
+
+=item *
+
+Using any of these three pragmata would cause C<hex> and C<oct> anywhere
+else in the program to evalute their arguments in list context and prevent
+them from inferring $_ when called without arguments.
+
+=item *
+
+Using any of these three pragmata would make C<oct("1234")> return 1234
+(for any number not beginning with 0) anywhere in the program. Now "1234"
+is translated from octal to decimal, whether within the pragma's scope or
+not.
+
+=item *
+
+The global overrides that facilitate lexical use of C<hex> and C<oct> now
+respect any existing overrides that were in place before the new overrides
+were installed, falling back to them outside of the scope of C<use bignum>.
+
+=item *
+
+C<use bignum "hex">, C<use bignum "oct"> and similar invocations for bigint
+and bigrat now export a C<hex> or C<oct> function, instead of providing a
+global override.
+
+=back
+
+=item *
+
+L<Carp> has been upgraded to 1.29.
+
+Carp is no longer confused when C<caller> returns undef for a package that
+has been deleted.
+
+The C<longmess()> and C<shortmess()> functions are now documented.
+
+=item *
+
+L<CGI> has been upgraded to 3.63.
+
+Unrecognized HTML escape sequences are now handled better, problematic
+trailing newlines are no longer inserted after E<lt>formE<gt> tags
+by C<startform()> or C<start_form()>, and bogus "Insecure Dependency"
+warnings appearing with some versions of perl are now worked around.
+
+=item *
+
+L<Class::Struct> has been upgraded to 0.64.
+
+The constructor now respects overridden accessor methods [perl #29230].
+
+=item *
+
+L<Compress::Raw::Bzip2> has been upgraded to 2.060.
+
+The misuse of Perl's "magic" API has been fixed.
+
+=item *
+
+L<Compress::Raw::Zlib> has been upgraded to 2.060.
+
+Upgrade bundled zlib to version 1.2.7.
+
+Fix build failures on Irix, Solaris, and Win32, and also when building as C++
+[rt.cpan.org #69985], [rt.cpan.org #77030], [rt.cpan.org #75222].
+
+The misuse of Perl's "magic" API has been fixed.
+
+C<compress()>, C<uncompress()>, C<memGzip()> and C<memGunzip()> have
+been speeded up by making parameter validation more efficient.
+
+=item *
+
+L<CPAN::Meta::Requirements> has been upgraded to 2.122.
+
+Treat undef requirements to C<from_string_hash> as 0 (with a warning).
+
+Added C<requirements_for_module> method.
+
+=item *
+
+L<CPANPLUS> has been upgraded to 0.9135.
+
+Allow adding F<blib/script> to PATH.
+
+Save the history between invocations of the shell.
+
+Handle multiple C<makemakerargs> and C<makeflags> arguments better.
+
+This resolves issues with the SQLite source engine.
+
+=item *
+
+L<Data::Dumper> has been upgraded to 2.145.
+
+It has been optimized to only build a seen-scalar hash as necessary,
+thereby speeding up serialization drastically.
+
+Additional tests were added in order to improve statement, branch, condition
+and subroutine coverage. On the basis of the coverage analysis, some of the
+internals of Dumper.pm were refactored. Almost all methods are now
+documented.
+
+=item *
+
+L<DB_File> has been upgraded to 1.827.
+
+The main Perl module no longer uses the C<"@_"> construct.
+
+=item *
+
+L<Devel::Peek> has been upgraded to 1.11.
+
+This fixes compilation with C++ compilers and makes the module work with
+the new pad API.
+
+=item *
+
+L<Digest::MD5> has been upgraded to 2.52.
+
+Fix C<Digest::Perl::MD5> OO fallback [rt.cpan.org #66634].
+
+=item *
+
+L<Digest::SHA> has been upgraded to 5.84.
+
+This fixes a double-free bug, which might have caused vulnerabilities
+in some cases.
+
+=item *
+
+L<DynaLoader> has been upgraded to 1.18.
+
+This is due to a minor code change in the XS for the VMS implementation.
+
+This fixes warnings about using C<CODE> sections without an C<OUTPUT>
+section.
+
+=item *
+
+L<Encode> has been upgraded to 2.49.
+
+The Mac alias x-mac-ce has been added, and various bugs have been fixed
+in Encode::Unicode, Encode::UTF7 and Encode::GSM0338.
+
+=item *
+
+L<Env> has been upgraded to 1.04.
+
+Its SPLICE implementation no longer misbehaves in list context.
+
+=item *
+
+L<ExtUtils::CBuilder> has been upgraded to 0.280210.
+
+Manifest files are now correctly embedded for those versions of VC++ which
+make use of them. [perl #111782, #111798].
+
+A list of symbols to export can now be passed to C<link()> when on
+Windows, as on other OSes [perl #115100].
+
+=item *
+
+L<ExtUtils::ParseXS> has been upgraded to 3.18.
+
+The generated C code now avoids unnecessarily incrementing
+C<PL_amagic_generation> on Perl versions where it's done automatically
+(or on current Perl where the variable no longer exists).
+
+This avoids a bogus warning for initialised XSUB non-parameters [perl
+#112776].
+
+=item *
+
+L<File::Copy> has been upgraded to 2.26.
+
+C<copy()> no longer zeros files when copying into the same directory,
+and also now fails (as it has long been documented to do) when attempting
+to copy a file over itself.
+
+=item *
+
+L<File::DosGlob> has been upgraded to 1.10.
+
+The internal cache of file names that it keeps for each caller is now
+freed when that caller is freed. This means
+C<< use File::DosGlob 'glob'; eval 'scalar <*>' >> no longer leaks memory.
+
+=item *
+
+L<File::Fetch> has been upgraded to 0.38.
+
+Added the 'file_default' option for URLs that do not have a file
+component.
+
+Use C<File::HomeDir> when available, and provide C<PERL5_CPANPLUS_HOME> to
+override the autodetection.
+
+Always re-fetch F<CHECKSUMS> if C<fetchdir> is set.
+
+=item *
+
+L<File::Find> has been upgraded to 1.23.
+
+This fixes inconsistent unixy path handling on VMS.
+
+Individual files may now appear in list of directories to be searched
+[perl #59750].
+
+=item *
+
+L<File::Glob> has been upgraded to 1.20.
+
+File::Glob has had exactly the same fix as File::DosGlob. Since it is
+what Perl's own C<glob> operator itself uses (except on VMS), this means
+C<< eval 'scalar <*>' >> no longer leaks.
+
+A space-separated list of patterns return long lists of results no longer
+results in memory corruption or crashes. This bug was introduced in
+Perl 5.16.0. [perl #114984]
+
+=item *
+
+L<File::Spec::Unix> has been upgraded to 3.40.
+
+C<abs2rel> could produce incorrect results when given two relative paths or
+the root directory twice [perl #111510].
+
+=item *
+
+L<File::stat> has been upgraded to 1.07.
+
+C<File::stat> ignores the L<filetest> pragma, and warns when used in
+combination therewith. But it was not warning for C<-r>. This has been
+fixed [perl #111640].
+
+C<-p> now works, and does not return false for pipes [perl #111638].
+
+Previously C<File::stat>'s overloaded C<-x> and C<-X> operators did not give
+the correct results for directories or executable files when running as
+root. They had been treating executable permissions for root just like for
+any other user, performing group membership tests I<etc> for files not owned
+by root. They now follow the correct Unix behaviour - for a directory they
+are always true, and for a file if any of the three execute permission bits
+are set then they report that root can execute the file. Perl's builtin
+C<-x> and C<-X> operators have always been correct.
+
+=item *
+
+L<File::Temp> has been upgraded to 0.23
+
+Fixes various bugs involving directory removal. Defers unlinking tempfiles if
+the initial unlink fails, which fixes problems on NFS.
+
+=item *
+
+L<GDBM_File> has been upgraded to 1.15.
+
+The undocumented optional fifth parameter to C<TIEHASH> has been
+removed. This was intended to provide control of the callback used by
+C<gdbm*> functions in case of fatal errors (such as filesystem problems),
+but did not work (and could never have worked). No code on CPAN even
+attempted to use it. The callback is now always the previous default,
+C<croak>. Problems on some platforms with how the C<C> C<croak> function
+is called have also been resolved.
+
+=item *
+
+L<Hash::Util> has been upgraded to 0.15.
+
+C<hash_unlocked> and C<hashref_unlocked> now returns true if the hash is
+unlocked, instead of always returning false [perl #112126].
+
+C<hash_unlocked>, C<hashref_unlocked>, C<lock_hash_recurse> and
+C<unlock_hash_recurse> are now exportable [perl #112126].
+
+Two new functions, C<hash_locked> and C<hashref_locked>, have been added.
+Oddly enough, these two functions were already exported, even though they
+did not exist [perl #112126].
+
+=item *
+
+L<HTTP::Tiny> has been upgraded to 0.025.
+
+Add SSL verification features [github #6], [github #9].
+
+Include the final URL in the response hashref.
+
+Add C<local_address> option.
+
+This improves SSL support.
+
+=item *
+
+L<IO> has been upgraded to 1.28.
+
+C<sync()> can now be called on read-only file handles [perl #64772].
+
+L<IO::Socket> tries harder to cache or otherwise fetch socket
+information.
+
+=item *
+
+L<IPC::Cmd> has been upgraded to 0.80.
+
+Use C<POSIX::_exit> instead of C<exit> in C<run_forked> [rt.cpan.org #76901].
+
+=item *
+
+L<IPC::Open3> has been upgraded to 1.13.
+
+The C<open3()> function no longer uses C<POSIX::close()> to close file
+descriptors since that breaks the ref-counting of file descriptors done by
+PerlIO in cases where the file descriptors are shared by PerlIO streams,
+leading to attempts to close the file descriptors a second time when
+any such PerlIO streams are closed later on.
+
+=item *
+
+L<Locale::Codes> has been upgraded to 3.25.
+
+It includes some new codes.
+
+=item *
+
+L<Memoize> has been upgraded to 1.03.
+
+Fix the C<MERGE> cache option.
+
+=item *
+
+L<Module::Build> has been upgraded to 0.4003.
+
+Fixed bug where modules without C<$VERSION> might have a version of '0' listed
+in 'provides' metadata, which will be rejected by PAUSE.
+
+Fixed bug in PodParser to allow numerals in module names.
+
+Fixed bug where giving arguments twice led to them becoming arrays, resulting
+in install paths like F<ARRAY(0xdeadbeef)/lib/Foo.pm>.
+
+A minor bug fix allows markup to be used around the leading "Name" in
+a POD "abstract" line, and some documentation improvements have been made.
+
+=item *
+
+L<Module::CoreList> has been upgraded to 2.90
+
+Version information is now stored as a delta, which greatly reduces the
+size of the F<CoreList.pm> file.
+
+This restores compatibility with older versions of perl and cleans up
+the corelist data for various modules.
+
+=item *
+
+L<Module::Load::Conditional> has been upgraded to 0.54.
+
+Fix use of C<requires> on perls installed to a path with spaces.
+
+Various enhancements include the new use of Module::Metadata.
+
+=item *
+
+L<Module::Metadata> has been upgraded to 1.000011.
+
+The creation of a Module::Metadata object for a typical module file has
+been sped up by about 40%, and some spurious warnings about C<$VERSION>s
+have been suppressed.
+
+=item *
+
+L<Module::Pluggable> has been upgraded to 4.7.
+
+Amongst other changes, triggers are now allowed on events, which gives
+a powerful way to modify behaviour.
+
+=item *
+
+L<Net::Ping> has been upgraded to 2.41.
+
+This fixes some test failures on Windows.
+
+=item *
+
+L<Opcode> has been upgraded to 1.25.
+
+Reflect the removal of the boolkeys opcode and the addition of the
+clonecv, introcv and padcv opcodes.
+
+=item *
+
+L<overload> has been upgraded to 1.22.
+
+C<no overload> now warns for invalid arguments, just like C<use overload>.
+
+=item *
+
+L<PerlIO::encoding> has been upgraded to 0.16.
+
+This is the module implementing the ":encoding(...)" I/O layer. It no
+longer corrupts memory or crashes when the encoding back-end reallocates
+the buffer or gives it a typeglob or shared hash key scalar.
+
+=item *
+
+L<PerlIO::scalar> has been upgraded to 0.16.
+
+The buffer scalar supplied may now only contain code pounts 0xFF or
+lower. [perl #109828]
+
+=item *
+
+L<Perl::OSType> has been upgraded to 1.003.
+
+This fixes a bug detecting the VOS operating system.
+
+=item *
+
+L<Pod::Html> has been upgraded to 1.18.
+
+The option C<--libpods> has been reinstated. It is deprecated, and its use
+does nothing other than issue a warning that it is no longer supported.
+
+Since the HTML files generated by pod2html claim to have a UTF-8 charset,
+actually write the files out using UTF-8 [perl #111446].
+
+=item *
+
+L<Pod::Simple> has been upgraded to 3.28.
+
+Numerous improvements have been made, mostly to Pod::Simple::XHTML,
+which also has a compatibility change: the C<codes_in_verbatim> option
+is now disabled by default. See F<cpan/Pod-Simple/ChangeLog> for the
+full details.
+
+=item *
+
+L<re> has been upgraded to 0.23
+
+Single character [class]es like C</[s]/> or C</[s]/i> are now optimized
+as if they did not have the brackets, i.e. C</s/> or C</s/i>.
+
+See note about C<op_comp> in the L</Internal Changes> section below.
+
+=item *
+
+L<Safe> has been upgraded to 2.35.
+
+Fix interactions with C<Devel::Cover>.
+
+Don't eval code under C<no strict>.
+
+=item *
+
+L<Scalar::Util> has been upgraded to version 1.27.
+
+Fix an overloading issue with C<sum>.
+
+C<first> and C<reduce> now check the callback first (so C<&first(1)> is
+disallowed).
+
+Fix C<tainted> on magical values [rt.cpan.org #55763].
+
+Fix C<sum> on previously magical values [rt.cpan.org #61118].
+
+Fix reading past the end of a fixed buffer [rt.cpan.org #72700].
+
+=item *
+
+L<Search::Dict> has been upgraded to 1.07.
+
+No longer require C<stat> on filehandles.
+
+Use C<fc> for casefolding.
+
+=item *
+
+L<Socket> has been upgraded to 2.009.
+
+Constants and functions required for IP multicast source group membership
+have been added.
+
+C<unpack_sockaddr_in()> and C<unpack_sockaddr_in6()> now return just the IP
+address in scalar context, and C<inet_ntop()> now guards against incorrect
+length scalars being passed in.
+
+This fixes an uninitialized memory read.
+
+=item *
+
+L<Storable> has been upgraded to 2.41.
+
+Modifying C<$_[0]> within C<STORABLE_freeze> no longer results in crashes
+[perl #112358].
+
+An object whose class implements C<STORABLE_attach> is now thawed only once
+when there are multiple references to it in the structure being thawed
+[perl #111918].
+
+Restricted hashes were not always thawed correctly [perl #73972].
+
+Storable would croak when freezing a blessed REF object with a
+C<STORABLE_freeze()> method [perl #113880].
+
+It can now freeze and thaw vstrings correctly. This causes a slight
+incompatible change in the storage format, so the format version has
+increased to 2.9.
+
+This contains various bugfixes, including compatibility fixes for older
+versions of Perl and vstring handling.
+
+=item *
+
+L<Sys::Syslog> has been upgraded to 0.32.
+
+This contains several bug fixes relating to C<getservbyname()>,
+C<setlogsock()>and log levels in C<syslog()>, together with fixes for
+Windows, Haiku-OS and GNU/kFreeBSD. See F<cpan/Sys-Syslog/Changes>
+for the full details.
+
+=item *
+
+L<Term::ANSIColor> has been upgraded to 4.02.
+
+Add support for italics.
+
+Improve error handling.
+
+=item *
+
+L<Term::ReadLine> has been upgraded to 1.10. This fixes the
+use of the B<cpan> and B<cpanp> shells on Windows in the event that the current
+drive happens to contain a F<\dev\tty> file.
+
+=item *
+
+L<Test::Harness> has been upgraded to 3.26.
+
+Fix glob semantics on Win32 [rt.cpan.org #49732].
+
+Don't use C<Win32::GetShortPathName> when calling perl [rt.cpan.org #47890].
+
+Ignore -T when reading shebang [rt.cpan.org #64404].
+
+Handle the case where we don't know the wait status of the test more
+gracefully.
+
+Make the test summary 'ok' line overridable so that it can be changed to a
+plugin to make the output of prove idempotent.
+
+Don't run world-writable files.
+
+=item *
+
+L<Text::Tabs> and L<Text::Wrap> have been upgraded to
+2012.0818. Support for Unicode combining characters has been added to them
+both.
+
+=item *
+
+L<threads::shared> has been upgraded to 1.31.
+
+This adds the option to warn about or ignore attempts to clone structures
+that can't be cloned, as opposed to just unconditionally dying in
+that case.
+
+This adds support for dual-valued values as created by
+L<Scalar::Util::dualvar|Scalar::Util/"dualvar NUM, STRING">.
+
+=item *
+
+L<Tie::StdHandle> has been upgraded to 4.3.
+
+C<READ> now respects the offset argument to C<read> [perl #112826].
+
+=item *
+
+L<Time::Local> has been upgraded to 1.2300.
+
+Seconds values greater than 59 but less than 60 no longer cause
+C<timegm()> and C<timelocal()> to croak.
+
+=item *
+
+L<Unicode::UCD> has been upgraded to 0.53.
+
+This adds a function L<all_casefolds()|Unicode::UCD/all_casefolds()>
+that returns all the casefolds.
+
+=item *
+
+L<Win32> has been upgraded to 0.47.
+
+New APIs have been added for getting and setting the current code page.
+
+=back
+
+
+=head2 Removed Modules and Pragmata
+
+=over
+
+=item *
+
+L<Version::Requirements> has been removed from the core distribution. It is
+available under a different name: L<CPAN::Meta::Requirements>.
+
+=back
+
+=head1 Documentation
+
+=head2 Changes to Existing Documentation
+
+=head3 L<perlcheat>
+
+=over 4
+
+=item *
+
+L<perlcheat> has been reorganized, and a few new sections were added.
+
+=back
+
+=head3 L<perldata>
+
+=over 4
+
+=item *
+
+Now explicitly documents the behaviour of hash initializer lists that
+contain duplicate keys.
+
+=back
+
+=head3 L<perldiag>
+
+=over 4
+
+=item *
+
+The explanation of symbolic references being prevented by "strict refs"
+now doesn't assume that the reader knows what symbolic references are.
+
+=back
+
+=head3 L<perlfaq>
+
+=over 4
+
+=item *
+
+L<perlfaq> has been synchronized with version 5.0150040 from CPAN.
+
+=back
+
+=head3 L<perlfunc>
+
+=over 4
+
+=item *
+
+The return value of C<pipe> is now documented.
+
+=item *
+
+Clarified documentation of C<our>.
+
+=back
+
+=head3 L<perlop>
+
+=over 4
+
+=item *
+
+Loop control verbs (C<dump>, C<goto>, C<next>, C<last> and C<redo>) have always
+had the same precedence as assignment operators, but this was not documented
+until now.
+
+=back
+
+=head3 Diagnostics
+
+The following additions or changes have been made to diagnostic output,
+including warnings and fatal error messages. For the complete list of
+diagnostic messages, see L<perldiag>.
+
+=head2 New Diagnostics
+
+=head3 New Errors
+
+=over 4
+
+=item *
+
+L<Unterminated delimiter for here document|perldiag/"Unterminated delimiter for here document">
+
+This message now occurs when a here document label has an initial quotation
+mark but the final quotation mark is missing.
+
+This replaces a bogus and misleading error message about not finding the label
+itself [perl #114104].
+
+=item *
+
+L<panic: child pseudo-process was never scheduled|perldiag/"panic: child pseudo-process was never scheduled">
+
+This error is thrown when a child pseudo-process in the ithreads implementation
+on Windows was not scheduled within the time period allowed and therefore was
+not able to initialize properly [perl #88840].
+
+=item *
+
+L<Group name must start with a non-digit word character in regex; marked by <-- HERE in mE<sol>%sE<sol>|perldiag/"Group name must start with a non-digit word character in regex; marked by <-- HERE in m/%s/">
+
+This error has been added for C<(?&0)>, which is invalid. It used to
+produce an incomprehensible error message [perl #101666].
+
+=item *
+
+L<Can't use an undefined value as a subroutine reference|perldiag/"Can't use an undefined value as %s reference">
+
+Calling an undefined value as a subroutine now produces this error message.
+It used to, but was accidentally disabled, first in Perl 5.004 for
+non-magical variables, and then in Perl v5.14 for magical (e.g., tied)
+variables. It has now been restored. In the mean time, undef was treated
+as an empty string [perl #113576].
+
+=item *
+
+L<Experimental "%s" subs not enabled|perldiag/"Experimental "%s" subs not enabled">
+
+To use lexical subs, you must first enable them:
+
+ no warnings 'experimental::lexical_subs';
+ use feature 'lexical_subs';
+ my sub foo { ... }
+
+=back
+
+=head3 New Warnings
+
+=over 4
+
+=item *
+
+L<'Strings with code points over 0xFF may not be mapped into in-memory file handles'|perldiag/"Strings with code points over 0xFF may not be mapped into in-memory file handles">
+
+=item *
+
+L<'%s' resolved to '\o{%s}%d'|perldiag/"'%s' resolved to '\o{%s}%d'">
+
+=item *
+
+L<'Trailing white-space in a charnames alias definition is deprecated'|perldiag/"Trailing white-space in a charnames alias definition is deprecated">
+
+=item *
+
+L<'A sequence of multiple spaces in a charnames alias definition is deprecated'|perldiag/"A sequence of multiple spaces in a charnames alias definition is deprecated">
+
+=item *
+
+L<'Passing malformed UTF-8 to "%s" is deprecated'|perldiag/"Passing malformed UTF-8 to "%s" is deprecated">
+
+=item *
+
+L<Subroutine "&%s" is not available|perldiag/"Subroutine "&%s" is not available">
+
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical subroutine that is not currently
+available. This can happen for one of two reasons. First, the lexical
+subroutine may be declared in an outer anonymous subroutine that has not
+yet been created. (Remember that named subs are created at compile time,
+while anonymous subs are created at run-time.) For example,
+
+ sub { my sub a {...} sub f { \&a } }
+
+At the time that f is created, it can't capture the current the "a" sub,
+since the anonymous subroutine hasn't been created yet. Conversely, the
+following won't give a warning since the anonymous subroutine has by now
+been created and is live:
+
+ sub { my sub a {...} eval 'sub f { \&a }' }->();
+
+The second situation is caused by an eval accessing a variable that has
+gone out of scope, for example,
+
+ sub f {
+ my sub a {...}
+ sub { eval '\&a' }
+ }
+ f()->();
+
+Here, when the '\&a' in the eval is being compiled, f() is not currently
+being executed, so its &a is not available for capture.
+
+=item *
+
+L<"%s" subroutine &%s masks earlier declaration in same %s|perldiag/"%s" subroutine &%s masks earlier declaration in same %s>
+
+(W misc) A "my" or "state" subroutine has been redeclared in the
+current scope or statement, effectively eliminating all access to
+the previous instance. This is almost always a typographical error.
+Note that the earlier subroutine will still exist until the end of
+the scope or until all closure references to it are destroyed.
+
+=item *
+
+L<The %s feature is experimental|perldiag/"The %s feature is experimental">
+
+(S experimental) This warning is emitted if you enable an experimental
+feature via C<use feature>. Simply suppress the warning if you want
+to use the feature, but know that in doing so you are taking the risk
+of using an experimental feature which may change or be removed in a
+future Perl version:
+
+ no warnings "experimental::lexical_subs";
+ use feature "lexical_subs";
+
+=item *
+
+L<sleep(%u) too large|perldiag/"sleep(%u) too large">
+
+(W overflow) You called C<sleep> with a number that was larger than it can
+reliably handle and C<sleep> probably slept for less time than requested.
+
+=item *
+
+L<Wide character in setenv|perldiag/"Wide character in %s">
+
+Attempts to put wide characters into environment variables via C<%ENV> now
+provoke this warning.
+
+=item *
+
+"L<Invalid negative number (%s) in chr|perldiag/"Invalid negative number (%s) in chr">"
+
+C<chr()> now warns when passed a negative value [perl #83048].
+
+=item *
+
+"L<Integer overflow in srand|perldiag/"Integer overflow in srand">"
+
+C<srand()> now warns when passed a value that doesn't fit in a C<UV> (since the
+value will be truncated rather than overflowing) [perl #40605].
+
+=item *
+
+"L<-i used with no filenames on the command line, reading from STDIN|perldiag/"-i used with no filenames on the command line, reading from STDIN">"
+
+Running perl with the C<-i> flag now warns if no input files are provided on
+the command line [perl #113410].
+
+=back
+
+=head2 Changes to Existing Diagnostics
+
+=over 4
+
+=item *
+
+L<$* is no longer supported|perldiag/"$* is no longer supported">
+
+The warning that use of C<$*> and C<$#> is no longer supported is now
+generated for every location that references them. Previously it would fail
+to be generated if another variable using the same typeglob was seen first
+(e.g. C<@*> before C<$*>), and would not be generated for the second and
+subsequent uses. (It's hard to fix the failure to generate warnings at all
+without also generating them every time, and warning every time is
+consistent with the warnings that C<$[> used to generate.)
+
+=item *
+
+The warnings for C<\b{> and C<\B{> were added. They are a deprecation
+warning which should be turned off by that category. One should not
+have to turn off regular regexp warnings as well to get rid of these.
+
+=item *
+
+L<Constant(%s): Call to &{$^H{%s}} did not return a defined value|perldiag/Constant(%s): Call to &{$^H{%s}} did not return a defined value>
+
+Constant overloading that returns C<undef> results in this error message.
+For numeric constants, it used to say "Constant(undef)". "undef" has been
+replaced with the number itself.
+
+=item *
+
+The error produced when a module cannot be loaded now includes a hint that
+the module may need to be installed: "Can't locate hopping.pm in @INC (you
+may need to install the hopping module) (@INC contains: ...)"
+
+=item *
+
+L<vector argument not supported with alpha versions|perldiag/vector argument not supported with alpha versions>
+
+This warning was not suppressable, even with C<no warnings>. Now it is
+suppressible, and has been moved from the "internal" category to the
+"printf" category.
+
+=item *
+
+C<< Can't do {n,m} with n > m in regex; marked by <-- HERE in m/%s/ >>
+
+This fatal error has been turned into a warning that reads:
+
+L<< Quantifier {n,m} with n > m can't match in regex | perldiag/Quantifier {n,m} with n > m can't match in regex >>
+
+(W regexp) Minima should be less than or equal to maxima. If you really want
+your regexp to match something 0 times, just put {0}.
+
+=item *
+
+The "Runaway prototype" warning that occurs in bizarre cases has been
+removed as being unhelpful and inconsistent.
+
+=item *
+
+The "Not a format reference" error has been removed, as the only case in
+which it could be triggered was a bug.
+
+=item *
+
+The "Unable to create sub named %s" error has been removed for the same
+reason.
+
+=item *
+
+The 'Can't use "my %s" in sort comparison' error has been downgraded to a
+warning, '"my %s" used in sort comparison' (with 'state' instead of 'my'
+for state variables). In addition, the heuristics for guessing whether
+lexical $a or $b has been misused have been improved to generate fewer
+false positives. Lexical $a and $b are no longer disallowed if they are
+outside the sort block. Also, a named unary or list operator inside the
+sort block no longer causes the $a or $b to be ignored [perl #86136].
+
+=back
+
+=head1 Utility Changes
+
+=head3 L<h2xs>
+
+=over 4
+
+=item *
+
+F<h2xs> no longer produces invalid code for empty defines. [perl #20636]
+
+=back
+
+=head1 Configuration and Compilation
+
+=over 4
+
+=item *
+
+Added C<useversionedarchname> option to Configure
+
+When set, it includes 'api_versionstring' in 'archname'. E.g.
+x86_64-linux-5.13.6-thread-multi. It is unset by default.
+
+This feature was requested by Tim Bunce, who observed that
+C<INSTALL_BASE> creates a library structure that does not
+differentiate by perl version. Instead, it places architecture
+specific files in "$install_base/lib/perl5/$archname". This makes
+it difficult to use a common C<INSTALL_BASE> library path with
+multiple versions of perl.
+
+By setting C<-Duseversionedarchname>, the $archname will be
+distinct for architecture I<and> API version, allowing mixed use of
+C<INSTALL_BASE>.
+
+=item *
+
+Add a C<PERL_NO_INLINE_FUNCTIONS> option
+
+If C<PERL_NO_INLINE_FUNCTIONS> is defined, don't include "inline.h"
+
+This permits test code to include the perl headers for definitions without
+creating a link dependency on the perl library (which may not exist yet).
+
+=item *
+
+Configure will honour the external C<MAILDOMAIN> environment variable, if set.
+
+=item *
+
+C<installman> no longer ignores the silent option
+
+=item *
+
+Both C<META.yml> and C<META.json> files are now included in the distribution.
+
+=item *
+
+F<Configure> will now correctly detect C<isblank()> when compiling with a C++
+compiler.
+
+=item *
+
+The pager detection in F<Configure> has been improved to allow responses which
+specify options after the program name, e.g. B</usr/bin/less -R>, if the user
+accepts the default value. This helps B<perldoc> when handling ANSI escapes
+[perl #72156].
+
+=back
+
+=head1 Testing
+
+=over 4
+
+=item *
+
+The test suite now has a section for tests that require very large amounts
+of memory. These tests won't run by default; they can be enabled by
+setting the C<PERL_TEST_MEMORY> environment variable to the number of
+gibibytes of memory that may be safely used.
+
+=back
+
+=head1 Platform Support
+
+=head2 Discontinued Platforms
+
+=over 4
+
+=item BeOS
+
+BeOS was an operating system for personal computers developed by Be Inc,
+initially for their BeBox hardware. The OS Haiku was written as an open
+source replacement for/continuation of BeOS, and its perl port is current and
+actively maintained.
+
+=item UTS Global
+
+Support code relating to UTS global has been removed. UTS was a mainframe
+version of System V created by Amdahl, subsequently sold to UTS Global. The
+port has not been touched since before Perl v5.8.0, and UTS Global is now
+defunct.
+
+=item VM/ESA
+
+Support for VM/ESA has been removed. The port was tested on 2.3.0, which
+IBM ended service on in March 2002. 2.4.0 ended service in June 2003, and
+was superseded by Z/VM. The current version of Z/VM is V6.2.0, and scheduled
+for end of service on 2015/04/30.
+
+=item MPE/IX
+
+Support for MPE/IX has been removed.
+
+=item EPOC
+
+Support code relating to EPOC has been removed. EPOC was a family of
+operating systems developed by Psion for mobile devices. It was the
+predecessor of Symbian. The port was last updated in April 2002.
+
+=item Rhapsody
+
+Support for Rhapsody has been removed.
+
+=back
+
+=head2 Platform-Specific Notes
+
+=head3 AIX
+
+Configure now always adds C<-qlanglvl=extc99> to the CC flags on AIX when
+using xlC. This will make it easier to compile a number of XS-based modules
+that assume C99 [perl #113778].
+
+=head3 clang++
+
+There is now a workaround for a compiler bug that prevented compiling
+with clang++ since Perl v5.15.7 [perl #112786].
+
+=head3 C++
+
+When compiling the Perl core as C++ (which is only semi-supported), the
+mathom functions are now compiled as C<extern "C">, to ensure proper
+binary compatibility. (However, binary compatibility isn't generally
+guaranteed anyway in the situations where this would matter.)
+
+=head3 Darwin
+
+Stop hardcoding an alignment on 8 byte boundaries to fix builds using
+-Dusemorebits.
+
+=head3 Haiku
+
+Perl should now work out of the box on Haiku R1 Alpha 4.
+
+=head3 MidnightBSD
+
+C<libc_r> was removed from recent versions of MidnightBSD and older versions
+work better with C<pthread>. Threading is now enabled using C<pthread> which
+corrects build errors with threading enabled on 0.4-CURRENT.
+
+=head3 Solaris
+
+In Configure, avoid running sed commands with flags not supported on Solaris.
+
+=head3 VMS
+
+=over
+
+=item *
+
+Where possible, the case of filenames and command-line arguments is now
+preserved by enabling the CRTL features C<DECC$EFS_CASE_PRESERVE> and
+C<DECC$ARGV_PARSE_STYLE> at start-up time. The latter only takes effect
+when extended parse is enabled in the process from which Perl is run.
+
+=item *
+
+The character set for Extended Filename Syntax (EFS) is now enabled by default
+on VMS. Among other things, this provides better handling of dots in directory
+names, multiple dots in filenames, and spaces in filenames. To obtain the old
+behavior, set the logical name C<DECC$EFS_CHARSET> to C<DISABLE>.
+
+=item *
+
+Fixed linking on builds configured with C<-Dusemymalloc=y>.
+
+=item *
+
+Experimental support for building Perl with the HP C++ compiler is available
+by configuring with C<-Dusecxx>.
+
+=item *
+
+All C header files from the top-level directory of the distribution are now
+installed on VMS, providing consistency with a long-standing practice on other
+platforms. Previously only a subset were installed, which broke non-core
+extension builds for extensions that depended on the missing include files.
+
+=item *
+
+Quotes are now removed from the command verb (but not the parameters) for
+commands spawned via C<system>, backticks, or a piped C<open>. Previously,
+quotes on the verb were passed through to DCL, which would fail to recognize
+the command. Also, if the verb is actually a path to an image or command
+procedure on an ODS-5 volume, quoting it now allows the path to contain spaces.
+
+=item *
+
+The B<a2p> build has been fixed for the HP C++ compiler on OpenVMS.
+
+=back
+
+=head3 Win32
+
+=over
+
+=item *
+
+Perl can now be built using Microsoft's Visual C++ 2012 compiler by specifying
+CCTYPE=MSVC110 (or MSVC110FREE if you are using the free Express edition for
+Windows Desktop) in F<win32/Makefile>.
+
+=item *
+
+The option to build without C<USE_SOCKETS_AS_HANDLES> has been removed.
+
+=item *
+
+Fixed a problem where perl could crash while cleaning up threads (including the
+main thread) in threaded debugging builds on Win32 and possibly other platforms
+[perl #114496].
+
+=item *
+
+A rare race condition that would lead to L<sleep|perlfunc/sleep> taking more
+time than requested, and possibly even hanging, has been fixed [perl #33096].
+
+=item *
+
+C<link> on Win32 now attempts to set C<$!> to more appropriate values
+based on the Win32 API error code. [perl #112272]
+
+Perl no longer mangles the environment block, e.g. when launching a new
+sub-process, when the environment contains non-ASCII characters. Known
+problems still remain, however, when the environment contains characters
+outside of the current ANSI codepage (e.g. see the item about Unicode in
+C<%ENV> in L<http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod>).
+[perl #113536]
+
+=item *
+
+Building perl with some Windows compilers used to fail due to a problem
+with miniperl's C<glob> operator (which uses the C<perlglob> program)
+deleting the PATH environment variable [perl #113798].
+
+=item *
+
+A new makefile option, C<USE_64_BIT_INT>, has been added to the Windows
+makefiles. Set this to "define" when building a 32-bit perl if you want
+it to use 64-bit integers.
+
+Machine code size reductions, already made to the DLLs of XS modules in
+Perl v5.17.2, have now been extended to the perl DLL itself.
+
+Building with VC++ 6.0 was inadvertently broken in Perl v5.17.2 but has
+now been fixed again.
+
+=back
+
+=head3 WinCE
+
+Building on WinCE is now possible once again, although more work is required
+to fully restore a clean build.
+
+=head1 Internal Changes
+
+=over
+
+=item *
+
+Synonyms for the misleadingly named C<av_len()> have been created:
+C<av_top_index()> and C<av_tindex>. All three of these return the
+number of the highest index in the array, not the number of elements it
+contains.
+
+=item *
+
+SvUPGRADE() is no longer an expression. Originally this macro (and its
+underlying function, sv_upgrade()) were documented as boolean, although
+in reality they always croaked on error and never returned false. In 2005
+the documentation was updated to specify a void return value, but
+SvUPGRADE() was left always returning 1 for backwards compatibility. This
+has now been removed, and SvUPGRADE() is now a statement with no return
+value.
+
+So this is now a syntax error:
+
+ if (!SvUPGRADE(sv)) { croak(...); }
+
+If you have code like that, simply replace it with
+
+ SvUPGRADE(sv);
+
+or to avoid compiler warnings with older perls, possibly
+
+ (void)SvUPGRADE(sv);
+
+=item *
+
+Perl has a new copy-on-write mechanism that allows any SvPOK scalar to be
+upgraded to a copy-on-write scalar. A reference count on the string buffer
+is stored in the string buffer itself. This feature is B<not enabled by
+default>.
+
+It can be enabled in a perl build by running F<Configure> with
+B<-Accflags=-DPERL_NEW_COPY_ON_WRITE>, and we would encourage XS authors
+to try their code with such an enabled perl, and provide feedback.
+Unfortunately, there is not yet a good guide to updating XS code to cope
+with COW. Until such a document is available, consult the perl5-porters
+mailing list.
+
+It breaks a few XS modules by allowing copy-on-write scalars to go
+through code paths that never encountered them before.
+
+=item *
+
+Copy-on-write no longer uses the SvFAKE and SvREADONLY flags. Hence,
+SvREADONLY indicates a true read-only SV.
+
+Use the SvIsCOW macro (as before) to identify a copy-on-write scalar.
+
+=item *
+
+C<PL_glob_index> is gone.
+
+=item *
+
+The private Perl_croak_no_modify has had its context parameter removed. It is
+now has a void prototype. Users of the public API croak_no_modify remain
+unaffected.
+
+=item *
+
+Copy-on-write (shared hash key) scalars are no longer marked read-only.
+C<SvREADONLY> returns false on such an SV, but C<SvIsCOW> still returns
+true.
+
+=item *
+
+A new op type, C<OP_PADRANGE> has been introduced. The perl peephole
+optimiser will, where possible, substitute a single padrange op for a
+pushmark followed by one or more pad ops, and possibly also skipping list
+and nextstate ops. In addition, the op can carry out the tasks associated
+with the RHS of a C<< my(...) = @_ >> assignment, so those ops may be optimised
+away too.
+
+=item *
+
+Case-insensitive matching inside a [bracketed] character class with a
+multi-character fold no longer excludes one of the possibilities in the
+circumstances that it used to. [perl #89774].
+
+=item *
+
+C<PL_formfeed> has been removed.
+
+=item *
+
+The regular expression engine no longer reads one byte past the end of the
+target string. While for all internally well-formed scalars this should
+never have been a problem, this change facilitates clever tricks with
+string buffers in CPAN modules. [perl #73542]
+
+=item *
+
+Inside a BEGIN block, C<PL_compcv> now points to the currently-compiling
+subroutine, rather than the BEGIN block itself.
+
+=item *
+
+C<mg_length> has been deprecated.
+
+=item *
+
+C<sv_len> now always returns a byte count and C<sv_len_utf8> a character
+count. Previously, C<sv_len> and C<sv_len_utf8> were both buggy and would
+sometimes returns bytes and sometimes characters. C<sv_len_utf8> no longer
+assumes that its argument is in UTF-8. Neither of these creates UTF-8 caches
+for tied or overloaded values or for non-PVs any more.
+
+=item *
+
+C<sv_mortalcopy> now copies string buffers of shared hash key scalars when
+called from XS modules [perl #79824].
+
+=item *
+
+C<RXf_SPLIT> and C<RXf_SKIPWHITE> are no longer used. They are now
+#defined as 0.
+
+=item *
+
+The new C<RXf_MODIFIES_VARS> flag can be set by custom regular expression
+engines to indicate that the execution of the regular expression may cause
+variables to be modified. This lets C<s///> know to skip certain
+optimisations. Perl's own regular expression engine sets this flag for the
+special backtracking verbs that set $REGMARK and $REGERROR.
+
+=item *
+
+The APIs for accessing lexical pads have changed considerably.
+
+C<PADLIST>s are now longer C<AV>s, but their own type instead.
+C<PADLIST>s now contain a C<PAD> and a C<PADNAMELIST> of C<PADNAME>s,
+rather than C<AV>s for the pad and the list of pad names. C<PAD>s,
+C<PADNAMELIST>s, and C<PADNAME>s are to be accessed as such through the
+newly added pad API instead of the plain C<AV> and C<SV> APIs. See
+L<perlapi> for details.
+
+=item *
+
+In the regex API, the numbered capture callbacks are passed an index
+indicating what match variable is being accessed. There are special
+index values for the C<$`, $&, $&> variables. Previously the same three
+values were used to retrieve C<${^PREMATCH}, ${^MATCH}, ${^POSTMATCH}>
+too, but these have now been assigned three separate values. See
+L<perlreapi/Numbered capture callbacks>.
+
+=item *
+
+C<PL_sawampersand> was previously a boolean indicating that any of
+C<$`, $&, $&> had been seen; it now contains three one-bit flags
+indicating the presence of each of the variables individually.
+
+=item *
+
+The C<CV *> typemap entry now supports C<&{}> overloading and typeglobs,
+just like C<&{...}> [perl #96872].
+
+=item *
+
+The C<SVf_AMAGIC> flag to indicate overloading is now on the stash, not the
+object. It is now set automatically whenever a method or @ISA changes, so
+its meaning has changed, too. It now means "potentially overloaded". When
+the overload table is calculated, the flag is automatically turned off if
+there is no overloading, so there should be no noticeable slowdown.
+
+The staleness of the overload tables is now checked when overload methods
+are invoked, rather than during C<bless>.
+
+"A" magic is gone. The changes to the handling of the C<SVf_AMAGIC> flag
+eliminate the need for it.
+
+C<PL_amagic_generation> has been removed as no longer necessary. For XS
+modules, it is now a macro alias to C<PL_na>.
+
+The fallback overload setting is now stored in a stash entry separate from
+overloadedness itself.
+
+=item *
+
+The character-processing code has been cleaned up in places. The changes
+should be operationally invisible.
+
+=item *
+
+The C<study> function was made a no-op in v5.16. It was simply disabled via
+a C<return> statement; the code was left in place. Now the code supporting
+what C<study> used to do has been removed.
+
+=item *
+
+Under threaded perls, there is no longer a separate PV allocated for every
+COP to store its package name (C<< cop->stashpv >>). Instead, there is an
+offset (C<< cop->stashoff >>) into the new C<PL_stashpad> array, which
+holds stash pointers.
+
+=item *
+
+In the pluggable regex API, the C<regexp_engine> struct has acquired a new
+field C<op_comp>, which is currently just for perl's internal use, and
+should be initialized to NULL by other regex plugin modules.
+
+=item *
+
+A new function C<alloccopstash> has been added to the API, but is considered
+experimental. See L<perlapi>.
+
+=item *
+
+Perl used to implement get magic in a way that would sometimes hide bugs in
+code that could call mg_get() too many times on magical values. This hiding of
+errors no longer occurs, so long-standing bugs may become visible now. If
+you see magic-related errors in XS code, check to make sure it, together
+with the Perl API functions it uses, calls mg_get() only once on SvGMAGICAL()
+values.
+
+=item *
+
+OP allocation for CVs now uses a slab allocator. This simplifies
+memory management for OPs allocated to a CV, so cleaning up after a
+compilation error is simpler and safer [perl #111462][perl #112312].
+
+=item *
+
+C<PERL_DEBUG_READONLY_OPS> has been rewritten to work with the new slab
+allocator, allowing it to catch more violations than before.
+
+=item *
+
+The old slab allocator for ops, which was only enabled for C<PERL_IMPLICIT_SYS>
+and C<PERL_DEBUG_READONLY_OPS>, has been retired.
+
+=back
+
+=head1 Selected Bug Fixes
+
+=over 4
+
+=item *
+
+Here document terminators no longer require a terminating newline character when
+they occur at the end of a file. This was already the case at the end of a
+string eval [perl #65838].
+
+=item *
+
+C<-DPERL_GLOBAL_STRUCT> builds now free the global struct B<after>
+they've finished using it.
+
+=item *
+
+A trailing '/' on a path in @INC will no longer have an additional '/'
+appended.
+
+=item *
+
+The C<:crlf> layer now works when unread data doesn't fit into its own
+buffer. [perl #112244].
+
+=item *
+
+C<ungetc()> now handles UTF-8 encoded data. [perl #116322].
+
+=item *
+
+A bug in the core typemap caused any C types that map to the T_BOOL core
+typemap entry to not be set, updated, or modified when the T_BOOL variable was
+used in an OUTPUT: section with an exception for RETVAL. T_BOOL in an INPUT:
+section was not affected. Using a T_BOOL return type for an XSUB (RETVAL)
+was not affected. A side effect of fixing this bug is, if a T_BOOL is specified
+in the OUTPUT: section (which previous did nothing to the SV), and a read only
+SV (literal) is passed to the XSUB, croaks like "Modification of a read-only
+value attempted" will happen. [perl #115796]
+
+=item *
+
+On many platforms, providing a directory name as the script name caused perl
+to do nothing and report success. It should now universally report an error
+and exit nonzero. [perl #61362]
+
+=item *
+
+C<sort {undef} ...> under fatal warnings no longer crashes. It had
+begun crashing in Perl v5.16.
+
+=item *
+
+Stashes blessed into each other
+(C<bless \%Foo::, 'Bar'; bless \%Bar::, 'Foo'>) no longer result in double
+frees. This bug started happening in Perl v5.16.
+
+=item *
+
+Numerous memory leaks have been fixed, mostly involving fatal warnings and
+syntax errors.
+
+=item *
+
+Some failed regular expression matches such as C<'f' =~ /../g> were not
+resetting C<pos>. Also, "match-once" patterns (C<m?...?g>) failed to reset
+it, too, when invoked a second time [perl #23180].
+
+=item *
+
+Several bugs involving C<local *ISA> and C<local *Foo::> causing stale
+MRO caches have been fixed.
+
+=item *
+
+Defining a subroutine when its typeglob has been aliased no longer results
+in stale method caches. This bug was introduced in Perl v5.10.
+
+=item *
+
+Localising a typeglob containing a subroutine when the typeglob's package
+has been deleted from its parent stash no longer produces an error. This
+bug was introduced in Perl v5.14.
+
+=item *
+
+Under some circumstances, C<local *method=...> would fail to reset method
+caches upon scope exit.
+
+=item *
+
+C</[.foo.]/> is no longer an error, but produces a warning (as before) and
+is treated as C</[.fo]/> [perl #115818].
+
+=item *
+
+C<goto $tied_var> now calls FETCH before deciding what type of goto
+(subroutine or label) this is.
+
+=item *
+
+Renaming packages through glob assignment
+(C<*Foo:: = *Bar::; *Bar:: = *Baz::>) in combination with C<m?...?> and
+C<reset> no longer makes threaded builds crash.
+
+=item *
+
+A number of bugs related to assigning a list to hash have been fixed. Many of
+these involve lists with repeated keys like C<(1, 1, 1, 1)>.
+
+=over 4
+
+=item *
+
+The expression C<scalar(%h = (1, 1, 1, 1))> now returns C<4>, not C<2>.
+
+=item *
+
+The return value of C<%h = (1, 1, 1)> in list context was wrong. Previously
+this would return C<(1, undef, 1)>, now it returns C<(1, undef)>.
+
+=item *
+
+Perl now issues the same warning on C<($s, %h) = (1, {})> as it does for
+C<(%h) = ({})>, "Reference found where even-sized list expected".
+
+=item *
+
+A number of additional edge cases in list assignment to hashes were
+corrected. For more details see commit 23b7025ebc.
+
+=back
+
+=item *
+
+Attributes applied to lexical variables no longer leak memory.
+[perl #114764]
+
+=item *
+
+C<dump>, C<goto>, C<last>, C<next>, C<redo> or C<require> followed by a
+bareword (or version) and then an infix operator is no longer a syntax
+error. It used to be for those infix operators (like C<+>) that have a
+different meaning where a term is expected. [perl #105924]
+
+=item *
+
+C<require a::b . 1> and C<require a::b + 1> no longer produce erroneous
+ambiguity warnings. [perl #107002]
+
+=item *
+
+Class method calls are now allowed on any string, and not just strings
+beginning with an alphanumeric character. [perl #105922]
+
+=item *
+
+An empty pattern created with C<qr//> used in C<m///> no longer triggers
+the "empty pattern reuses last pattern" behaviour. [perl #96230]
+
+=item *
+
+Tying a hash during iteration no longer results in a memory leak.
+
+=item *
+
+Freeing a tied hash during iteration no longer results in a memory leak.
+
+=item *
+
+List assignment to a tied array or hash that dies on STORE no longer
+results in a memory leak.
+
+=item *
+
+If the hint hash (C<%^H>) is tied, compile-time scope entry (which copies
+the hint hash) no longer leaks memory if FETCH dies. [perl #107000]
+
+=item *
+
+Constant folding no longer inappropriately triggers the special
+C<split " "> behaviour. [perl #94490]
+
+=item *
+
+C<defined scalar(@array)>, C<defined do { &foo }>, and similar constructs
+now treat the argument to C<defined> as a simple scalar. [perl #97466]
+
+=item *
+
+Running a custom debugging that defines no C<*DB::DB> glob or provides a
+subroutine stub for C<&DB::DB> no longer results in a crash, but an error
+instead. [perl #114990]
+
+=item *
+
+C<reset ""> now matches its documentation. C<reset> only resets C<m?...?>
+patterns when called with no argument. An empty string for an argument now
+does nothing. (It used to be treated as no argument.) [perl #97958]
+
+=item *
+
+C<printf> with an argument returning an empty list no longer reads past the
+end of the stack, resulting in erratic behaviour. [perl #77094]
+
+=item *
+
+C<--subname> no longer produces erroneous ambiguity warnings.
+[perl #77240]
+
+=item *
+
+C<v10> is now allowed as a label or package name. This was inadvertently
+broken when v-strings were added in Perl v5.6. [perl #56880]
+
+=item *
+
+C<length>, C<pos>, C<substr> and C<sprintf> could be confused by ties,
+overloading, references and typeglobs if the stringification of such
+changed the internal representation to or from UTF-8. [perl #114410]
+
+=item *
+
+utf8::encode now calls FETCH and STORE on tied variables. utf8::decode now
+calls STORE (it was already calling FETCH).
+
+=item *
+
+C<$tied =~ s/$non_utf8/$utf8/> no longer loops infinitely if the tied
+variable returns a Latin-1 string, shared hash key scalar, or reference or
+typeglob that stringifies as ASCII or Latin-1. This was a regression from
+v5.12.
+
+=item *
+
+C<s///> without /e is now better at detecting when it needs to forego
+certain optimisations, fixing some buggy cases:
+
+=over
+
+=item *
+
+Match variables in certain constructs (C<&&>, C<||>, C<..> and others) in
+the replacement part; e.g., C<s/(.)/$l{$a||$1}/g>. [perl #26986]
+
+=item *
+
+Aliases to match variables in the replacement.
+
+=item *
+
+C<$REGERROR> or C<$REGMARK> in the replacement. [perl #49190]
+
+=item *
+
+An empty pattern (C<s//$foo/>) that causes the last-successful pattern to
+be used, when that pattern contains code blocks that modify the variables
+in the replacement.
+
+=back
+
+=item *
+
+The taintedness of the replacement string no longer affects the taintedness
+of the return value of C<s///e>.
+
+=item *
+
+The C<$|> autoflush variable is created on-the-fly when needed. If this
+happened (e.g., if it was mentioned in a module or eval) when the
+currently-selected filehandle was a typeglob with an empty IO slot, it used
+to crash. [perl #115206]
+
+=item *
+
+Line numbers at the end of a string eval are no longer off by one.
+[perl #114658]
+
+=item *
+
+ at INC filters (subroutines returned by subroutines in @INC) that set $_ to a
+copy-on-write scalar no longer cause the parser to modify that string
+buffer in place.
+
+=item *
+
+C<length($object)> no longer returns the undefined value if the object has
+string overloading that returns undef. [perl #115260]
+
+=item *
+
+The use of C<PL_stashcache>, the stash name lookup cache for method calls, has
+been restored,
+
+Commit da6b625f78f5f133 in August 2011 inadvertently broke the code that looks
+up values in C<PL_stashcache>. As it's a only cache, quite correctly everything
+carried on working without it.
+
+=item *
+
+The error "Can't localize through a reference" had disappeared in v5.16.0
+when C<local %$ref> appeared on the last line of an lvalue subroutine.
+This error disappeared for C<\local %$ref> in perl v5.8.1. It has now
+been restored.
+
+=item *
+
+The parsing of here-docs has been improved significantly, fixing several
+parsing bugs and crashes and one memory leak, and correcting wrong
+subsequent line numbers under certain conditions.
+
+=item *
+
+Inside an eval, the error message for an unterminated here-doc no longer
+has a newline in the middle of it [perl #70836].
+
+=item *
+
+A substitution inside a substitution pattern (C<s/${s|||}//>) no longer
+confuses the parser.
+
+=item *
+
+It may be an odd place to allow comments, but C<s//"" # hello/e> has
+always worked, I<unless> there happens to be a null character before the
+first #. Now it works even in the presence of nulls.
+
+=item *
+
+An invalid range in C<tr///> or C<y///> no longer results in a memory leak.
+
+=item *
+
+String eval no longer treats a semicolon-delimited quote-like operator at
+the very end (C<eval 'q;;'>) as a syntax error.
+
+=item *
+
+C<< warn {$_ => 1} + 1 >> is no longer a syntax error. The parser used to
+get confused with certain list operators followed by an anonymous hash and
+then an infix operator that shares its form with a unary operator.
+
+=item *
+
+C<(caller $n)[6]> (which gives the text of the eval) used to return the
+actual parser buffer. Modifying it could result in crashes. Now it always
+returns a copy. The string returned no longer has "\n;" tacked on to the
+end. The returned text also includes here-doc bodies, which used to be
+omitted.
+
+=item *
+
+The UTF-8 position cache is now reset when accessing magical variables, to
+avoid the string buffer and the UTF-8 position cache getting out of sync
+[perl #114410].
+
+=item *
+
+Various cases of get magic being called twice for magical UTF-8
+strings have been fixed.
+
+=item *
+
+This code (when not in the presence of C<$&> etc)
+
+ $_ = 'x' x 1_000_000;
+ 1 while /(.)/;
+
+used to skip the buffer copy for performance reasons, but suffered from C<$1>
+etc changing if the original string changed. That's now been fixed.
+
+=item *
+
+Perl doesn't use PerlIO anymore to report out of memory messages, as PerlIO
+might attempt to allocate more memory.
+
+=item *
+
+In a regular expression, if something is quantified with C<{n,m}> where
+C<S<n E<gt> m>>, it can't possibly match. Previously this was a fatal
+error, but now is merely a warning (and that something won't match).
+[perl #82954].
+
+=item *
+
+It used to be possible for formats defined in subroutines that have
+subsequently been undefined and redefined to close over variables in the
+wrong pad (the newly-defined enclosing sub), resulting in crashes or
+"Bizarre copy" errors.
+
+=item *
+
+Redefinition of XSUBs at run time could produce warnings with the wrong
+line number.
+
+=item *
+
+The %vd sprintf format does not support version objects for alpha versions.
+It used to output the format itself (%vd) when passed an alpha version, and
+also emit an "Invalid conversion in printf" warning. It no longer does,
+but produces the empty string in the output. It also no longer leaks
+memory in this case.
+
+=item *
+
+C<< $obj->SUPER::method >> calls in the main package could fail if the
+SUPER package had already been accessed by other means.
+
+=item *
+
+Stash aliasing (C<< *foo:: = *bar:: >>) no longer causes SUPER calls to ignore
+changes to methods or @ISA or use the wrong package.
+
+=item *
+
+Method calls on packages whose names end in ::SUPER are no longer treated
+as SUPER method calls, resulting in failure to find the method.
+Furthermore, defining subroutines in such packages no longer causes them to
+be found by SUPER method calls on the containing package [perl #114924].
+
+=item *
+
+C<\w> now matches the code points U+200C (ZERO WIDTH NON-JOINER) and U+200D
+(ZERO WIDTH JOINER). C<\W> no longer matches these. This change is because
+Unicode corrected their definition of what C<\w> should match.
+
+=item *
+
+C<dump LABEL> no longer leaks its label.
+
+=item *
+
+Constant folding no longer changes the behaviour of functions like C<stat()>
+and C<truncate()> that can take either filenames or handles.
+C<stat 1 ? foo : bar> nows treats its argument as a file name (since it is an
+arbitrary expression), rather than the handle "foo".
+
+=item *
+
+C<truncate FOO, $len> no longer falls back to treating "FOO" as a file name if
+the filehandle has been deleted. This was broken in Perl v5.16.0.
+
+=item *
+
+Subroutine redefinitions after sub-to-glob and glob-to-glob assignments no
+longer cause double frees or panic messages.
+
+=item *
+
+C<s///> now turns vstrings into plain strings when performing a substitution,
+even if the resulting string is the same (C<s/a/a/>).
+
+=item *
+
+Prototype mismatch warnings no longer erroneously treat constant subs as having
+no prototype when they actually have "".
+
+=item *
+
+Constant subroutines and forward declarations no longer prevent prototype
+mismatch warnings from omitting the sub name.
+
+=item *
+
+C<undef> on a subroutine now clears call checkers.
+
+=item *
+
+The C<ref> operator started leaking memory on blessed objects in Perl v5.16.0.
+This has been fixed [perl #114340].
+
+=item *
+
+C<use> no longer tries to parse its arguments as a statement, making
+C<use constant { () };> a syntax error [perl #114222].
+
+=item *
+
+On debugging builds, "uninitialized" warnings inside formats no longer cause
+assertion failures.
+
+=item *
+
+On debugging builds, subroutines nested inside formats no longer cause
+assertion failures [perl #78550].
+
+=item *
+
+Formats and C<use> statements are now permitted inside formats.
+
+=item *
+
+C<print $x> and C<sub { print $x }-E<gt>()> now always produce the same output.
+It was possible for the latter to refuse to close over $x if the variable was
+not active; e.g., if it was defined outside a currently-running named
+subroutine.
+
+=item *
+
+Similarly, C<print $x> and C<print eval '$x'> now produce the same output.
+This also allows "my $x if 0" variables to be seen in the debugger [perl
+#114018].
+
+=item *
+
+Formats called recursively no longer stomp on their own lexical variables, but
+each recursive call has its own set of lexicals.
+
+=item *
+
+Attempting to free an active format or the handle associated with it no longer
+results in a crash.
+
+=item *
+
+Format parsing no longer gets confused by braces, semicolons and low-precedence
+operators. It used to be possible to use braces as format delimiters (instead
+of C<=> and C<.>), but only sometimes. Semicolons and low-precedence operators
+in format argument lines no longer confuse the parser into ignoring the line's
+return value. In format argument lines, braces can now be used for anonymous
+hashes, instead of being treated always as C<do> blocks.
+
+=item *
+
+Formats can now be nested inside code blocks in regular expressions and other
+quoted constructs (C</(?{...})/> and C<qq/${...}/>) [perl #114040].
+
+=item *
+
+Formats are no longer created after compilation errors.
+
+=item *
+
+Under debugging builds, the B<-DA> command line option started crashing in Perl
+v5.16.0. It has been fixed [perl #114368].
+
+=item *
+
+A potential deadlock scenario involving the premature termination of a pseudo-
+forked child in a Windows build with ithreads enabled has been fixed. This
+resolves the common problem of the F<t/op/fork.t> test hanging on Windows [perl
+#88840].
+
+=item *
+
+The code which generates errors from C<require()> could potentially read one or
+two bytes before the start of the filename for filenames less than three bytes
+long and ending C</\.p?\z/>. This has now been fixed. Note that it could
+never have happened with module names given to C<use()> or C<require()> anyway.
+
+=item *
+
+The handling of pathnames of modules given to C<require()> has been made
+thread-safe on VMS.
+
+=item *
+
+Non-blocking sockets have been fixed on VMS.
+
+=item *
+
+Pod can now be nested in code inside a quoted construct outside of a string
+eval. This used to work only within string evals [perl #114040].
+
+=item *
+
+C<goto ''> now looks for an empty label, producing the "goto must have
+label" error message, instead of exiting the program [perl #111794].
+
+=item *
+
+C<goto "\0"> now dies with "Can't find label" instead of "goto must have
+label".
+
+=item *
+
+The C function C<hv_store> used to result in crashes when used on C<%^H>
+[perl #111000].
+
+=item *
+
+A call checker attached to a closure prototype via C<cv_set_call_checker>
+is now copied to closures cloned from it. So C<cv_set_call_checker> now
+works inside an attribute handler for a closure.
+
+=item *
+
+Writing to C<$^N> used to have no effect. Now it croaks with "Modification
+of a read-only value" by default, but that can be overridden by a custom
+regular expression engine, as with C<$1> [perl #112184].
+
+=item *
+
+C<undef> on a control character glob (C<undef *^H>) no longer emits an
+erroneous warning about ambiguity [perl #112456].
+
+=item *
+
+For efficiency's sake, many operators and built-in functions return the
+same scalar each time. Lvalue subroutines and subroutines in the CORE::
+namespace were allowing this implementation detail to leak through.
+C<print &CORE::uc("a"), &CORE::uc("b")> used to print "BB". The same thing
+would happen with an lvalue subroutine returning the return value of C<uc>.
+Now the value is copied in such cases.
+
+=item *
+
+C<method {}> syntax with an empty block or a block returning an empty list
+used to crash or use some random value left on the stack as its invocant.
+Now it produces an error.
+
+=item *
+
+C<vec> now works with extremely large offsets (E<gt>2 GB) [perl #111730].
+
+=item *
+
+Changes to overload settings now take effect immediately, as do changes to
+inheritance that affect overloading. They used to take effect only after
+C<bless>.
+
+Objects that were created before a class had any overloading used to remain
+non-overloaded even if the class gained overloading through C<use overload>
+or @ISA changes, and even after C<bless>. This has been fixed
+[perl #112708].
+
+=item *
+
+Classes with overloading can now inherit fallback values.
+
+=item *
+
+Overloading was not respecting a fallback value of 0 if there were
+overloaded objects on both sides of an assignment operator like C<+=>
+[perl #111856].
+
+=item *
+
+C<pos> now croaks with hash and array arguments, instead of producing
+erroneous warnings.
+
+=item *
+
+C<while(each %h)> now implies C<while(defined($_ = each %h))>, like
+C<readline> and C<readdir>.
+
+=item *
+
+Subs in the CORE:: namespace no longer crash after C<undef *_> when called
+with no argument list (C<&CORE::time> with no parentheses).
+
+=item *
+
+C<unpack> no longer produces the "'/' must follow a numeric type in unpack"
+error when it is the data that are at fault [perl #60204].
+
+=item *
+
+C<join> and C<"@array"> now call FETCH only once on a tied C<$">
+[perl #8931].
+
+=item *
+
+Some subroutine calls generated by compiling core ops affected by a
+C<CORE::GLOBAL> override had op checking performed twice. The checking
+is always idempotent for pure Perl code, but the double checking can
+matter when custom call checkers are involved.
+
+=item *
+
+A race condition used to exist around fork that could cause a signal sent to
+the parent to be handled by both parent and child. Signals are now blocked
+briefly around fork to prevent this from happening [perl #82580].
+
+=item *
+
+The implementation of code blocks in regular expressions, such as C<(?{})>
+and C<(??{})>, has been heavily reworked to eliminate a whole slew of bugs.
+The main user-visible changes are:
+
+=over 4
+
+=item *
+
+Code blocks within patterns are now parsed in the same pass as the
+surrounding code; in particular it is no longer necessary to have balanced
+braces: this now works:
+
+ /(?{ $x='{' })/
+
+This means that this error message is no longer generated:
+
+ Sequence (?{...}) not terminated or not {}-balanced in regex
+
+but a new error may be seen:
+
+ Sequence (?{...}) not terminated with ')'
+
+In addition, literal code blocks within run-time patterns are only
+compiled once, at perl compile-time:
+
+ for my $p (...) {
+ # this 'FOO' block of code is compiled once,
+ # at the same time as the surrounding 'for' loop
+ /$p{(?{FOO;})/;
+ }
+
+=item *
+
+Lexical variables are now sane as regards scope, recursion and closure
+behavior. In particular, C</A(?{B})C/> behaves (from a closure viewpoint)
+exactly like C</A/ && do { B } && /C/>, while C<qr/A(?{B})C/> is like
+C<sub {/A/ && do { B } && /C/}>. So this code now works how you might
+expect, creating three regexes that match 0, 1, and 2:
+
+ for my $i (0..2) {
+ push @r, qr/^(??{$i})$/;
+ }
+ "1" =~ $r[1]; # matches
+
+=item *
+
+The C<use re 'eval'> pragma is now only required for code blocks defined
+at runtime; in particular in the following, the text of the C<$r> pattern is
+still interpolated into the new pattern and recompiled, but the individual
+compiled code-blocks within C<$r> are reused rather than being recompiled,
+and C<use re 'eval'> isn't needed any more:
+
+ my $r = qr/abc(?{....})def/;
+ /xyz$r/;
+
+=item *
+
+Flow control operators no longer crash. Each code block runs in a new
+dynamic scope, so C<next> etc. will not see
+any enclosing loops. C<return> returns a value
+from the code block, not from any enclosing subroutine.
+
+=item *
+
+Perl normally caches the compilation of run-time patterns, and doesn't
+recompile if the pattern hasn't changed, but this is now disabled if
+required for the correct behavior of closures. For example:
+
+ my $code = '(??{$x})';
+ for my $x (1..3) {
+ # recompile to see fresh value of $x each time
+ $x =~ /$code/;
+ }
+
+=item *
+
+The C</msix> and C<(?msix)> etc. flags are now propagated into the return
+value from C<(??{})>; this now works:
+
+ "AB" =~ /a(??{'b'})/i;
+
+=item *
+
+Warnings and errors will appear to come from the surrounding code (or for
+run-time code blocks, from an eval) rather than from an C<re_eval>:
+
+ use re 'eval'; $c = '(?{ warn "foo" })'; /$c/;
+ /(?{ warn "foo" })/;
+
+formerly gave:
+
+ foo at (re_eval 1) line 1.
+ foo at (re_eval 2) line 1.
+
+and now gives:
+
+ foo at (eval 1) line 1.
+ foo at /some/prog line 2.
+
+=back
+
+=item *
+
+Perl now can be recompiled to use any Unicode version. In v5.16, it
+worked on Unicodes 6.0 and 6.1, but there were various bugs if earlier
+releases were used; the older the release the more problems.
+
+=item *
+
+C<vec> no longer produces "uninitialized" warnings in lvalue context
+[perl #9423].
+
+=item *
+
+An optimization involving fixed strings in regular expressions could cause
+a severe performance penalty in edge cases. This has been fixed
+[perl #76546].
+
+=item *
+
+In certain cases, including empty subpatterns within a regular expression (such
+as C<(?:)> or C<(?:|)>) could disable some optimizations. This has been fixed.
+
+=item *
+
+The "Can't find an opnumber" message that C<prototype> produces when passed
+a string like "CORE::nonexistent_keyword" now passes UTF-8 and embedded
+NULs through unchanged [perl #97478].
+
+=item *
+
+C<prototype> now treats magical variables like C<$1> the same way as
+non-magical variables when checking for the CORE:: prefix, instead of
+treating them as subroutine names.
+
+=item *
+
+Under threaded perls, a runtime code block in a regular expression could
+corrupt the package name stored in the op tree, resulting in bad reads
+in C<caller>, and possibly crashes [perl #113060].
+
+=item *
+
+Referencing a closure prototype (C<\&{$_[1]}> in an attribute handler for a
+closure) no longer results in a copy of the subroutine (or assertion
+failures on debugging builds).
+
+=item *
+
+C<eval '__PACKAGE__'> now returns the right answer on threaded builds if
+the current package has been assigned over (as in
+C<*ThisPackage:: = *ThatPackage::>) [perl #78742].
+
+=item *
+
+If a package is deleted by code that it calls, it is possible for C<caller>
+to see a stack frame belonging to that deleted package. C<caller> could
+crash if the stash's memory address was reused for a scalar and a
+substitution was performed on the same scalar [perl #113486].
+
+=item *
+
+C<UNIVERSAL::can> no longer treats its first argument differently
+depending on whether it is a string or number internally.
+
+=item *
+
+C<open> with C<< <& >> for the mode checks to see whether the third argument is
+a number, in determining whether to treat it as a file descriptor or a handle
+name. Magical variables like C<$1> were always failing the numeric check and
+being treated as handle names.
+
+=item *
+
+C<warn>'s handling of magical variables (C<$1>, ties) has undergone several
+fixes. C<FETCH> is only called once now on a tied argument or a tied C<$@>
+[perl #97480]. Tied variables returning objects that stringify as "" are
+no longer ignored. A tied C<$@> that happened to return a reference the
+I<previous> time it was used is no longer ignored.
+
+=item *
+
+C<warn ""> now treats C<$@> with a number in it the same way, regardless of
+whether it happened via C<$@=3> or C<$@="3">. It used to ignore the
+former. Now it appends "\t...caught", as it has always done with
+C<$@="3">.
+
+=item *
+
+Numeric operators on magical variables (e.g., S<C<$1 + 1>>) used to use
+floating point operations even where integer operations were more appropriate,
+resulting in loss of accuracy on 64-bit platforms [perl #109542].
+
+=item *
+
+Unary negation no longer treats a string as a number if the string happened
+to be used as a number at some point. So, if C<$x> contains the string "dogs",
+C<-$x> returns "-dogs" even if C<$y=0+$x> has happened at some point.
+
+=item *
+
+In Perl v5.14, C<-'-10'> was fixed to return "10", not "+10". But magical
+variables (C<$1>, ties) were not fixed till now [perl #57706].
+
+=item *
+
+Unary negation now treats strings consistently, regardless of the internal
+C<UTF8> flag.
+
+=item *
+
+A regression introduced in Perl v5.16.0 involving
+C<tr/I<SEARCHLIST>/I<REPLACEMENTLIST>/> has been fixed. Only the first
+instance is supposed to be meaningful if a character appears more than
+once in C<I<SEARCHLIST>>. Under some circumstances, the final instance
+was overriding all earlier ones. [perl #113584]
+
+=item *
+
+Regular expressions like C<qr/\87/> previously silently inserted a NUL
+character, thus matching as if it had been written C<qr/\00087/>. Now it
+matches as if it had been written as C<qr/87/>, with a message that the
+sequence C<"\8"> is unrecognized.
+
+=item *
+
+C<__SUB__> now works in special blocks (C<BEGIN>, C<END>, etc.).
+
+=item *
+
+Thread creation on Windows could theoretically result in a crash if done
+inside a C<BEGIN> block. It still does not work properly, but it no longer
+crashes [perl #111610].
+
+=item *
+
+C<\&{''}> (with the empty string) now autovivifies a stub like any other
+sub name, and no longer produces the "Unable to create sub" error
+[perl #94476].
+
+=item *
+
+A regression introduced in v5.14.0 has been fixed, in which some calls
+to the C<re> module would clobber C<$_> [perl #113750].
+
+=item *
+
+C<do FILE> now always either sets or clears C<$@>, even when the file can't be
+read. This ensures that testing C<$@> first (as recommended by the
+documentation) always returns the correct result.
+
+=item *
+
+The array iterator used for the C<each @array> construct is now correctly
+reset when C<@array> is cleared [perl #75596]. This happens, for example, when
+the array is globally assigned to, as in C<@array = (...)>, but not when its
+B<values> are assigned to. In terms of the XS API, it means that C<av_clear()>
+will now reset the iterator.
+
+This mirrors the behaviour of the hash iterator when the hash is cleared.
+
+=item *
+
+C<< $class->can >>, C<< $class->isa >>, and C<< $class->DOES >> now return
+correct results, regardless of whether that package referred to by C<$class>
+exists [perl #47113].
+
+=item *
+
+Arriving signals no longer clear C<$@> [perl #45173].
+
+=item *
+
+Allow C<my ()> declarations with an empty variable list [perl #113554].
+
+=item *
+
+During parsing, subs declared after errors no longer leave stubs
+[perl #113712].
+
+=item *
+
+Closures containing no string evals no longer hang on to their containing
+subroutines, allowing variables closed over by outer subroutines to be
+freed when the outer sub is freed, even if the inner sub still exists
+[perl #89544].
+
+=item *
+
+Duplication of in-memory filehandles by opening with a "<&=" or ">&=" mode
+stopped working properly in v5.16.0. It was causing the new handle to
+reference a different scalar variable. This has been fixed [perl #113764].
+
+=item *
+
+C<qr//> expressions no longer crash with custom regular expression engines
+that do not set C<offs> at regular expression compilation time
+[perl #112962].
+
+=item *
+
+C<delete local> no longer crashes with certain magical arrays and hashes
+[perl #112966].
+
+=item *
+
+C<local> on elements of certain magical arrays and hashes used not to
+arrange to have the element deleted on scope exit, even if the element did
+not exist before C<local>.
+
+=item *
+
+C<scalar(write)> no longer returns multiple items [perl #73690].
+
+=item *
+
+String to floating point conversions no longer misparse certain strings under
+C<use locale> [perl #109318].
+
+=item *
+
+C<@INC> filters that die no longer leak memory [perl #92252].
+
+=item *
+
+The implementations of overloaded operations are now called in the correct
+context. This allows, among other things, being able to properly override
+C<< <> >> [perl #47119].
+
+=item *
+
+Specifying only the C<fallback> key when calling C<use overload> now behaves
+properly [perl #113010].
+
+=item *
+
+C<< sub foo { my $a = 0; while ($a) { ... } } >> and
+C<< sub foo { while (0) { ... } } >> now return the same thing [perl #73618].
+
+=item *
+
+String negation now behaves the same under C<use integer;> as it does
+without [perl #113012].
+
+=item *
+
+C<chr> now returns the Unicode replacement character (U+FFFD) for -1,
+regardless of the internal representation. -1 used to wrap if the argument
+was tied or a string internally.
+
+=item *
+
+Using a C<format> after its enclosing sub was freed could crash as of
+perl v5.12.0, if the format referenced lexical variables from the outer sub.
+
+=item *
+
+Using a C<format> after its enclosing sub was undefined could crash as of
+perl v5.10.0, if the format referenced lexical variables from the outer sub.
+
+=item *
+
+Using a C<format> defined inside a closure, which format references
+lexical variables from outside, never really worked unless the C<write>
+call was directly inside the closure. In v5.10.0 it even started crashing.
+Now the copy of that closure nearest the top of the call stack is used to
+find those variables.
+
+=item *
+
+Formats that close over variables in special blocks no longer crash if a
+stub exists with the same name as the special block before the special
+block is compiled.
+
+=item *
+
+The parser no longer gets confused, treating C<eval foo ()> as a syntax
+error if preceded by C<print;> [perl #16249].
+
+=item *
+
+The return value of C<syscall> is no longer truncated on 64-bit platforms
+[perl #113980].
+
+=item *
+
+Constant folding no longer causes C<print 1 ? FOO : BAR> to print to the
+FOO handle [perl #78064].
+
+=item *
+
+C<do subname> now calls the named subroutine and uses the file name it
+returns, instead of opening a file named "subname".
+
+=item *
+
+Subroutines looked up by rv2cv check hooks (registered by XS modules) are
+now taken into consideration when determining whether C<foo bar> should be
+the sub call C<foo(bar)> or the method call C<< "bar"->foo >>.
+
+=item *
+
+C<CORE::foo::bar> is no longer treated specially, allowing global overrides
+to be called directly via C<CORE::GLOBAL::uc(...)> [perl #113016].
+
+=item *
+
+Calling an undefined sub whose typeglob has been undefined now produces the
+customary "Undefined subroutine called" error, instead of "Not a CODE
+reference".
+
+=item *
+
+Two bugs involving @ISA have been fixed. C<*ISA = *glob_without_array> and
+C<undef *ISA; @{*ISA}> would prevent future modifications to @ISA from
+updating the internal caches used to look up methods. The
+*glob_without_array case was a regression from Perl v5.12.
+
+=item *
+
+Regular expression optimisations sometimes caused C<$> with C</m> to
+produce failed or incorrect matches [perl #114068].
+
+=item *
+
+C<__SUB__> now works in a C<sort> block when the enclosing subroutine is
+predeclared with C<sub foo;> syntax [perl #113710].
+
+=item *
+
+Unicode properties only apply to Unicode code points, which leads to
+some subtleties when regular expressions are matched against
+above-Unicode code points. There is a warning generated to draw your
+attention to this. However, this warning was being generated
+inappropriately in some cases, such as when a program was being parsed.
+Non-Unicode matches such as C<\w> and C<[:word:]> should not generate the
+warning, as their definitions don't limit them to apply to only Unicode
+code points. Now the message is only generated when matching against
+C<\p{}> and C<\P{}>. There remains a bug, [perl #114148], for the very
+few properties in Unicode that match just a single code point. The
+warning is not generated if they are matched against an above-Unicode
+code point.
+
+=item *
+
+Uninitialized warnings mentioning hash elements would only mention the
+element name if it was not in the first bucket of the hash, due to an
+off-by-one error.
+
+=item *
+
+A regular expression optimizer bug could cause multiline "^" to behave
+incorrectly in the presence of line breaks, such that
+C<"/\n\n" =~ m#\A(?:^/$)#im> would not match [perl #115242].
+
+=item *
+
+Failed C<fork> in list context no longer corrupts the stack.
+C<@a = (1, 2, fork, 3)> used to gobble up the 2 and assign C<(1, undef, 3)>
+if the C<fork> call failed.
+
+=item *
+
+Numerous memory leaks have been fixed, mostly involving tied variables that
+die, regular expression character classes and code blocks, and syntax
+errors.
+
+=item *
+
+Assigning a regular expression (C<${qr//}>) to a variable that happens to
+hold a floating point number no longer causes assertion failures on
+debugging builds.
+
+=item *
+
+Assigning a regular expression to a scalar containing a number no longer
+causes subsequent numification to produce random numbers.
+
+=item *
+
+Assigning a regular expression to a magic variable no longer wipes away the
+magic. This was a regression from v5.10.
+
+=item *
+
+Assigning a regular expression to a blessed scalar no longer results in
+crashes. This was also a regression from v5.10.
+
+=item *
+
+Regular expression can now be assigned to tied hash and array elements with
+flattening into strings.
+
+=item *
+
+Numifying a regular expression no longer results in an uninitialized
+warning.
+
+=item *
+
+Negative array indices no longer cause EXISTS methods of tied variables to
+be ignored. This was a regression from v5.12.
+
+=item *
+
+Negative array indices no longer result in crashes on arrays tied to
+non-objects.
+
+=item *
+
+C<$byte_overload .= $utf8> no longer results in doubly-encoded UTF-8 if the
+left-hand scalar happened to have produced a UTF-8 string the last time
+overloading was invoked.
+
+=item *
+
+C<goto &sub> now uses the current value of @_, instead of using the array
+the subroutine was originally called with. This means
+C<local @_ = (...); goto &sub> now works [perl #43077].
+
+=item *
+
+If a debugger is invoked recursively, it no longer stomps on its own
+lexical variables. Formerly under recursion all calls would share the same
+set of lexical variables [perl #115742].
+
+=item *
+
+C<*_{ARRAY}> returned from a subroutine no longer spontaneously
+becomes empty.
+
+=back
+
+=head1 Known Problems
+
+=over 4
+
+=item *
+
+UTF8-flagged strings in C<%ENV> on HP-UX 11.00 are buggy
+
+The interaction of UTF8-flagged strings and C<%ENV> on HP-UX 11.00 is
+currently dodgy in some not-yet-fully-diagnosed way. Expect test
+failures in F<t/op/magic.t>, followed by unknown behavior when storing
+wide characters in the environment.
+
+=back
+
+=head1 Obituary
+
+Hojung Yoon (AMORETTE), 24, of Seoul, South Korea, went to his long rest
+on May 8, 2013 with llama figurine and autographed TIMTOADY card. He
+was a brilliant young Perl 5 & 6 hacker and a devoted member of
+Seoul.pm. He programmed Perl, talked Perl, ate Perl, and loved Perl. We
+believe that he is still programming in Perl with his broken IBM laptop
+somewhere. He will be missed.
+
+=head1 Acknowledgements
+
+Perl v5.18.0 represents approximately 12 months of development since
+Perl v5.16.0 and contains approximately 400,000 lines of changes across
+2,100 files from 113 authors.
+
+Perl continues to flourish into its third decade thanks to a vibrant
+community of users and developers. The following people are known to
+have contributed the improvements that became Perl v5.18.0:
+
+Aaron Crane, Aaron Trevena, Abhijit Menon-Sen, Adrian M. Enache, Alan
+Haggai Alavi, Alexandr Ciornii, Andrew Tam, Andy Dougherty, Anton Nikishaev,
+Aristotle Pagaltzis, Augustina Blair, Bob Ernst, Brad Gilbert, Breno G. de
+Oliveira, Brian Carlson, Brian Fraser, Charlie Gonzalez, Chip Salzenberg, Chris
+'BinGOs' Williams, Christian Hansen, Colin Kuskie, Craig A. Berry, Dagfinn
+Ilmari Mannsåker, Daniel Dragan, Daniel Perrett, Darin McBride, Dave Rolsky,
+David Golden, David Leadbeater, David Mitchell, David Nicol, Dominic
+Hargreaves, E. Choroba, Eric Brine, Evan Miller, Father Chrysostomos, Florian
+Ragwitz, François Perrad, George Greer, Goro Fuji, H.Merijn Brand, Herbert
+Breunung, Hugo van der Sanden, Igor Zaytsev, James E Keenan, Jan Dubois,
+Jasmine Ahuja, Jerry D. Hedden, Jess Robinson, Jesse Luehrs, Joaquin Ferrero,
+Joel Berger, John Goodyear, John Peacock, Karen Etheridge, Karl Williamson,
+Karthik Rajagopalan, Kent Fredric, Leon Timmermans, Lucas Holt, Lukas Mai,
+Marcus Holland-Moritz, Markus Jansen, Martin Hasch, Matthew Horsfall, Max
+Maischein, Michael G Schwern, Michael Schroeder, Moritz Lenz, Nicholas Clark,
+Niko Tyni, Oleg Nesterov, Patrik Hägglund, Paul Green, Paul Johnson, Paul
+Marquess, Peter Martini, Rafael Garcia-Suarez, Reini Urban, Renee Baecker,
+Rhesa Rozendaal, Ricardo Signes, Robin Barker, Ronald J. Kimball, Ruslan
+Zakirov, Salvador Fandiño, Sawyer X, Scott Lanning, Sergey Alekseev, Shawn M
+Moore, Shirakata Kentaro, Shlomi Fish, Sisyphus, Smylers, Steffen Müller,
+Steve Hay, Steve Peters, Steven Schubiger, Sullivan Beck, Sven Strickroth,
+Sébastien Aperghis-Tramoni, Thomas Sibley, Tobias Leich, Tom Wyant, Tony Cook,
+Vadim Konovalov, Vincent Pit, Volker Schatz, Walt Mankowski, Yves Orton,
+Zefram.
+
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
+
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
+
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
+
+=head1 Reporting Bugs
+
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ . There may also be information at
+http://www.perl.org/ , the Perl Home Page.
+
+If you believe you have an unreported bug, please run the L<perlbug> program
+included with your release. Be sure to trim your bug down to a tiny but
+sufficient test case. Your bug report, along with the output of C<perl -V>,
+will be sent off to perlbug at perl.org to be analysed by the Perl porting team.
+
+If the bug you are reporting has security implications, which make it
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
+co-ordinate the release of patches to mitigate or fix the problem across all
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
+
+=head1 SEE ALSO
+
+The F<Changes> file for an explanation of how to view exhaustive details on
+what changed.
+
+The F<INSTALL> file for how to build Perl.
+
+The F<README> file for general stuff.
+
+The F<Artistic> and F<Copying> files for copyright information.
+
+=cut
Modified: trunk/contrib/perl/pod/perl561delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl561delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl561delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,6 +1,6 @@
=head1 NAME
-perl561delta - what's new for perl v5.6.x
+perl561delta - what's new for perl v5.6.1
=head1 DESCRIPTION
@@ -2977,7 +2977,6 @@
The C<use attrs> pragma is now obsolete, and is only provided for
backward-compatibility. See L<perlsub/"Subroutine Attributes">.
-
=item Premature end of script headers
See Server error.
@@ -3364,8 +3363,8 @@
Perl, whose interfaces continue to match those of prior versions
(but subject to the other options described here).
-See L<perlguts/"The Perl API"> for detailed information on the
-ramifications of building Perl with this option.
+See L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for detailed information
+on the ramifications of building Perl with this option.
NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
with one of -Dusethreads, -Dusemultiplicity, or both. It is not
Property changes on: trunk/contrib/perl/pod/perl561delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl56delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl56delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl56delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -2372,7 +2372,6 @@
The C<use attrs> pragma is now obsolete, and is only provided for
backward-compatibility. See L<perlsub/"Subroutine Attributes">.
-
=item Premature end of script headers
See Server error.
@@ -2759,7 +2758,8 @@
Perl, whose interfaces continue to match those of prior versions
(but subject to the other options described here).
-See L<perlguts/"The Perl API"> for detailed information on the
+
+See L<perlguts/Background and PERL_IMPLICIT_CONTEXT> for detailed information on the
ramifications of building Perl with this option.
NOTE: PERL_IMPLICIT_CONTEXT is automatically enabled whenever Perl is built
Property changes on: trunk/contrib/perl/pod/perl56delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl570delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl570delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl570delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl570delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl571delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl571delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl571delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl571delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl572delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl572delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl572delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl572delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl573delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl573delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl573delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl573delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl581delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl581delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl581delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl581delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl582delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl582delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl582delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl582delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl583delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl583delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl583delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl583delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl584delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl584delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl584delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl584delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl585delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl585delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl585delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl585delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl586delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl586delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl586delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl586delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl587delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl587delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl587delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl587delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl588delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl588delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl588delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl588delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl589delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl589delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl589delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1228,7 +1228,7 @@
=item *
-L<reverse> function documentation received scalar context examples.
+C<reverse> function documentation received scalar context examples.
=back
@@ -1259,7 +1259,7 @@
L<perlvar> fixes confusion about real GID C<$(> and effective GID C<$)>.
Perl thread tutorial example is fixed in section
-L<perlthrtut/Queues: Passing Data Around> and L<perlothrtut>.
+L<perlthrtut/Queues: Passing Data Around> and L<perlthrtut>.
L<perlhack> documentation extensively improved by Jarkko Hietaniemi and others.
@@ -2317,7 +2317,8 @@
If the bug you are reporting has security implications, which make it
inappropriate to send to a publicly archived mailing list, then please send
it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
+unarchived mailing list, which includes
+all the core committers, who will be able
to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
platforms on which Perl is supported. Please only use this address for security
Property changes on: trunk/contrib/perl/pod/perl589delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perl58delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl58delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl58delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -730,7 +730,7 @@
=item *
-L<utime> now supports C<utime undef, undef, @files> to change the
+L<perlfunc/utime> now supports C<utime undef, undef, @files> to change the
file timestamps to the current time.
=item *
@@ -2018,7 +2018,9 @@
have been regained. Many test suite tests still fail and the
co-existence of Unicode and EBCDIC isn't quite settled, but the
situation is much better than with Perl 5.6. See L<perlos390>,
-L<perlbs2000> (for POSIX-BC), and L<perlvmesa> for more information.
+L<perlbs2000> (for POSIX-BC), and perlvmesa for more information.
+(B<Note:> support for VM/ESA was removed in Perl v5.18.0. The relevant
+information was in F<README.vmesa>)
=item *
@@ -3376,7 +3378,8 @@
ext/POSIX/t/sigaction...............FAILED at test 13
ext/POSIX/t/waitpid.................FAILED at test 1
-See L<perlbeos> (README.beos) for more details.
+(B<Note:> more information was available in F<README.beos> until support for
+BeOS was removed in Perl v5.18.0)
=head2 Cygwin "unable to remap"
@@ -3631,7 +3634,9 @@
=head2 UTS
-There are a few known test failures, see L<perluts> (README.uts).
+There are a few known test failures. (B<Note:> the relevant information was
+available in F<README.uts> until support for UTS was removed in Perl
+v5.18.0)
=head2 VOS (Stratus)
Property changes on: trunk/contrib/perl/pod/perl58delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl590delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl590delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl590delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl590delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl591delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl591delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl591delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl591delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl592delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl592delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl592delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl592delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl593delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl593delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl593delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl593delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl594delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl594delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl594delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl594delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perl595delta.pod
===================================================================
--- trunk/contrib/perl/pod/perl595delta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perl595delta.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perl595delta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlapi.pod (from rev 6437, vendor/perl/5.18.1/pod/perlapi.pod)
===================================================================
--- trunk/contrib/perl/pod/perlapi.pod (rev 0)
+++ trunk/contrib/perl/pod/perlapi.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,7193 @@
+-*- buffer-read-only: t -*-
+
+!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+This file is built by autodoc.pl extracting documentation from the C source
+files.
+
+=head1 NAME
+
+perlapi - autogenerated documentation for the perl public API
+
+=head1 DESCRIPTION
+X<Perl API> X<API> X<api>
+
+This file contains the documentation of the perl public API generated by
+embed.pl, specifically a listing of functions, macros, flags, and variables
+that may be used by extension writers. The interfaces of any functions that
+are not listed here are subject to change without notice. For this reason,
+blindly using functions listed in proto.h is to be avoided when writing
+extensions.
+
+Note that all Perl API global variables must be referenced with the C<PL_>
+prefix. Some macros are provided for compatibility with the older,
+unadorned names, but this support may be disabled in a future release.
+
+The listing is alphabetical, case insensitive.
+
+
+=head1 "Gimme" Values
+
+=over 8
+
+=item GIMME
+X<GIMME>
+
+A backward-compatible version of C<GIMME_V> which can only return
+C<G_SCALAR> or C<G_ARRAY>; in a void context, it returns C<G_SCALAR>.
+Deprecated. Use C<GIMME_V> instead.
+
+ U32 GIMME
+
+=for hackers
+Found in file op.h
+
+=item GIMME_V
+X<GIMME_V>
+
+The XSUB-writer's equivalent to Perl's C<wantarray>. Returns C<G_VOID>,
+C<G_SCALAR> or C<G_ARRAY> for void, scalar or list context,
+respectively.
+
+ U32 GIMME_V
+
+=for hackers
+Found in file op.h
+
+=item G_ARRAY
+X<G_ARRAY>
+
+Used to indicate list context. See C<GIMME_V>, C<GIMME> and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_DISCARD
+X<G_DISCARD>
+
+Indicates that arguments returned from a callback should be discarded. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_EVAL
+X<G_EVAL>
+
+Used to force a Perl C<eval> wrapper around a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_NOARGS
+X<G_NOARGS>
+
+Indicates that no arguments are being sent to a callback. See
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_SCALAR
+X<G_SCALAR>
+
+Used to indicate scalar context. See C<GIMME_V>, C<GIMME>, and
+L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+=item G_VOID
+X<G_VOID>
+
+Used to indicate void context. See C<GIMME_V> and L<perlcall>.
+
+=for hackers
+Found in file cop.h
+
+
+=back
+
+=head1 Array Manipulation Functions
+
+=over 8
+
+=item AvFILL
+X<AvFILL>
+
+Same as C<av_len()>. Deprecated, use C<av_len()> instead.
+
+ int AvFILL(AV* av)
+
+=for hackers
+Found in file av.h
+
+=item av_clear
+X<av_clear>
+
+Clears an array, making it empty. Does not free the memory used by the
+array itself.
+
+ void av_clear(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_create_and_push
+X<av_create_and_push>
+
+Push an SV onto the end of the array, creating the array if necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ void av_create_and_push(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
+=item av_create_and_unshift_one
+X<av_create_and_unshift_one>
+
+Unshifts an SV onto the beginning of the array, creating the array if
+necessary.
+A small internal helper function to remove a commonly duplicated idiom.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ SV** av_create_and_unshift_one(AV **const avp, SV *const val)
+
+=for hackers
+Found in file av.c
+
+=item av_delete
+X<av_delete>
+
+Deletes the element indexed by C<key> from the array. Returns the
+deleted element. If C<flags> equals C<G_DISCARD>, the element is freed
+and null is returned.
+
+ SV* av_delete(AV* ar, I32 key, I32 flags)
+
+=for hackers
+Found in file av.c
+
+=item av_exists
+X<av_exists>
+
+Returns true if the element indexed by C<key> has been initialized.
+
+This relies on the fact that uninitialized array elements are set to
+C<&PL_sv_undef>.
+
+ bool av_exists(AV* ar, I32 key)
+
+=for hackers
+Found in file av.c
+
+=item av_extend
+X<av_extend>
+
+Pre-extend an array. The C<key> is the index to which the array should be
+extended.
+
+ void av_extend(AV* ar, I32 key)
+
+=for hackers
+Found in file av.c
+
+=item av_fetch
+X<av_fetch>
+
+Returns the SV at the specified index in the array. The C<key> is the
+index. If C<lval> is set then the fetch will be part of a store. Check
+that the return value is non-null before dereferencing it to a C<SV*>.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
+more information on how to use this function on tied arrays.
+
+ SV** av_fetch(AV* ar, I32 key, I32 lval)
+
+=for hackers
+Found in file av.c
+
+=item av_fill
+X<av_fill>
+
+Set the highest index in the array to the given number, equivalent to
+Perl's C<$#array = $fill;>.
+
+The number of elements in the an array will be C<fill + 1> after
+av_fill() returns. If the array was previously shorter then the
+additional elements appended are set to C<PL_sv_undef>. If the array
+was longer, then the excess elements are freed. C<av_fill(av, -1)> is
+the same as C<av_clear(av)>.
+
+ void av_fill(AV* ar, I32 fill)
+
+=for hackers
+Found in file av.c
+
+=item av_len
+X<av_len>
+
+Returns the highest index in the array. The number of elements in the
+array is C<av_len(av) + 1>. Returns -1 if the array is empty.
+
+ I32 av_len(const AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_make
+X<av_make>
+
+Creates a new AV and populates it with a list of SVs. The SVs are copied
+into the array, so they may be freed after the call to av_make. The new AV
+will have a reference count of 1.
+
+ AV* av_make(I32 size, SV** svp)
+
+=for hackers
+Found in file av.c
+
+=item av_pop
+X<av_pop>
+
+Pops an SV off the end of the array. Returns C<&PL_sv_undef> if the array
+is empty.
+
+ SV* av_pop(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_push
+X<av_push>
+
+Pushes an SV onto the end of the array. The array will grow automatically
+to accommodate the addition.
+
+ void av_push(AV* ar, SV* val)
+
+=for hackers
+Found in file av.c
+
+=item av_shift
+X<av_shift>
+
+Shifts an SV off the beginning of the array.
+
+ SV* av_shift(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_store
+X<av_store>
+
+Stores an SV in an array. The array index is specified as C<key>. The
+return value will be NULL if the operation failed or if the value did not
+need to be actually stored within the array (as in the case of tied
+arrays). Otherwise it can be dereferenced to get the original C<SV*>. Note
+that the caller is responsible for suitably incrementing the reference
+count of C<val> before the call, and decrementing it if the function
+returned NULL.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for
+more information on how to use this function on tied arrays.
+
+ SV** av_store(AV* ar, I32 key, SV* val)
+
+=for hackers
+Found in file av.c
+
+=item av_undef
+X<av_undef>
+
+Undefines the array. Frees the memory used by the array itself.
+
+ void av_undef(AV* ar)
+
+=for hackers
+Found in file av.c
+
+=item av_unshift
+X<av_unshift>
+
+Unshift the given number of C<undef> values onto the beginning of the
+array. The array will grow automatically to accommodate the addition. You
+must then use C<av_store> to assign values to these new elements.
+
+ void av_unshift(AV* ar, I32 num)
+
+=for hackers
+Found in file av.c
+
+=item get_av
+X<get_av>
+
+Returns the AV of the specified Perl array. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ AV* get_av(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item newAV
+X<newAV>
+
+Creates a new AV. The reference count is set to 1.
+
+ AV* newAV()
+
+=for hackers
+Found in file av.c
+
+=item sortsv
+X<sortsv>
+
+Sort an array. Here is an example:
+
+ sortsv(AvARRAY(av), av_len(av)+1, Perl_sv_cmp_locale);
+
+Currently this always uses mergesort. See sortsv_flags for a more
+flexible routine.
+
+ void sortsv(SV** array, size_t num_elts, SVCOMPARE_t cmp)
+
+=for hackers
+Found in file pp_sort.c
+
+=item sortsv_flags
+X<sortsv_flags>
+
+Sort an array, with various options.
+
+ void sortsv_flags(SV** array, size_t num_elts, SVCOMPARE_t cmp, U32 flags)
+
+=for hackers
+Found in file pp_sort.c
+
+
+=back
+
+=head1 Callback Functions
+
+=over 8
+
+=item call_argv
+X<call_argv>
+
+Performs a callback to the specified Perl sub. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_argv(const char* sub_name, I32 flags, char** argv)
+
+=for hackers
+Found in file perl.c
+
+=item call_method
+X<call_method>
+
+Performs a callback to the specified Perl method. The blessed object must
+be on the stack. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_method(const char* methname, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item call_pv
+X<call_pv>
+
+Performs a callback to the specified Perl sub. See L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_pv(const char* sub_name, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item call_sv
+X<call_sv>
+
+Performs a callback to the Perl sub whose name is in the SV. See
+L<perlcall>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 call_sv(SV* sv, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item ENTER
+X<ENTER>
+
+Opening bracket on a callback. See C<LEAVE> and L<perlcall>.
+
+ ENTER;
+
+=for hackers
+Found in file scope.h
+
+=item eval_pv
+X<eval_pv>
+
+Tells Perl to C<eval> the given string and return an SV* result.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ SV* eval_pv(const char* p, I32 croak_on_error)
+
+=for hackers
+Found in file perl.c
+
+=item eval_sv
+X<eval_sv>
+
+Tells Perl to C<eval> the string in the SV.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ I32 eval_sv(SV* sv, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item FREETMPS
+X<FREETMPS>
+
+Closing bracket for temporaries on a callback. See C<SAVETMPS> and
+L<perlcall>.
+
+ FREETMPS;
+
+=for hackers
+Found in file scope.h
+
+=item LEAVE
+X<LEAVE>
+
+Closing bracket on a callback. See C<ENTER> and L<perlcall>.
+
+ LEAVE;
+
+=for hackers
+Found in file scope.h
+
+=item SAVETMPS
+X<SAVETMPS>
+
+Opening bracket for temporaries on a callback. See C<FREETMPS> and
+L<perlcall>.
+
+ SAVETMPS;
+
+=for hackers
+Found in file scope.h
+
+
+=back
+
+=head1 Character classes
+
+=over 8
+
+=item isALNUM
+X<isALNUM>
+
+Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric
+character (including underscore) or digit.
+
+ bool isALNUM(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isALPHA
+X<isALPHA>
+
+Returns a boolean indicating whether the C C<char> is an ASCII alphabetic
+character.
+
+ bool isALPHA(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isDIGIT
+X<isDIGIT>
+
+Returns a boolean indicating whether the C C<char> is an ASCII
+digit.
+
+ bool isDIGIT(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isLOWER
+X<isLOWER>
+
+Returns a boolean indicating whether the C C<char> is a lowercase
+character.
+
+ bool isLOWER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isSPACE
+X<isSPACE>
+
+Returns a boolean indicating whether the C C<char> is whitespace.
+
+ bool isSPACE(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item isUPPER
+X<isUPPER>
+
+Returns a boolean indicating whether the C C<char> is an uppercase
+character.
+
+ bool isUPPER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item toLOWER
+X<toLOWER>
+
+Converts the specified character to lowercase.
+
+ char toLOWER(char ch)
+
+=for hackers
+Found in file handy.h
+
+=item toUPPER
+X<toUPPER>
+
+Converts the specified character to uppercase.
+
+ char toUPPER(char ch)
+
+=for hackers
+Found in file handy.h
+
+
+=back
+
+=head1 Cloning an interpreter
+
+=over 8
+
+=item perl_clone
+X<perl_clone>
+
+Create and return a new interpreter by cloning the current one.
+
+perl_clone takes these flags as parameters:
+
+CLONEf_COPY_STACKS - is used to, well, copy the stacks also,
+without it we only clone the data and zero the stacks,
+with it we copy the stacks and the new perl interpreter is
+ready to run at the exact same point as the previous one.
+The pseudo-fork code uses COPY_STACKS while the
+threads->create doesn't.
+
+CLONEf_KEEP_PTR_TABLE
+perl_clone keeps a ptr_table with the pointer of the old
+variable as a key and the new variable as a value,
+this allows it to check if something has been cloned and not
+clone it again but rather just use the value and increase the
+refcount. If KEEP_PTR_TABLE is not set then perl_clone will kill
+the ptr_table using the function
+C<ptr_table_free(PL_ptr_table); PL_ptr_table = NULL;>,
+reason to keep it around is if you want to dup some of your own
+variable who are outside the graph perl scans, example of this
+code is in threads.xs create
+
+CLONEf_CLONE_HOST
+This is a win32 thing, it is ignored on unix, it tells perls
+win32host code (which is c++) to clone itself, this is needed on
+win32 if you want to run two threads at the same time,
+if you just want to do some stuff in a separate perl interpreter
+and then throw it away and return to the original one,
+you don't need to do anything.
+
+ PerlInterpreter* perl_clone(PerlInterpreter* interp, UV flags)
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 CV Manipulation Functions
+
+=over 8
+
+=item CvSTASH
+X<CvSTASH>
+
+Returns the stash of the CV.
+
+ HV* CvSTASH(CV* cv)
+
+=for hackers
+Found in file cv.h
+
+=item get_cv
+X<get_cv>
+
+Uses C<strlen> to get the length of C<name>, then calls C<get_cvn_flags>.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cv(const char* name, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+=item get_cvn_flags
+X<get_cvn_flags>
+
+Returns the CV of the specified Perl subroutine. C<flags> are passed to
+C<gv_fetchpvn_flags>. If C<GV_ADD> is set and the Perl subroutine does not
+exist then it will be declared (which has the same effect as saying
+C<sub name;>). If C<GV_ADD> is not set and the subroutine does not exist
+then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ CV* get_cvn_flags(const char* name, STRLEN len, I32 flags)
+
+=for hackers
+Found in file perl.c
+
+
+=back
+
+=head1 Embedding Functions
+
+=over 8
+
+=item cv_undef
+X<cv_undef>
+
+Clear out all the active components of a CV. This can happen either
+by an explicit C<undef &foo>, or by the reference count going to zero.
+In the former case, we keep the CvOUTSIDE pointer, so that any anonymous
+children can still follow the full lexical scope chain.
+
+ void cv_undef(CV* cv)
+
+=for hackers
+Found in file op.c
+
+=item load_module
+X<load_module>
+
+Loads the module whose name is pointed to by the string part of name.
+Note that the actual module name, not its filename, should be given.
+Eg, "Foo::Bar" instead of "Foo/Bar.pm". flags can be any of
+PERL_LOADMOD_DENY, PERL_LOADMOD_NOIMPORT, or PERL_LOADMOD_IMPORT_OPS
+(or 0 for no flags). ver, if specified, provides version semantics
+similar to C<use Foo::Bar VERSION>. The optional trailing SV*
+arguments can be used to specify arguments to the module's import()
+method, similar to C<use Foo::Bar VERSION LIST>.
+
+ void load_module(U32 flags, SV* name, SV* ver, ...)
+
+=for hackers
+Found in file op.c
+
+=item nothreadhook
+X<nothreadhook>
+
+Stub that provides thread hook for perl_destruct when there are
+no threads.
+
+ int nothreadhook()
+
+=for hackers
+Found in file perl.c
+
+=item perl_alloc
+X<perl_alloc>
+
+Allocates a new Perl interpreter. See L<perlembed>.
+
+ PerlInterpreter* perl_alloc()
+
+=for hackers
+Found in file perl.c
+
+=item perl_construct
+X<perl_construct>
+
+Initializes a new Perl interpreter. See L<perlembed>.
+
+ void perl_construct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_destruct
+X<perl_destruct>
+
+Shuts down a Perl interpreter. See L<perlembed>.
+
+ int perl_destruct(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_free
+X<perl_free>
+
+Releases a Perl interpreter. See L<perlembed>.
+
+ void perl_free(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item perl_parse
+X<perl_parse>
+
+Tells a Perl interpreter to parse a Perl script. See L<perlembed>.
+
+ int perl_parse(PerlInterpreter* interp, XSINIT_t xsinit, int argc, char** argv, char** env)
+
+=for hackers
+Found in file perl.c
+
+=item perl_run
+X<perl_run>
+
+Tells a Perl interpreter to run. See L<perlembed>.
+
+ int perl_run(PerlInterpreter* interp)
+
+=for hackers
+Found in file perl.c
+
+=item require_pv
+X<require_pv>
+
+Tells Perl to C<require> the file named by the string argument. It is
+analogous to the Perl code C<eval "require '$file'">. It's even
+implemented that way; consider using load_module instead.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ void require_pv(const char* pv)
+
+=for hackers
+Found in file perl.c
+
+
+=back
+
+=head1 Functions in file dump.c
+
+
+=over 8
+
+=item pv_display
+X<pv_display>
+
+ char *pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len,
+ STRLEN pvlim, U32 flags)
+
+Similar to
+
+ pv_escape(dsv,pv,cur,pvlim,PERL_PV_ESCAPE_QUOTE);
+
+except that an additional "\0" will be appended to the string when
+len > cur and pv[cur] is "\0".
+
+Note that the final string may be up to 7 chars longer than pvlim.
+
+ char* pv_display(SV *dsv, const char *pv, STRLEN cur, STRLEN len, STRLEN pvlim)
+
+=for hackers
+Found in file dump.c
+
+=item pv_escape
+X<pv_escape>
+
+ |const STRLEN count|const STRLEN max
+ |STRLEN const *escaped, const U32 flags
+
+Escapes at most the first "count" chars of pv and puts the results into
+dsv such that the size of the escaped string will not exceed "max" chars
+and will not contain any incomplete escape sequences.
+
+If flags contains PERL_PV_ESCAPE_QUOTE then any double quotes in the string
+will also be escaped.
+
+Normally the SV will be cleared before the escaped string is prepared,
+but when PERL_PV_ESCAPE_NOCLEAR is set this will not occur.
+
+If PERL_PV_ESCAPE_UNI is set then the input string is treated as Unicode,
+if PERL_PV_ESCAPE_UNI_DETECT is set then the input string is scanned
+using C<is_utf8_string()> to determine if it is Unicode.
+
+If PERL_PV_ESCAPE_ALL is set then all input chars will be output
+using C<\x01F1> style escapes, otherwise only chars above 255 will be
+escaped using this style, other non printable chars will use octal or
+common escaped patterns like C<\n>. If PERL_PV_ESCAPE_NOBACKSLASH
+then all chars below 255 will be treated as printable and
+will be output as literals.
+
+If PERL_PV_ESCAPE_FIRSTCHAR is set then only the first char of the
+string will be escaped, regardles of max. If the string is utf8 and
+the chars value is >255 then it will be returned as a plain hex
+sequence. Thus the output will either be a single char,
+an octal escape sequence, a special escape like C<\n> or a 3 or
+more digit hex value.
+
+If PERL_PV_ESCAPE_RE is set then the escape char used will be a '%' and
+not a '\\'. This is because regexes very often contain backslashed
+sequences, whereas '%' is not a particularly common character in patterns.
+
+Returns a pointer to the escaped text as held by dsv.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ char* pv_escape(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, STRLEN * const escaped, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+=item pv_pretty
+X<pv_pretty>
+
+ |const STRLEN count|const STRLEN max\
+ |const char const *start_color| const char const *end_color\
+ |const U32 flags
+
+Converts a string into something presentable, handling escaping via
+pv_escape() and supporting quoting and ellipses.
+
+If the PERL_PV_PRETTY_QUOTE flag is set then the result will be
+double quoted with any double quotes in the string escaped. Otherwise
+if the PERL_PV_PRETTY_LTGT flag is set then the result be wrapped in
+angle brackets.
+
+If the PERL_PV_PRETTY_ELLIPSES flag is set and not all characters in
+string were output then an ellipsis C<...> will be appended to the
+string. Note that this happens AFTER it has been quoted.
+
+If start_color is non-null then it will be inserted after the opening
+quote (if there is one) but before the escaped text. If end_color
+is non-null then it will be inserted after the escaped text but before
+any quotes or ellipses.
+
+Returns a pointer to the prettified text as held by dsv.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ char* pv_pretty(SV *dsv, char const * const str, const STRLEN count, const STRLEN max, char const * const start_color, char const * const end_color, const U32 flags)
+
+=for hackers
+Found in file dump.c
+
+
+=back
+
+=head1 Functions in file mathoms.c
+
+
+=over 8
+
+=item gv_fetchmethod
+X<gv_fetchmethod>
+
+See L<gv_fetchmethod_autoload>.
+
+ GV* gv_fetchmethod(HV* stash, const char* name)
+
+=for hackers
+Found in file mathoms.c
+
+=item pack_cat
+X<pack_cat>
+
+The engine implementing pack() Perl function. Note: parameters next_in_list and
+flags are not used. This call should not be used; use packlist instead.
+
+ void pack_cat(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist, SV ***next_in_list, U32 flags)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_2pvbyte_nolen
+X<sv_2pvbyte_nolen>
+
+Return a pointer to the byte-encoded representation of the SV.
+May cause the SV to be downgraded from UTF-8 as a side-effect.
+
+Usually accessed via the C<SvPVbyte_nolen> macro.
+
+ char* sv_2pvbyte_nolen(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_2pvutf8_nolen
+X<sv_2pvutf8_nolen>
+
+Return a pointer to the UTF-8-encoded representation of the SV.
+May cause the SV to be upgraded to UTF-8 as a side-effect.
+
+Usually accessed via the C<SvPVutf8_nolen> macro.
+
+ char* sv_2pvutf8_nolen(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_2pv_nolen
+X<sv_2pv_nolen>
+
+Like C<sv_2pv()>, but doesn't return the length too. You should usually
+use the macro wrapper C<SvPV_nolen(sv)> instead.
+ char* sv_2pv_nolen(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_catpvn_mg
+X<sv_catpvn_mg>
+
+Like C<sv_catpvn>, but also handles 'set' magic.
+
+ void sv_catpvn_mg(SV *sv, const char *ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_catsv_mg
+X<sv_catsv_mg>
+
+Like C<sv_catsv>, but also handles 'set' magic.
+
+ void sv_catsv_mg(SV *dstr, SV *sstr)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_force_normal
+X<sv_force_normal>
+
+Undo various types of fakery on an SV: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an xpvmg. See also C<sv_force_normal_flags>.
+
+ void sv_force_normal(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_iv
+X<sv_iv>
+
+A private implementation of the C<SvIVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+ IV sv_iv(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_nolocking
+X<sv_nolocking>
+
+Dummy routine which "locks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could
+potentially warn under some level of strict-ness.
+
+"Superseded" by sv_nosharing().
+
+ void sv_nolocking(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_nounlocking
+X<sv_nounlocking>
+
+Dummy routine which "unlocks" an SV when there is no locking module present.
+Exists to avoid test for a NULL function pointer and because it could
+potentially warn under some level of strict-ness.
+
+"Superseded" by sv_nosharing().
+
+ void sv_nounlocking(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_nv
+X<sv_nv>
+
+A private implementation of the C<SvNVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+ NV sv_nv(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pv
+X<sv_pv>
+
+Use the C<SvPV_nolen> macro instead
+
+ char* sv_pv(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pvbyte
+X<sv_pvbyte>
+
+Use C<SvPVbyte_nolen> instead.
+
+ char* sv_pvbyte(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pvbyten
+X<sv_pvbyten>
+
+A private implementation of the C<SvPVbyte> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
+
+ char* sv_pvbyten(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pvn
+X<sv_pvn>
+
+A private implementation of the C<SvPV> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+ char* sv_pvn(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pvutf8
+X<sv_pvutf8>
+
+Use the C<SvPVutf8_nolen> macro instead
+
+ char* sv_pvutf8(SV *sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_pvutf8n
+X<sv_pvutf8n>
+
+A private implementation of the C<SvPVutf8> macro for compilers
+which can't cope with complex macro expressions. Always use the macro
+instead.
+
+ char* sv_pvutf8n(SV *sv, STRLEN *len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_taint
+X<sv_taint>
+
+Taint an SV. Use C<SvTAINTED_on> instead.
+ void sv_taint(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_unref
+X<sv_unref>
+
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV. This can almost be thought of
+as a reversal of C<newSVrv>. This is C<sv_unref_flags> with the C<flag>
+being zero. See C<SvROK_off>.
+
+ void sv_unref(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_usepvn
+X<sv_usepvn>
+
+Tells an SV to use C<ptr> to find its string value. Implemented by
+calling C<sv_usepvn_flags> with C<flags> of 0, hence does not handle 'set'
+magic. See C<sv_usepvn_flags>.
+
+ void sv_usepvn(SV* sv, char* ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_usepvn_mg
+X<sv_usepvn_mg>
+
+Like C<sv_usepvn>, but also handles 'set' magic.
+
+ void sv_usepvn_mg(SV *sv, char *ptr, STRLEN len)
+
+=for hackers
+Found in file mathoms.c
+
+=item sv_uv
+X<sv_uv>
+
+A private implementation of the C<SvUVx> macro for compilers which can't
+cope with complex macro expressions. Always use the macro instead.
+
+ UV sv_uv(SV* sv)
+
+=for hackers
+Found in file mathoms.c
+
+=item unpack_str
+X<unpack_str>
+
+The engine implementing unpack() Perl function. Note: parameters strbeg, new_s
+and ocnt are not used. This call should not be used, use unpackstring instead.
+
+ I32 unpack_str(const char *pat, const char *patend, const char *s, const char *strbeg, const char *strend, char **new_s, I32 ocnt, U32 flags)
+
+=for hackers
+Found in file mathoms.c
+
+
+=back
+
+=head1 Functions in file pp_ctl.c
+
+
+=over 8
+
+=item find_runcv
+X<find_runcv>
+
+Locate the CV corresponding to the currently executing sub or eval.
+If db_seqp is non_null, skip CVs that are in the DB package and populate
+*db_seqp with the cop sequence number at the point that the DB:: code was
+entered. (allows debuggers to eval in the scope of the breakpoint rather
+than in the scope of the debugger itself).
+
+ CV* find_runcv(U32 *db_seqp)
+
+=for hackers
+Found in file pp_ctl.c
+
+
+=back
+
+=head1 Functions in file pp_pack.c
+
+
+=over 8
+
+=item packlist
+X<packlist>
+
+The engine implementing pack() Perl function.
+
+ void packlist(SV *cat, const char *pat, const char *patend, SV **beglist, SV **endlist)
+
+=for hackers
+Found in file pp_pack.c
+
+=item unpackstring
+X<unpackstring>
+
+The engine implementing unpack() Perl function. C<unpackstring> puts the
+extracted list items on the stack and returns the number of elements.
+Issue C<PUTBACK> before and C<SPAGAIN> after the call to this function.
+
+ I32 unpackstring(const char *pat, const char *patend, const char *s, const char *strend, U32 flags)
+
+=for hackers
+Found in file pp_pack.c
+
+
+=back
+
+=head1 GV Functions
+
+=over 8
+
+=item GvSV
+X<GvSV>
+
+Return the SV from the GV.
+
+ SV* GvSV(GV* gv)
+
+=for hackers
+Found in file gv.h
+
+=item gv_const_sv
+X<gv_const_sv>
+
+If C<gv> is a typeglob whose subroutine entry is a constant sub eligible for
+inlining, or C<gv> is a placeholder reference that would be promoted to such
+a typeglob, then returns the value returned by the sub. Otherwise, returns
+NULL.
+
+ SV* gv_const_sv(GV* gv)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmeth
+X<gv_fetchmeth>
+
+Returns the glob with the given C<name> and a defined subroutine or
+C<NULL>. The glob lives in the given C<stash>, or in the stashes
+accessible via @ISA and UNIVERSAL::.
+
+The argument C<level> should be either 0 or -1. If C<level==0>, as a
+side-effect creates a glob with the given C<name> in the given C<stash>
+which in the case of success contains an alias for the subroutine, and sets
+up caching info for this glob.
+
+This function grants C<"SUPER"> token as a postfix of the stash name. The
+GV returned from C<gv_fetchmeth> may be a method cache entry, which is not
+visible to Perl code. So when calling C<call_sv>, you should not use
+the GV directly; instead, you should use the method's CV, which can be
+obtained from the GV with the C<GvCV> macro.
+
+ GV* gv_fetchmeth(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmethod_autoload
+X<gv_fetchmethod_autoload>
+
+Returns the glob which contains the subroutine to call to invoke the method
+on the C<stash>. In fact in the presence of autoloading this may be the
+glob for "AUTOLOAD". In this case the corresponding variable $AUTOLOAD is
+already setup.
+
+The third parameter of C<gv_fetchmethod_autoload> determines whether
+AUTOLOAD lookup is performed if the given method is not present: non-zero
+means yes, look for AUTOLOAD; zero means no, don't look for AUTOLOAD.
+Calling C<gv_fetchmethod> is equivalent to calling C<gv_fetchmethod_autoload>
+with a non-zero C<autoload> parameter.
+
+These functions grant C<"SUPER"> token as a prefix of the method name. Note
+that if you want to keep the returned glob for a long time, you need to
+check for it being "AUTOLOAD", since at the later time the call may load a
+different subroutine due to $AUTOLOAD changing its value. Use the glob
+created via a side effect to do this.
+
+These functions have the same side-effects and as C<gv_fetchmeth> with
+C<level==0>. C<name> should be writable if contains C<':'> or C<'
+''>. The warning against passing the GV returned by C<gv_fetchmeth> to
+C<call_sv> apply equally to these functions.
+
+ GV* gv_fetchmethod_autoload(HV* stash, const char* name, I32 autoload)
+
+=for hackers
+Found in file gv.c
+
+=item gv_fetchmeth_autoload
+X<gv_fetchmeth_autoload>
+
+Same as gv_fetchmeth(), but looks for autoloaded subroutines too.
+Returns a glob for the subroutine.
+
+For an autoloaded subroutine without a GV, will create a GV even
+if C<level < 0>. For an autoloaded subroutine without a stub, GvCV()
+of the result may be zero.
+
+ GV* gv_fetchmeth_autoload(HV* stash, const char* name, STRLEN len, I32 level)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpv
+X<gv_stashpv>
+
+Returns a pointer to the stash for a specified package. Uses C<strlen> to
+determine the length of C<name>, then calls C<gv_stashpvn()>.
+
+ HV* gv_stashpv(const char* name, I32 flags)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpvn
+X<gv_stashpvn>
+
+Returns a pointer to the stash for a specified package. The C<namelen>
+parameter indicates the length of the C<name>, in bytes. C<flags> is passed
+to C<gv_fetchpvn_flags()>, so if set to C<GV_ADD> then the package will be
+created if it does not already exist. If the package does not exist and
+C<flags> is 0 (or any other setting that does not create packages) then NULL
+is returned.
+
+
+ HV* gv_stashpvn(const char* name, U32 namelen, I32 flags)
+
+=for hackers
+Found in file gv.c
+
+=item gv_stashpvs
+X<gv_stashpvs>
+
+Like C<gv_stashpvn>, but takes a literal string instead of a string/length pair.
+
+ HV* gv_stashpvs(const char* name, I32 create)
+
+=for hackers
+Found in file handy.h
+
+=item gv_stashsv
+X<gv_stashsv>
+
+Returns a pointer to the stash for a specified package. See C<gv_stashpvn>.
+
+ HV* gv_stashsv(SV* sv, I32 flags)
+
+=for hackers
+Found in file gv.c
+
+
+=back
+
+=head1 Handy Values
+
+=over 8
+
+=item Nullav
+X<Nullav>
+
+Null AV pointer.
+
+=for hackers
+Found in file av.h
+
+=item Nullch
+X<Nullch>
+
+Null character pointer.
+
+=for hackers
+Found in file handy.h
+
+=item Nullcv
+X<Nullcv>
+
+Null CV pointer.
+
+=for hackers
+Found in file cv.h
+
+=item Nullhv
+X<Nullhv>
+
+Null HV pointer.
+
+=for hackers
+Found in file hv.h
+
+=item Nullsv
+X<Nullsv>
+
+Null SV pointer.
+
+=for hackers
+Found in file handy.h
+
+
+=back
+
+=head1 Hash Manipulation Functions
+
+=over 8
+
+=item get_hv
+X<get_hv>
+
+Returns the HV of the specified Perl hash. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ HV* get_hv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item HEf_SVKEY
+X<HEf_SVKEY>
+
+This flag, used in the length slot of hash entries and magic structures,
+specifies the structure contains an C<SV*> pointer where a C<char*> pointer
+is to be expected. (For information only--not to be used).
+
+=for hackers
+Found in file hv.h
+
+=item HeHASH
+X<HeHASH>
+
+Returns the computed hash stored in the hash entry.
+
+ U32 HeHASH(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeKEY
+X<HeKEY>
+
+Returns the actual pointer stored in the key slot of the hash entry. The
+pointer may be either C<char*> or C<SV*>, depending on the value of
+C<HeKLEN()>. Can be assigned to. The C<HePV()> or C<HeSVKEY()> macros are
+usually preferable for finding the value of a key.
+
+ void* HeKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeKLEN
+X<HeKLEN>
+
+If this is negative, and amounts to C<HEf_SVKEY>, it indicates the entry
+holds an C<SV*> key. Otherwise, holds the actual length of the key. Can
+be assigned to. The C<HePV()> macro is usually preferable for finding key
+lengths.
+
+ STRLEN HeKLEN(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HePV
+X<HePV>
+
+Returns the key slot of the hash entry as a C<char*> value, doing any
+necessary dereferencing of possibly C<SV*> keys. The length of the string
+is placed in C<len> (this is a macro, so do I<not> use C<&len>). If you do
+not care about what the length of the key is, you may use the global
+variable C<PL_na>, though this is rather less efficient than using a local
+variable. Remember though, that hash keys in perl are free to contain
+embedded nulls, so using C<strlen()> or similar is not a good way to find
+the length of hash keys. This is very similar to the C<SvPV()> macro
+described elsewhere in this document.
+
+ char* HePV(HE* he, STRLEN len)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY
+X<HeSVKEY>
+
+Returns the key as an C<SV*>, or C<NULL> if the hash entry does not
+contain an C<SV*> key.
+
+ SV* HeSVKEY(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_force
+X<HeSVKEY_force>
+
+Returns the key as an C<SV*>. Will create and return a temporary mortal
+C<SV*> if the hash entry contains only a C<char*> key.
+
+ SV* HeSVKEY_force(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HeSVKEY_set
+X<HeSVKEY_set>
+
+Sets the key to a given C<SV*>, taking care to set the appropriate flags to
+indicate the presence of an C<SV*> key, and returns the same
+C<SV*>.
+
+ SV* HeSVKEY_set(HE* he, SV* sv)
+
+=for hackers
+Found in file hv.h
+
+=item HeVAL
+X<HeVAL>
+
+Returns the value slot (type C<SV*>) stored in the hash entry.
+
+ SV* HeVAL(HE* he)
+
+=for hackers
+Found in file hv.h
+
+=item HvNAME
+X<HvNAME>
+
+Returns the package name of a stash, or NULL if C<stash> isn't a stash.
+See C<SvSTASH>, C<CvSTASH>.
+
+ char* HvNAME(HV* stash)
+
+=for hackers
+Found in file hv.h
+
+=item hv_assert
+X<hv_assert>
+
+Check that a hash is in an internally consistent state.
+
+ void hv_assert(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_clear
+X<hv_clear>
+
+Clears a hash, making it empty.
+
+ void hv_clear(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_clear_placeholders
+X<hv_clear_placeholders>
+
+Clears any placeholders from a hash. If a restricted hash has any of its keys
+marked as readonly and the key is subsequently deleted, the key is not actually
+deleted but is marked by assigning it a value of &PL_sv_placeholder. This tags
+it so it will be ignored by future operations such as iterating over the hash,
+but will still allow the hash to have a value reassigned to the key at some
+future point. This function clears any such placeholder keys from the hash.
+See Hash::Util::lock_keys() for an example of its use.
+
+ void hv_clear_placeholders(HV* hb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete
+X<hv_delete>
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<klen> is the length of the key.
+The C<flags> value will normally be zero; if set to G_DISCARD then NULL
+will be returned.
+
+ SV* hv_delete(HV* tb, const char* key, I32 klen, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_delete_ent
+X<hv_delete_ent>
+
+Deletes a key/value pair in the hash. The value SV is removed from the
+hash and returned to the caller. The C<flags> value will normally be zero;
+if set to G_DISCARD then NULL will be returned. C<hash> can be a valid
+precomputed hash value, or 0 to ask for it to be computed.
+
+ SV* hv_delete_ent(HV* tb, SV* key, I32 flags, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists
+X<hv_exists>
+
+Returns a boolean indicating whether the specified hash key exists. The
+C<klen> is the length of the key.
+
+ bool hv_exists(HV* tb, const char* key, I32 klen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_exists_ent
+X<hv_exists_ent>
+
+Returns a boolean indicating whether the specified hash key exists. C<hash>
+can be a valid precomputed hash value, or 0 to ask for it to be
+computed.
+
+ bool hv_exists_ent(HV* tb, SV* key, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetch
+X<hv_fetch>
+
+Returns the SV which corresponds to the specified key in the hash. The
+C<klen> is the length of the key. If C<lval> is set then the fetch will be
+part of a store. Check that the return value is non-null before
+dereferencing it to an C<SV*>.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_fetch(HV* tb, const char* key, I32 klen, I32 lval)
+
+=for hackers
+Found in file hv.c
+
+=item hv_fetchs
+X<hv_fetchs>
+
+Like C<hv_fetch>, but takes a literal string instead of a string/length pair.
+
+ SV** hv_fetchs(HV* tb, const char* key, I32 lval)
+
+=for hackers
+Found in file handy.h
+
+=item hv_fetch_ent
+X<hv_fetch_ent>
+
+Returns the hash entry which corresponds to the specified key in the hash.
+C<hash> must be a valid precomputed hash number for the given C<key>, or 0
+if you want the function to compute it. IF C<lval> is set then the fetch
+will be part of a store. Make sure the return value is non-null before
+accessing it. The return value when C<tb> is a tied hash is a pointer to a
+static location, so be sure to make a copy of the structure if you need to
+store it somewhere.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_fetch_ent(HV* tb, SV* key, I32 lval, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterinit
+X<hv_iterinit>
+
+Prepares a starting point to traverse a hash table. Returns the number of
+keys in the hash (i.e. the same as C<HvKEYS(tb)>). The return value is
+currently only meaningful for hashes without tie magic.
+
+NOTE: Before version 5.004_65, C<hv_iterinit> used to return the number of
+hash buckets that happen to be in use. If you still need that esoteric
+value, you can get it through the macro C<HvFILL(tb)>.
+
+
+ I32 hv_iterinit(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkey
+X<hv_iterkey>
+
+Returns the key from the current position of the hash iterator. See
+C<hv_iterinit>.
+
+ char* hv_iterkey(HE* entry, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterkeysv
+X<hv_iterkeysv>
+
+Returns the key as an C<SV*> from the current position of the hash
+iterator. The return value will always be a mortal copy of the key. Also
+see C<hv_iterinit>.
+
+ SV* hv_iterkeysv(HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext
+X<hv_iternext>
+
+Returns entries from a hash iterator. See C<hv_iterinit>.
+
+You may call C<hv_delete> or C<hv_delete_ent> on the hash entry that the
+iterator currently points to, without losing your place or invalidating your
+iterator. Note that in this case the current entry is deleted from the hash
+with your iterator holding the last reference to it. Your iterator is flagged
+to free the entry on the next call to C<hv_iternext>, so you must not discard
+your iterator immediately else the entry will leak - call C<hv_iternext> to
+trigger the resource deallocation.
+
+ HE* hv_iternext(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternextsv
+X<hv_iternextsv>
+
+Performs an C<hv_iternext>, C<hv_iterkey>, and C<hv_iterval> in one
+operation.
+
+ SV* hv_iternextsv(HV* hv, char** key, I32* retlen)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iternext_flags
+X<hv_iternext_flags>
+
+Returns entries from a hash iterator. See C<hv_iterinit> and C<hv_iternext>.
+The C<flags> value will normally be zero; if HV_ITERNEXT_WANTPLACEHOLDERS is
+set the placeholders keys (for restricted hashes) will be returned in addition
+to normal keys. By default placeholders are automatically skipped over.
+Currently a placeholder is implemented with a value that is
+C<&Perl_sv_placeholder>. Note that the implementation of placeholders and
+restricted hashes may change, and the implementation currently is
+insufficiently abstracted for any change to be tidy.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ HE* hv_iternext_flags(HV* tb, I32 flags)
+
+=for hackers
+Found in file hv.c
+
+=item hv_iterval
+X<hv_iterval>
+
+Returns the value from the current position of the hash iterator. See
+C<hv_iterkey>.
+
+ SV* hv_iterval(HV* tb, HE* entry)
+
+=for hackers
+Found in file hv.c
+
+=item hv_magic
+X<hv_magic>
+
+Adds magic to a hash. See C<sv_magic>.
+
+ void hv_magic(HV* hv, GV* gv, int how)
+
+=for hackers
+Found in file hv.c
+
+=item hv_scalar
+X<hv_scalar>
+
+Evaluates the hash in scalar context and returns the result. Handles magic when the hash is tied.
+
+ SV* hv_scalar(HV* hv)
+
+=for hackers
+Found in file hv.c
+
+=item hv_store
+X<hv_store>
+
+Stores an SV in a hash. The hash key is specified as C<key> and C<klen> is
+the length of the key. The C<hash> parameter is the precomputed hash
+value; if it is zero then Perl will compute it. The return value will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise it can
+be dereferenced to get the original C<SV*>. Note that the caller is
+responsible for suitably incrementing the reference count of C<val> before
+the call, and decrementing it if the function returned NULL. Effectively
+a successful hv_store takes ownership of one reference to C<val>. This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, hv_store
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up. hv_store is not implemented as a call to
+hv_store_ent, and does not create a temporary SV for the key, so if your
+key data is not already in SV form then use hv_store in preference to
+hv_store_ent.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ SV** hv_store(HV* tb, const char* key, I32 klen, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_stores
+X<hv_stores>
+
+Like C<hv_store>, but takes a literal string instead of a string/length pair
+and omits the hash parameter.
+
+ SV** hv_stores(HV* tb, const char* key, NULLOK SV* val)
+
+=for hackers
+Found in file handy.h
+
+=item hv_store_ent
+X<hv_store_ent>
+
+Stores C<val> in a hash. The hash key is specified as C<key>. The C<hash>
+parameter is the precomputed hash value; if it is zero then Perl will
+compute it. The return value is the new hash entry so created. It will be
+NULL if the operation failed or if the value did not need to be actually
+stored within the hash (as in the case of tied hashes). Otherwise the
+contents of the return value can be accessed using the C<He?> macros
+described here. Note that the caller is responsible for suitably
+incrementing the reference count of C<val> before the call, and
+decrementing it if the function returned NULL. Effectively a successful
+hv_store_ent takes ownership of one reference to C<val>. This is
+usually what you want; a newly created SV has a reference count of one, so
+if all your code does is create SVs then store them in a hash, hv_store
+will own the only reference to the new SV, and your code doesn't need to do
+anything further to tidy up. Note that hv_store_ent only reads the C<key>;
+unlike C<val> it does not take ownership of it, so maintaining the correct
+reference count on C<key> is entirely the caller's responsibility. hv_store
+is not implemented as a call to hv_store_ent, and does not create a temporary
+SV for the key, so if your key data is not already in SV form then use
+hv_store in preference to hv_store_ent.
+
+See L<perlguts/"Understanding the Magic of Tied Hashes and Arrays"> for more
+information on how to use this function on tied hashes.
+
+ HE* hv_store_ent(HV* tb, SV* key, SV* val, U32 hash)
+
+=for hackers
+Found in file hv.c
+
+=item hv_undef
+X<hv_undef>
+
+Undefines the hash.
+
+ void hv_undef(HV* tb)
+
+=for hackers
+Found in file hv.c
+
+=item newHV
+X<newHV>
+
+Creates a new HV. The reference count is set to 1.
+
+ HV* newHV()
+
+=for hackers
+Found in file hv.c
+
+
+=back
+
+=head1 Magical Functions
+
+=over 8
+
+=item mg_clear
+X<mg_clear>
+
+Clear something magical that the SV represents. See C<sv_magic>.
+
+ int mg_clear(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_copy
+X<mg_copy>
+
+Copies the magic from one SV to another. See C<sv_magic>.
+
+ int mg_copy(SV* sv, SV* nsv, const char* key, I32 klen)
+
+=for hackers
+Found in file mg.c
+
+=item mg_find
+X<mg_find>
+
+Finds the magic pointer for type matching the SV. See C<sv_magic>.
+
+ MAGIC* mg_find(const SV* sv, int type)
+
+=for hackers
+Found in file mg.c
+
+=item mg_free
+X<mg_free>
+
+Free any magic storage used by the SV. See C<sv_magic>.
+
+ int mg_free(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_get
+X<mg_get>
+
+Do magic after a value is retrieved from the SV. See C<sv_magic>.
+
+ int mg_get(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_length
+X<mg_length>
+
+Report on the SV's length. See C<sv_magic>.
+
+ U32 mg_length(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_magical
+X<mg_magical>
+
+Turns on the magical status of an SV. See C<sv_magic>.
+
+ void mg_magical(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item mg_set
+X<mg_set>
+
+Do magic after a value is assigned to the SV. See C<sv_magic>.
+
+ int mg_set(SV* sv)
+
+=for hackers
+Found in file mg.c
+
+=item SvGETMAGIC
+X<SvGETMAGIC>
+
+Invokes C<mg_get> on an SV if it has 'get' magic. This macro evaluates its
+argument more than once.
+
+ void SvGETMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvLOCK
+X<SvLOCK>
+
+Arranges for a mutual exclusion lock to be obtained on sv if a suitable module
+has been loaded.
+
+ void SvLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSETMAGIC
+X<SvSETMAGIC>
+
+Invokes C<mg_set> on an SV if it has 'set' magic. This macro evaluates its
+argument more than once.
+
+ void SvSETMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetMagicSV
+X<SvSetMagicSV>
+
+Like C<SvSetSV>, but does any set magic required afterwards.
+
+ void SvSetMagicSV(SV* dsb, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetMagicSV_nosteal
+X<SvSetMagicSV_nosteal>
+
+Like C<SvSetSV_nosteal>, but does any set magic required afterwards.
+
+ void SvSetMagicSV_nosteal(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetSV
+X<SvSetSV>
+
+Calls C<sv_setsv> if dsv is not the same as ssv. May evaluate arguments
+more than once.
+
+ void SvSetSV(SV* dsb, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSetSV_nosteal
+X<SvSetSV_nosteal>
+
+Calls a non-destructive version of C<sv_setsv> if dsv is not the same as
+ssv. May evaluate arguments more than once.
+
+ void SvSetSV_nosteal(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSHARE
+X<SvSHARE>
+
+Arranges for sv to be shared between threads if a suitable module
+has been loaded.
+
+ void SvSHARE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUNLOCK
+X<SvUNLOCK>
+
+Releases a mutual exclusion lock on sv if a suitable module
+has been loaded.
+
+ void SvUNLOCK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+
+=back
+
+=head1 Memory Management
+
+=over 8
+
+=item Copy
+X<Copy>
+
+The XSUB-writer's interface to the C C<memcpy> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. May fail on overlapping copies. See also C<Move>.
+
+ void Copy(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item CopyD
+X<CopyD>
+
+Like C<Copy> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * CopyD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Move
+X<Move>
+
+The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
+source, C<dest> is the destination, C<nitems> is the number of items, and C<type> is
+the type. Can do overlapping moves. See also C<Copy>.
+
+ void Move(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item MoveD
+X<MoveD>
+
+Like C<Move> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * MoveD(void* src, void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Newx
+X<Newx>
+
+The XSUB-writer's interface to the C C<malloc> function.
+
+In 5.9.3, Newx() and friends replace the older New() API, and drops
+the first parameter, I<x>, a debug aid which allowed callers to identify
+themselves. This aid has been superseded by a new build option,
+PERL_MEM_LOG (see L<perlhack/PERL_MEM_LOG>). The older API is still
+there for use in XS modules supporting older perls.
+
+ void Newx(void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Newxc
+X<Newxc>
+
+The XSUB-writer's interface to the C C<malloc> function, with
+cast. See also C<Newx>.
+
+ void Newxc(void* ptr, int nitems, type, cast)
+
+=for hackers
+Found in file handy.h
+
+=item Newxz
+X<Newxz>
+
+The XSUB-writer's interface to the C C<malloc> function. The allocated
+memory is zeroed with C<memzero>. See also C<Newx>.
+
+ void Newxz(void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Poison
+X<Poison>
+
+PoisonWith(0xEF) for catching access to freed memory.
+
+ void Poison(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonFree
+X<PoisonFree>
+
+PoisonWith(0xEF) for catching access to freed memory.
+
+ void PoisonFree(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonNew
+X<PoisonNew>
+
+PoisonWith(0xAB) for catching access to allocated but uninitialized memory.
+
+ void PoisonNew(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item PoisonWith
+X<PoisonWith>
+
+Fill up memory with a byte pattern (a byte repeated over and over
+again) that hopefully catches attempts to access uninitialized memory.
+
+ void PoisonWith(void* dest, int nitems, type, U8 byte)
+
+=for hackers
+Found in file handy.h
+
+=item Renew
+X<Renew>
+
+The XSUB-writer's interface to the C C<realloc> function.
+
+ void Renew(void* ptr, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item Renewc
+X<Renewc>
+
+The XSUB-writer's interface to the C C<realloc> function, with
+cast.
+
+ void Renewc(void* ptr, int nitems, type, cast)
+
+=for hackers
+Found in file handy.h
+
+=item Safefree
+X<Safefree>
+
+The XSUB-writer's interface to the C C<free> function.
+
+ void Safefree(void* ptr)
+
+=for hackers
+Found in file handy.h
+
+=item savepv
+X<savepv>
+
+Perl's version of C<strdup()>. Returns a pointer to a newly allocated
+string which is a duplicate of C<pv>. The size of the string is
+determined by C<strlen()>. The memory allocated for the new string can
+be freed with the C<Safefree()> function.
+
+ char* savepv(const char* pv)
+
+=for hackers
+Found in file util.c
+
+=item savepvn
+X<savepvn>
+
+Perl's version of what C<strndup()> would be if it existed. Returns a
+pointer to a newly allocated string which is a duplicate of the first
+C<len> bytes from C<pv>, plus a trailing NUL byte. The memory allocated for
+the new string can be freed with the C<Safefree()> function.
+
+ char* savepvn(const char* pv, I32 len)
+
+=for hackers
+Found in file util.c
+
+=item savepvs
+X<savepvs>
+
+Like C<savepvn>, but takes a literal string instead of a string/length pair.
+
+ char* savepvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item savesharedpv
+X<savesharedpv>
+
+A version of C<savepv()> which allocates the duplicate string in memory
+which is shared between threads.
+
+ char* savesharedpv(const char* pv)
+
+=for hackers
+Found in file util.c
+
+=item savesharedpvn
+X<savesharedpvn>
+
+A version of C<savepvn()> which allocates the duplicate string in memory
+which is shared between threads. (With the specific difference that a NULL
+pointer is not acceptable)
+
+ char* savesharedpvn(const char *const pv, const STRLEN len)
+
+=for hackers
+Found in file util.c
+
+=item savesvpv
+X<savesvpv>
+
+A version of C<savepv()>/C<savepvn()> which gets the string to duplicate from
+the passed in SV using C<SvPV()>
+
+ char* savesvpv(SV* sv)
+
+=for hackers
+Found in file util.c
+
+=item StructCopy
+X<StructCopy>
+
+This is an architecture-independent macro to copy one structure to another.
+
+ void StructCopy(type src, type dest, type)
+
+=for hackers
+Found in file handy.h
+
+=item Zero
+X<Zero>
+
+The XSUB-writer's interface to the C C<memzero> function. The C<dest> is the
+destination, C<nitems> is the number of items, and C<type> is the type.
+
+ void Zero(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+=item ZeroD
+X<ZeroD>
+
+Like C<Zero> but returns dest. Useful for encouraging compilers to tail-call
+optimise.
+
+ void * ZeroD(void* dest, int nitems, type)
+
+=for hackers
+Found in file handy.h
+
+
+=back
+
+=head1 Miscellaneous Functions
+
+=over 8
+
+=item fbm_compile
+X<fbm_compile>
+
+Analyses the string in order to make fast searches on it using fbm_instr()
+-- the Boyer-Moore algorithm.
+
+ void fbm_compile(SV* sv, U32 flags)
+
+=for hackers
+Found in file util.c
+
+=item fbm_instr
+X<fbm_instr>
+
+Returns the location of the SV in the string delimited by C<str> and
+C<strend>. It returns C<NULL> if the string can't be found. The C<sv>
+does not have to be fbm_compiled, but the search will not be as fast
+then.
+
+ char* fbm_instr(unsigned char* big, unsigned char* bigend, SV* littlesv, U32 flags)
+
+=for hackers
+Found in file util.c
+
+=item form
+X<form>
+
+Takes a sprintf-style format pattern and conventional
+(non-SV) arguments and returns the formatted string.
+
+ (char *) Perl_form(pTHX_ const char* pat, ...)
+
+can be used any place a string (char *) is required:
+
+ char * s = Perl_form("%d.%d",major,minor);
+
+Uses a single private buffer so if you want to format several strings you
+must explicitly copy the earlier strings away (and free the copies when you
+are done).
+
+ char* form(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
+=item getcwd_sv
+X<getcwd_sv>
+
+Fill the sv with current working directory
+
+ int getcwd_sv(SV* sv)
+
+=for hackers
+Found in file util.c
+
+=item my_snprintf
+X<my_snprintf>
+
+The C library C<snprintf> functionality, if available and
+standards-compliant (uses C<vsnprintf>, actually). However, if the
+C<vsnprintf> is not available, will unfortunately use the unsafe
+C<vsprintf> which can overrun the buffer (there is an overrun check,
+but that may be too late). Consider using C<sv_vcatpvf> instead, or
+getting C<vsnprintf>.
+
+ int my_snprintf(char *buffer, const Size_t len, const char *format, ...)
+
+=for hackers
+Found in file util.c
+
+=item my_sprintf
+X<my_sprintf>
+
+The C library C<sprintf>, wrapped if necessary, to ensure that it will return
+the length of the string written to the buffer. Only rare pre-ANSI systems
+need the wrapper function - usually this is a direct call to C<sprintf>.
+
+ int my_sprintf(char *buffer, const char *pat, ...)
+
+=for hackers
+Found in file util.c
+
+=item my_vsnprintf
+X<my_vsnprintf>
+
+The C library C<vsnprintf> if available and standards-compliant.
+However, if if the C<vsnprintf> is not available, will unfortunately
+use the unsafe C<vsprintf> which can overrun the buffer (there is an
+overrun check, but that may be too late). Consider using
+C<sv_vcatpvf> instead, or getting C<vsnprintf>.
+
+ int my_vsnprintf(char *buffer, const Size_t len, const char *format, va_list ap)
+
+=for hackers
+Found in file util.c
+
+=item new_version
+X<new_version>
+
+Returns a new version object based on the passed in SV:
+
+ SV *sv = new_version(SV *ver);
+
+Does not alter the passed in ver SV. See "upg_version" if you
+want to upgrade the SV.
+
+ SV* new_version(SV *ver)
+
+=for hackers
+Found in file util.c
+
+=item scan_version
+X<scan_version>
+
+Returns a pointer to the next character after the parsed
+version string, as well as upgrading the passed in SV to
+an RV.
+
+Function must be called with an already existing SV like
+
+ sv = newSV(0);
+ s = scan_version(s, SV *sv, bool qv);
+
+Performs some preprocessing to the string to ensure that
+it has the correct characteristics of a version. Flags the
+object if it contains an underscore (which denotes this
+is an alpha version). The boolean qv denotes that the version
+should be interpreted as if it had multiple decimals, even if
+it doesn't.
+
+ const char* scan_version(const char *vstr, SV *sv, bool qv)
+
+=for hackers
+Found in file util.c
+
+=item strEQ
+X<strEQ>
+
+Test two strings to see if they are equal. Returns true or false.
+
+ bool strEQ(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strGE
+X<strGE>
+
+Test two strings to see if the first, C<s1>, is greater than or equal to
+the second, C<s2>. Returns true or false.
+
+ bool strGE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strGT
+X<strGT>
+
+Test two strings to see if the first, C<s1>, is greater than the second,
+C<s2>. Returns true or false.
+
+ bool strGT(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strLE
+X<strLE>
+
+Test two strings to see if the first, C<s1>, is less than or equal to the
+second, C<s2>. Returns true or false.
+
+ bool strLE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strLT
+X<strLT>
+
+Test two strings to see if the first, C<s1>, is less than the second,
+C<s2>. Returns true or false.
+
+ bool strLT(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strNE
+X<strNE>
+
+Test two strings to see if they are different. Returns true or
+false.
+
+ bool strNE(char* s1, char* s2)
+
+=for hackers
+Found in file handy.h
+
+=item strnEQ
+X<strnEQ>
+
+Test two strings to see if they are equal. The C<len> parameter indicates
+the number of bytes to compare. Returns true or false. (A wrapper for
+C<strncmp>).
+
+ bool strnEQ(char* s1, char* s2, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
+=item strnNE
+X<strnNE>
+
+Test two strings to see if they are different. The C<len> parameter
+indicates the number of bytes to compare. Returns true or false. (A
+wrapper for C<strncmp>).
+
+ bool strnNE(char* s1, char* s2, STRLEN len)
+
+=for hackers
+Found in file handy.h
+
+=item sv_destroyable
+X<sv_destroyable>
+
+Dummy routine which reports that object can be destroyed when there is no
+sharing module present. It ignores its single SV argument, and returns
+'true'. Exists to avoid test for a NULL function pointer and because it
+could potentially warn under some level of strict-ness.
+
+ bool sv_destroyable(SV *sv)
+
+=for hackers
+Found in file util.c
+
+=item sv_nosharing
+X<sv_nosharing>
+
+Dummy routine which "shares" an SV when there is no sharing module present.
+Or "locks" it. Or "unlocks" it. In other words, ignores its single SV argument.
+Exists to avoid test for a NULL function pointer and because it could
+potentially warn under some level of strict-ness.
+
+ void sv_nosharing(SV *sv)
+
+=for hackers
+Found in file util.c
+
+=item upg_version
+X<upg_version>
+
+In-place upgrade of the supplied SV to a version object.
+
+ SV *sv = upg_version(SV *sv, bool qv);
+
+Returns a pointer to the upgraded SV. Set the boolean qv if you want
+to force this SV to be interpreted as an "extended" version.
+
+ SV* upg_version(SV *ver, bool qv)
+
+=for hackers
+Found in file util.c
+
+=item vcmp
+X<vcmp>
+
+Version object aware cmp. Both operands must already have been
+converted into version objects.
+
+ int vcmp(SV *lvs, SV *rvs)
+
+=for hackers
+Found in file util.c
+
+=item vnormal
+X<vnormal>
+
+Accepts a version object and returns the normalized string
+representation. Call like:
+
+ sv = vnormal(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+ SV* vnormal(SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vnumify
+X<vnumify>
+
+Accepts a version object and returns the normalized floating
+point representation. Call like:
+
+ sv = vnumify(rv);
+
+NOTE: you can pass either the object directly or the SV
+contained within the RV.
+
+ SV* vnumify(SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vstringify
+X<vstringify>
+
+In order to maintain maximum compatibility with earlier versions
+of Perl, this function will return either the floating point
+notation or the multiple dotted notation, depending on whether
+the original version contained 1 or more dots, respectively
+
+ SV* vstringify(SV *vs)
+
+=for hackers
+Found in file util.c
+
+=item vverify
+X<vverify>
+
+Validates that the SV contains a valid version object.
+
+ bool vverify(SV *vobj);
+
+Note that it only confirms the bare minimum structure (so as not to get
+confused by derived classes which may contain additional hash entries):
+
+ bool vverify(SV *vs)
+
+=for hackers
+Found in file util.c
+
+
+=back
+
+=head1 MRO Functions
+
+=over 8
+
+=item mro_get_linear_isa
+X<mro_get_linear_isa>
+
+Returns either C<mro_get_linear_isa_c3> or
+C<mro_get_linear_isa_dfs> for the given stash,
+dependant upon which MRO is in effect
+for that stash. The return value is a
+read-only AV*.
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+ AV* mro_get_linear_isa(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+=item mro_method_changed_in
+X<mro_method_changed_in>
+
+Invalidates method caching on any child classes
+of the given stash, so that they might notice
+the changes in this one.
+
+Ideally, all instances of C<PL_sub_generation++> in
+perl source outside of C<mro.c> should be
+replaced by calls to this.
+
+Perl automatically handles most of the common
+ways a method might be redefined. However, there
+are a few ways you could change a method in a stash
+without the cache code noticing, in which case you
+need to call this method afterwards:
+
+1) Directly manipulating the stash HV entries from
+XS code.
+
+2) Assigning a reference to a readonly scalar
+constant into a stash entry in order to create
+a constant subroutine (like constant.pm
+does).
+
+This same method is available from pure perl
+via, C<mro::method_changed_in(classname)>.
+
+ void mro_method_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
+=head1 Multicall Functions
+
+=over 8
+
+=item dMULTICALL
+X<dMULTICALL>
+
+Declare local variables for a multicall. See L<perlcall/Lightweight Callbacks>.
+
+ dMULTICALL;
+
+=for hackers
+Found in file cop.h
+
+=item MULTICALL
+X<MULTICALL>
+
+Make a lightweight callback. See L<perlcall/Lightweight Callbacks>.
+
+ MULTICALL;
+
+=for hackers
+Found in file cop.h
+
+=item POP_MULTICALL
+X<POP_MULTICALL>
+
+Closing bracket for a lightweight callback.
+See L<perlcall/Lightweight Callbacks>.
+
+ POP_MULTICALL;
+
+=for hackers
+Found in file cop.h
+
+=item PUSH_MULTICALL
+X<PUSH_MULTICALL>
+
+Opening bracket for a lightweight callback.
+See L<perlcall/Lightweight Callbacks>.
+
+ PUSH_MULTICALL;
+
+=for hackers
+Found in file cop.h
+
+
+=back
+
+=head1 Numeric functions
+
+=over 8
+
+=item grok_bin
+X<grok_bin>
+
+converts a string representing a binary number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= C<UV_MAX> it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_bin>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The binary number may optionally be prefixed with "0b" or "b" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the binary
+number may use '_' characters to separate digits.
+
+ UV grok_bin(const char* start, STRLEN* len_p, I32* flags, NV *result)
+
+=for hackers
+Found in file numeric.c
+
+=item grok_hex
+X<grok_hex>
+
+converts a string representing a hex number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_hex>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+The hex number may optionally be prefixed with "0x" or "x" unless
+C<PERL_SCAN_DISALLOW_PREFIX> is set in I<*flags> on entry. If
+C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the hex
+number may use '_' characters to separate digits.
+
+ UV grok_hex(const char* start, STRLEN* len_p, I32* flags, NV *result)
+
+=for hackers
+Found in file numeric.c
+
+=item grok_number
+X<grok_number>
+
+Recognise (or not) a number. The type of the number is returned
+(0 if unrecognised), otherwise it is a bit-ORed combination of
+IS_NUMBER_IN_UV, IS_NUMBER_GREATER_THAN_UV_MAX, IS_NUMBER_NOT_INT,
+IS_NUMBER_NEG, IS_NUMBER_INFINITY, IS_NUMBER_NAN (defined in perl.h).
+
+If the value of the number can fit an in UV, it is returned in the *valuep
+IS_NUMBER_IN_UV will be set to indicate that *valuep is valid, IS_NUMBER_IN_UV
+will never be set unless *valuep is valid, but *valuep may have been assigned
+to during processing even though IS_NUMBER_IN_UV is not set on return.
+If valuep is NULL, IS_NUMBER_IN_UV will be set for the same cases as when
+valuep is non-NULL, but no actual assignment (or SEGV) will occur.
+
+IS_NUMBER_NOT_INT will be set with IS_NUMBER_IN_UV if trailing decimals were
+seen (in which case *valuep gives the true value truncated to an integer), and
+IS_NUMBER_NEG if the number is negative (in which case *valuep holds the
+absolute value). IS_NUMBER_IN_UV is not set if e notation was used or the
+number is larger than a UV.
+
+ int grok_number(const char *pv, STRLEN len, UV *valuep)
+
+=for hackers
+Found in file numeric.c
+
+=item grok_numeric_radix
+X<grok_numeric_radix>
+
+Scan and skip for a numeric decimal separator (radix).
+
+ bool grok_numeric_radix(const char **sp, const char *send)
+
+=for hackers
+Found in file numeric.c
+
+=item grok_oct
+X<grok_oct>
+
+converts a string representing an octal number to numeric form.
+
+On entry I<start> and I<*len> give the string to scan, I<*flags> gives
+conversion flags, and I<result> should be NULL or a pointer to an NV.
+The scan stops at the end of the string, or the first invalid character.
+Unless C<PERL_SCAN_SILENT_ILLDIGIT> is set in I<*flags>, encountering an
+invalid character will also trigger a warning.
+On return I<*len> is set to the length of the scanned string,
+and I<*flags> gives output flags.
+
+If the value is <= UV_MAX it is returned as a UV, the output flags are clear,
+and nothing is written to I<*result>. If the value is > UV_MAX C<grok_oct>
+returns UV_MAX, sets C<PERL_SCAN_GREATER_THAN_UV_MAX> in the output flags,
+and writes the value to I<*result> (or the value is discarded if I<result>
+is NULL).
+
+If C<PERL_SCAN_ALLOW_UNDERSCORES> is set in I<*flags> then the octal
+number may use '_' characters to separate digits.
+
+ UV grok_oct(const char* start, STRLEN* len_p, I32* flags, NV *result)
+
+=for hackers
+Found in file numeric.c
+
+=item Perl_signbit
+X<Perl_signbit>
+
+Return a non-zero integer if the sign bit on an NV is set, and 0 if
+it is not.
+
+If Configure detects this system has a signbit() that will work with
+our NVs, then we just use it via the #define in perl.h. Otherwise,
+fall back on this implementation. As a first pass, this gets everything
+right except -0.0. Alas, catching -0.0 is the main use for this function,
+so this is not too helpful yet. Still, at least we have the scaffolding
+in place to support other systems, should that prove useful.
+
+
+Configure notes: This function is called 'Perl_signbit' instead of a
+plain 'signbit' because it is easy to imagine a system having a signbit()
+function or macro that doesn't happen to work with our particular choice
+of NVs. We shouldn't just re-#define signbit as Perl_signbit and expect
+the standard system headers to be happy. Also, this is a no-context
+function (no pTHX_) because Perl_signbit() is usually re-#defined in
+perl.h as a simple macro call to the system's signbit().
+Users should just always call Perl_signbit().
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ int Perl_signbit(NV f)
+
+=for hackers
+Found in file numeric.c
+
+=item scan_bin
+X<scan_bin>
+
+For backwards compatibility. Use C<grok_bin> instead.
+
+ NV scan_bin(const char* start, STRLEN len, STRLEN* retlen)
+
+=for hackers
+Found in file numeric.c
+
+=item scan_hex
+X<scan_hex>
+
+For backwards compatibility. Use C<grok_hex> instead.
+
+ NV scan_hex(const char* start, STRLEN len, STRLEN* retlen)
+
+=for hackers
+Found in file numeric.c
+
+=item scan_oct
+X<scan_oct>
+
+For backwards compatibility. Use C<grok_oct> instead.
+
+ NV scan_oct(const char* start, STRLEN len, STRLEN* retlen)
+
+=for hackers
+Found in file numeric.c
+
+
+=back
+
+=head1 Optree Manipulation Functions
+
+=over 8
+
+=item cv_const_sv
+X<cv_const_sv>
+
+If C<cv> is a constant sub eligible for inlining. returns the constant
+value returned by the sub. Otherwise, returns NULL.
+
+Constant subs can be created with C<newCONSTSUB> or as described in
+L<perlsub/"Constant Functions">.
+
+ SV* cv_const_sv(CV* cv)
+
+=for hackers
+Found in file op.c
+
+=item newCONSTSUB
+X<newCONSTSUB>
+
+Creates a constant sub equivalent to Perl C<sub FOO () { 123 }> which is
+eligible for inlining at compile-time.
+
+ CV* newCONSTSUB(HV* stash, const char* name, SV* sv)
+
+=for hackers
+Found in file op.c
+
+=item newXS
+X<newXS>
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs. I<filename> needs to be
+static storage, as it is used directly as CvFILE(), without a copy being made.
+
+=for hackers
+Found in file op.c
+
+
+=back
+
+=head1 Pad Data Structures
+
+=over 8
+
+=item pad_sv
+X<pad_sv>
+
+Get the value at offset po in the current pad.
+Use macro PAD_SV instead of calling this function directly.
+
+ SV* pad_sv(PADOFFSET po)
+
+=for hackers
+Found in file pad.c
+
+
+=back
+
+=head1 Per-Interpreter Variables
+
+=over 8
+
+=item PL_modglobal
+X<PL_modglobal>
+
+C<PL_modglobal> is a general purpose, interpreter global HV for use by
+extensions that need to keep information on a per-interpreter basis.
+In a pinch, it can also be used as a symbol table for extensions
+to share data among each other. It is a good idea to use keys
+prefixed by the package name of the extension that owns the data.
+
+ HV* PL_modglobal
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_na
+X<PL_na>
+
+A convenience variable which is typically used with C<SvPV> when one
+doesn't care about the length of the string. It is usually more efficient
+to either declare a local variable and use that instead or to use the
+C<SvPV_nolen> macro.
+
+ STRLEN PL_na
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_no
+X<PL_sv_no>
+
+This is the C<false> SV. See C<PL_sv_yes>. Always refer to this as
+C<&PL_sv_no>.
+
+ SV PL_sv_no
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_undef
+X<PL_sv_undef>
+
+This is the C<undef> SV. Always refer to this as C<&PL_sv_undef>.
+
+ SV PL_sv_undef
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_sv_yes
+X<PL_sv_yes>
+
+This is the C<true> SV. See C<PL_sv_no>. Always refer to this as
+C<&PL_sv_yes>.
+
+ SV PL_sv_yes
+
+=for hackers
+Found in file intrpvar.h
+
+
+=back
+
+=head1 REGEXP Functions
+
+=over 8
+
+=item SvRX
+X<SvRX>
+
+Convenience macro to get the REGEXP from a SV. This is approximately
+equivalent to the following snippet:
+
+ if (SvMAGICAL(sv))
+ mg_get(sv);
+ if (SvROK(sv) &&
+ (tmpsv = (SV*)SvRV(sv)) &&
+ SvTYPE(tmpsv) == SVt_PVMG &&
+ (tmpmg = mg_find(tmpsv, PERL_MAGIC_qr)))
+ {
+ return (REGEXP *)tmpmg->mg_obj;
+ }
+
+NULL will be returned if a REGEXP* is not found.
+
+ REGEXP * SvRX(SV *sv)
+
+=for hackers
+Found in file regexp.h
+
+=item SvRXOK
+X<SvRXOK>
+
+Returns a boolean indicating whether the SV contains qr magic
+(PERL_MAGIC_qr).
+
+If you want to do something with the REGEXP* later use SvRX instead
+and check for NULL.
+
+ bool SvRXOK(SV* sv)
+
+=for hackers
+Found in file regexp.h
+
+
+=back
+
+=head1 Simple Exception Handling Macros
+
+=over 8
+
+=item dXCPT
+X<dXCPT>
+
+Set up necessary local variables for exception handling.
+See L<perlguts/"Exception Handling">.
+
+ dXCPT;
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_CATCH
+X<XCPT_CATCH>
+
+Introduces a catch block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_RETHROW
+X<XCPT_RETHROW>
+
+Rethrows a previously caught exception. See L<perlguts/"Exception Handling">.
+
+ XCPT_RETHROW;
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_TRY_END
+X<XCPT_TRY_END>
+
+Ends a try block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+=item XCPT_TRY_START
+X<XCPT_TRY_START>
+
+Starts a try block. See L<perlguts/"Exception Handling">.
+
+=for hackers
+Found in file XSUB.h
+
+
+=back
+
+=head1 Stack Manipulation Macros
+
+=over 8
+
+=item dMARK
+X<dMARK>
+
+Declare a stack marker variable, C<mark>, for the XSUB. See C<MARK> and
+C<dORIGMARK>.
+
+ dMARK;
+
+=for hackers
+Found in file pp.h
+
+=item dORIGMARK
+X<dORIGMARK>
+
+Saves the original stack mark for the XSUB. See C<ORIGMARK>.
+
+ dORIGMARK;
+
+=for hackers
+Found in file pp.h
+
+=item dSP
+X<dSP>
+
+Declares a local copy of perl's stack pointer for the XSUB, available via
+the C<SP> macro. See C<SP>.
+
+ dSP;
+
+=for hackers
+Found in file pp.h
+
+=item EXTEND
+X<EXTEND>
+
+Used to extend the argument stack for an XSUB's return values. Once
+used, guarantees that there is room for at least C<nitems> to be pushed
+onto the stack.
+
+ void EXTEND(SP, int nitems)
+
+=for hackers
+Found in file pp.h
+
+=item MARK
+X<MARK>
+
+Stack marker variable for the XSUB. See C<dMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHi
+X<mPUSHi>
+
+Push an integer onto the stack. The stack must have room for this element.
+Handles 'set' magic. Does not use C<TARG>. See also C<PUSHi>, C<mXPUSHi>
+and C<XPUSHi>.
+
+ void mPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHn
+X<mPUSHn>
+
+Push a double onto the stack. The stack must have room for this element.
+Handles 'set' magic. Does not use C<TARG>. See also C<PUSHn>, C<mXPUSHn>
+and C<XPUSHn>.
+
+ void mPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHp
+X<mPUSHp>
+
+Push a string onto the stack. The stack must have room for this element.
+The C<len> indicates the length of the string. Handles 'set' magic. Does
+not use C<TARG>. See also C<PUSHp>, C<mXPUSHp> and C<XPUSHp>.
+
+ void mPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item mPUSHu
+X<mPUSHu>
+
+Push an unsigned integer onto the stack. The stack must have room for this
+element. Handles 'set' magic. Does not use C<TARG>. See also C<PUSHu>,
+C<mXPUSHu> and C<XPUSHu>.
+
+ void mPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHi
+X<mXPUSHi>
+
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. Does not use C<TARG>. See also C<XPUSHi>, C<mPUSHi> and
+C<PUSHi>.
+
+ void mXPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHn
+X<mXPUSHn>
+
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. Does not use C<TARG>. See also C<XPUSHn>, C<mPUSHn> and
+C<PUSHn>.
+
+ void mXPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHp
+X<mXPUSHp>
+
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. Does not use
+C<TARG>. See also C<XPUSHp>, C<mPUSHp> and C<PUSHp>.
+
+ void mXPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item mXPUSHu
+X<mXPUSHu>
+
+Push an unsigned integer onto the stack, extending the stack if necessary.
+Handles 'set' magic. Does not use C<TARG>. See also C<XPUSHu>, C<mPUSHu>
+and C<PUSHu>.
+
+ void mXPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item ORIGMARK
+X<ORIGMARK>
+
+The original stack mark for the XSUB. See C<dORIGMARK>.
+
+=for hackers
+Found in file pp.h
+
+=item POPi
+X<POPi>
+
+Pops an integer off the stack.
+
+ IV POPi
+
+=for hackers
+Found in file pp.h
+
+=item POPl
+X<POPl>
+
+Pops a long off the stack.
+
+ long POPl
+
+=for hackers
+Found in file pp.h
+
+=item POPn
+X<POPn>
+
+Pops a double off the stack.
+
+ NV POPn
+
+=for hackers
+Found in file pp.h
+
+=item POPp
+X<POPp>
+
+Pops a string off the stack. Deprecated. New code should use POPpx.
+
+ char* POPp
+
+=for hackers
+Found in file pp.h
+
+=item POPpbytex
+X<POPpbytex>
+
+Pops a string off the stack which must consist of bytes i.e. characters < 256.
+
+ char* POPpbytex
+
+=for hackers
+Found in file pp.h
+
+=item POPpx
+X<POPpx>
+
+Pops a string off the stack.
+
+ char* POPpx
+
+=for hackers
+Found in file pp.h
+
+=item POPs
+X<POPs>
+
+Pops an SV off the stack.
+
+ SV* POPs
+
+=for hackers
+Found in file pp.h
+
+=item PUSHi
+X<PUSHi>
+
+Push an integer onto the stack. The stack must have room for this element.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mPUSHi> instead. See also C<XPUSHi> and
+C<mXPUSHi>.
+
+ void PUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHMARK
+X<PUSHMARK>
+
+Opening bracket for arguments on a callback. See C<PUTBACK> and
+L<perlcall>.
+
+ void PUSHMARK(SP)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHmortal
+X<PUSHmortal>
+
+Push a new mortal SV onto the stack. The stack must have room for this
+element. Does not handle 'set' magic. Does not use C<TARG>. See also
+C<PUSHs>, C<XPUSHmortal> and C<XPUSHs>.
+
+ void PUSHmortal()
+
+=for hackers
+Found in file pp.h
+
+=item PUSHn
+X<PUSHn>
+
+Push a double onto the stack. The stack must have room for this element.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mPUSHn> instead. See also C<XPUSHn> and
+C<mXPUSHn>.
+
+ void PUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHp
+X<PUSHp>
+
+Push a string onto the stack. The stack must have room for this element.
+The C<len> indicates the length of the string. Handles 'set' magic. Uses
+C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to declare it. Do not
+call multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mPUSHp> instead. See also C<XPUSHp> and C<mXPUSHp>.
+
+ void PUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHs
+X<PUSHs>
+
+Push an SV onto the stack. The stack must have room for this element.
+Does not handle 'set' magic. Does not use C<TARG>. See also C<PUSHmortal>,
+C<XPUSHs> and C<XPUSHmortal>.
+
+ void PUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item PUSHu
+X<PUSHu>
+
+Push an unsigned integer onto the stack. The stack must have room for this
+element. Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG>
+should be called to declare it. Do not call multiple C<TARG>-oriented
+macros to return lists from XSUB's - see C<mPUSHu> instead. See also
+C<XPUSHu> and C<mXPUSHu>.
+
+ void PUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item PUTBACK
+X<PUTBACK>
+
+Closing bracket for XSUB arguments. This is usually handled by C<xsubpp>.
+See C<PUSHMARK> and L<perlcall> for other uses.
+
+ PUTBACK;
+
+=for hackers
+Found in file pp.h
+
+=item SP
+X<SP>
+
+Stack pointer. This is usually handled by C<xsubpp>. See C<dSP> and
+C<SPAGAIN>.
+
+=for hackers
+Found in file pp.h
+
+=item SPAGAIN
+X<SPAGAIN>
+
+Refetch the stack pointer. Used after a callback. See L<perlcall>.
+
+ SPAGAIN;
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHi
+X<XPUSHi>
+
+Push an integer onto the stack, extending the stack if necessary. Handles
+'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it. Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHi> instead. See also C<PUSHi> and C<mPUSHi>.
+
+ void XPUSHi(IV iv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHmortal
+X<XPUSHmortal>
+
+Push a new mortal SV onto the stack, extending the stack if necessary. Does
+not handle 'set' magic. Does not use C<TARG>. See also C<XPUSHs>,
+C<PUSHmortal> and C<PUSHs>.
+
+ void XPUSHmortal()
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHn
+X<XPUSHn>
+
+Push a double onto the stack, extending the stack if necessary. Handles
+'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be called to
+declare it. Do not call multiple C<TARG>-oriented macros to return lists
+from XSUB's - see C<mXPUSHn> instead. See also C<PUSHn> and C<mPUSHn>.
+
+ void XPUSHn(NV nv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHp
+X<XPUSHp>
+
+Push a string onto the stack, extending the stack if necessary. The C<len>
+indicates the length of the string. Handles 'set' magic. Uses C<TARG>, so
+C<dTARGET> or C<dXSTARG> should be called to declare it. Do not call
+multiple C<TARG>-oriented macros to return lists from XSUB's - see
+C<mXPUSHp> instead. See also C<PUSHp> and C<mPUSHp>.
+
+ void XPUSHp(char* str, STRLEN len)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHs
+X<XPUSHs>
+
+Push an SV onto the stack, extending the stack if necessary. Does not
+handle 'set' magic. Does not use C<TARG>. See also C<XPUSHmortal>,
+C<PUSHs> and C<PUSHmortal>.
+
+ void XPUSHs(SV* sv)
+
+=for hackers
+Found in file pp.h
+
+=item XPUSHu
+X<XPUSHu>
+
+Push an unsigned integer onto the stack, extending the stack if necessary.
+Handles 'set' magic. Uses C<TARG>, so C<dTARGET> or C<dXSTARG> should be
+called to declare it. Do not call multiple C<TARG>-oriented macros to
+return lists from XSUB's - see C<mXPUSHu> instead. See also C<PUSHu> and
+C<mPUSHu>.
+
+ void XPUSHu(UV uv)
+
+=for hackers
+Found in file pp.h
+
+=item XSRETURN
+X<XSRETURN>
+
+Return from XSUB, indicating number of items on the stack. This is usually
+handled by C<xsubpp>.
+
+ void XSRETURN(int nitems)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_EMPTY
+X<XSRETURN_EMPTY>
+
+Return an empty list from an XSUB immediately.
+
+ XSRETURN_EMPTY;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_IV
+X<XSRETURN_IV>
+
+Return an integer from an XSUB immediately. Uses C<XST_mIV>.
+
+ void XSRETURN_IV(IV iv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NO
+X<XSRETURN_NO>
+
+Return C<&PL_sv_no> from an XSUB immediately. Uses C<XST_mNO>.
+
+ XSRETURN_NO;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_NV
+X<XSRETURN_NV>
+
+Return a double from an XSUB immediately. Uses C<XST_mNV>.
+
+ void XSRETURN_NV(NV nv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_PV
+X<XSRETURN_PV>
+
+Return a copy of a string from an XSUB immediately. Uses C<XST_mPV>.
+
+ void XSRETURN_PV(char* str)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_UNDEF
+X<XSRETURN_UNDEF>
+
+Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
+
+ XSRETURN_UNDEF;
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_UV
+X<XSRETURN_UV>
+
+Return an integer from an XSUB immediately. Uses C<XST_mUV>.
+
+ void XSRETURN_UV(IV uv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XSRETURN_YES
+X<XSRETURN_YES>
+
+Return C<&PL_sv_yes> from an XSUB immediately. Uses C<XST_mYES>.
+
+ XSRETURN_YES;
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mIV
+X<XST_mIV>
+
+Place an integer into the specified position C<pos> on the stack. The
+value is stored in a new mortal SV.
+
+ void XST_mIV(int pos, IV iv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mNO
+X<XST_mNO>
+
+Place C<&PL_sv_no> into the specified position C<pos> on the
+stack.
+
+ void XST_mNO(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mNV
+X<XST_mNV>
+
+Place a double into the specified position C<pos> on the stack. The value
+is stored in a new mortal SV.
+
+ void XST_mNV(int pos, NV nv)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mPV
+X<XST_mPV>
+
+Place a copy of a string into the specified position C<pos> on the stack.
+The value is stored in a new mortal SV.
+
+ void XST_mPV(int pos, char* str)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mUNDEF
+X<XST_mUNDEF>
+
+Place C<&PL_sv_undef> into the specified position C<pos> on the
+stack.
+
+ void XST_mUNDEF(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+=item XST_mYES
+X<XST_mYES>
+
+Place C<&PL_sv_yes> into the specified position C<pos> on the
+stack.
+
+ void XST_mYES(int pos)
+
+=for hackers
+Found in file XSUB.h
+
+
+=back
+
+=head1 SV Flags
+
+=over 8
+
+=item svtype
+X<svtype>
+
+An enum of flags for Perl types. These are found in the file B<sv.h>
+in the C<svtype> enum. Test these flags with the C<SvTYPE> macro.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_IV
+X<SVt_IV>
+
+Integer type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_NV
+X<SVt_NV>
+
+Double type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PV
+X<SVt_PV>
+
+Pointer type flag for scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVAV
+X<SVt_PVAV>
+
+Type flag for arrays. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVCV
+X<SVt_PVCV>
+
+Type flag for code refs. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVHV
+X<SVt_PVHV>
+
+Type flag for hashes. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+=item SVt_PVMG
+X<SVt_PVMG>
+
+Type flag for blessed scalars. See C<svtype>.
+
+=for hackers
+Found in file sv.h
+
+
+=back
+
+=head1 SV Manipulation Functions
+
+=over 8
+
+=item get_sv
+X<get_sv>
+
+Returns the SV of the specified Perl scalar. If C<create> is set and the
+Perl variable does not exist then it will be created. If C<create> is not
+set and the variable does not exist then NULL is returned.
+
+NOTE: the perl_ form of this function is deprecated.
+
+ SV* get_sv(const char* name, I32 create)
+
+=for hackers
+Found in file perl.c
+
+=item newRV_inc
+X<newRV_inc>
+
+Creates an RV wrapper for an SV. The reference count for the original SV is
+incremented.
+
+ SV* newRV_inc(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvCUR
+X<SvCUR>
+
+Returns the length of the string which is in the SV. See C<SvLEN>.
+
+ STRLEN SvCUR(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvCUR_set
+X<SvCUR_set>
+
+Set the current length of the string which is in the SV. See C<SvCUR>
+and C<SvIV_set>.
+
+ void SvCUR_set(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvEND
+X<SvEND>
+
+Returns a pointer to the last character in the string which is in the SV.
+See C<SvCUR>. Access the character as *(SvEND(sv)).
+
+ char* SvEND(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvGAMAGIC
+X<SvGAMAGIC>
+
+Returns true if the SV has get magic or overloading. If either is true then
+the scalar is active data, and has the potential to return a new value every
+time it is accessed. Hence you must be careful to only read it once per user
+logical operation and work with that returned value. If neither is true then
+the scalar's value cannot change unless written to.
+
+ char* SvGAMAGIC(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvGROW
+X<SvGROW>
+
+Expands the character buffer in the SV so that it has room for the
+indicated number of bytes (remember to reserve space for an extra trailing
+NUL character). Calls C<sv_grow> to perform the expansion if necessary.
+Returns a pointer to the character buffer.
+
+ char * SvGROW(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK
+X<SvIOK>
+
+Returns a U32 value indicating whether the SV contains an integer.
+
+ U32 SvIOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOKp
+X<SvIOKp>
+
+Returns a U32 value indicating whether the SV contains an integer. Checks
+the B<private> setting. Use C<SvIOK>.
+
+ U32 SvIOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_notUV
+X<SvIOK_notUV>
+
+Returns a boolean indicating whether the SV contains a signed integer.
+
+ bool SvIOK_notUV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_off
+X<SvIOK_off>
+
+Unsets the IV status of an SV.
+
+ void SvIOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_on
+X<SvIOK_on>
+
+Tells an SV that it is an integer.
+
+ void SvIOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_only
+X<SvIOK_only>
+
+Tells an SV that it is an integer and disables all other OK bits.
+
+ void SvIOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_only_UV
+X<SvIOK_only_UV>
+
+Tells and SV that it is an unsigned integer and disables all other OK bits.
+
+ void SvIOK_only_UV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIOK_UV
+X<SvIOK_UV>
+
+Returns a boolean indicating whether the SV contains an unsigned integer.
+
+ bool SvIOK_UV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIsCOW
+X<SvIsCOW>
+
+Returns a boolean indicating whether the SV is Copy-On-Write. (either shared
+hash key scalars, or full Copy On Write scalars if 5.9.0 is configured for
+COW)
+
+ bool SvIsCOW(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIsCOW_shared_hash
+X<SvIsCOW_shared_hash>
+
+Returns a boolean indicating whether the SV is Copy-On-Write shared hash key
+scalar.
+
+ bool SvIsCOW_shared_hash(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIV
+X<SvIV>
+
+Coerces the given SV to an integer and returns it. See C<SvIVx> for a
+version which guarantees to evaluate sv only once.
+
+ IV SvIV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIVX
+X<SvIVX>
+
+Returns the raw value in the SV's IV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvIV()>.
+
+ IV SvIVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIVx
+X<SvIVx>
+
+Coerces the given SV to an integer and returns it. Guarantees to evaluate
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvIV>.
+
+ IV SvIVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIV_nomg
+X<SvIV_nomg>
+
+Like C<SvIV> but doesn't process magic.
+
+ IV SvIV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvIV_set
+X<SvIV_set>
+
+Set the value of the IV pointer in sv to val. It is possible to perform
+the same function of this macro with an lvalue assignment to C<SvIVX>.
+With future Perls, however, it will be more efficient to use
+C<SvIV_set> instead of the lvalue assignment to C<SvIVX>.
+
+ void SvIV_set(SV* sv, IV val)
+
+=for hackers
+Found in file sv.h
+
+=item SvLEN
+X<SvLEN>
+
+Returns the size of the string buffer in the SV, not including any part
+attributable to C<SvOOK>. See C<SvCUR>.
+
+ STRLEN SvLEN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvLEN_set
+X<SvLEN_set>
+
+Set the actual length of the string which is in the SV. See C<SvIV_set>.
+
+ void SvLEN_set(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvMAGIC_set
+X<SvMAGIC_set>
+
+Set the value of the MAGIC pointer in sv to val. See C<SvIV_set>.
+
+ void SvMAGIC_set(SV* sv, MAGIC* val)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOK
+X<SvNIOK>
+
+Returns a U32 value indicating whether the SV contains a number, integer or
+double.
+
+ U32 SvNIOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOKp
+X<SvNIOKp>
+
+Returns a U32 value indicating whether the SV contains a number, integer or
+double. Checks the B<private> setting. Use C<SvNIOK>.
+
+ U32 SvNIOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNIOK_off
+X<SvNIOK_off>
+
+Unsets the NV/IV status of an SV.
+
+ void SvNIOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK
+X<SvNOK>
+
+Returns a U32 value indicating whether the SV contains a double.
+
+ U32 SvNOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOKp
+X<SvNOKp>
+
+Returns a U32 value indicating whether the SV contains a double. Checks the
+B<private> setting. Use C<SvNOK>.
+
+ U32 SvNOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_off
+X<SvNOK_off>
+
+Unsets the NV status of an SV.
+
+ void SvNOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_on
+X<SvNOK_on>
+
+Tells an SV that it is a double.
+
+ void SvNOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNOK_only
+X<SvNOK_only>
+
+Tells an SV that it is a double and disables all other OK bits.
+
+ void SvNOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNV
+X<SvNV>
+
+Coerce the given SV to a double and return it. See C<SvNVx> for a version
+which guarantees to evaluate sv only once.
+
+ NV SvNV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNVX
+X<SvNVX>
+
+Returns the raw value in the SV's NV slot, without checks or conversions.
+Only use when you are sure SvNOK is true. See also C<SvNV()>.
+
+ NV SvNVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNVx
+X<SvNVx>
+
+Coerces the given SV to a double and returns it. Guarantees to evaluate
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvNV>.
+
+ NV SvNVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvNV_set
+X<SvNV_set>
+
+Set the value of the NV pointer in sv to val. See C<SvIV_set>.
+
+ void SvNV_set(SV* sv, NV val)
+
+=for hackers
+Found in file sv.h
+
+=item SvOK
+X<SvOK>
+
+Returns a U32 value indicating whether the value is an SV. It also tells
+whether the value is defined or not.
+
+ U32 SvOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvOOK
+X<SvOOK>
+
+Returns a U32 indicating whether the SvIVX is a valid offset value for
+the SvPVX. This hack is used internally to speed up removal of characters
+from the beginning of a SvPV. When SvOOK is true, then the start of the
+allocated string buffer is really (SvPVX - SvIVX).
+
+ U32 SvOOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK
+X<SvPOK>
+
+Returns a U32 value indicating whether the SV contains a character
+string.
+
+ U32 SvPOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOKp
+X<SvPOKp>
+
+Returns a U32 value indicating whether the SV contains a character string.
+Checks the B<private> setting. Use C<SvPOK>.
+
+ U32 SvPOKp(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_off
+X<SvPOK_off>
+
+Unsets the PV status of an SV.
+
+ void SvPOK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_on
+X<SvPOK_on>
+
+Tells an SV that it is a string.
+
+ void SvPOK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_only
+X<SvPOK_only>
+
+Tells an SV that it is a string and disables all other OK bits.
+Will also turn off the UTF-8 status.
+
+ void SvPOK_only(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPOK_only_UTF8
+X<SvPOK_only_UTF8>
+
+Tells an SV that it is a string and disables all other OK bits,
+and leaves the UTF-8 status as it was.
+
+ void SvPOK_only_UTF8(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV
+X<SvPV>
+
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified version becoming C<SvPOK>. Handles 'get' magic. See also
+C<SvPVx> for a version which guarantees to evaluate sv only once.
+
+ char* SvPV(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbyte
+X<SvPVbyte>
+
+Like C<SvPV>, but converts sv to byte representation first if necessary.
+
+ char* SvPVbyte(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbytex
+X<SvPVbytex>
+
+Like C<SvPV>, but converts sv to byte representation first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte>
+otherwise.
+
+ char* SvPVbytex(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbytex_force
+X<SvPVbytex_force>
+
+Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVbyte_force>
+otherwise.
+
+ char* SvPVbytex_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbyte_force
+X<SvPVbyte_force>
+
+Like C<SvPV_force>, but converts sv to byte representation first if necessary.
+
+ char* SvPVbyte_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVbyte_nolen
+X<SvPVbyte_nolen>
+
+Like C<SvPV_nolen>, but converts sv to byte representation first if necessary.
+
+ char* SvPVbyte_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8
+X<SvPVutf8>
+
+Like C<SvPV>, but converts sv to utf8 first if necessary.
+
+ char* SvPVutf8(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8x
+X<SvPVutf8x>
+
+Like C<SvPV>, but converts sv to utf8 first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8>
+otherwise.
+
+ char* SvPVutf8x(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8x_force
+X<SvPVutf8x_force>
+
+Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+Guarantees to evaluate sv only once; use the more efficient C<SvPVutf8_force>
+otherwise.
+
+ char* SvPVutf8x_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8_force
+X<SvPVutf8_force>
+
+Like C<SvPV_force>, but converts sv to utf8 first if necessary.
+
+ char* SvPVutf8_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVutf8_nolen
+X<SvPVutf8_nolen>
+
+Like C<SvPV_nolen>, but converts sv to utf8 first if necessary.
+
+ char* SvPVutf8_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVX
+X<SvPVX>
+
+Returns a pointer to the physical string in the SV. The SV must contain a
+string.
+
+ char* SvPVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPVx
+X<SvPVx>
+
+A version of C<SvPV> which guarantees to evaluate C<sv> only once.
+Only use this if C<sv> is an expression with side effects, otherwise use the
+more efficient C<SvPVX>.
+
+ char* SvPVx(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_force
+X<SvPV_force>
+
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly.
+
+ char* SvPV_force(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_force_nomg
+X<SvPV_force_nomg>
+
+Like C<SvPV> but will force the SV into containing just a string
+(C<SvPOK_only>). You want force if you are going to update the C<SvPVX>
+directly. Doesn't process magic.
+
+ char* SvPV_force_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_nolen
+X<SvPV_nolen>
+
+Returns a pointer to the string in the SV, or a stringified form of
+the SV if the SV does not contain a string. The SV may cache the
+stringified form becoming C<SvPOK>. Handles 'get' magic.
+
+ char* SvPV_nolen(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_nomg
+X<SvPV_nomg>
+
+Like C<SvPV> but doesn't process magic.
+
+ char* SvPV_nomg(SV* sv, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item SvPV_set
+X<SvPV_set>
+
+Set the value of the PV pointer in sv to val. See C<SvIV_set>.
+
+ void SvPV_set(SV* sv, char* val)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT
+X<SvREFCNT>
+
+Returns the value of the object's reference count.
+
+ U32 SvREFCNT(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_dec
+X<SvREFCNT_dec>
+
+Decrements the reference count of the given SV.
+
+ void SvREFCNT_dec(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc
+X<SvREFCNT_inc>
+
+Increments the reference count of the given SV.
+
+All of the following SvREFCNT_inc* macros are optimized versions of
+SvREFCNT_inc, and can be replaced with SvREFCNT_inc.
+
+ SV* SvREFCNT_inc(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_NN
+X<SvREFCNT_inc_NN>
+
+Same as SvREFCNT_inc, but can only be used if you know I<sv>
+is not NULL. Since we don't have to check the NULLness, it's faster
+and smaller.
+
+ SV* SvREFCNT_inc_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple
+X<SvREFCNT_inc_simple>
+
+Same as SvREFCNT_inc, but can only be used with expressions without side
+effects. Since we don't have to store a temporary value, it's faster.
+
+ SV* SvREFCNT_inc_simple(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_NN
+X<SvREFCNT_inc_simple_NN>
+
+Same as SvREFCNT_inc_simple, but can only be used if you know I<sv>
+is not NULL. Since we don't have to check the NULLness, it's faster
+and smaller.
+
+ SV* SvREFCNT_inc_simple_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void
+X<SvREFCNT_inc_simple_void>
+
+Same as SvREFCNT_inc_simple, but can only be used if you don't need the
+return value. The macro doesn't need to return a meaningful value.
+
+ void SvREFCNT_inc_simple_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_simple_void_NN
+X<SvREFCNT_inc_simple_void_NN>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the return
+value, and you know that I<sv> is not NULL. The macro doesn't need
+to return a meaningful value, or check for NULLness, so it's smaller
+and faster.
+
+ void SvREFCNT_inc_simple_void_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void
+X<SvREFCNT_inc_void>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the
+return value. The macro doesn't need to return a meaningful value.
+
+ void SvREFCNT_inc_void(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvREFCNT_inc_void_NN
+X<SvREFCNT_inc_void_NN>
+
+Same as SvREFCNT_inc, but can only be used if you don't need the return
+value, and you know that I<sv> is not NULL. The macro doesn't need
+to return a meaningful value, or check for NULLness, so it's smaller
+and faster.
+
+ void SvREFCNT_inc_void_NN(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK
+X<SvROK>
+
+Tests if the SV is an RV.
+
+ U32 SvROK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK_off
+X<SvROK_off>
+
+Unsets the RV status of an SV.
+
+ void SvROK_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvROK_on
+X<SvROK_on>
+
+Tells an SV that it is an RV.
+
+ void SvROK_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvRV
+X<SvRV>
+
+Dereferences an RV to return the SV.
+
+ SV* SvRV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvRV_set
+X<SvRV_set>
+
+Set the value of the RV pointer in sv to val. See C<SvIV_set>.
+
+ void SvRV_set(SV* sv, SV* val)
+
+=for hackers
+Found in file sv.h
+
+=item SvSTASH
+X<SvSTASH>
+
+Returns the stash of the SV.
+
+ HV* SvSTASH(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvSTASH_set
+X<SvSTASH_set>
+
+Set the value of the STASH pointer in sv to val. See C<SvIV_set>.
+
+ void SvSTASH_set(SV* sv, HV* val)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINT
+X<SvTAINT>
+
+Taints an SV if tainting is enabled.
+
+ void SvTAINT(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED
+X<SvTAINTED>
+
+Checks to see if an SV is tainted. Returns TRUE if it is, FALSE if
+not.
+
+ bool SvTAINTED(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_off
+X<SvTAINTED_off>
+
+Untaints an SV. Be I<very> careful with this routine, as it short-circuits
+some of Perl's fundamental security features. XS module authors should not
+use this function unless they fully understand all the implications of
+unconditionally untainting the value. Untainting should be done in the
+standard perl fashion, via a carefully crafted regexp, rather than directly
+untainting variables.
+
+ void SvTAINTED_off(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTAINTED_on
+X<SvTAINTED_on>
+
+Marks an SV as tainted if tainting is enabled.
+
+ void SvTAINTED_on(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTRUE
+X<SvTRUE>
+
+Returns a boolean indicating whether Perl would evaluate the SV as true or
+false, defined or undefined. Does not handle 'get' magic.
+
+ bool SvTRUE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvTYPE
+X<SvTYPE>
+
+Returns the type of the SV. See C<svtype>.
+
+ svtype SvTYPE(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUOK
+X<SvUOK>
+
+Returns a boolean indicating whether the SV contains an unsigned integer.
+
+ bool SvUOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUPGRADE
+X<SvUPGRADE>
+
+Used to upgrade an SV to a more complex form. Uses C<sv_upgrade> to
+perform the upgrade if necessary. See C<svtype>.
+
+ void SvUPGRADE(SV* sv, svtype type)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8
+X<SvUTF8>
+
+Returns a U32 value indicating whether the SV contains UTF-8 encoded data.
+Call this after SvPV() in case any call to string overloading updates the
+internal flag.
+
+ U32 SvUTF8(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8_off
+X<SvUTF8_off>
+
+Unsets the UTF-8 status of an SV.
+
+ void SvUTF8_off(SV *sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUTF8_on
+X<SvUTF8_on>
+
+Turn on the UTF-8 status of an SV (the data is not changed, just the flag).
+Do not use frivolously.
+
+ void SvUTF8_on(SV *sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV
+X<SvUV>
+
+Coerces the given SV to an unsigned integer and returns it. See C<SvUVx>
+for a version which guarantees to evaluate sv only once.
+
+ UV SvUV(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUVX
+X<SvUVX>
+
+Returns the raw value in the SV's UV slot, without checks or conversions.
+Only use when you are sure SvIOK is true. See also C<SvUV()>.
+
+ UV SvUVX(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUVx
+X<SvUVx>
+
+Coerces the given SV to an unsigned integer and returns it. Guarantees to
+C<sv> only once. Only use this if C<sv> is an expression with side effects,
+otherwise use the more efficient C<SvUV>.
+
+ UV SvUVx(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV_nomg
+X<SvUV_nomg>
+
+Like C<SvUV> but doesn't process magic.
+
+ UV SvUV_nomg(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item SvUV_set
+X<SvUV_set>
+
+Set the value of the UV pointer in sv to val. See C<SvIV_set>.
+
+ void SvUV_set(SV* sv, UV val)
+
+=for hackers
+Found in file sv.h
+
+=item SvVOK
+X<SvVOK>
+
+Returns a boolean indicating whether the SV contains a v-string.
+
+ bool SvVOK(SV* sv)
+
+=for hackers
+Found in file sv.h
+
+=item sv_catpvn_nomg
+X<sv_catpvn_nomg>
+
+Like C<sv_catpvn> but doesn't process magic.
+
+ void sv_catpvn_nomg(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.h
+
+=item sv_catsv_nomg
+X<sv_catsv_nomg>
+
+Like C<sv_catsv> but doesn't process magic.
+
+ void sv_catsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+=item sv_derived_from
+X<sv_derived_from>
+
+Returns a boolean indicating whether the SV is derived from the specified class
+I<at the C level>. To check derivation at the Perl level, call C<isa()> as a
+normal Perl method.
+
+ bool sv_derived_from(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
+=item sv_does
+X<sv_does>
+
+Returns a boolean indicating whether the SV performs a specific, named role.
+The SV can be a Perl object or the name of a Perl class.
+
+ bool sv_does(SV* sv, const char* name)
+
+=for hackers
+Found in file universal.c
+
+=item sv_report_used
+X<sv_report_used>
+
+Dump the contents of all SVs not yet freed. (Debugging aid).
+
+ void sv_report_used()
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv_nomg
+X<sv_setsv_nomg>
+
+Like C<sv_setsv> but doesn't process magic.
+
+ void sv_setsv_nomg(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.h
+
+
+=back
+
+=head1 SV-Body Allocation
+
+=over 8
+
+=item looks_like_number
+X<looks_like_number>
+
+Test if the content of an SV looks like a number (or is a number).
+C<Inf> and C<Infinity> are treated as numbers (so will not issue a
+non-numeric warning), even if your atof() doesn't grok them.
+
+ I32 looks_like_number(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item newRV_noinc
+X<newRV_noinc>
+
+Creates an RV wrapper for an SV. The reference count for the original
+SV is B<not> incremented.
+
+ SV* newRV_noinc(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item newSV
+X<newSV>
+
+Creates a new SV. A non-zero C<len> parameter indicates the number of
+bytes of preallocated string space the SV should have. An extra byte for a
+trailing NUL is also reserved. (SvPOK is not set for the SV even if string
+space is allocated.) The reference count for the new SV is set to 1.
+
+In 5.9.3, newSV() replaces the older NEWSV() API, and drops the first
+parameter, I<x>, a debug aid which allowed callers to identify themselves.
+This aid has been superseded by a new build option, PERL_MEM_LOG (see
+L<perlhack/PERL_MEM_LOG>). The older API is still there for use in XS
+modules supporting older perls.
+
+ SV* newSV(STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item newSVhek
+X<newSVhek>
+
+Creates a new SV from the hash key structure. It will generate scalars that
+point to the shared string table where possible. Returns a new (undefined)
+SV if the hek is NULL.
+
+ SV* newSVhek(const HEK *hek)
+
+=for hackers
+Found in file sv.c
+
+=item newSViv
+X<newSViv>
+
+Creates a new SV and copies an integer into it. The reference count for the
+SV is set to 1.
+
+ SV* newSViv(IV i)
+
+=for hackers
+Found in file sv.c
+
+=item newSVnv
+X<newSVnv>
+
+Creates a new SV and copies a floating point value into it.
+The reference count for the SV is set to 1.
+
+ SV* newSVnv(NV n)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpv
+X<newSVpv>
+
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. If C<len> is zero, Perl will compute the length using
+strlen(). For efficiency, consider using C<newSVpvn> instead.
+
+ SV* newSVpv(const char* s, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvf
+X<newSVpvf>
+
+Creates a new SV and initializes it with the string formatted like
+C<sprintf>.
+
+ SV* newSVpvf(const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvn
+X<newSVpvn>
+
+Creates a new SV and copies a string into it. The reference count for the
+SV is set to 1. Note that if C<len> is zero, Perl will create a zero length
+string. You are responsible for ensuring that the source string is at least
+C<len> bytes long. If the C<s> argument is NULL the new SV will be undefined.
+
+ SV* newSVpvn(const char* s, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvn_share
+X<newSVpvn_share>
+
+Creates a new SV with its SvPVX_const pointing to a shared string in the string
+table. If the string does not already exist in the table, it is created
+first. Turns on READONLY and FAKE. If the C<hash> parameter is non-zero, that
+value is used; otherwise the hash is computed. The string's hash can be later
+be retrieved from the SV with the C<SvSHARED_HASH()> macro. The idea here is
+that as the string table is used for shared hash keys these strings will have
+SvPVX_const == HeKEY and hash lookup will avoid string compare.
+
+ SV* newSVpvn_share(const char* s, I32 len, U32 hash)
+
+=for hackers
+Found in file sv.c
+
+=item newSVpvs
+X<newSVpvs>
+
+Like C<newSVpvn>, but takes a literal string instead of a string/length pair.
+
+ SV* newSVpvs(const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item newSVpvs_share
+X<newSVpvs_share>
+
+Like C<newSVpvn_share>, but takes a literal string instead of a string/length
+pair and omits the hash parameter.
+
+ SV* newSVpvs_share(const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item newSVrv
+X<newSVrv>
+
+Creates a new SV for the RV, C<rv>, to point to. If C<rv> is not an RV then
+it will be upgraded to one. If C<classname> is non-null then the new SV will
+be blessed in the specified package. The new SV is returned and its
+reference count is 1.
+
+ SV* newSVrv(SV* rv, const char* classname)
+
+=for hackers
+Found in file sv.c
+
+=item newSVsv
+X<newSVsv>
+
+Creates a new SV which is an exact duplicate of the original SV.
+(Uses C<sv_setsv>).
+
+ SV* newSVsv(SV* old)
+
+=for hackers
+Found in file sv.c
+
+=item newSVuv
+X<newSVuv>
+
+Creates a new SV and copies an unsigned integer into it.
+The reference count for the SV is set to 1.
+
+ SV* newSVuv(UV u)
+
+=for hackers
+Found in file sv.c
+
+=item newSV_type
+X<newSV_type>
+
+Creates a new SV, of the type specified. The reference count for the new SV
+is set to 1.
+
+ SV* newSV_type(svtype type)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2bool
+X<sv_2bool>
+
+This function is only called on magical items, and is only used by
+sv_true() or its macro equivalent.
+
+ bool sv_2bool(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2cv
+X<sv_2cv>
+
+Using various gambits, try to get a CV from an SV; in addition, try if
+possible to set C<*st> and C<*gvp> to the stash and GV associated with it.
+The flags in C<lref> are passed to sv_fetchsv.
+
+ CV* sv_2cv(SV* sv, HV** st, GV** gvp, I32 lref)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2io
+X<sv_2io>
+
+Using various gambits, try to get an IO from an SV: the IO slot if its a
+GV; or the recursive result if we're an RV; or the IO slot of the symbol
+named after the PV if we're a string.
+
+ IO* sv_2io(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2iv_flags
+X<sv_2iv_flags>
+
+Return the integer value of an SV, doing any necessary string
+conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvIV(sv)> and C<SvIVx(sv)> macros.
+
+ IV sv_2iv_flags(SV* sv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2mortal
+X<sv_2mortal>
+
+Marks an existing SV as mortal. The SV will be destroyed "soon", either
+by an explicit call to FREETMPS, or by an implicit call at places such as
+statement boundaries. SvTEMP() is turned on which means that the SV's
+string buffer can be "stolen" if this SV is copied. See also C<sv_newmortal>
+and C<sv_mortalcopy>.
+
+ SV* sv_2mortal(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2nv
+X<sv_2nv>
+
+Return the num value of an SV, doing any necessary string or integer
+conversion, magic etc. Normally used via the C<SvNV(sv)> and C<SvNVx(sv)>
+macros.
+
+ NV sv_2nv(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pvbyte
+X<sv_2pvbyte>
+
+Return a pointer to the byte-encoded representation of the SV, and set *lp
+to its length. May cause the SV to be downgraded from UTF-8 as a
+side-effect.
+
+Usually accessed via the C<SvPVbyte> macro.
+
+ char* sv_2pvbyte(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pvutf8
+X<sv_2pvutf8>
+
+Return a pointer to the UTF-8-encoded representation of the SV, and set *lp
+to its length. May cause the SV to be upgraded to UTF-8 as a side-effect.
+
+Usually accessed via the C<SvPVutf8> macro.
+
+ char* sv_2pvutf8(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2pv_flags
+X<sv_2pv_flags>
+
+Returns a pointer to the string value of an SV, and sets *lp to its length.
+If flags includes SV_GMAGIC, does an mg_get() first. Coerces sv to a string
+if necessary.
+Normally invoked via the C<SvPV_flags> macro. C<sv_2pv()> and C<sv_2pv_nomg>
+usually end up here too.
+
+ char* sv_2pv_flags(SV* sv, STRLEN* lp, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_2uv_flags
+X<sv_2uv_flags>
+
+Return the unsigned integer value of an SV, doing any necessary string
+conversion. If flags includes SV_GMAGIC, does an mg_get() first.
+Normally used via the C<SvUV(sv)> and C<SvUVx(sv)> macros.
+
+ UV sv_2uv_flags(SV* sv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_backoff
+X<sv_backoff>
+
+Remove any string offset. You should normally use the C<SvOOK_off> macro
+wrapper instead.
+
+ int sv_backoff(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_bless
+X<sv_bless>
+
+Blesses an SV into a specified package. The SV must be an RV. The package
+must be designated by its stash (see C<gv_stashpv()>). The reference count
+of the SV is unaffected.
+
+ SV* sv_bless(SV* sv, HV* stash)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpv
+X<sv_catpv>
+
+Concatenates the string onto the end of the string which is in the SV.
+If the SV has the UTF-8 status set, then the bytes appended should be
+valid UTF-8. Handles 'get' magic, but not 'set' magic. See C<sv_catpv_mg>.
+
+ void sv_catpv(SV* sv, const char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvf
+X<sv_catpvf>
+
+Processes its arguments like C<sprintf> and appends the formatted
+output to an SV. If the appended data contains "wide" characters
+(including, but not limited to, SVs with a UTF-8 PV formatted with %s,
+and characters >255 formatted with %c), the original SV might get
+upgraded to UTF-8. Handles 'get' magic, but not 'set' magic. See
+C<sv_catpvf_mg>. If the original SV was UTF-8, the pattern should be
+valid UTF-8; if the original SV was bytes, the pattern should be too.
+
+ void sv_catpvf(SV* sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvf_mg
+X<sv_catpvf_mg>
+
+Like C<sv_catpvf>, but also handles 'set' magic.
+
+ void sv_catpvf_mg(SV *sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvn
+X<sv_catpvn>
+
+Concatenates the string onto the end of the string which is in the SV. The
+C<len> indicates number of bytes to copy. If the SV has the UTF-8
+status set, then the bytes appended should be valid UTF-8.
+Handles 'get' magic, but not 'set' magic. See C<sv_catpvn_mg>.
+
+ void sv_catpvn(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvn_flags
+X<sv_catpvn_flags>
+
+Concatenates the string onto the end of the string which is in the SV. The
+C<len> indicates number of bytes to copy. If the SV has the UTF-8
+status set, then the bytes appended should be valid UTF-8.
+If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<dsv> if
+appropriate, else not. C<sv_catpvn> and C<sv_catpvn_nomg> are implemented
+in terms of this function.
+
+ void sv_catpvn_flags(SV* sv, const char* ptr, STRLEN len, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catpvs
+X<sv_catpvs>
+
+Like C<sv_catpvn>, but takes a literal string instead of a string/length pair.
+
+ void sv_catpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item sv_catpv_mg
+X<sv_catpv_mg>
+
+Like C<sv_catpv>, but also handles 'set' magic.
+
+ void sv_catpv_mg(SV *sv, const char *ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catsv
+X<sv_catsv>
+
+Concatenates the string from SV C<ssv> onto the end of the string in
+SV C<dsv>. Modifies C<dsv> but not C<ssv>. Handles 'get' magic, but
+not 'set' magic. See C<sv_catsv_mg>.
+
+ void sv_catsv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_catsv_flags
+X<sv_catsv_flags>
+
+Concatenates the string from SV C<ssv> onto the end of the string in
+SV C<dsv>. Modifies C<dsv> but not C<ssv>. If C<flags> has C<SV_GMAGIC>
+bit set, will C<mg_get> on the SVs if appropriate, else not. C<sv_catsv>
+and C<sv_catsv_nomg> are implemented in terms of this function.
+
+ void sv_catsv_flags(SV* dsv, SV* ssv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_chop
+X<sv_chop>
+
+Efficient removal of characters from the beginning of the string buffer.
+SvPOK(sv) must be true and the C<ptr> must be a pointer to somewhere inside
+the string buffer. The C<ptr> becomes the first character of the adjusted
+string. Uses the "OOK hack".
+Beware: after this function returns, C<ptr> and SvPVX_const(sv) may no longer
+refer to the same chunk of data.
+
+ void sv_chop(SV* sv, const char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_clear
+X<sv_clear>
+
+Clear an SV: call any destructors, free up any memory used by the body,
+and free the body itself. The SV's head is I<not> freed, although
+its type is set to all 1's so that it won't inadvertently be assumed
+to be live during global destruction etc.
+This function should only be called when REFCNT is zero. Most of the time
+you'll want to call C<sv_free()> (or its macro wrapper C<SvREFCNT_dec>)
+instead.
+
+ void sv_clear(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_cmp
+X<sv_cmp>
+
+Compares the strings in two SVs. Returns -1, 0, or 1 indicating whether the
+string in C<sv1> is less than, equal to, or greater than the string in
+C<sv2>. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+coerce its args to strings if necessary. See also C<sv_cmp_locale>.
+
+ I32 sv_cmp(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_cmp_locale
+X<sv_cmp_locale>
+
+Compares the strings in two SVs in a locale-aware manner. Is UTF-8 and
+'use bytes' aware, handles get magic, and will coerce its args to strings
+if necessary. See also C<sv_cmp_locale>. See also C<sv_cmp>.
+
+ I32 sv_cmp_locale(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_collxfrm
+X<sv_collxfrm>
+
+Add Collate Transform magic to an SV if it doesn't already have it.
+
+Any scalar variable may carry PERL_MAGIC_collxfrm magic that contains the
+scalar data of the variable, but transformed to such a format that a normal
+memory comparison can be used to compare the data according to the locale
+settings.
+
+ char* sv_collxfrm(SV* sv, STRLEN* nxp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_copypv
+X<sv_copypv>
+
+Copies a stringified representation of the source SV into the
+destination SV. Automatically performs any necessary mg_get and
+coercion of numeric values into strings. Guaranteed to preserve
+UTF8 flag even from overloaded objects. Similar in nature to
+sv_2pv[_flags] but operates directly on an SV instead of just the
+string. Mostly uses sv_2pv_flags to do its work, except when that
+would lose the UTF-8'ness of the PV.
+
+ void sv_copypv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_dec
+X<sv_dec>
+
+Auto-decrement of the value in the SV, doing string to numeric conversion
+if necessary. Handles 'get' magic.
+
+ void sv_dec(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_eq
+X<sv_eq>
+
+Returns a boolean indicating whether the strings in the two SVs are
+identical. Is UTF-8 and 'use bytes' aware, handles get magic, and will
+coerce its args to strings if necessary.
+
+ I32 sv_eq(SV* sv1, SV* sv2)
+
+=for hackers
+Found in file sv.c
+
+=item sv_force_normal_flags
+X<sv_force_normal_flags>
+
+Undo various types of fakery on an SV: if the PV is a shared string, make
+a private copy; if we're a ref, stop refing; if we're a glob, downgrade to
+an xpvmg; if we're a copy-on-write scalar, this is the on-write time when
+we do the copy, and is also used locally. If C<SV_COW_DROP_PV> is set
+then a copy-on-write scalar drops its PV buffer (if any) and becomes
+SvPOK_off rather than making a copy. (Used where this scalar is about to be
+set to some other value.) In addition, the C<flags> parameter gets passed to
+C<sv_unref_flags()> when unrefing. C<sv_force_normal> calls this function
+with flags set to 0.
+
+ void sv_force_normal_flags(SV *sv, U32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_free
+X<sv_free>
+
+Decrement an SV's reference count, and if it drops to zero, call
+C<sv_clear> to invoke destructors and free up any memory used by
+the body; finally, deallocate the SV's head itself.
+Normally called via a wrapper macro C<SvREFCNT_dec>.
+
+ void sv_free(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_gets
+X<sv_gets>
+
+Get a line from the filehandle and store it into the SV, optionally
+appending to the currently-stored string.
+
+ char* sv_gets(SV* sv, PerlIO* fp, I32 append)
+
+=for hackers
+Found in file sv.c
+
+=item sv_grow
+X<sv_grow>
+
+Expands the character buffer in the SV. If necessary, uses C<sv_unref> and
+upgrades the SV to C<SVt_PV>. Returns a pointer to the character buffer.
+Use the C<SvGROW> wrapper instead.
+
+ char* sv_grow(SV* sv, STRLEN newlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_inc
+X<sv_inc>
+
+Auto-increment of the value in the SV, doing string to numeric conversion
+if necessary. Handles 'get' magic.
+
+ void sv_inc(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_insert
+X<sv_insert>
+
+Inserts a string at the specified offset/length within the SV. Similar to
+the Perl substr() function.
+
+ void sv_insert(SV* bigsv, STRLEN offset, STRLEN len, const char* little, STRLEN littlelen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_isa
+X<sv_isa>
+
+Returns a boolean indicating whether the SV is blessed into the specified
+class. This does not check for subtypes; use C<sv_derived_from> to verify
+an inheritance relationship.
+
+ int sv_isa(SV* sv, const char* name)
+
+=for hackers
+Found in file sv.c
+
+=item sv_isobject
+X<sv_isobject>
+
+Returns a boolean indicating whether the SV is an RV pointing to a blessed
+object. If the SV is not an RV, or if the object is not blessed, then this
+will return false.
+
+ int sv_isobject(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_len
+X<sv_len>
+
+Returns the length of the string in the SV. Handles magic and type
+coercion. See also C<SvCUR>, which gives raw access to the xpv_cur slot.
+
+ STRLEN sv_len(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_len_utf8
+X<sv_len_utf8>
+
+Returns the number of characters in the string in an SV, counting wide
+UTF-8 bytes as a single character. Handles magic and type coercion.
+
+ STRLEN sv_len_utf8(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_magic
+X<sv_magic>
+
+Adds magic to an SV. First upgrades C<sv> to type C<SVt_PVMG> if necessary,
+then adds a new magic item of type C<how> to the head of the magic list.
+
+See C<sv_magicext> (which C<sv_magic> now calls) for a description of the
+handling of the C<name> and C<namlen> arguments.
+
+You need to use C<sv_magicext> to add magic to SvREADONLY SVs and also
+to add more than one instance of the same 'how'.
+
+ void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_magicext
+X<sv_magicext>
+
+Adds magic to an SV, upgrading it if necessary. Applies the
+supplied vtable and returns a pointer to the magic added.
+
+Note that C<sv_magicext> will allow things that C<sv_magic> will not.
+In particular, you can add magic to SvREADONLY SVs, and add more than
+one instance of the same 'how'.
+
+If C<namlen> is greater than zero then a C<savepvn> I<copy> of C<name> is
+stored, if C<namlen> is zero then C<name> is stored as-is and - as another
+special case - if C<(name && namlen == HEf_SVKEY)> then C<name> is assumed
+to contain an C<SV*> and is stored as-is with its REFCNT incremented.
+
+(This is now used as a subroutine by C<sv_magic>.)
+
+ MAGIC * sv_magicext(SV* sv, SV* obj, int how, const MGVTBL *vtbl, const char* name, I32 namlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_mortalcopy
+X<sv_mortalcopy>
+
+Creates a new SV which is a copy of the original SV (using C<sv_setsv>).
+The new SV is marked as mortal. It will be destroyed "soon", either by an
+explicit call to FREETMPS, or by an implicit call at places such as
+statement boundaries. See also C<sv_newmortal> and C<sv_2mortal>.
+
+ SV* sv_mortalcopy(SV* oldsv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_newmortal
+X<sv_newmortal>
+
+Creates a new null SV which is mortal. The reference count of the SV is
+set to 1. It will be destroyed "soon", either by an explicit call to
+FREETMPS, or by an implicit call at places such as statement boundaries.
+See also C<sv_mortalcopy> and C<sv_2mortal>.
+
+ SV* sv_newmortal()
+
+=for hackers
+Found in file sv.c
+
+=item sv_newref
+X<sv_newref>
+
+Increment an SV's reference count. Use the C<SvREFCNT_inc()> wrapper
+instead.
+
+ SV* sv_newref(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pos_b2u
+X<sv_pos_b2u>
+
+Converts the value pointed to by offsetp from a count of bytes from the
+start of the string, to a count of the equivalent number of UTF-8 chars.
+Handles magic and type coercion.
+
+ void sv_pos_b2u(SV* sv, I32* offsetp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pos_u2b
+X<sv_pos_u2b>
+
+Converts the value pointed to by offsetp from a count of UTF-8 chars from
+the start of the string, to a count of the equivalent number of bytes; if
+lenp is non-zero, it does the same to lenp, but this time starting from
+the offset, rather than from the start of the string. Handles magic and
+type coercion.
+
+ void sv_pos_u2b(SV* sv, I32* offsetp, I32* lenp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvbyten_force
+X<sv_pvbyten_force>
+
+The backend for the C<SvPVbytex_force> macro. Always use the macro instead.
+
+ char* sv_pvbyten_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvn_force
+X<sv_pvn_force>
+
+Get a sensible string out of the SV somehow.
+A private implementation of the C<SvPV_force> macro for compilers which
+can't cope with complex macro expressions. Always use the macro instead.
+
+ char* sv_pvn_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvn_force_flags
+X<sv_pvn_force_flags>
+
+Get a sensible string out of the SV somehow.
+If C<flags> has C<SV_GMAGIC> bit set, will C<mg_get> on C<sv> if
+appropriate, else not. C<sv_pvn_force> and C<sv_pvn_force_nomg> are
+implemented in terms of this function.
+You normally want to use the various wrapper macros instead: see
+C<SvPV_force> and C<SvPV_force_nomg>
+
+ char* sv_pvn_force_flags(SV* sv, STRLEN* lp, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_pvutf8n_force
+X<sv_pvutf8n_force>
+
+The backend for the C<SvPVutf8x_force> macro. Always use the macro instead.
+
+ char* sv_pvutf8n_force(SV* sv, STRLEN* lp)
+
+=for hackers
+Found in file sv.c
+
+=item sv_reftype
+X<sv_reftype>
+
+Returns a string describing what the SV is a reference to.
+
+ const char* sv_reftype(const SV* sv, int ob)
+
+=for hackers
+Found in file sv.c
+
+=item sv_replace
+X<sv_replace>
+
+Make the first argument a copy of the second, then delete the original.
+The target SV physically takes over ownership of the body of the source SV
+and inherits its flags; however, the target keeps any magic it owns,
+and any magic in the source is discarded.
+Note that this is a rather specialist SV copying operation; most of the
+time you'll want to use C<sv_setsv> or one of its many macro front-ends.
+
+ void sv_replace(SV* sv, SV* nsv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_reset
+X<sv_reset>
+
+Underlying implementation for the C<reset> Perl function.
+Note that the perl-level function is vaguely deprecated.
+
+ void sv_reset(const char* s, HV* stash)
+
+=for hackers
+Found in file sv.c
+
+=item sv_rvweaken
+X<sv_rvweaken>
+
+Weaken a reference: set the C<SvWEAKREF> flag on this RV; give the
+referred-to SV C<PERL_MAGIC_backref> magic if it hasn't already; and
+push a back-reference to this RV onto the array of backreferences
+associated with that magic. If the RV is magical, set magic will be
+called after the RV is cleared.
+
+ SV* sv_rvweaken(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setiv
+X<sv_setiv>
+
+Copies an integer into the given SV, upgrading first if necessary.
+Does not handle 'set' magic. See also C<sv_setiv_mg>.
+
+ void sv_setiv(SV* sv, IV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setiv_mg
+X<sv_setiv_mg>
+
+Like C<sv_setiv>, but also handles 'set' magic.
+
+ void sv_setiv_mg(SV *sv, IV i)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setnv
+X<sv_setnv>
+
+Copies a double into the given SV, upgrading first if necessary.
+Does not handle 'set' magic. See also C<sv_setnv_mg>.
+
+ void sv_setnv(SV* sv, NV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setnv_mg
+X<sv_setnv_mg>
+
+Like C<sv_setnv>, but also handles 'set' magic.
+
+ void sv_setnv_mg(SV *sv, NV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpv
+X<sv_setpv>
+
+Copies a string into an SV. The string must be null-terminated. Does not
+handle 'set' magic. See C<sv_setpv_mg>.
+
+ void sv_setpv(SV* sv, const char* ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvf
+X<sv_setpvf>
+
+Works like C<sv_catpvf> but copies the text into the SV instead of
+appending it. Does not handle 'set' magic. See C<sv_setpvf_mg>.
+
+ void sv_setpvf(SV* sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvf_mg
+X<sv_setpvf_mg>
+
+Like C<sv_setpvf>, but also handles 'set' magic.
+
+ void sv_setpvf_mg(SV *sv, const char* pat, ...)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpviv
+X<sv_setpviv>
+
+Copies an integer into the given SV, also updating its string value.
+Does not handle 'set' magic. See C<sv_setpviv_mg>.
+
+ void sv_setpviv(SV* sv, IV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpviv_mg
+X<sv_setpviv_mg>
+
+Like C<sv_setpviv>, but also handles 'set' magic.
+
+ void sv_setpviv_mg(SV *sv, IV iv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvn
+X<sv_setpvn>
+
+Copies a string into an SV. The C<len> parameter indicates the number of
+bytes to be copied. If the C<ptr> argument is NULL the SV will become
+undefined. Does not handle 'set' magic. See C<sv_setpvn_mg>.
+
+ void sv_setpvn(SV* sv, const char* ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvn_mg
+X<sv_setpvn_mg>
+
+Like C<sv_setpvn>, but also handles 'set' magic.
+
+ void sv_setpvn_mg(SV *sv, const char *ptr, STRLEN len)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setpvs
+X<sv_setpvs>
+
+Like C<sv_setpvn>, but takes a literal string instead of a string/length pair.
+
+ void sv_setpvs(SV* sv, const char* s)
+
+=for hackers
+Found in file handy.h
+
+=item sv_setpv_mg
+X<sv_setpv_mg>
+
+Like C<sv_setpv>, but also handles 'set' magic.
+
+ void sv_setpv_mg(SV *sv, const char *ptr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_iv
+X<sv_setref_iv>
+
+Copies an integer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
+will have a reference count of 1, and the RV will be returned.
+
+ SV* sv_setref_iv(SV* rv, const char* classname, IV iv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_nv
+X<sv_setref_nv>
+
+Copies a double into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
+will have a reference count of 1, and the RV will be returned.
+
+ SV* sv_setref_nv(SV* rv, const char* classname, NV nv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_pv
+X<sv_setref_pv>
+
+Copies a pointer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. If the C<pv> argument is NULL then C<PL_sv_undef> will be placed
+into the SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
+will have a reference count of 1, and the RV will be returned.
+
+Do not use with other Perl types such as HV, AV, SV, CV, because those
+objects will become corrupted by the pointer copy process.
+
+Note that C<sv_setref_pvn> copies the string while this copies the pointer.
+
+ SV* sv_setref_pv(SV* rv, const char* classname, void* pv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_pvn
+X<sv_setref_pvn>
+
+Copies a string into a new SV, optionally blessing the SV. The length of the
+string must be specified with C<n>. The C<rv> argument will be upgraded to
+an RV. That RV will be modified to point to the new SV. The C<classname>
+argument indicates the package for the blessing. Set C<classname> to
+C<NULL> to avoid the blessing. The new SV will have a reference count
+of 1, and the RV will be returned.
+
+Note that C<sv_setref_pv> copies the pointer while this copies the string.
+
+ SV* sv_setref_pvn(SV* rv, const char* classname, const char* pv, STRLEN n)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setref_uv
+X<sv_setref_uv>
+
+Copies an unsigned integer into a new SV, optionally blessing the SV. The C<rv>
+argument will be upgraded to an RV. That RV will be modified to point to
+the new SV. The C<classname> argument indicates the package for the
+blessing. Set C<classname> to C<NULL> to avoid the blessing. The new SV
+will have a reference count of 1, and the RV will be returned.
+
+ SV* sv_setref_uv(SV* rv, const char* classname, UV uv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv
+X<sv_setsv>
+
+Copies the contents of the source SV C<ssv> into the destination SV
+C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
+function if the source SV needs to be reused. Does not handle 'set' magic.
+Loosely speaking, it performs a copy-by-value, obliterating any previous
+content of the destination.
+
+You probably want to use one of the assortment of wrappers, such as
+C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
+C<SvSetMagicSV_nosteal>.
+
+ void sv_setsv(SV* dsv, SV* ssv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv_flags
+X<sv_setsv_flags>
+
+Copies the contents of the source SV C<ssv> into the destination SV
+C<dsv>. The source SV may be destroyed if it is mortal, so don't use this
+function if the source SV needs to be reused. Does not handle 'set' magic.
+Loosely speaking, it performs a copy-by-value, obliterating any previous
+content of the destination.
+If the C<flags> parameter has the C<SV_GMAGIC> bit set, will C<mg_get> on
+C<ssv> if appropriate, else not. If the C<flags> parameter has the
+C<NOSTEAL> bit set then the buffers of temps will not be stolen. <sv_setsv>
+and C<sv_setsv_nomg> are implemented in terms of this function.
+
+You probably want to use one of the assortment of wrappers, such as
+C<SvSetSV>, C<SvSetSV_nosteal>, C<SvSetMagicSV> and
+C<SvSetMagicSV_nosteal>.
+
+This is the primary function for copying scalars, and most other
+copy-ish functions and macros use this underneath.
+
+ void sv_setsv_flags(SV* dsv, SV* ssv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setsv_mg
+X<sv_setsv_mg>
+
+Like C<sv_setsv>, but also handles 'set' magic.
+
+ void sv_setsv_mg(SV *dstr, SV *sstr)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setuv
+X<sv_setuv>
+
+Copies an unsigned integer into the given SV, upgrading first if necessary.
+Does not handle 'set' magic. See also C<sv_setuv_mg>.
+
+ void sv_setuv(SV* sv, UV num)
+
+=for hackers
+Found in file sv.c
+
+=item sv_setuv_mg
+X<sv_setuv_mg>
+
+Like C<sv_setuv>, but also handles 'set' magic.
+
+ void sv_setuv_mg(SV *sv, UV u)
+
+=for hackers
+Found in file sv.c
+
+=item sv_tainted
+X<sv_tainted>
+
+Test an SV for taintedness. Use C<SvTAINTED> instead.
+ bool sv_tainted(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_true
+X<sv_true>
+
+Returns true if the SV has a true value by Perl's rules.
+Use the C<SvTRUE> macro instead, which may call C<sv_true()> or may
+instead use an in-line version.
+
+ I32 sv_true(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_unmagic
+X<sv_unmagic>
+
+Removes all magic of type C<type> from an SV.
+
+ int sv_unmagic(SV* sv, int type)
+
+=for hackers
+Found in file sv.c
+
+=item sv_unref_flags
+X<sv_unref_flags>
+
+Unsets the RV status of the SV, and decrements the reference count of
+whatever was being referenced by the RV. This can almost be thought of
+as a reversal of C<newSVrv>. The C<cflags> argument can contain
+C<SV_IMMEDIATE_UNREF> to force the reference count to be decremented
+(otherwise the decrementing is conditional on the reference count being
+different from one or the reference being a readonly SV).
+See C<SvROK_off>.
+
+ void sv_unref_flags(SV* sv, U32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_untaint
+X<sv_untaint>
+
+Untaint an SV. Use C<SvTAINTED_off> instead.
+ void sv_untaint(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_upgrade
+X<sv_upgrade>
+
+Upgrade an SV to a more complex form. Generally adds a new body type to the
+SV, then copies across as much information as possible from the old body.
+You generally want to use the C<SvUPGRADE> macro wrapper. See also C<svtype>.
+
+ void sv_upgrade(SV* sv, svtype new_type)
+
+=for hackers
+Found in file sv.c
+
+=item sv_usepvn_flags
+X<sv_usepvn_flags>
+
+Tells an SV to use C<ptr> to find its string value. Normally the
+string is stored inside the SV but sv_usepvn allows the SV to use an
+outside string. The C<ptr> should point to memory that was allocated
+by C<malloc>. The string length, C<len>, must be supplied. By default
+this function will realloc (i.e. move) the memory pointed to by C<ptr>,
+so that pointer should not be freed or used by the programmer after
+giving it to sv_usepvn, and neither should any pointers from "behind"
+that pointer (e.g. ptr + 1) be used.
+
+If C<flags> & SV_SMAGIC is true, will call SvSETMAGIC. If C<flags> &
+SV_HAS_TRAILING_NUL is true, then C<ptr[len]> must be NUL, and the realloc
+will be skipped. (i.e. the buffer is actually at least 1 byte longer than
+C<len>, and already meets the requirements for storing in C<SvPVX>)
+
+ void sv_usepvn_flags(SV* sv, char* ptr, STRLEN len, U32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_decode
+X<sv_utf8_decode>
+
+If the PV of the SV is an octet sequence in UTF-8
+and contains a multiple-byte character, the C<SvUTF8> flag is turned on
+so that it looks like a character. If the PV contains only single-byte
+characters, the C<SvUTF8> flag stays being off.
+Scans PV for validity and returns false if the PV is invalid UTF-8.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ bool sv_utf8_decode(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_downgrade
+X<sv_utf8_downgrade>
+
+Attempts to convert the PV of an SV from characters to bytes.
+If the PV contains a character beyond byte, this conversion will fail;
+in this case, either returns false or, if C<fail_ok> is not
+true, croaks.
+
+This is not as a general purpose Unicode to byte encoding interface:
+use the Encode extension for that.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ bool sv_utf8_downgrade(SV *sv, bool fail_ok)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_encode
+X<sv_utf8_encode>
+
+Converts the PV of an SV to UTF-8, but then turns the C<SvUTF8>
+flag off so that it looks like octets again.
+
+ void sv_utf8_encode(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade
+X<sv_utf8_upgrade>
+
+Converts the PV of an SV to its UTF-8-encoded form.
+Forces the SV to string form if it is not already.
+Always sets the SvUTF8 flag to avoid future validity checks even
+if all the bytes have hibit clear.
+
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
+ STRLEN sv_utf8_upgrade(SV *sv)
+
+=for hackers
+Found in file sv.c
+
+=item sv_utf8_upgrade_flags
+X<sv_utf8_upgrade_flags>
+
+Converts the PV of an SV to its UTF-8-encoded form.
+Forces the SV to string form if it is not already.
+Always sets the SvUTF8 flag to avoid future validity checks even
+if all the bytes have hibit clear. If C<flags> has C<SV_GMAGIC> bit set,
+will C<mg_get> on C<sv> if appropriate, else not. C<sv_utf8_upgrade> and
+C<sv_utf8_upgrade_nomg> are implemented in terms of this function.
+
+This is not as a general purpose byte encoding to Unicode interface:
+use the Encode extension for that.
+
+ STRLEN sv_utf8_upgrade_flags(SV *sv, I32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vcatpvf
+X<sv_vcatpvf>
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV. Does not handle 'set' magic. See C<sv_vcatpvf_mg>.
+
+Usually used via its frontend C<sv_catpvf>.
+
+ void sv_vcatpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vcatpvfn
+X<sv_vcatpvfn>
+
+Processes its arguments like C<vsprintf> and appends the formatted output
+to an SV. Uses an array of SVs if the C style variable argument list is
+missing (NULL). When running with taint checks enabled, indicates via
+C<maybe_tainted> if results are untrustworthy (often due to the use of
+locales).
+
+Usually used via one of its frontends C<sv_vcatpvf> and C<sv_vcatpvf_mg>.
+
+ void sv_vcatpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vcatpvf_mg
+X<sv_vcatpvf_mg>
+
+Like C<sv_vcatpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_catpvf_mg>.
+
+ void sv_vcatpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvf
+X<sv_vsetpvf>
+
+Works like C<sv_vcatpvf> but copies the text into the SV instead of
+appending it. Does not handle 'set' magic. See C<sv_vsetpvf_mg>.
+
+Usually used via its frontend C<sv_setpvf>.
+
+ void sv_vsetpvf(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvfn
+X<sv_vsetpvfn>
+
+Works like C<sv_vcatpvfn> but copies the text into the SV instead of
+appending it.
+
+Usually used via one of its frontends C<sv_vsetpvf> and C<sv_vsetpvf_mg>.
+
+ void sv_vsetpvfn(SV* sv, const char* pat, STRLEN patlen, va_list* args, SV** svargs, I32 svmax, bool *maybe_tainted)
+
+=for hackers
+Found in file sv.c
+
+=item sv_vsetpvf_mg
+X<sv_vsetpvf_mg>
+
+Like C<sv_vsetpvf>, but also handles 'set' magic.
+
+Usually used via its frontend C<sv_setpvf_mg>.
+
+ void sv_vsetpvf_mg(SV* sv, const char* pat, va_list* args)
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 Unicode Support
+
+=over 8
+
+=item bytes_from_utf8
+X<bytes_from_utf8>
+
+Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
+Unlike C<utf8_to_bytes> but like C<bytes_to_utf8>, returns a pointer to
+the newly-created string, and updates C<len> to contain the new
+length. Returns the original string if no conversion occurs, C<len>
+is unchanged. Do nothing if C<is_utf8> points to 0. Sets C<is_utf8> to
+0 if C<s> is converted or contains all 7bit characters.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_from_utf8(const U8 *s, STRLEN *len, bool *is_utf8)
+
+=for hackers
+Found in file utf8.c
+
+=item bytes_to_utf8
+X<bytes_to_utf8>
+
+Converts a string C<s> of length C<len> from ASCII into UTF-8 encoding.
+Returns a pointer to the newly-created string, and sets C<len> to
+reflect the new length.
+
+If you want to convert to UTF-8 from other encodings than ASCII,
+see sv_recode_to_utf8().
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* bytes_to_utf8(const U8 *s, STRLEN *len)
+
+=for hackers
+Found in file utf8.c
+
+=item ibcmp_utf8
+X<ibcmp_utf8>
+
+Return true if the strings s1 and s2 differ case-insensitively, false
+if not (if they are equal case-insensitively). If u1 is true, the
+string s1 is assumed to be in UTF-8-encoded Unicode. If u2 is true,
+the string s2 is assumed to be in UTF-8-encoded Unicode. If u1 or u2
+are false, the respective string is assumed to be in native 8-bit
+encoding.
+
+If the pe1 and pe2 are non-NULL, the scanning pointers will be copied
+in there (they will point at the beginning of the I<next> character).
+If the pointers behind pe1 or pe2 are non-NULL, they are the end
+pointers beyond which scanning will not continue under any
+circumstances. If the byte lengths l1 and l2 are non-zero, s1+l1 and
+s2+l2 will be used as goal end pointers that will also stop the scan,
+and which qualify towards defining a successful match: all the scans
+that define an explicit length must reach their goal pointers for
+a match to succeed).
+
+For case-insensitiveness, the "casefolding" of Unicode is used
+instead of upper/lowercasing both the characters, see
+http://www.unicode.org/unicode/reports/tr21/ (Case Mappings).
+
+ I32 ibcmp_utf8(const char* a, char **pe1, UV l1, bool u1, const char* b, char **pe2, UV l2, bool u2)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_char
+X<is_utf8_char>
+
+Tests if some arbitrary number of bytes begins in a valid UTF-8
+character. Note that an INVARIANT (i.e. ASCII) character is a valid
+UTF-8 character. The actual number of bytes in the UTF-8 character
+will be returned if it is valid, otherwise 0.
+
+ STRLEN is_utf8_char(const U8 *p)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string
+X<is_utf8_string>
+
+Returns true if first C<len> bytes of the given string form a valid
+UTF-8 string, false otherwise. Note that 'a valid UTF-8 string' does
+not mean 'a string that contains code points above 0x7F encoded in UTF-8'
+because a valid ASCII string is a valid UTF-8 string.
+
+See also is_utf8_string_loclen() and is_utf8_string_loc().
+
+ bool is_utf8_string(const U8 *s, STRLEN len)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string_loc
+X<is_utf8_string_loc>
+
+Like is_utf8_string() but stores the location of the failure (in the
+case of "utf8ness failure") or the location s+len (in the case of
+"utf8ness success") in the C<ep>.
+
+See also is_utf8_string_loclen() and is_utf8_string().
+
+ bool is_utf8_string_loc(const U8 *s, STRLEN len, const U8 **p)
+
+=for hackers
+Found in file utf8.c
+
+=item is_utf8_string_loclen
+X<is_utf8_string_loclen>
+
+Like is_utf8_string() but stores the location of the failure (in the
+case of "utf8ness failure") or the location s+len (in the case of
+"utf8ness success") in the C<ep>, and the number of UTF-8
+encoded characters in the C<el>.
+
+See also is_utf8_string_loc() and is_utf8_string().
+
+ bool is_utf8_string_loclen(const U8 *s, STRLEN len, const U8 **ep, STRLEN *el)
+
+=for hackers
+Found in file utf8.c
+
+=item pv_uni_display
+X<pv_uni_display>
+
+Build to the scalar dsv a displayable version of the string spv,
+length len, the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument can have UNI_DISPLAY_ISPRINT set to display
+isPRINT()able characters as themselves, UNI_DISPLAY_BACKSLASH
+to display the \\[nrfta\\] as the backslashed versions (like '\n')
+(UNI_DISPLAY_BACKSLASH is preferred over UNI_DISPLAY_ISPRINT for \\).
+UNI_DISPLAY_QQ (and its alias UNI_DISPLAY_REGEX) have both
+UNI_DISPLAY_BACKSLASH and UNI_DISPLAY_ISPRINT turned on.
+
+The pointer to the PV of the dsv is returned.
+
+ char* pv_uni_display(SV *dsv, const U8 *spv, STRLEN len, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item sv_cat_decode
+X<sv_cat_decode>
+
+The encoding is assumed to be an Encode object, the PV of the ssv is
+assumed to be octets in that encoding and decoding the input starts
+from the position which (PV + *offset) pointed to. The dsv will be
+concatenated the decoded UTF-8 string from ssv. Decoding will terminate
+when the string tstr appears in decoding output or the input ends on
+the PV of the ssv. The value which the offset points will be modified
+to the last input position on the ssv.
+
+Returns TRUE if the terminator was found, else returns FALSE.
+
+ bool sv_cat_decode(SV* dsv, SV *encoding, SV *ssv, int *offset, char* tstr, int tlen)
+
+=for hackers
+Found in file sv.c
+
+=item sv_recode_to_utf8
+X<sv_recode_to_utf8>
+
+The encoding is assumed to be an Encode object, on entry the PV
+of the sv is assumed to be octets in that encoding, and the sv
+will be converted into Unicode (and UTF-8).
+
+If the sv already is UTF-8 (or if it is not POK), or if the encoding
+is not a reference, nothing is done to the sv. If the encoding is not
+an C<Encode::XS> Encoding object, bad things will happen.
+(See F<lib/encoding.pm> and L<Encode>).
+
+The PV of the sv is returned.
+
+ char* sv_recode_to_utf8(SV* sv, SV *encoding)
+
+=for hackers
+Found in file sv.c
+
+=item sv_uni_display
+X<sv_uni_display>
+
+Build to the scalar dsv a displayable version of the scalar sv,
+the displayable version being at most pvlim bytes long
+(if longer, the rest is truncated and "..." will be appended).
+
+The flags argument is as in pv_uni_display().
+
+The pointer to the PV of the dsv is returned.
+
+ char* sv_uni_display(SV *dsv, SV *ssv, STRLEN pvlim, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_case
+X<to_utf8_case>
+
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
+
+The "ustrp" is a pointer to the character buffer to put the
+conversion result to. The "lenp" is a pointer to the length
+of the result.
+
+The "swashp" is a pointer to the swash to use.
+
+Both the special and normal mappings are stored lib/unicore/To/Foo.pl,
+and loaded by SWASHNEW, using lib/utf8_heavy.pl. The special (usually,
+but not always, a multicharacter mapping), is tried first.
+
+The "special" is a string like "utf8::ToSpecLower", which means the
+hash %utf8::ToSpecLower. The access to the hash is through
+Perl_to_utf8_case().
+
+The "normal" is a string like "ToLower" which means the swash
+%utf8::ToLower.
+
+ UV to_utf8_case(const U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp, const char *normal, const char *special)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_fold
+X<to_utf8_fold>
+
+Convert the UTF-8 encoded character at p to its foldcase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
+foldcase version may be longer than the original character (up to
+three characters).
+
+The first character of the foldcased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_fold(const U8 *p, U8* ustrp, STRLEN *lenp)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_lower
+X<to_utf8_lower>
+
+Convert the UTF-8 encoded character at p to its lowercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
+lowercase version may be longer than the original character.
+
+The first character of the lowercased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_lower(const U8 *p, U8* ustrp, STRLEN *lenp)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_title
+X<to_utf8_title>
+
+Convert the UTF-8 encoded character at p to its titlecase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since the
+titlecase version may be longer than the original character.
+
+The first character of the titlecased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_title(const U8 *p, U8* ustrp, STRLEN *lenp)
+
+=for hackers
+Found in file utf8.c
+
+=item to_utf8_upper
+X<to_utf8_upper>
+
+Convert the UTF-8 encoded character at p to its uppercase version and
+store that in UTF-8 in ustrp and its length in bytes in lenp. Note
+that the ustrp needs to be at least UTF8_MAXBYTES_CASE+1 bytes since
+the uppercase version may be longer than the original character.
+
+The first character of the uppercased version is returned
+(but note, as explained above, that there may be more.)
+
+ UV to_utf8_upper(const U8 *p, U8* ustrp, STRLEN *lenp)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8n_to_uvchr
+X<utf8n_to_uvchr>
+
+flags
+
+Returns the native character value of the first character in the string
+C<s>
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
+length, in bytes, of that character.
+
+Allows length and flags to be passed to low level routine.
+
+ UV utf8n_to_uvchr(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8n_to_uvuni
+X<utf8n_to_uvuni>
+
+Bottom level UTF-8 decode routine.
+Returns the Unicode code point value of the first character in the string C<s>
+which is assumed to be in UTF-8 encoding and no longer than C<curlen>;
+C<retlen> will be set to the length, in bytes, of that character.
+
+If C<s> does not point to a well-formed UTF-8 character, the behaviour
+is dependent on the value of C<flags>: if it contains UTF8_CHECK_ONLY,
+it is assumed that the caller will raise a warning, and this function
+will silently just set C<retlen> to C<-1> and return zero. If the
+C<flags> does not contain UTF8_CHECK_ONLY, warnings about
+malformations will be given, C<retlen> will be set to the expected
+length of the UTF-8 character in bytes, and zero will be returned.
+
+The C<flags> can also contain various flags to allow deviations from
+the strict UTF-8 encoding (see F<utf8.h>).
+
+Most code should use utf8_to_uvchr() rather than call this directly.
+
+ UV utf8n_to_uvuni(const U8 *s, STRLEN curlen, STRLEN *retlen, U32 flags)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_distance
+X<utf8_distance>
+
+Returns the number of UTF-8 characters between the UTF-8 pointers C<a>
+and C<b>.
+
+WARNING: use only if you *know* that the pointers point inside the
+same UTF-8 buffer.
+
+ IV utf8_distance(const U8 *a, const U8 *b)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_hop
+X<utf8_hop>
+
+Return the UTF-8 pointer C<s> displaced by C<off> characters, either
+forward or backward.
+
+WARNING: do not use the following unless you *know* C<off> is within
+the UTF-8 data pointed to by C<s> *and* that on entry C<s> is aligned
+on the first byte of character or just after the last byte of a character.
+
+ U8* utf8_hop(const U8 *s, I32 off)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_length
+X<utf8_length>
+
+Return the length of the UTF-8 char encoded string C<s> in characters.
+Stops at C<e> (inclusive). If C<e E<lt> s> or if the scan would end
+up past C<e>, croaks.
+
+ STRLEN utf8_length(const U8* s, const U8 *e)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_to_bytes
+X<utf8_to_bytes>
+
+Converts a string C<s> of length C<len> from UTF-8 into byte encoding.
+Unlike C<bytes_to_utf8>, this over-writes the original string, and
+updates len to contain the new length.
+Returns zero on failure, setting C<len> to -1.
+
+If you need a copy of the string, see C<bytes_from_utf8>.
+
+NOTE: this function is experimental and may change or be
+removed without notice.
+
+ U8* utf8_to_bytes(U8 *s, STRLEN *len)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_to_uvchr
+X<utf8_to_uvchr>
+
+Returns the native character value of the first character in the string C<s>
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
+length, in bytes, of that character.
+
+If C<s> does not point to a well-formed UTF-8 character, zero is
+returned and retlen is set, if possible, to -1.
+
+ UV utf8_to_uvchr(const U8 *s, STRLEN *retlen)
+
+=for hackers
+Found in file utf8.c
+
+=item utf8_to_uvuni
+X<utf8_to_uvuni>
+
+Returns the Unicode code point of the first character in the string C<s>
+which is assumed to be in UTF-8 encoding; C<retlen> will be set to the
+length, in bytes, of that character.
+
+This function should only be used when returned UV is considered
+an index into the Unicode semantic tables (e.g. swashes).
+
+If C<s> does not point to a well-formed UTF-8 character, zero is
+returned and retlen is set, if possible, to -1.
+
+ UV utf8_to_uvuni(const U8 *s, STRLEN *retlen)
+
+=for hackers
+Found in file utf8.c
+
+=item uvchr_to_utf8
+X<uvchr_to_utf8>
+
+Adds the UTF-8 representation of the Native codepoint C<uv> to the end
+of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
+bytes available. The return value is the pointer to the byte after the
+end of the new character. In other words,
+
+ d = uvchr_to_utf8(d, uv);
+
+is the recommended wide native character-aware way of saying
+
+ *(d++) = uv;
+
+ U8* uvchr_to_utf8(U8 *d, UV uv)
+
+=for hackers
+Found in file utf8.c
+
+=item uvuni_to_utf8_flags
+X<uvuni_to_utf8_flags>
+
+Adds the UTF-8 representation of the Unicode codepoint C<uv> to the end
+of the string C<d>; C<d> should be have at least C<UTF8_MAXBYTES+1> free
+bytes available. The return value is the pointer to the byte after the
+end of the new character. In other words,
+
+ d = uvuni_to_utf8_flags(d, uv, flags);
+
+or, in most cases,
+
+ d = uvuni_to_utf8(d, uv);
+
+(which is equivalent to)
+
+ d = uvuni_to_utf8_flags(d, uv, 0);
+
+is the recommended Unicode-aware way of saying
+
+ *(d++) = uv;
+
+ U8* uvuni_to_utf8_flags(U8 *d, UV uv, UV flags)
+
+=for hackers
+Found in file utf8.c
+
+
+=back
+
+=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
+
+=over 8
+
+=item ax
+X<ax>
+
+Variable which is setup by C<xsubpp> to indicate the stack base offset,
+used by the C<ST>, C<XSprePUSH> and C<XSRETURN> macros. The C<dMARK> macro
+must be called prior to setup the C<MARK> variable.
+
+ I32 ax
+
+=for hackers
+Found in file XSUB.h
+
+=item CLASS
+X<CLASS>
+
+Variable which is setup by C<xsubpp> to indicate the
+class name for a C++ XS constructor. This is always a C<char*>. See C<THIS>.
+
+ char* CLASS
+
+=for hackers
+Found in file XSUB.h
+
+=item dAX
+X<dAX>
+
+Sets up the C<ax> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+ dAX;
+
+=for hackers
+Found in file XSUB.h
+
+=item dAXMARK
+X<dAXMARK>
+
+Sets up the C<ax> variable and stack marker variable C<mark>.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+ dAXMARK;
+
+=for hackers
+Found in file XSUB.h
+
+=item dITEMS
+X<dITEMS>
+
+Sets up the C<items> variable.
+This is usually handled automatically by C<xsubpp> by calling C<dXSARGS>.
+
+ dITEMS;
+
+=for hackers
+Found in file XSUB.h
+
+=item dUNDERBAR
+X<dUNDERBAR>
+
+Sets up the C<padoff_du> variable for an XSUB that wishes to use
+C<UNDERBAR>.
+
+ dUNDERBAR;
+
+=for hackers
+Found in file XSUB.h
+
+=item dXSARGS
+X<dXSARGS>
+
+Sets up stack and mark pointers for an XSUB, calling dSP and dMARK.
+Sets up the C<ax> and C<items> variables by calling C<dAX> and C<dITEMS>.
+This is usually handled automatically by C<xsubpp>.
+
+ dXSARGS;
+
+=for hackers
+Found in file XSUB.h
+
+=item dXSI32
+X<dXSI32>
+
+Sets up the C<ix> variable for an XSUB which has aliases. This is usually
+handled automatically by C<xsubpp>.
+
+ dXSI32;
+
+=for hackers
+Found in file XSUB.h
+
+=item items
+X<items>
+
+Variable which is setup by C<xsubpp> to indicate the number of
+items on the stack. See L<perlxs/"Variable-length Parameter Lists">.
+
+ I32 items
+
+=for hackers
+Found in file XSUB.h
+
+=item ix
+X<ix>
+
+Variable which is setup by C<xsubpp> to indicate which of an
+XSUB's aliases was used to invoke it. See L<perlxs/"The ALIAS: Keyword">.
+
+ I32 ix
+
+=for hackers
+Found in file XSUB.h
+
+=item newXSproto
+X<newXSproto>
+
+Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
+the subs.
+
+=for hackers
+Found in file XSUB.h
+
+=item RETVAL
+X<RETVAL>
+
+Variable which is setup by C<xsubpp> to hold the return value for an
+XSUB. This is always the proper type for the XSUB. See
+L<perlxs/"The RETVAL Variable">.
+
+ (whatever) RETVAL
+
+=for hackers
+Found in file XSUB.h
+
+=item ST
+X<ST>
+
+Used to access elements on the XSUB's stack.
+
+ SV* ST(int ix)
+
+=for hackers
+Found in file XSUB.h
+
+=item THIS
+X<THIS>
+
+Variable which is setup by C<xsubpp> to designate the object in a C++
+XSUB. This is always the proper type for the C++ object. See C<CLASS> and
+L<perlxs/"Using XS With C++">.
+
+ (whatever) THIS
+
+=for hackers
+Found in file XSUB.h
+
+=item UNDERBAR
+X<UNDERBAR>
+
+The SV* corresponding to the $_ variable. Works even if there
+is a lexical $_ in scope.
+
+=for hackers
+Found in file XSUB.h
+
+=item XS
+X<XS>
+
+Macro to declare an XSUB and its C parameter list. This is handled by
+C<xsubpp>.
+
+=for hackers
+Found in file XSUB.h
+
+=item XS_VERSION
+X<XS_VERSION>
+
+The version identifier for an XS module. This is usually
+handled automatically by C<ExtUtils::MakeMaker>. See C<XS_VERSION_BOOTCHECK>.
+
+=for hackers
+Found in file XSUB.h
+
+=item XS_VERSION_BOOTCHECK
+X<XS_VERSION_BOOTCHECK>
+
+Macro to verify that a PM module's $VERSION variable matches the XS
+module's C<XS_VERSION> variable. This is usually handled automatically by
+C<xsubpp>. See L<perlxs/"The VERSIONCHECK: Keyword">.
+
+ XS_VERSION_BOOTCHECK;
+
+=for hackers
+Found in file XSUB.h
+
+
+=back
+
+=head1 Warning and Dieing
+
+=over 8
+
+=item croak
+X<croak>
+
+This is the XSUB-writer's interface to Perl's C<die> function.
+Normally call this function the same way you call the C C<printf>
+function. Calling C<croak> returns control directly to Perl,
+sidestepping the normal C order of execution. See C<warn>.
+
+If you want to throw an exception object, assign the object to
+C<$@> and then pass C<NULL> to croak():
+
+ errsv = get_sv("@", TRUE);
+ sv_setsv(errsv, exception_object);
+ croak(NULL);
+
+ void croak(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
+=item warn
+X<warn>
+
+This is the XSUB-writer's interface to Perl's C<warn> function. Call this
+function the same way you call the C C<printf> function. See C<croak>.
+
+ void warn(const char* pat, ...)
+
+=for hackers
+Found in file util.c
+
+
+=back
+
+=head1 AUTHORS
+
+Until May 1997, this document was maintained by Jeff Okamoto
+<okamoto at corp.hp.com>. It is now maintained as part of Perl itself.
+
+With lots of help and suggestions from Dean Roehrich, Malcolm Beattie,
+Andreas Koenig, Paul Hudson, Ilya Zakharevich, Paul Marquess, Neil
+Bowers, Matthew Green, Tim Bunce, Spider Boardman, Ulrich Pfeifer,
+Stephen McCamant, and Gurusamy Sarathy.
+
+API Listing originally by Dean Roehrich <roehrich at cray.com>.
+
+Updated to be autogenerated from comments in the source by Benjamin Stuhl.
+
+=head1 SEE ALSO
+
+perlguts(1), perlxs(1), perlxstut(1), perlintern(1)
+
+=cut
+
+ ex: set ro:
Modified: trunk/contrib/perl/pod/perlapio.pod
===================================================================
--- trunk/contrib/perl/pod/perlapio.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlapio.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -390,9 +390,8 @@
PerlIO_fast_gets(f) = PerlIO_has_cntptr(f) && \
PerlIO_canset_cnt(f) && \
- `Can set pointer into buffer'
+ 'Can set pointer into buffer'
-
=item B<PerlIO_has_cntptr(f)>
Implementation can return pointer to current position in the "buffer"
Property changes on: trunk/contrib/perl/pod/perlapio.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlartistic.pod
===================================================================
--- trunk/contrib/perl/pod/perlartistic.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlartistic.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlartistic.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlbook.pod
===================================================================
--- trunk/contrib/perl/pod/perlbook.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlbook.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -22,9 +22,10 @@
=item I<Programming Perl> (the "Camel Book"):
- by Larry Wall, Tom Christiansen, and Jon Orwant
- ISBN 978-0-596-00027-1 [3rd edition July 2000]
- http://oreilly.com/catalog/9780596000271/
+ by Tom Christiansen, brian d foy, Larry Wall with Jon Orwant
+ ISBN 978-0-596-00492-7 [4th edition February 2012]
+ ISBN 978-1-4493-9890-3 [ebook]
+ http://oreilly.com/catalog/9780596004927
=back
@@ -51,8 +52,8 @@
=item I<Learning Perl> (the "Llama Book")
by Randal L. Schwartz, Tom Phoenix, and brian d foy
- ISBN 978-0-596-52011-3 [5th edition June 2008]
- http://oreilly.com/catalog/9780596520113
+ ISBN 978-1-4493-0358-7 [6th edition June 2011]
+ http://oreilly.com/catalog/0636920018452
=back
@@ -66,8 +67,8 @@
by Randal L. Schwartz and brian d foy, with Tom Phoenix
foreword by Damian Conway
- ISBN 978-0-596-00478-1 [1st edition March 2006]
- http://oreilly.com/catalog/9780596004781/
+ ISBN 978-1-4493-9309-0 [2nd edition August 2012]
+ http://oreilly.com/catalog/0636920012689/
=back
@@ -80,8 +81,9 @@
=item I<Perl 5 Pocket Reference>
by Johan Vromans
- ISBN 978-0-596-00374-6 [4th edition July 2002]
- http://oreilly.com/catalog/9780596003746/
+ ISBN 978-1-4493-0370-9 [5th edition July 2011]
+ ISBN 978-1-4493-0813-1 [ebook]
+ http://oreilly.com/catalog/0636920018476/
=item I<Perl Debugger Pocket Reference>
@@ -105,7 +107,7 @@
by James Lee
ISBN 1-59059-391-X [3rd edition April 2010]
- http://www.apress.com/book/view/1430227931
+ http://www.apress.com/9781430227939
=item I<Learning Perl>
@@ -142,7 +144,7 @@
by Sam Tregar
ISBN 1-59059-018-X [1st edition August 2002]
- http://www.apress.com/book/view/159059018X
+ http://www.apress.com/9781590590188
=item I<The Perl Cookbook>
@@ -151,7 +153,6 @@
ISBN 1-56592-243-3 [2nd edition August 2003]
http://oreilly.com/catalog/9780596003135
-
=item I<Automating System Administration with Perl>
by David N. Blank-Edelman
@@ -162,7 +163,7 @@
by Linchi Shea
ISBN 1-59059-097-X [1st edition July 2003]
- http://www.apress.com/book/view/159059097X
+ http://www.apress.com/9781590590973
=back
@@ -241,7 +242,7 @@
by Richard Foley with Andy Lester
ISBN 1-59059-454-1 [1st edition July 2005]
- http://www.apress.com/book/view/1590594541
+ http://www.apress.com/9781590594544
=back
@@ -251,8 +252,6 @@
I<Higher-Order Perl>: http://hop.perl.plover.com/
-I<Writing Perl Modules for CPAN>: http://www.apress.com/resource/freeebook/9781590590188
-
=head2 Other interesting, non-Perl books
You might notice several familiar Perl concepts in this collection of
Property changes on: trunk/contrib/perl/pod/perlbook.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlboot.pod
===================================================================
--- trunk/contrib/perl/pod/perlboot.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlboot.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,884 +1,12 @@
+=encoding utf8
+
=head1 NAME
-perlboot - Beginner's Object-Oriented Tutorial
+perlboot - This document has been deleted
=head1 DESCRIPTION
-If you're not familiar with objects from other languages, some of the
-other Perl object documentation may be a little daunting, such as
-L<perlobj>, a basic reference in using objects, and L<perltoot>, which
-introduces readers to the peculiarities of Perl's object system in a
-tutorial way.
+For information on OO programming with Perl, please see L<perlootut>
+and L<perlobj>.
-So, let's take a different approach, presuming no prior object
-experience. It helps if you know about subroutines (L<perlsub>),
-references (L<perlref> et. seq.), and packages (L<perlmod>), so become
-familiar with those first if you haven't already.
-
-=head2 If we could talk to the animals...
-
-Let's let the animals talk for a moment:
-
- sub Cow::speak {
- print "a Cow goes moooo!\n";
- }
- sub Horse::speak {
- print "a Horse goes neigh!\n";
- }
- sub Sheep::speak {
- print "a Sheep goes baaaah!\n";
- }
-
- Cow::speak;
- Horse::speak;
- Sheep::speak;
-
-This results in:
-
- a Cow goes moooo!
- a Horse goes neigh!
- a Sheep goes baaaah!
-
-Nothing spectacular here. Simple subroutines, albeit from separate
-packages, and called using the full package name. So let's create
-an entire pasture:
-
- # Cow::speak, Horse::speak, Sheep::speak as before
- @pasture = qw(Cow Cow Horse Sheep Sheep);
- foreach $animal (@pasture) {
- &{$animal."::speak"};
- }
-
-This results in:
-
- a Cow goes moooo!
- a Cow goes moooo!
- a Horse goes neigh!
- a Sheep goes baaaah!
- a Sheep goes baaaah!
-
-Wow. That symbolic coderef de-referencing there is pretty nasty.
-We're counting on C<no strict refs> mode, certainly not recommended
-for larger programs. And why was that necessary? Because the name of
-the package seems to be inseparable from the name of the subroutine we
-want to invoke within that package.
-
-Or is it?
-
-=head2 Introducing the method invocation arrow
-
-For now, let's say that C<< Class->method >> invokes subroutine
-C<method> in package C<Class>. (Here, "Class" is used in its
-"category" meaning, not its "scholastic" meaning.) That's not
-completely accurate, but we'll do this one step at a time. Now let's
-use it like so:
-
- # Cow::speak, Horse::speak, Sheep::speak as before
- Cow->speak;
- Horse->speak;
- Sheep->speak;
-
-And once again, this results in:
-
- a Cow goes moooo!
- a Horse goes neigh!
- a Sheep goes baaaah!
-
-That's not fun yet. Same number of characters, all constant, no
-variables. But yet, the parts are separable now. Watch:
-
- $a = "Cow";
- $a->speak; # invokes Cow->speak
-
-Ahh! Now that the package name has been parted from the subroutine
-name, we can use a variable package name. And this time, we've got
-something that works even when C<use strict refs> is enabled.
-
-=head2 Invoking a barnyard
-
-Let's take that new arrow invocation and put it back in the barnyard
-example:
-
- sub Cow::speak {
- print "a Cow goes moooo!\n";
- }
- sub Horse::speak {
- print "a Horse goes neigh!\n";
- }
- sub Sheep::speak {
- print "a Sheep goes baaaah!\n";
- }
-
- @pasture = qw(Cow Cow Horse Sheep Sheep);
- foreach $animal (@pasture) {
- $animal->speak;
- }
-
-There! Now we have the animals all talking, and safely at that,
-without the use of symbolic coderefs.
-
-But look at all that common code. Each of the C<speak> routines has a
-similar structure: a C<print> operator and a string that contains
-common text, except for two of the words. It'd be nice if we could
-factor out the commonality, in case we decide later to change it all
-to C<says> instead of C<goes>.
-
-And we actually have a way of doing that without much fuss, but we
-have to hear a bit more about what the method invocation arrow is
-actually doing for us.
-
-=head2 The extra parameter of method invocation
-
-The invocation of:
-
- Class->method(@args)
-
-attempts to invoke subroutine C<Class::method> as:
-
- Class::method("Class", @args);
-
-(If the subroutine can't be found, "inheritance" kicks in, but we'll
-get to that later.) This means that we get the class name as the
-first parameter (the only parameter, if no arguments are given). So
-we can rewrite the C<Sheep> speaking subroutine as:
-
- sub Sheep::speak {
- my $class = shift;
- print "a $class goes baaaah!\n";
- }
-
-And the other two animals come out similarly:
-
- sub Cow::speak {
- my $class = shift;
- print "a $class goes moooo!\n";
- }
- sub Horse::speak {
- my $class = shift;
- print "a $class goes neigh!\n";
- }
-
-In each case, C<$class> will get the value appropriate for that
-subroutine. But once again, we have a lot of similar structure. Can
-we factor that out even further? Yes, by calling another method in
-the same class.
-
-=head2 Calling a second method to simplify things
-
-Let's call out from C<speak> to a helper method called C<sound>.
-This method provides the constant text for the sound itself.
-
- { package Cow;
- sub sound { "moooo" }
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- }
- }
-
-Now, when we call C<< Cow->speak >>, we get a C<$class> of C<Cow> in
-C<speak>. This in turn selects the C<< Cow->sound >> method, which
-returns C<moooo>. But how different would this be for the C<Horse>?
-
- { package Horse;
- sub sound { "neigh" }
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- }
- }
-
-Only the name of the package and the specific sound change. So can we
-somehow share the definition for C<speak> between the Cow and the
-Horse? Yes, with inheritance!
-
-=head2 Inheriting the windpipes
-
-We'll define a common subroutine package called C<Animal>, with the
-definition for C<speak>:
-
- { package Animal;
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- }
- }
-
-Then, for each animal, we say it "inherits" from C<Animal>, along
-with the animal-specific sound:
-
- { package Cow;
- @ISA = qw(Animal);
- sub sound { "moooo" }
- }
-
-Note the added C<@ISA> array (pronounced "is a"). We'll get to that in a minute.
-
-But what happens when we invoke C<< Cow->speak >> now?
-
-First, Perl constructs the argument list. In this case, it's just
-C<Cow>. Then Perl looks for C<Cow::speak>. But that's not there, so
-Perl checks for the inheritance array C<@Cow::ISA>. It's there,
-and contains the single name C<Animal>.
-
-Perl next checks for C<speak> inside C<Animal> instead, as in
-C<Animal::speak>. And that's found, so Perl invokes that subroutine
-with the already frozen argument list.
-
-Inside the C<Animal::speak> subroutine, C<$class> becomes C<Cow> (the
-first argument). So when we get to the step of invoking
-C<< $class->sound >>, it'll be looking for C<< Cow->sound >>, which
-gets it on the first try without looking at C<@ISA>. Success!
-
-=head2 A few notes about @ISA
-
-This magical C<@ISA> variable has declared that C<Cow> "is a" C<Animal>.
-Note that it's an array, not a simple single value, because on rare
-occasions, it makes sense to have more than one parent class searched
-for the missing methods.
-
-If C<Animal> also had an C<@ISA>, then we'd check there too. The
-search is recursive, depth-first, left-to-right in each C<@ISA> by
-default (see L<mro> for alternatives). Typically, each C<@ISA> has
-only one element (multiple elements means multiple inheritance and
-multiple headaches), so we get a nice tree of inheritance.
-
-When we turn on C<use strict>, we'll get complaints on C<@ISA>, since
-it's not a variable containing an explicit package name, nor is it a
-lexical ("my") variable. We can't make it a lexical variable though
-(it has to belong to the package to be found by the inheritance mechanism),
-so there's a couple of straightforward ways to handle that.
-
-The easiest is to just spell the package name out:
-
- @Cow::ISA = qw(Animal);
-
-Or declare it as a package global variable:
-
- package Cow;
- our @ISA = qw(Animal);
-
-Or allow it as an implicitly named package variable:
-
- package Cow;
- use vars qw(@ISA);
- @ISA = qw(Animal);
-
-If the C<Animal> class comes from another (object-oriented) module, then
-just employ C<use base> to specify that C<Animal> should serve as the basis
-for the C<Cow> class:
-
- package Cow;
- use base qw(Animal);
-
-Now that's pretty darn simple!
-
-=head2 Overriding the methods
-
-Let's add a mouse, which can barely be heard:
-
- # Animal package from before
- { package Mouse;
- @ISA = qw(Animal);
- sub sound { "squeak" }
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- print "[but you can barely hear it!]\n";
- }
- }
-
- Mouse->speak;
-
-which results in:
-
- a Mouse goes squeak!
- [but you can barely hear it!]
-
-Here, C<Mouse> has its own speaking routine, so C<< Mouse->speak >>
-doesn't immediately invoke C<< Animal->speak >>. This is known as
-"overriding". In fact, we don't even need to say that a C<Mouse> is
-an C<Animal> at all, because all of the methods needed for C<speak> are
-completely defined for C<Mouse>; this is known as "duck typing":
-"If it walks like a duck and quacks like a duck, I would call it a duck"
-(James Whitcomb). However, it would probably be beneficial to allow a
-closer examination to conclude that a C<Mouse> is indeed an C<Animal>,
-so it is actually better to define C<Mouse> with C<Animal> as its base
-(that is, it is better to "derive C<Mouse> from C<Animal>").
-
-Moreover, this duplication of code could become a maintenance headache
-(though code-reuse is not actually a good reason for inheritance; good
-design practices dictate that a derived class should be usable wherever
-its base class is usable, which might not be the outcome if code-reuse
-is the sole criterion for inheritance. Just remember that a C<Mouse>
-should always act like an C<Animal>).
-
-So, let's make C<Mouse> an C<Animal>!
-
-The obvious solution is to invoke C<Animal::speak> directly:
-
- # Animal package from before
- { package Mouse;
- @ISA = qw(Animal);
- sub sound { "squeak" }
- sub speak {
- my $class = shift;
- Animal::speak($class);
- print "[but you can barely hear it!]\n";
- }
- }
-
-Note that we're using C<Animal::speak>. If we were to invoke
-C<< Animal->speak >> instead, the first parameter to C<Animal::speak>
-would automatically be C<"Animal"> rather than C<"Mouse">, so that
-the call to C<< $class->sound >> in C<Animal::speak> would become
-C<< Animal->sound >> rather than C<< Mouse->sound >>.
-
-Also, without the method arrow C<< -> >>, it becomes necessary to specify
-the first parameter to C<Animal::speak> ourselves, which is why C<$class>
-is explicitly passed: C<Animal::speak($class)>.
-
-However, invoking C<Animal::speak> directly is a mess: Firstly, it assumes
-that the C<speak> method is a member of the C<Animal> class; what if C<Animal>
-actually inherits C<speak> from its own base? Because we are no longer using
-C<< -> >> to access C<speak>, the special method look up mechanism wouldn't be
-used, so C<speak> wouldn't even be found!
-
-The second problem is more subtle: C<Animal> is now hardwired into the subroutine
-selection. Let's assume that C<Animal::speak> does exist. What happens when,
-at a later time, someone expands the class hierarchy by having C<Mouse>
-inherit from C<Mus> instead of C<Animal>. Unless the invocation of C<Animal::speak>
-is also changed to an invocation of C<Mus::speak>, centuries worth of taxonomical
-classification could be obliterated!
-
-What we have here is a fragile or leaky abstraction; it is the beginning of a
-maintenance nightmare. What we need is the ability to search for the right
-method wih as few assumptions as possible.
-
-=head2 Starting the search from a different place
-
-A I<better> solution is to tell Perl where in the inheritance chain to begin searching
-for C<speak>. This can be achieved with a modified version of the method arrow C<< -> >>:
-
- ClassName->FirstPlaceToLook::method
-
-So, the improved C<Mouse> class is:
-
- # same Animal as before
- { package Mouse;
- # same @ISA, &sound as before
- sub speak {
- my $class = shift;
- $class->Animal::speak;
- print "[but you can barely hear it!]\n";
- }
- }
-
-Using this syntax, we start with C<Animal> to find C<speak>, and then
-use all of C<Animal>'s inheritance chain if it is not found immediately.
-As usual, the first parameter to C<speak> would be C<$class>, so we no
-longer need to pass C<$class> explicitly to C<speak>.
-
-But what about the second problem? We're still hardwiring C<Animal> into
-the method lookup.
-
-=head2 The SUPER way of doing things
-
-If C<Animal> is replaced with the special placeholder C<SUPER> in that
-invocation, then the contents of C<Mouse>'s C<@ISA> are used for the
-search, beginning with C<$ISA[0]>. So, all of the problems can be fixed
-as follows:
-
- # same Animal as before
- { package Mouse;
- # same @ISA, &sound as before
- sub speak {
- my $class = shift;
- $class->SUPER::speak;
- print "[but you can barely hear it!]\n";
- }
- }
-
-In general, C<SUPER::speak> means look in the current package's C<@ISA>
-for a class that implements C<speak>, and invoke the first one found.
-The placeholder is called C<SUPER>, because many other languages refer
-to base classes as "I<super>classes", and Perl likes to be eclectic.
-
-Note that a call such as
-
- $class->SUPER::method;
-
-does I<not> look in the C<@ISA> of C<$class> unless C<$class> happens to
-be the current package.
-
-=head2 Let's review...
-
-So far, we've seen the method arrow syntax:
-
- Class->method(@args);
-
-or the equivalent:
-
- $a = "Class";
- $a->method(@args);
-
-which constructs an argument list of:
-
- ("Class", @args)
-
-and attempts to invoke:
-
- Class::method("Class", @args);
-
-However, if C<Class::method> is not found, then C<@Class::ISA> is examined
-(recursively) to locate a class (a package) that does indeed contain C<method>,
-and that subroutine is invoked instead.
-
-Using this simple syntax, we have class methods, (multiple) inheritance,
-overriding, and extending. Using just what we've seen so far, we've
-been able to factor out common code (though that's never a good reason
-for inheritance!), and provide a nice way to reuse implementations with
-variations.
-
-Now, what about data?
-
-=head2 A horse is a horse, of course of course, or is it?
-
-Let's start with the code for the C<Animal> class
-and the C<Horse> class:
-
- { package Animal;
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- }
- }
- { package Horse;
- @ISA = qw(Animal);
- sub sound { "neigh" }
- }
-
-This lets us invoke C<< Horse->speak >> to ripple upward to
-C<Animal::speak>, calling back to C<Horse::sound> to get the specific
-sound, and the output of:
-
- a Horse goes neigh!
-
-But all of our Horse objects would have to be absolutely identical.
-If we add a subroutine, all horses automatically share it. That's
-great for making horses the same, but how do we capture the
-distinctions of an individual horse? For example, suppose we want
-to give our first horse a name. There's got to be a way to keep its
-name separate from the other horses.
-
-That is to say, we want particular instances of C<Horse> to have
-different names.
-
-In Perl, any reference can be an "instance", so let's start with the
-simplest reference that can hold a horse's name: a scalar reference.
-
- my $name = "Mr. Ed";
- my $horse = \$name;
-
-So, now C<$horse> is a reference to what will be the instance-specific
-data (the name). The final step is to turn this reference into a real
-instance of a C<Horse> by using the special operator C<bless>:
-
- bless $horse, Horse;
-
-This operator stores information about the package named C<Horse> into
-the thing pointed at by the reference. At this point, we say
-C<$horse> is an instance of C<Horse>. That is, it's a specific
-horse. The reference is otherwise unchanged, and can still be used
-with traditional dereferencing operators.
-
-=head2 Invoking an instance method
-
-The method arrow can be used on instances, as well as classes (the names
-of packages). So, let's get the sound that C<$horse> makes:
-
- my $noise = $horse->sound("some", "unnecessary", "args");
-
-To invoke C<sound>, Perl first notes that C<$horse> is a blessed
-reference (and thus an instance). It then constructs an argument
-list, as per usual.
-
-Now for the fun part: Perl takes the class in which the instance was
-blessed, in this case C<Horse>, and uses that class to locate the
-subroutine. In this case, C<Horse::sound> is found directly (without
-using inheritance). In the end, it is as though our initial line were
-written as follows:
-
- my $noise = Horse::sound($horse, "some", "unnecessary", "args");
-
-Note that the first parameter here is still the instance, not the name
-of the class as before. We'll get C<neigh> as the return value, and
-that'll end up as the C<$noise> variable above.
-
-If Horse::sound had not been found, we'd be wandering up the C<@Horse::ISA>
-array, trying to find the method in one of the superclasses. The only
-difference between a class method and an instance method is whether the
-first parameter is an instance (a blessed reference) or a class name (a
-string).
-
-=head2 Accessing the instance data
-
-Because we get the instance as the first parameter, we can now access
-the instance-specific data. In this case, let's add a way to get at
-the name:
-
- { package Horse;
- @ISA = qw(Animal);
- sub sound { "neigh" }
- sub name {
- my $self = shift;
- $$self;
- }
- }
-
-Inside C<Horse::name>, the C<@_> array contains:
-
- ($horse, "some", "unnecessary", "args")
-
-so the C<shift> stores C<$horse> into C<$self>. Then, C<$self> gets
-de-referenced with C<$$self> as normal, yielding C<"Mr. Ed">.
-
-It's traditional to C<shift> the first parameter into a variable named
-C<$self> for instance methods and into a variable named C<$class> for
-class methods.
-
-Then, the following line:
-
- print $horse->name, " says ", $horse->sound, "\n";
-
-outputs:
-
- Mr. Ed says neigh.
-
-=head2 How to build a horse
-
-Of course, if we constructed all of our horses by hand, we'd most
-likely make mistakes from time to time. We're also violating one of
-the properties of object-oriented programming, in that the "inside
-guts" of a Horse are visible. That's good if you're a veterinarian,
-but not if you just like to own horses. So, let's have the Horse
-class handle the details inside a class method:
-
- { package Horse;
- @ISA = qw(Animal);
- sub sound { "neigh" }
- sub name {
- my $self = shift; # instance method, so use $self
- $$self;
- }
- sub named {
- my $class = shift; # class method, so use $class
- my $name = shift;
- bless \$name, $class;
- }
- }
-
-Now with the new C<named> method, we can build a horse as follows:
-
- my $horse = Horse->named("Mr. Ed");
-
-Notice we're back to a class method, so the two arguments to
-C<Horse::named> are C<Horse> and C<Mr. Ed>. The C<bless> operator
-not only blesses C<\$name>, it also returns that reference.
-
-This C<Horse::named> method is called a "constructor".
-
-We've called the constructor C<named> here, so that it quickly denotes
-the constructor's argument as the name for this particular C<Horse>.
-You can use different constructors with different names for different
-ways of "giving birth" to the object (like maybe recording its
-pedigree or date of birth). However, you'll find that most people
-coming to Perl from more limited languages use a single constructor
-named C<new>, with various ways of interpreting the arguments to
-C<new>. Either style is fine, as long as you document your particular
-way of giving birth to an object. (And you I<were> going to do that,
-right?)
-
-=head2 Inheriting the constructor
-
-But was there anything specific to C<Horse> in that method? No. Therefore,
-it's also the same recipe for building anything else that inherited from
-C<Animal>, so let's put C<name> and C<named> there:
-
- { package Animal;
- sub speak {
- my $class = shift;
- print "a $class goes ", $class->sound, "!\n";
- }
- sub name {
- my $self = shift;
- $$self;
- }
- sub named {
- my $class = shift;
- my $name = shift;
- bless \$name, $class;
- }
- }
- { package Horse;
- @ISA = qw(Animal);
- sub sound { "neigh" }
- }
-
-Ahh, but what happens if we invoke C<speak> on an instance?
-
- my $horse = Horse->named("Mr. Ed");
- $horse->speak;
-
-We get a debugging value:
-
- a Horse=SCALAR(0xaca42ac) goes neigh!
-
-Why? Because the C<Animal::speak> routine is expecting a classname as
-its first parameter, not an instance. When the instance is passed in,
-we'll end up using a blessed scalar reference as a string, and that
-shows up as we saw it just now.
-
-=head2 Making a method work with either classes or instances
-
-All we need is for a method to detect if it is being called on a class
-or called on an instance. The most straightforward way is with the
-C<ref> operator. This returns a string (the classname) when used on a
-blessed reference, and an empty string when used on a string (like a
-classname). Let's modify the C<name> method first to notice the change:
-
- sub name {
- my $either = shift;
- ref $either ? $$either : "Any $either";
- }
-
-Here, the C<?:> operator comes in handy to select either the
-dereference or a derived string. Now we can use this with either an
-instance or a class. Note that I've changed the first parameter
-holder to C<$either> to show that this is intended:
-
- my $horse = Horse->named("Mr. Ed");
- print Horse->name, "\n"; # prints "Any Horse\n"
- print $horse->name, "\n"; # prints "Mr Ed.\n"
-
-and now we'll fix C<speak> to use this:
-
- sub speak {
- my $either = shift;
- print $either->name, " goes ", $either->sound, "\n";
- }
-
-And since C<sound> already worked with either a class or an instance,
-we're done!
-
-=head2 Adding parameters to a method
-
-Let's train our animals to eat:
-
- { package Animal;
- sub named {
- my $class = shift;
- my $name = shift;
- bless \$name, $class;
- }
- sub name {
- my $either = shift;
- ref $either ? $$either : "Any $either";
- }
- sub speak {
- my $either = shift;
- print $either->name, " goes ", $either->sound, "\n";
- }
- sub eat {
- my $either = shift;
- my $food = shift;
- print $either->name, " eats $food.\n";
- }
- }
- { package Horse;
- @ISA = qw(Animal);
- sub sound { "neigh" }
- }
- { package Sheep;
- @ISA = qw(Animal);
- sub sound { "baaaah" }
- }
-
-And now try it out:
-
- my $horse = Horse->named("Mr. Ed");
- $horse->eat("hay");
- Sheep->eat("grass");
-
-which prints:
-
- Mr. Ed eats hay.
- Any Sheep eats grass.
-
-An instance method with parameters gets invoked with the instance,
-and then the list of parameters. So that first invocation is like:
-
- Animal::eat($horse, "hay");
-
-=head2 More interesting instances
-
-What if an instance needs more data? Most interesting instances are
-made of many items, each of which can in turn be a reference or even
-another object. The easiest way to store these is often in a hash.
-The keys of the hash serve as the names of parts of the object (often
-called "instance variables" or "member variables"), and the
-corresponding values are, well, the values.
-
-But how do we turn the horse into a hash? Recall that an object was
-any blessed reference. We can just as easily make it a blessed hash
-reference as a blessed scalar reference, as long as everything that
-looks at the reference is changed accordingly.
-
-Let's make a sheep that has a name and a color:
-
- my $bad = bless { Name => "Evil", Color => "black" }, Sheep;
-
-so C<< $bad->{Name} >> has C<Evil>, and C<< $bad->{Color} >> has
-C<black>. But we want to make C<< $bad->name >> access the name, and
-that's now messed up because it's expecting a scalar reference. Not
-to worry, because that's pretty easy to fix up.
-
-One solution is to override C<Animal::name> and C<Animal::named> by
-defining them anew in C<Sheep>, but then any methods added later to
-C<Animal> might still mess up, and we'd have to override all of those
-too. Therefore, it's never a good idea to define the data layout in a
-way that's different from the data layout of the base classes. In fact,
-it's a good idea to use blessed hash references in all cases. Also, this
-is why it's important to have constructors do the low-level work. So,
-let's redefine C<Animal>:
-
- ## in Animal
- sub name {
- my $either = shift;
- ref $either ? $either->{Name} : "Any $either";
- }
- sub named {
- my $class = shift;
- my $name = shift;
- my $self = { Name => $name };
- bless $self, $class;
- }
-
-Of course, we still need to override C<named> in order to handle
-constructing a C<Sheep> with a certain color:
-
- ## in Sheep
- sub named {
- my ($class, $name) = @_;
- my $self = $class->SUPER::named(@_);
- $$self{Color} = $class->default_color;
- $self
- }
-
-(Note that C<@_> contains the parameters to C<named>.)
-
-What's this C<default_color>? Well, if C<named> has only the name,
-we still need to set a color, so we'll have a class-specific default color.
-For a sheep, we might define it as white:
-
- ## in Sheep
- sub default_color { "white" }
-
-Now:
-
- my $sheep = Sheep->named("Bad");
- print $sheep->{Color}, "\n";
-
-outputs:
-
- white
-
-Now, there's nothing particularly specific to C<Sheep> when it comes
-to color, so let's remove C<Sheep::named> and implement C<Animal::named>
-to handle color instead:
-
- ## in Animal
- sub named {
- my ($class, $name) = @_;
- my $self = { Name => $name, Color => $class->default_color };
- bless $self, $class;
- }
-
-And then to keep from having to define C<default_color> for each additional
-class, we'll define a method that serves as the "default default" directly
-in C<Animal>:
-
- ## in Animal
- sub default_color { "brown" }
-
-Of course, because C<name> and C<named> were the only methods that
-referenced the "structure" of the object, the rest of the methods can
-remain the same, so C<speak> still works as before.
-
-=head2 A horse of a different color
-
-But having all our horses be brown would be boring. So let's add a
-method or two to get and set the color.
-
- ## in Animal
- sub color {
- $_[0]->{Color}
- }
- sub set_color {
- $_[0]->{Color} = $_[1];
- }
-
-Note the alternate way of accessing the arguments: C<$_[0]> is used
-in-place, rather than with a C<shift>. (This saves us a bit of time
-for something that may be invoked frequently.) And now we can fix
-that color for Mr. Ed:
-
- my $horse = Horse->named("Mr. Ed");
- $horse->set_color("black-and-white");
- print $horse->name, " is colored ", $horse->color, "\n";
-
-which results in:
-
- Mr. Ed is colored black-and-white
-
-=head2 Summary
-
-So, now we have class methods, constructors, instance methods, instance
-data, and even accessors. But that's still just the beginning of what
-Perl has to offer. We haven't even begun to talk about accessors that
-double as getters and setters, destructors, indirect object notation,
-overloading, "isa" and "can" tests, the C<UNIVERSAL> class, and so on.
-That's for the rest of the Perl documentation to cover. Hopefully, this
-gets you started, though.
-
-=head1 SEE ALSO
-
-For more information, see L<perlobj> (for all the gritty details about
-Perl objects, now that you've seen the basics), L<perltoot> (the
-tutorial for those who already know objects), L<perltooc> (dealing
-with class data), L<perlbot> (for some more tricks), and books such as
-Damian Conway's excellent I<Object Oriented Perl>.
-
-Some modules which might prove interesting are Class::Accessor,
-Class::Class, Class::Contract, Class::Data::Inheritable,
-Class::MethodMaker and Tie::SecureHash
-
-=head1 COPYRIGHT
-
-Copyright (c) 1999, 2000 by Randal L. Schwartz and Stonehenge
-Consulting Services, Inc.
-
-Copyright (c) 2009 by Michael F. Witten.
-
-Permission is hereby granted to distribute this document intact with
-the Perl distribution, and in accordance with the licenses of the Perl
-distribution; derived documents must include this copyright notice
-intact.
-
-Portions of this text have been derived from Perl Training materials
-originally appearing in the I<Packages, References, Objects, and
-Modules> course taught by instructors for Stonehenge Consulting
-Services, Inc. and used with permission.
-
-Portions of this text have been derived from materials originally
-appearing in I<Linux Magazine> and used with permission.
+=cut
Property changes on: trunk/contrib/perl/pod/perlboot.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlbot.pod
===================================================================
--- trunk/contrib/perl/pod/perlbot.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlbot.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,535 +1,12 @@
+=encoding utf8
+
=head1 NAME
-perlbot - Bag o' Object Tricks (the BOT)
+perlbot - This document has been deleted
=head1 DESCRIPTION
-The following collection of tricks and hints is intended to whet curious
-appetites about such things as the use of instance variables and the
-mechanics of object and class relationships. The reader is encouraged to
-consult relevant textbooks for discussion of Object Oriented definitions and
-methodology. This is not intended as a tutorial for object-oriented
-programming or as a comprehensive guide to Perl's object oriented features,
-nor should it be construed as a style guide. If you're looking for tutorials,
-be sure to read L<perlboot>, L<perltoot>, and L<perltooc>.
+For information on OO programming with Perl, please see L<perlootut>
+and L<perlobj>.
-The Perl motto still holds: There's more than one way to do it.
-
-=head1 OO SCALING TIPS
-
-=over 5
-
-=item 1
-
-Do not attempt to verify the type of $self. That'll break if the class is
-inherited, when the type of $self is valid but its package isn't what you
-expect. See rule 5.
-
-=item 2
-
-If an object-oriented (OO) or indirect-object (IO) syntax was used, then the
-object is probably the correct type and there's no need to become paranoid
-about it. Perl isn't a paranoid language anyway. If people subvert the OO
-or IO syntax then they probably know what they're doing and you should let
-them do it. See rule 1.
-
-=item 3
-
-Use the two-argument form of bless(). Let a subclass use your constructor.
-See L<INHERITING A CONSTRUCTOR>.
-
-=item 4
-
-The subclass is allowed to know things about its immediate superclass, the
-superclass is allowed to know nothing about a subclass.
-
-=item 5
-
-Don't be trigger happy with inheritance. A "using", "containing", or
-"delegation" relationship (some sort of aggregation, at least) is often more
-appropriate. See L<OBJECT RELATIONSHIPS>, L<USING RELATIONSHIP WITH SDBM>,
-and L<"DELEGATION">.
-
-=item 6
-
-The object is the namespace. Make package globals accessible via the
-object. This will remove the guess work about the symbol's home package.
-See L<CLASS CONTEXT AND THE OBJECT>.
-
-=item 7
-
-IO syntax is certainly less noisy, but it is also prone to ambiguities that
-can cause difficult-to-find bugs. Allow people to use the sure-thing OO
-syntax, even if you don't like it.
-
-=item 8
-
-Do not use function-call syntax on a method. You're going to be bitten
-someday. Someone might move that method into a superclass and your code
-will be broken. On top of that you're feeding the paranoia in rule 2.
-
-=item 9
-
-Don't assume you know the home package of a method. You're making it
-difficult for someone to override that method. See L<THINKING OF CODE REUSE>.
-
-=back
-
-=head1 INSTANCE VARIABLES
-
-An anonymous array or anonymous hash can be used to hold instance
-variables. Named parameters are also demonstrated.
-
- package Foo;
-
- sub new {
- my $type = shift;
- my %params = @_;
- my $self = {};
- $self->{'High'} = $params{'High'};
- $self->{'Low'} = $params{'Low'};
- bless $self, $type;
- }
-
-
- package Bar;
-
- sub new {
- my $type = shift;
- my %params = @_;
- my $self = [];
- $self->[0] = $params{'Left'};
- $self->[1] = $params{'Right'};
- bless $self, $type;
- }
-
- package main;
-
- $a = Foo->new( 'High' => 42, 'Low' => 11 );
- print "High=$a->{'High'}\n";
- print "Low=$a->{'Low'}\n";
-
- $b = Bar->new( 'Left' => 78, 'Right' => 40 );
- print "Left=$b->[0]\n";
- print "Right=$b->[1]\n";
-
-=head1 SCALAR INSTANCE VARIABLES
-
-An anonymous scalar can be used when only one instance variable is needed.
-
- package Foo;
-
- sub new {
- my $type = shift;
- my $self;
- $self = shift;
- bless \$self, $type;
- }
-
- package main;
-
- $a = Foo->new( 42 );
- print "a=$$a\n";
-
-
-=head1 INSTANCE VARIABLE INHERITANCE
-
-This example demonstrates how one might inherit instance variables from a
-superclass for inclusion in the new class. This requires calling the
-superclass's constructor and adding one's own instance variables to the new
-object.
-
- package Bar;
-
- sub new {
- my $type = shift;
- my $self = {};
- $self->{'buz'} = 42;
- bless $self, $type;
- }
-
- package Foo;
- @ISA = qw( Bar );
-
- sub new {
- my $type = shift;
- my $self = Bar->new;
- $self->{'biz'} = 11;
- bless $self, $type;
- }
-
- package main;
-
- $a = Foo->new;
- print "buz = ", $a->{'buz'}, "\n";
- print "biz = ", $a->{'biz'}, "\n";
-
-
-
-=head1 OBJECT RELATIONSHIPS
-
-The following demonstrates how one might implement "containing" and "using"
-relationships between objects.
-
- package Bar;
-
- sub new {
- my $type = shift;
- my $self = {};
- $self->{'buz'} = 42;
- bless $self, $type;
- }
-
- package Foo;
-
- sub new {
- my $type = shift;
- my $self = {};
- $self->{'Bar'} = Bar->new;
- $self->{'biz'} = 11;
- bless $self, $type;
- }
-
- package main;
-
- $a = Foo->new;
- print "buz = ", $a->{'Bar'}->{'buz'}, "\n";
- print "biz = ", $a->{'biz'}, "\n";
-
-
-
-=head1 OVERRIDING SUPERCLASS METHODS
-
-The following example demonstrates how to override a superclass method and
-then call the overridden method. The B<SUPER> pseudo-class allows the
-programmer to call an overridden superclass method without actually knowing
-where that method is defined.
-
- package Buz;
- sub goo { print "here's the goo\n" }
-
- package Bar; @ISA = qw( Buz );
- sub google { print "google here\n" }
-
- package Baz;
- sub mumble { print "mumbling\n" }
-
- package Foo;
- @ISA = qw( Bar Baz );
-
- sub new {
- my $type = shift;
- bless [], $type;
- }
- sub grr { print "grumble\n" }
- sub goo {
- my $self = shift;
- $self->SUPER::goo();
- }
- sub mumble {
- my $self = shift;
- $self->SUPER::mumble();
- }
- sub google {
- my $self = shift;
- $self->SUPER::google();
- }
-
- package main;
-
- $foo = Foo->new;
- $foo->mumble;
- $foo->grr;
- $foo->goo;
- $foo->google;
-
-Note that C<SUPER> refers to the superclasses of the current package
-(C<Foo>), not to the superclasses of C<$self>.
-
-
-=head1 USING RELATIONSHIP WITH SDBM
-
-This example demonstrates an interface for the SDBM class. This creates a
-"using" relationship between the SDBM class and the new class Mydbm.
-
- package Mydbm;
-
- require SDBM_File;
- require Tie::Hash;
- @ISA = qw( Tie::Hash );
-
- sub TIEHASH {
- my $type = shift;
- my $ref = SDBM_File->new(@_);
- bless {'dbm' => $ref}, $type;
- }
- sub FETCH {
- my $self = shift;
- my $ref = $self->{'dbm'};
- $ref->FETCH(@_);
- }
- sub STORE {
- my $self = shift;
- if (defined $_[0]){
- my $ref = $self->{'dbm'};
- $ref->STORE(@_);
- } else {
- die "Cannot STORE an undefined key in Mydbm\n";
- }
- }
-
- package main;
- use Fcntl qw( O_RDWR O_CREAT );
-
- tie %foo, "Mydbm", "Sdbm", O_RDWR|O_CREAT, 0640;
- $foo{'bar'} = 123;
- print "foo-bar = $foo{'bar'}\n";
-
- tie %bar, "Mydbm", "Sdbm2", O_RDWR|O_CREAT, 0640;
- $bar{'Cathy'} = 456;
- print "bar-Cathy = $bar{'Cathy'}\n";
-
-=head1 THINKING OF CODE REUSE
-
-One strength of Object-Oriented languages is the ease with which old code
-can use new code. The following examples will demonstrate first how one can
-hinder code reuse and then how one can promote code reuse.
-
-This first example illustrates a class which uses a fully-qualified method
-call to access the "private" method BAZ(). The second example will show
-that it is impossible to override the BAZ() method.
-
- package FOO;
-
- sub new {
- my $type = shift;
- bless {}, $type;
- }
- sub bar {
- my $self = shift;
- $self->FOO::private::BAZ;
- }
-
- package FOO::private;
-
- sub BAZ {
- print "in BAZ\n";
- }
-
- package main;
-
- $a = FOO->new;
- $a->bar;
-
-Now we try to override the BAZ() method. We would like FOO::bar() to call
-GOOP::BAZ(), but this cannot happen because FOO::bar() explicitly calls
-FOO::private::BAZ().
-
- package FOO;
-
- sub new {
- my $type = shift;
- bless {}, $type;
- }
- sub bar {
- my $self = shift;
- $self->FOO::private::BAZ;
- }
-
- package FOO::private;
-
- sub BAZ {
- print "in BAZ\n";
- }
-
- package GOOP;
- @ISA = qw( FOO );
- sub new {
- my $type = shift;
- bless {}, $type;
- }
-
- sub BAZ {
- print "in GOOP::BAZ\n";
- }
-
- package main;
-
- $a = GOOP->new;
- $a->bar;
-
-To create reusable code we must modify class FOO, flattening class
-FOO::private. The next example shows a reusable class FOO which allows the
-method GOOP::BAZ() to be used in place of FOO::BAZ().
-
- package FOO;
-
- sub new {
- my $type = shift;
- bless {}, $type;
- }
- sub bar {
- my $self = shift;
- $self->BAZ;
- }
-
- sub BAZ {
- print "in BAZ\n";
- }
-
- package GOOP;
- @ISA = qw( FOO );
-
- sub new {
- my $type = shift;
- bless {}, $type;
- }
- sub BAZ {
- print "in GOOP::BAZ\n";
- }
-
- package main;
-
- $a = GOOP->new;
- $a->bar;
-
-=head1 CLASS CONTEXT AND THE OBJECT
-
-Use the object to solve package and class context problems. Everything a
-method needs should be available via the object or should be passed as a
-parameter to the method.
-
-A class will sometimes have static or global data to be used by the
-methods. A subclass may want to override that data and replace it with new
-data. When this happens the superclass may not know how to find the new
-copy of the data.
-
-This problem can be solved by using the object to define the context of the
-method. Let the method look in the object for a reference to the data. The
-alternative is to force the method to go hunting for the data ("Is it in my
-class, or in a subclass? Which subclass?"), and this can be inconvenient
-and will lead to hackery. It is better just to let the object tell the
-method where that data is located.
-
- package Bar;
-
- %fizzle = ( 'Password' => 'XYZZY' );
-
- sub new {
- my $type = shift;
- my $self = {};
- $self->{'fizzle'} = \%fizzle;
- bless $self, $type;
- }
-
- sub enter {
- my $self = shift;
-
- # Don't try to guess if we should use %Bar::fizzle
- # or %Foo::fizzle. The object already knows which
- # we should use, so just ask it.
- #
- my $fizzle = $self->{'fizzle'};
-
- print "The word is ", $fizzle->{'Password'}, "\n";
- }
-
- package Foo;
- @ISA = qw( Bar );
-
- %fizzle = ( 'Password' => 'Rumple' );
-
- sub new {
- my $type = shift;
- my $self = Bar->new;
- $self->{'fizzle'} = \%fizzle;
- bless $self, $type;
- }
-
- package main;
-
- $a = Bar->new;
- $b = Foo->new;
- $a->enter;
- $b->enter;
-
-=head1 INHERITING A CONSTRUCTOR
-
-An inheritable constructor should use the second form of bless() which allows
-blessing directly into a specified class. Notice in this example that the
-object will be a BAR not a FOO, even though the constructor is in class FOO.
-
- package FOO;
-
- sub new {
- my $type = shift;
- my $self = {};
- bless $self, $type;
- }
-
- sub baz {
- print "in FOO::baz()\n";
- }
-
- package BAR;
- @ISA = qw(FOO);
-
- sub baz {
- print "in BAR::baz()\n";
- }
-
- package main;
-
- $a = BAR->new;
- $a->baz;
-
-=head1 DELEGATION
-
-Some classes, such as SDBM_File, cannot be effectively subclassed because
-they create foreign objects. Such a class can be extended with some sort of
-aggregation technique such as the "using" relationship mentioned earlier or
-by delegation.
-
-The following example demonstrates delegation using an AUTOLOAD() function to
-perform message-forwarding. This will allow the Mydbm object to behave
-exactly like an SDBM_File object. The Mydbm class could now extend the
-behavior by adding custom FETCH() and STORE() methods, if this is desired.
-
- package Mydbm;
-
- require SDBM_File;
- require Tie::Hash;
- @ISA = qw(Tie::Hash);
-
- sub TIEHASH {
- my $type = shift;
- my $ref = SDBM_File->new(@_);
- bless {'delegate' => $ref};
- }
-
- sub AUTOLOAD {
- my $self = shift;
-
- # The Perl interpreter places the name of the
- # message in a variable called $AUTOLOAD.
-
- # DESTROY messages should never be propagated.
- return if $AUTOLOAD =~ /::DESTROY$/;
-
- # Remove the package name.
- $AUTOLOAD =~ s/^Mydbm:://;
-
- # Pass the message to the delegate.
- $self->{'delegate'}->$AUTOLOAD(@_);
- }
-
- package main;
- use Fcntl qw( O_RDWR O_CREAT );
-
- tie %foo, "Mydbm", "adbm", O_RDWR|O_CREAT, 0640;
- $foo{'bar'} = 123;
- print "foo-bar = $foo{'bar'}\n";
-
-=head1 SEE ALSO
-
-L<perlboot>, L<perltoot>, L<perltooc>.
+=cut
Property changes on: trunk/contrib/perl/pod/perlbot.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlcall.pod
===================================================================
--- trunk/contrib/perl/pod/perlcall.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlcall.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -28,7 +28,7 @@
=item * An Event-Driven Program
The classic example of where callbacks are used is when writing an
-event driven program, such as for an X windows application. In this case
+event driven program, such as for an X11 application. In this case
you register functions to be called whenever specific events occur,
e.g., a mouse button is pressed, the cursor moves into a window or a
menu item is selected.
@@ -56,7 +56,7 @@
I32 call_sv(SV* sv, I32 flags);
I32 call_pv(char *subname, I32 flags);
I32 call_method(char *methname, I32 flags);
- I32 call_argv(char *subname, I32 flags, register char **argv);
+ I32 call_argv(char *subname, I32 flags, char **argv);
The key function is I<call_sv>. All the other functions are
fairly simple wrappers which make it easier to call Perl subroutines in
@@ -203,7 +203,6 @@
It indicates to the subroutine being called that it is executing in a
list context (if it executes I<wantarray> the result will be true).
-
=item 2.
It ensures that all items returned from the subroutine will be
@@ -1032,8 +1031,8 @@
call_pv(name, G_DISCARD|G_NOARGS);
That is fine as far as it goes. The thing is, the Perl subroutine
-can be specified as only a string. For Perl 4 this was adequate,
-but Perl 5 allows references to subroutines and anonymous subroutines.
+can be specified as only a string, however, Perl allows references
+to subroutines and anonymous subroutines.
This is where I<call_sv> is useful.
The code below for I<CallSubSV> is identical to I<CallSubPV> except
@@ -1901,7 +1900,7 @@
dMULTICALL; /* Declare local variables */
I32 gimme = G_SCALAR; /* context of the call: G_SCALAR,
- * G_LIST, or G_VOID */
+ * G_ARRAY, or G_VOID */
PUSH_MULTICALL(cv); /* Set up the context for calling cv,
and set local vars appropriately */
Property changes on: trunk/contrib/perl/pod/perlcall.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlcheat.pod
===================================================================
--- trunk/contrib/perl/pod/perlcheat.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlcheat.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -10,68 +10,71 @@
=head2 The sheet
- CONTEXTS SIGILS ARRAYS HASHES
- void $scalar whole: @array %hash
- scalar @array slice: @array[0, 2] @hash{'a', 'b'}
- list %hash element: $array[0] $hash{'a'}
- &sub
- *glob SCALAR VALUES
- number, string, reference, glob, undef
+ CONTEXTS SIGILS ref ARRAYS HASHES
+ void $scalar SCALAR @array %hash
+ scalar @array ARRAY @array[0, 2] @hash{'a', 'b'}
+ list %hash HASH $array[0] $hash{'a'}
+ &sub CODE
+ *glob GLOB SCALAR VALUES
+ FORMAT number, string, ref, glob, undef
REFERENCES
- \ references $$foo[1] aka $foo->[1]
- $@%&* dereference $$foo{bar} aka $foo->{bar}
- [] anon. arrayref ${$$foo[1]}[2] aka $foo->[1]->[2]
- {} anon. hashref ${$$foo[1]}[2] aka $foo->[1][2]
- \() list of refs
- NUMBERS vs STRINGS LINKS
- OPERATOR PRECEDENCE = = perl.plover.com
- -> + . search.cpan.org
- ++ -- == != eq ne cpan.org
- ** < > <= >= lt gt le ge pm.org
- ! ~ \ u+ u- <=> cmp tpj.com
- =~ !~ perldoc.com
- * / % x SYNTAX
- + - . for (LIST) { }, for (a;b;c) { }
- << >> while ( ) { }, until ( ) { }
- named uops if ( ) { } elsif ( ) { } else { }
- < > <= >= lt gt le ge unless ( ) { } elsif ( ) { } else { }
- == != <=> eq ne cmp ~~ for equals foreach (ALWAYS)
+ \ reference $$foo[1] aka $foo->[1]
+ $@%&* dereference $$foo{bar} aka $foo->{bar}
+ [] anon. arrayref ${$$foo[1]}[2] aka $foo->[1]->[2]
+ {} anon. hashref ${$$foo[1]}[2] aka $foo->[1][2]
+ \() list of refs
+ SYNTAX
+ OPERATOR PRECEDENCE foreach (LIST) { } for (a;b;c) { }
+ -> while (e) { } until (e) { }
+ ++ -- if (e) { } elsif (e) { } else { }
+ ** unless (e) { } elsif (e) { } else { }
+ ! ~ \ u+ u- given (e) { when (e) {} default {} }
+ =~ !~
+ * / % x NUMBERS vs STRINGS FALSE vs TRUE
+ + - . = = undef, "", 0, "0"
+ << >> + . anything else
+ named uops == != eq ne
+ < > <= >= lt gt le ge < > <= >= lt gt le ge
+ == != <=> eq ne cmp ~~ <=> cmp
&
- | ^ REGEX METACHARS REGEX MODIFIERS
- && ^ string begin /i case insens.
- || // $ str. end (before \n) /m line based ^$
- .. ... + one or more /s . includes \n
- ?: * zero or more /x ign. wh.space
- = += -= *= etc. ? zero or one /g global
- , => {3,7} repeat in range /o cmpl pat. once
- list ops () capture
- not (?:) no capture REGEX CHARCLASSES
- and [] character class . == [^\n]
- or xor | alternation \s == whitespace
- \b word boundary \w == word characters
- \z string end \d == digits
- DO \S, \W and \D negate
- use strict; DON'T
- use warnings; "$foo" LINKS
- my $var; $$variable_name perl.com
- open() or die $!; `$userinput` use.perl.org
- use Modules; /$userinput/ perl.apache.org
-
+ | ^ REGEX MODIFIERS REGEX METACHARS
+ && /i case insensitive ^ string begin
+ || // /m line based ^$ $ str end (bfr \n)
+ .. ... /s . includes \n + one or more
+ ?: /x ignore wh.space * zero or more
+ = += last goto /p preserve ? zero or one
+ , => /a ASCII /aa safe {3,7} repeat in range
+ list ops /l locale /d dual | alternation
+ not /u Unicode [] character class
+ and /e evaluate /ee rpts \b word boundary
+ or xor /g global \z string end
+ /o compile pat once () capture
+ DEBUG (?:p) no capture
+ -MO=Deparse REGEX CHARCLASSES (?#t) comment
+ -MO=Terse . [^\n] (?=p) ZW pos ahead
+ -D## \s whitespace (?!p) ZW neg ahead
+ -d:Trace \w word chars (?<=p) ZW pos behind \K
+ \d digits (?<!p) ZW neg behind
+ CONFIGURATION \pP named property (?>p) no backtrack
+ perl -V:ivsize \h horiz.wh.space (?|p|p)branch reset
+ \R linebreak (?<n>p)named capture
+ \S \W \D \H negate \g{n} ref to named cap
+ \K keep left part
FUNCTION RETURN LISTS
stat localtime caller SPECIAL VARIABLES
- 0 dev 0 second 0 package $_ default variable
- 1 ino 1 minute 1 filename $0 program name
- 2 mode 2 hour 2 line $/ input separator
- 3 nlink 3 day 3 subroutine $\ output separator
- 4 uid 4 month-1 4 hasargs $| autoflush
- 5 gid 5 year-1900 5 wantarray $! sys/libcall error
- 6 rdev 6 weekday 6 evaltext $@ eval error
- 7 size 7 yearday 7 is_require $$ process ID
- 8 atime 8 is_dst 8 hints $. line number
- 9 mtime 9 bitmask @ARGV command line args
- 10 ctime just use @INC include paths
- 11 blksz POSIX:: 3..9 only @_ subroutine args
- 12 blcks strftime! with EXPR %ENV environment
+ 0 dev 0 second 0 package $_ default variable
+ 1 ino 1 minute 1 filename $0 program name
+ 2 mode 2 hour 2 line $/ input separator
+ 3 nlink 3 day 3 subroutine $\ output separator
+ 4 uid 4 month-1 4 hasargs $| autoflush
+ 5 gid 5 year-1900 5 wantarray $! sys/libcall error
+ 6 rdev 6 weekday 6 evaltext $@ eval error
+ 7 size 7 yearday 7 is_require $$ process ID
+ 8 atime 8 is_dst 8 hints $. line number
+ 9 mtime 9 bitmask @ARGV command line args
+ 10 ctime 10 hinthash @INC include paths
+ 11 blksz 3..10 only @_ subroutine args
+ 12 blcks with EXPR %ENV environment
=head1 ACKNOWLEDGEMENTS
Property changes on: trunk/contrib/perl/pod/perlcheat.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlclib.pod
===================================================================
--- trunk/contrib/perl/pod/perlclib.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlclib.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -99,8 +99,8 @@
Instead Of: Use:
- t* p = malloc(n) Newx(id, p, n, t)
- t* p = calloc(n, s) Newxz(id, p, n, t)
+ t* p = malloc(n) Newx(p, n, t)
+ t* p = calloc(n, s) Newxz(p, n, t)
p = realloc(p, n) Renew(p, n, t)
memcpy(dst, src, n) Copy(src, dst, n, t)
memmove(dst, src, n) Move(src, dst, n, t)
Property changes on: trunk/contrib/perl/pod/perlclib.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlcommunity.pod
===================================================================
--- trunk/contrib/perl/pod/perlcommunity.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlcommunity.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -65,11 +65,17 @@
Perl-related literature), perl.com provides current Perl news, articles, and
resources for Perl developers as well as a directory of other useful websites.
+=item L<http://blogs.perl.org/>
+
+Many members of the community have a Perl-related blog on this site. If
+you'd like to join them, you can sign up for free.
+
=item L<http://use.perl.org/>
-use Perl; provides a slashdot-style Perl news website covering all things Perl,
-from minutes of the meetings of the Perl 6 Design team to conference
-announcements with (ir)relevant discussion.
+use Perl; used to provide a slashdot-style news/blog website covering all
+things Perl, from minutes of the meetings of the Perl 6 Design team to
+conference announcements with (ir)relevant discussion. It no longer accepts
+updates, but you can still use the site to read old entries and comments.
=back
@@ -83,6 +89,12 @@
for individuals to polish, improve, and showcase their Perl skills." and "A
community which allows everyone to grow and learn from each other."
+=item L<http://stackoverflow.com/>
+
+Stack Overflow is a free question-and-answer site for programmers. It's not
+focussed solely on Perl, but it does have an active group of users who do
+their best to help people with their Perl programming questions.
+
=back
=head2 User Groups
Property changes on: trunk/contrib/perl/pod/perlcommunity.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlcompile.pod
===================================================================
--- trunk/contrib/perl/pod/perlcompile.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlcompile.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlcompile.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldata.pod
===================================================================
--- trunk/contrib/perl/pod/perldata.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldata.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -24,8 +24,9 @@
be a chain of identifiers, separated by C<::> (or by the slightly
archaic C<'>); all but the last are interpreted as names of packages,
to locate the namespace in which to look up the final identifier
-(see L<perlmod/Packages> for details). It's possible to substitute
-for a simple identifier, an expression that produces a reference
+(see L<perlmod/Packages> for details). For a more in-depth discussion
+on identifiers, see L<Identifier parsing>. It's possible to
+substitute for a simple identifier, an expression that produces a reference
to the value at runtime. This is described in more detail below
and in L<perlref>.
X<identifier>
@@ -104,6 +105,105 @@
significance to Perl. For instance, C<$$> is the current process
id.)
+=head2 Identifier parsing
+X<identifiers>
+
+Up until Perl 5.18, the actual rules of what a valid identifier
+was were a bit fuzzy. However, in general, anything defined here should
+work on previous versions of Perl, while the opposite -- edge cases
+that work in previous versions, but aren't defined here -- probably
+won't work on newer versions.
+As an important side note, please note that the following only applies
+to bareword identifiers as found in Perl source code, not identifiers
+introduced through symbolic references, which have much fewer
+restrictions.
+If working under the effect of the C<use utf8;> pragma, the following
+rules apply:
+
+ / (?[ ( \p{Word} & \p{XID_Start} ) + [_] ]) \p{XID_Continue}* /x
+
+If not under C<use utf8>, the source is treated as ASCII + 128 extra
+controls, and identifiers should match
+
+ / (?aa) (?!\d) \w+ /x
+
+That is, any word character in the ASCII range, as long as the first
+character is not a digit.
+
+There are two package separators in Perl: A double colon (C<::>) and a single
+quote (C<'>). Normal identifiers can start or end with a double colon, and
+can contain several parts delimited by double colons.
+Single quotes have similar rules, but with the exception that they are not
+legal at the end of an identifier: That is, C<$'foo> and C<$foo'bar> are
+legal, but C<$foo'bar'> are not.
+
+
+Finally, if the identifier is preceded by a sigil --
+More so, normal identifiers can start or end with any number
+of double colons (::), and can contain several parts delimited
+by double colons.
+And additionally, if the identifier is preceded by a sigil --
+that is, if the identifier is part of a variable name -- it
+may optionally be enclosed in braces.
+
+While you can mix double colons with singles quotes, the quotes must come
+after the colons: C<$::::'foo> and C<$foo::'bar> are legal, but C<$::'::foo>
+and C<$foo'::bar> are not.
+
+Put together, a grammar to match a basic identifier becomes
+
+ /
+ (?(DEFINE)
+ (?<variable>
+ (?&sigil)
+ (?:
+ (?&normal_identifier)
+ | \{ \s* (?&normal_identifier) \s* \}
+ )
+ )
+ (?<normal_identifier>
+ (?: :: )* '?
+ (?&basic_identifier)
+ (?: (?= (?: :: )+ '? | (?: :: )* ' ) (?&normal_identifier) )?
+ (?: :: )*
+ )
+ (?<basic_identifier>
+ # is use utf8 on?
+ (?(?{ (caller(0))[8] & $utf8::hint_bits })
+ (?&Perl_XIDS) \p{XID_Continue}*
+ | (?aa) (?!\d) \w+
+ )
+ )
+ (?<sigil> [&*\$\@\%])
+ (?<Perl_XIDS> (?[ ( \p{Word} & \p{XID_Start} ) + [_] ]) )
+ )
+ /x
+
+Meanwhile, special identifiers don't follow the above rules; For the most
+part, all of the identifiers in this category have a special meaning given
+by Perl. Because they have special parsing rules, these generally can't be
+fully-qualified. They come in four forms:
+
+=over
+
+=item A sigil, followed solely by digits matching \p{POSIX_Digit}, like C<$0>,
+C<$1>, or C<$10000>.
+
+=item A sigil, followed by either a caret and a single POSIX uppercase letter,
+like C<$^V> or C<$^W>, or a sigil followed by a literal control character
+matching the C<\p{POSIX_Cntrl}> property. Due to a historical oddity, if not
+running under C<use utf8>, the 128 extra controls in the C<[0x80-0xff]> range
+may also be used in length one variables.
+
+=item Similar to the above, a sigil, followed by bareword text in brackets,
+where the first character is either a caret followed by an uppercase letter,
+or a literal control, like C<${^GLOBAL_PHASE}> or C<${\7LOBAL_PHASE}>.
+
+=item A sigil followed by a single character matching the C<\p{POSIX_Punct}>
+property, like C<$!> or C<%+>.
+
+=back
+
=head2 Context
X<context> X<scalar context> X<list context>
@@ -179,8 +279,9 @@
references are strongly-typed, uncastable pointers with builtin
reference-counting and destructor invocation.
-A scalar value is interpreted as TRUE in the Boolean sense if it is not
-the null string or the number 0 (or its string equivalent, "0"). The
+A scalar value is interpreted as FALSE in the Boolean sense
+if it is undefined, the null string or the number 0 (or its
+string equivalent, "0"), and TRUE if it is anything else. The
Boolean context is just a special kind of scalar context where no
conversion to a string or a number is ever performed.
X<boolean> X<bool> X<true> X<false> X<truth>
@@ -231,8 +332,7 @@
Assigning to C<$#days> actually changes the length of the array.
Shortening an array this way destroys intervening values. Lengthening
an array that was previously shortened does not recover values
-that were in those elements. (It used to do so in Perl 4, but we
-had to break this to make sure destructors were called when expected.)
+that were in those elements.
X<$#> X<array, length>
You can also gain some minuscule measure of efficiency by pre-extending
@@ -251,14 +351,6 @@
always true:
X<array, length>
- scalar(@whatever) == $#whatever - $[ + 1;
-
-Version 5 of Perl changed the semantics of C<$[>: files that don't set
-the value of C<$[> no longer need to worry about whether another
-file changed its value. (In other words, use of C<$[> is deprecated.)
-So in general you can assume that
-X<$[>
-
scalar(@whatever) == $#whatever + 1;
Some programmers choose to use an explicit conversion so as to
@@ -302,7 +394,9 @@
0b011011 # binary
You are allowed to use underscores (underbars) in numeric literals
-between digits for legibility. You could, for example, group binary
+between digits for legibility (but not multiple underscores in a row:
+C<23__500> is not legal; C<23_500> is).
+You could, for example, group binary
digits by threes (as for a Unix-style mode argument such as 0b110_100_100)
or by fours (to represent nibbles, as in 0b1010_0110) or in other groups.
X<number, literal>
@@ -360,8 +454,8 @@
$0 and the $s variables in the (presumably) non-existent package
C<who>.
-In fact, an identifier within such curlies is forced to be a string,
-as is any simple identifier within a hash subscript. Neither need
+In fact, a simple identifier within such curlies is forced to be
+a string, and likewise within a hash subscript. Neither need
quoting. Our earlier example, C<$days{'Feb'}> can be written as
C<$days{Feb}> and the quotes will be assumed automatically. But
anything more complicated in the subscript will be interpreted as an
@@ -403,12 +497,16 @@
The special literals __FILE__, __LINE__, and __PACKAGE__
represent the current filename, line number, and package name at that
-point in your program. They may be used only as separate tokens; they
+point in your program. __SUB__ gives a reference to the current
+subroutine. They may be used only as separate tokens; they
will not be interpolated into strings. If there is no current package
(due to an empty C<package;> directive), __PACKAGE__ is the undefined
-value. (But the empty C<package;> is no longer supported, as of version
-5.10.)
-X<__FILE__> X<__LINE__> X<__PACKAGE__> X<line> X<file> X<package>
+value. (But the empty C<package;> is no longer supported, as of version
+5.10.) Outside of a subroutine, __SUB__ is the undefined value. __SUB__
+is only available in 5.16 or higher, and only with a C<use v5.16> or
+C<use feature "current_sub"> declaration.
+X<__FILE__> X<__LINE__> X<__PACKAGE__> X<__SUB__>
+X<line> X<file> X<package>
The two control characters ^D and ^Z, and the tokens __END__ and __DATA__
may be used to indicate the logical end of the script before the actual
@@ -417,12 +515,13 @@
Text after __DATA__ may be read via the filehandle C<PACKNAME::DATA>,
where C<PACKNAME> is the package that was current when the __DATA__
token was encountered. The filehandle is left open pointing to the
-contents after __DATA__. It is the program's responsibility to
-C<close DATA> when it is done reading from it. For compatibility with
-older scripts written before __DATA__ was introduced, __END__ behaves
-like __DATA__ in the top level script (but not in files loaded with
-C<require> or C<do>) and leaves the remaining contents of the
-file accessible via C<main::DATA>.
+line after __DATA__. The program should C<close DATA> when it is done
+reading from it. (Leaving it open leaks filehandles if the module is
+reloaded for any reason, so it's a safer practice to close it.) For
+compatibility with older scripts written before __DATA__ was
+introduced, __END__ behaves like __DATA__ in the top level script (but
+not in files loaded with C<require> or C<do>) and leaves the remaining
+contents of the file accessible via C<main::DATA>.
See L<SelfLoader> for more description of __DATA__, and
an example of its use. Note that you cannot read from the DATA
@@ -545,7 +644,7 @@
This interpolation combines with the facts that the opening
and closing parentheses are optional (except when necessary for
precedence) and lists may end with an optional comma to mean that
-multiple commas within lists are legal syntax. The list C<1,,3> is a
+multiple commas within lists are legal syntax. The list C<1,,3> is a
concatenation of two lists, C<1,> and C<3>, the first of which ends
with that optional comma. C<1,,3> is C<(1,),(3)> is C<1,3> (And
similarly for C<1,,,3> is C<(1,),(,),3> is C<1,3> and so on.) Not that
@@ -592,7 +691,7 @@
It's also the source of a useful idiom for executing a function or
performing an operation in list context and then counting the number of
return values, by assigning to an empty list and then using that
-assignment in scalar context. For example, this code:
+assignment in scalar context. For example, this code:
$count = () = $string =~ /\d+/g;
@@ -599,9 +698,9 @@
will place into $count the number of digit groups found in $string.
This happens because the pattern match is in list context (since it
is being assigned to the empty list), and will therefore return a list
-of all matching parts of the string. The list assignment in scalar
+of all matching parts of the string. The list assignment in scalar
context will translate that into the number of elements (here, the
-number of times the pattern matched) and assign that to $count. Note
+number of times the pattern matched) and assign that to $count. Note
that simply using
$count = $string =~ /\d+/g;
@@ -635,8 +734,8 @@
pairs. The C<< => >> operator is mostly just a more visually distinctive
synonym for a comma, but it also arranges for its left-hand operand to be
interpreted as a string if it's a bareword that would be a legal simple
-identifier. C<< => >> doesn't quote compound identifiers, that contain
-double colons. This makes it nice for initializing hashes:
+identifier. C<< => >> doesn't quote compound identifiers, that contain
+double colons. This makes it nice for initializing hashes:
%map = (
red => 0x00f,
@@ -666,6 +765,29 @@
mean that it comes out in that order. See L<perlfunc/sort> for examples
of how to arrange for an output ordering.
+If a key appears more than once in the initializer list of a hash, the last
+occurrence wins:
+
+ %circle = (
+ center => [5, 10],
+ center => [27, 9],
+ radius => 100,
+ color => [0xDF, 0xFF, 0x00],
+ radius => 54,
+ );
+
+ # same as
+ %circle = (
+ center => [27, 9],
+ color => [0xDF, 0xFF, 0x00],
+ radius => 54,
+ );
+
+This can be used to provide overridable configuration defaults:
+
+ # values in %args take priority over %config_defaults
+ %config = (%config_defaults, %args);
+
=head2 Subscripts
An array can be accessed one scalar at a
@@ -676,12 +798,12 @@
@myarray = (5, 50, 500, 5000);
print "The Third Element is", $myarray[2], "\n";
-The array indices start with 0. A negative subscript retrieves its
+The array indices start with 0. A negative subscript retrieves its
value from the end. In our example, C<$myarray[-1]> would have been
5000, and C<$myarray[-2]> would have been 500.
Hash subscripts are similar, only instead of square brackets curly brackets
-are used. For example:
+are used. For example:
%scientists =
(
@@ -697,6 +819,20 @@
$dir = (getpwnam("daemon"))[7];
+=head2 Multi-dimensional array emulation
+
+Multidimensional arrays may be emulated by subscripting a hash with a
+list. The elements of the list are joined with the subscript separator
+(see L<perlvar/$;>).
+
+ $foo{$a,$b,$c}
+
+is equivalent to
+
+ $foo{join($;, $a, $b, $c)}
+
+The default subscript separator is "\034", the same as SUBSEP in B<awk>.
+
=head2 Slices
X<slice> X<array, slice> X<hash, slice>
@@ -741,7 +877,6 @@
@a = ()[1,0]; # @a has no elements
@b = (@a)[0,1]; # @b has no elements
- @c = (0,1)[2,3]; # @c has no elements
But:
@@ -748,6 +883,12 @@
@a = (1)[1,0]; # @a has two elements
@b = (1,undef)[1,0,2]; # @b has three elements
+More generally, a slice yields the empty list if it indexes only
+beyond the end of a list:
+
+ @a = (1)[ 1,2]; # @a has no elements
+ @b = (1)[0,1,2]; # @b has three elements
+
This makes it easy to write loops that terminate when a null list
is returned:
@@ -827,7 +968,7 @@
Now that we have the C<*foo{THING}> notation, typeglobs aren't used as much
for filehandle manipulations, although they're still needed to pass brand
-new file and directory handles into or out of functions. That's because
+new file and directory handles into or out of functions. That's because
C<*HANDLE{IO}> only works if HANDLE has already been used as a handle.
In other words, C<*FH> must be used to create new symbol table entries;
C<*foo{THING}> cannot. When in doubt, use C<*FH>.
@@ -835,10 +976,10 @@
All functions that are capable of creating filehandles (open(),
opendir(), pipe(), socketpair(), sysopen(), socket(), and accept())
automatically create an anonymous filehandle if the handle passed to
-them is an uninitialized scalar variable. This allows the constructs
+them is an uninitialized scalar variable. This allows the constructs
such as C<open(my $fh, ...)> and C<open(local $fh,...)> to be used to
create filehandles that will conveniently be closed automatically when
-the scope ends, provided there are no other references to them. This
+the scope ends, provided there are no other references to them. This
largely eliminates the need for typeglobs when opening filehandles
that must be passed around, as in the following example:
@@ -862,8 +1003,8 @@
Another way to create anonymous filehandles is with the Symbol
module or with the IO::Handle module and its ilk. These modules
have the advantage of not hiding different types of the same name
-during the local(). See the bottom of L<perlfunc/"open FILEHANDLE">
-for an example.
+during the local(). See the bottom of L<perlfunc/open> for an
+example.
=head1 SEE ALSO
Property changes on: trunk/contrib/perl/pod/perldata.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldbmfilter.pod
===================================================================
--- trunk/contrib/perl/pod/perldbmfilter.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldbmfilter.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -35,7 +35,6 @@
If a filter has been installed with this method, it will be invoked
every time you write a value to a DBM database.
-
=item B<filter_fetch_key>
If a filter has been installed with this method, it will be invoked
Property changes on: trunk/contrib/perl/pod/perldbmfilter.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldebguts.pod
===================================================================
--- trunk/contrib/perl/pod/perldebguts.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldebguts.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -38,7 +38,6 @@
file compiled by Perl. The same is also true for C<eval>ed strings
that contain subroutines, or which are currently being executed.
The $filename for C<eval>ed strings looks like C<(eval 34)>.
-Code assertions in regexes look like C<(re_eval 19)>.
Values in this array are magical in numeric context: they compare
equal to zero only if the line is not breakable.
@@ -53,7 +52,7 @@
The same holds for evaluated strings that contain subroutines, or
which are currently being executed. The $filename for C<eval>ed strings
-looks like C<(eval 34)> or C<(re_eval 19)>.
+looks like C<(eval 34)>.
=item *
@@ -60,7 +59,7 @@
Each scalar C<${"_<$filename"}> contains C<"_<$filename">. This is
also the case for evaluated strings that contain subroutines, or
which are currently being executed. The $filename for C<eval>ed
-strings looks like C<(eval 34)> or C<(re_eval 19)>.
+strings looks like C<(eval 34)>.
=item *
@@ -81,7 +80,7 @@
A hash C<%DB::sub> is maintained, whose keys are subroutine names
and whose values have the form C<filename:startline-endline>.
C<filename> has the form C<(eval 34)> for subroutines defined inside
-C<eval>s, or C<(re_eval 19)> for those within regex code assertions.
+C<eval>s.
=item *
@@ -227,7 +226,7 @@
Loading DB routines from perl5db.pl patch level 0.94
Emacs support available.
- Enter h or `h h' for help.
+ Enter h or 'h h' for help.
main::(-e:1): 0
DB<1> sub foo { 14 }
@@ -412,7 +411,7 @@
The debugging output at compile time looks like this:
- Compiling REx `[bc]d(ef*g)+h[ij]k$'
+ Compiling REx '[bc]d(ef*g)+h[ij]k$'
size 45 Got 364 bytes for offset annotations.
first at 1
rarest char g at 0
@@ -433,8 +432,8 @@
42: EXACT <k>(44)
44: EOL(45)
45: END(0)
- anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
- stclass `ANYOF[bc]' minlen 7
+ anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
+ stclass 'ANYOF[bc]' minlen 7
Offsets: [45]
1[4] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 0[0] 5[1]
0[0] 12[1] 0[0] 6[1] 0[0] 7[1] 0[0] 9[1] 8[1] 0[0] 10[1] 0[0]
@@ -450,8 +449,8 @@
The
- anchored `de' at 1 floating `gh' at 3..2147483647 (checking floating)
- stclass `ANYOF[bc]' minlen 7
+ anchored 'de' at 1 floating 'gh' at 3..2147483647 (checking floating)
+ stclass 'ANYOF[bc]' minlen 7
line (split into two lines above) contains optimizer
information. In the example shown, the optimizer found that the match
@@ -520,7 +519,7 @@
=back
If a substring is known to match at end-of-line only, it may be
-followed by C<$>, as in C<floating `k'$>.
+followed by C<$>, as in C<floating 'k'$>.
The optimizer-specific information is used to avoid entering (a slow) regex
engine on strings that will not definitely match. If the C<isall> flag
@@ -536,237 +535,259 @@
Here are the possible types, with short descriptions:
+=for comment
+This table is generated by regen/regcomp.pl. Any changes made here
+will be lost.
+
+=for regcomp.pl begin
+
# TYPE arg-description [num-args] [longjump-len] DESCRIPTION
# Exit points
- END no End of program.
- SUCCEED no Return from a subroutine, basically.
+ END no End of program.
+ SUCCEED no Return from a subroutine, basically.
+
# Anchors:
- BOL no Match "" at beginning of line.
- MBOL no Same, assuming multiline.
- SBOL no Same, assuming singleline.
- EOS no Match "" at end of string.
- EOL no Match "" at end of line.
- MEOL no Same, assuming multiline.
- SEOL no Same, assuming singleline.
- BOUND no Match "" at any word boundary using native charset
- semantics for non-utf8
- BOUNDL no Match "" at any locale word boundary
- BOUNDU no Match "" at any word boundary using Unicode semantics
- BOUNDA no Match "" at any word boundary using ASCII semantics
- NBOUND no Match "" at any word non-boundary using native charset
- semantics for non-utf8
- NBOUNDL no Match "" at any locale word non-boundary
- NBOUNDU no Match "" at any word non-boundary using Unicode semantics
- NBOUNDA no Match "" at any word non-boundary using ASCII semantics
- GPOS no Matches where last m//g left off.
+ BOL no Match "" at beginning of line.
+ MBOL no Same, assuming multiline.
+ SBOL no Same, assuming singleline.
+ EOS no Match "" at end of string.
+ EOL no Match "" at end of line.
+ MEOL no Same, assuming multiline.
+ SEOL no Same, assuming singleline.
+ BOUND no Match "" at any word boundary using
+ native charset semantics for non-utf8
+ BOUNDL no Match "" at any locale word boundary
+ BOUNDU no Match "" at any word boundary using
+ Unicode semantics
+ BOUNDA no Match "" at any word boundary using ASCII
+ semantics
+ NBOUND no Match "" at any word non-boundary using
+ native charset semantics for non-utf8
+ NBOUNDL no Match "" at any locale word non-boundary
+ NBOUNDU no Match "" at any word non-boundary using
+ Unicode semantics
+ NBOUNDA no Match "" at any word non-boundary using
+ ASCII semantics
+ GPOS no Matches where last m//g left off.
# [Special] alternatives:
- REG_ANY no Match any one character (except newline).
- SANY no Match any one character.
- CANY no Match any one byte.
- ANYOF sv Match character in (or not in) this class, single char
- match only
- ANYOFV sv Match character in (or not in) this class, can
- match-multiple chars
- ALNUM no Match any alphanumeric character using native charset
- semantics for non-utf8
- ALNUML no Match any alphanumeric char in locale
- ALNUMU no Match any alphanumeric char using Unicode semantics
- ALNUMA no Match [A-Za-z_0-9]
- NALNUM no Match any non-alphanumeric character using native charset
- semantics for non-utf8
- NALNUML no Match any non-alphanumeric char in locale
- NALNUMU no Match any non-alphanumeric char using Unicode semantics
- NALNUMA no Match [^A-Za-z_0-9]
- SPACE no Match any whitespace character using native charset
- semantics for non-utf8
- SPACEL no Match any whitespace char in locale
- SPACEU no Match any whitespace char using Unicode semantics
- SPACEA no Match [ \t\n\f\r]
- NSPACE no Match any non-whitespace character using native charset
- semantics for non-utf8
- NSPACEL no Match any non-whitespace char in locale
- NSPACEU no Match any non-whitespace char using Unicode semantics
- NSPACEA no Match [^ \t\n\f\r]
- DIGIT no Match any numeric character using native charset semantics
- for non-utf8
- DIGITL no Match any numeric character in locale
- DIGITA no Match [0-9]
- NDIGIT no Match any non-numeric character using native charset
- i semantics for non-utf8
- NDIGITL no Match any non-numeric character in locale
- NDIGITA no Match [^0-9]
- CLUMP no Match any extended grapheme cluster sequence
+ REG_ANY no Match any one character (except newline).
+ SANY no Match any one character.
+ CANY no Match any one byte.
+ ANYOF sv Match character in (or not in) this
+ class, single char match only
+ ANYOF_WARN_SUPER sv Match character in (or not in) this
+ class, warn (if enabled) upon matching a
+ char above Unicode max;
+ ANYOF_SYNTHETIC sv Synthetic start class
+ POSIXD none Some [[:class:]] under /d; the FLAGS
+ field gives which one
+ POSIXL none Some [[:class:]] under /l; the FLAGS
+ field gives which one
+ POSIXU none Some [[:class:]] under /u; the FLAGS
+ field gives which one
+ POSIXA none Some [[:class:]] under /a; the FLAGS
+ field gives which one
+ NPOSIXD none complement of POSIXD, [[:^class:]]
+ NPOSIXL none complement of POSIXL, [[:^class:]]
+ NPOSIXU none complement of POSIXU, [[:^class:]]
+ NPOSIXA none complement of POSIXA, [[:^class:]]
+
+ CLUMP no Match any extended grapheme cluster
+ sequence
+
# Alternation
- # BRANCH The set of branches constituting a single choice are hooked
- # together with their "next" pointers, since precedence prevents
- # anything being concatenated to any individual branch. The
- # "next" pointer of the last BRANCH in a choice points to the
- # thing following the whole choice. This is also where the
- # final "next" pointer of each individual branch points; each
- # branch starts with the operand node of a BRANCH node.
+ # BRANCH The set of branches constituting a single choice are
+ # hooked together with their "next" pointers, since
+ # precedence prevents anything being concatenated to
+ # any individual branch. The "next" pointer of the last
+ # BRANCH in a choice points to the thing following the
+ # whole choice. This is also where the final "next"
+ # pointer of each individual branch points; each branch
+ # starts with the operand node of a BRANCH node.
#
- BRANCH node Match this alternative, or the next...
+ BRANCH node Match this alternative, or the next...
# Back pointer
- # BACK Normal "next" pointers all implicitly point forward; BACK
- # exists to make loop structures possible.
+ # BACK Normal "next" pointers all implicitly point forward;
+ # BACK exists to make loop structures possible.
# not used
- BACK no Match "", "next" ptr points backward.
+ BACK no Match "", "next" ptr points backward.
# Literals
- EXACT str Match this string (preceded by length).
- EXACTF str Match this string, folded, native charset semantics for
- non-utf8 (prec. by length).
- EXACTFL str Match this string, folded in locale (w/len).
- EXACTFU str Match this string, folded, Unicode semantics for non-utf8
- (prec. by length).
- EXACTFA str Match this string, folded, Unicode semantics for non-utf8,
- but no ASCII-range character matches outside ASCII (prec.
- by length),.
+ EXACT str Match this string (preceded by length).
+ EXACTF str Match this non-UTF-8 string (not
+ guaranteed to be folded) using /id rules
+ (w/len).
+ EXACTFL str Match this string (not guaranteed to be
+ folded) using /il rules (w/len).
+ EXACTFU str Match this string (folded iff in UTF-8,
+ length in folding doesn't change if not
+ in UTF-8) using /iu rules (w/len).
+ EXACTFA str Match this string (not guaranteed to be
+ folded) using /iaa rules (w/len).
+ EXACTFU_SS str Match this string (folded iff in UTF-8,
+ length in folding may change even if not
+ in UTF-8) using /iu rules (w/len).
+ EXACTFU_TRICKYFOLD str Match this folded UTF-8 string using /iu
+ rules
# Do nothing types
- NOTHING no Match empty string.
+ NOTHING no Match empty string.
# A variant of above which delimits a group, thus stops optimizations
- TAIL no Match empty string. Can jump here from outside.
+ TAIL no Match empty string. Can jump here from
+ outside.
# Loops
- # STAR,PLUS '?', and complex '*' and '+', are implemented as circular
- # BRANCH structures using BACK. Simple cases (one character
- # per match) are implemented with STAR and PLUS for speed
- # and to minimize recursive plunges.
+ # STAR,PLUS '?', and complex '*' and '+', are implemented as
+ # circular BRANCH structures using BACK. Simple cases
+ # (one character per match) are implemented with STAR
+ # and PLUS for speed and to minimize recursive plunges.
#
- STAR node Match this (simple) thing 0 or more times.
- PLUS node Match this (simple) thing 1 or more times.
+ STAR node Match this (simple) thing 0 or more
+ times.
+ PLUS node Match this (simple) thing 1 or more
+ times.
- CURLY sv 2 Match this simple thing {n,m} times.
- CURLYN no 2 Capture next-after-this simple thing
- CURLYM no 2 Capture this medium-complex thing {n,m} times.
- CURLYX sv 2 Match this complex thing {n,m} times.
+ CURLY sv 2 Match this simple thing {n,m} times.
+ CURLYN no 2 Capture next-after-this simple thing
+ CURLYM no 2 Capture this medium-complex thing {n,m}
+ times.
+ CURLYX sv 2 Match this complex thing {n,m} times.
# This terminator creates a loop structure for CURLYX
- WHILEM no Do curly processing and see if rest matches.
+ WHILEM no Do curly processing and see if rest
+ matches.
# Buffer related
# OPEN,CLOSE,GROUPP ...are numbered at compile time.
- OPEN num 1 Mark this point in input as start of #n.
- CLOSE num 1 Analogous to OPEN.
+ OPEN num 1 Mark this point in input as start of #n.
+ CLOSE num 1 Analogous to OPEN.
- REF num 1 Match some already matched string
- REFF num 1 Match already matched string, folded using native charset
- semantics for non-utf8
- REFFL num 1 Match already matched string, folded in loc.
- REFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- REFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
+ REF num 1 Match some already matched string
+ REFF num 1 Match already matched string, folded
+ using native charset semantics for non-
+ utf8
+ REFFL num 1 Match already matched string, folded in
+ loc.
+ REFFU num 1 Match already matched string, folded
+ using unicode semantics for non-utf8
+ REFFA num 1 Match already matched string, folded
+ using unicode semantics for non-utf8, no
+ mixing ASCII, non-ASCII
- # Named references. Code in regcomp.c assumes that these all are after the
- # numbered references
- NREF no-sv 1 Match some already matched string
- NREFF no-sv 1 Match already matched string, folded using native charset
- semantics for non-utf8
- NREFFL no-sv 1 Match already matched string, folded in loc.
- NREFFU num 1 Match already matched string, folded using unicode
- semantics for non-utf8
- NREFFA num 1 Match already matched string, folded using unicode
- semantics for non-utf8, no mixing ASCII, non-ASCII
+ # Named references. Code in regcomp.c assumes that these all are after
+ # the numbered references
+ NREF no-sv 1 Match some already matched string
+ NREFF no-sv 1 Match already matched string, folded
+ using native charset semantics for non-
+ utf8
+ NREFFL no-sv 1 Match already matched string, folded in
+ loc.
+ NREFFU num 1 Match already matched string, folded
+ using unicode semantics for non-utf8
+ NREFFA num 1 Match already matched string, folded
+ using unicode semantics for non-utf8, no
+ mixing ASCII, non-ASCII
- IFMATCH off 1 2 Succeeds if the following matches.
- UNLESSM off 1 2 Fails if the following matches.
- SUSPEND off 1 1 "Independent" sub-RE.
- IFTHEN off 1 1 Switch, should be preceded by switcher.
- GROUPP num 1 Whether the group matched.
+ IFMATCH off 1 2 Succeeds if the following matches.
+ UNLESSM off 1 2 Fails if the following matches.
+ SUSPEND off 1 1 "Independent" sub-RE.
+ IFTHEN off 1 1 Switch, should be preceded by switcher.
+ GROUPP num 1 Whether the group matched.
# Support for long RE
- LONGJMP off 1 1 Jump far away.
- BRANCHJ off 1 1 BRANCH with long offset.
+ LONGJMP off 1 1 Jump far away.
+ BRANCHJ off 1 1 BRANCH with long offset.
# The heavy worker
- EVAL evl 1 Execute some Perl code.
+ EVAL evl 1 Execute some Perl code.
# Modifiers
- MINMOD no Next operator is not greedy.
- LOGICAL no Next opcode should set the flag only.
+ MINMOD no Next operator is not greedy.
+ LOGICAL no Next opcode should set the flag only.
# This is not used yet
- RENUM off 1 1 Group with independently numbered parens.
+ RENUM off 1 1 Group with independently numbered parens.
# Trie Related
- # Behave the same as A|LIST|OF|WORDS would. The '..C' variants have
- # inline charclass data (ascii only), the 'C' store it in the structure.
- # NOTE: the relative order of the TRIE-like regops is significant
+ # Behave the same as A|LIST|OF|WORDS would. The '..C' variants
+ # have inline charclass data (ascii only), the 'C' store it in the
+ # structure.
- TRIE trie 1 Match many EXACT(F[ALU]?)? at once. flags==type
- TRIEC charclass Same as TRIE, but with embedded charclass data
+ TRIE trie 1 Match many EXACT(F[ALU]?)? at once.
+ flags==type
+ TRIEC trie Same as TRIE, but with embedded charclass
+ charclass data
- # For start classes, contains an added fail table.
- AHOCORASICK trie 1 Aho Corasick stclass. flags==type
- AHOCORASICKC charclass Same as AHOCORASICK, but with embedded charclass data
+ AHOCORASICK trie 1 Aho Corasick stclass. flags==type
+ AHOCORASICKC trie Same as AHOCORASICK, but with embedded
+ charclass charclass data
# Regex Subroutines
- GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs arg2
- GOSTART no recurse to start of pattern
+ GOSUB num/ofs 2L recurse to paren arg1 at (signed) ofs
+ arg2
+ GOSTART no recurse to start of pattern
# Special conditionals
- NGROUPP no-sv 1 Whether the group matched.
- INSUBP num 1 Whether we are in a specific recurse.
- DEFINEP none 1 Never execute directly.
+ NGROUPP no-sv 1 Whether the group matched.
+ INSUBP num 1 Whether we are in a specific recurse.
+ DEFINEP none 1 Never execute directly.
# Backtracking Verbs
- ENDLIKE none Used only for the type field of verbs
- OPFAIL none Same as (?!)
- ACCEPT parno 1 Accepts the current matched string.
+ ENDLIKE none Used only for the type field of verbs
+ OPFAIL none Same as (?!)
+ ACCEPT parno 1 Accepts the current matched string.
-
# Verbs With Arguments
- VERB no-sv 1 Used only for the type field of verbs
- PRUNE no-sv 1 Pattern fails at this startpoint if no-backtracking through this
- MARKPOINT no-sv 1 Push the current location for rollback by cut.
- SKIP no-sv 1 On failure skip forward (to the mark) before retrying
- COMMIT no-sv 1 Pattern fails outright if backtracking through this
- CUTGROUP no-sv 1 On failure go to the next alternation in the group
+ VERB no-sv 1 Used only for the type field of verbs
+ PRUNE no-sv 1 Pattern fails at this startpoint if no-
+ backtracking through this
+ MARKPOINT no-sv 1 Push the current location for rollback by
+ cut.
+ SKIP no-sv 1 On failure skip forward (to the mark)
+ before retrying
+ COMMIT no-sv 1 Pattern fails outright if backtracking
+ through this
+ CUTGROUP no-sv 1 On failure go to the next alternation in
+ the group
# Control what to keep in $&.
- KEEPS no $& begins here.
+ KEEPS no $& begins here.
# New charclass like patterns
- LNBREAK none generic newline pattern
- VERTWS none vertical whitespace (Perl 6)
- NVERTWS none not vertical whitespace (Perl 6)
- HORIZWS none horizontal whitespace (Perl 6)
- NHORIZWS none not horizontal whitespace (Perl 6)
+ LNBREAK none generic newline pattern
- FOLDCHAR codepoint 1 codepoint with tricky case folding properties.
-
# SPECIAL REGOPS
- # This is not really a node, but an optimized away piece of a "long" node.
- # To simplify debugging output, we mark it as if it were a node
- OPTIMIZED off Placeholder for dump.
+ # This is not really a node, but an optimized away piece of a "long"
+ # node. To simplify debugging output, we mark it as if it were a node
+ OPTIMIZED off Placeholder for dump.
# Special opcode with the property that no opcode in a compiled program
# will ever be of this type. Thus it can be used as a flag value that
# no other opcode has been seen. END is used similarly, in that an END
- # node cant be optimized. So END implies "unoptimizable" and PSEUDO mean
- # "not seen anything to optimize yet".
- PSEUDO off Pseudo opcode for internal use.
+ # node cant be optimized. So END implies "unoptimizable" and PSEUDO
+ # mean "not seen anything to optimize yet".
+ PSEUDO off Pseudo opcode for internal use.
+=for regcomp.pl end
+
=for unprinted-credits
Next section M-J. Dominus (mjd-perl-patch+ at plover.com) 20010421
@@ -805,7 +826,7 @@
If the regex engine was entered, the output may look like this:
- Matching `[bc]d(ef*g)+h[ij]k$' against `abcdefg__gh__'
+ Matching '[bc]d(ef*g)+h[ij]k$' against 'abcdefg__gh__'
Setting an EVAL scope, savestack=3
2 <ab> <cdefg__gh_> | 1: ANYOF
3 <abc> <defg__gh_> | 11: EXACT <d>
Property changes on: trunk/contrib/perl/pod/perldebguts.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldebtut.pod
===================================================================
--- trunk/contrib/perl/pod/perldebtut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldebtut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -702,7 +702,6 @@
L<perldebug>,
L<perldebguts>,
L<perldiag>,
-L<dprofpp>,
L<perlrun>
Property changes on: trunk/contrib/perl/pod/perldebtut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldebug.pod
===================================================================
--- trunk/contrib/perl/pod/perldebug.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldebug.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -105,7 +105,6 @@
You may change the pager which is used via C<o pager=...> command.
-
=item p expr
X<debugger command, p>
@@ -270,15 +269,19 @@
List subroutine names [not] matching the regex.
-=item t
+=item t [n]
X<debugger command, t>
Toggle trace mode (see also the C<AutoTrace> option).
+Optional argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
-=item t expr
+=item t [n] expr
X<debugger command, t>
Trace through execution of C<expr>.
+Optional first argument is the maximum number of levels to trace below
+the current one; anything deeper than that will be silent.
See L<perldebguts/"Frame Listing Output Examples"> for examples.
=item b
@@ -301,6 +304,22 @@
b 237 ++$count237 < 11
b 33 /pattern/i
+If the line number is C<.>, sets a breakpoint on the current line:
+
+ b . $n > 100
+
+=item b [file]:[line] [condition]
+X<breakpoint>
+X<debugger command, b>
+
+Set a breakpoint before the given line in a (possibly different) file. If a
+condition is specified, it's evaluated each time the statement is reached: a
+breakpoint is taken only if the condition is true. Breakpoints may only be set
+on lines that begin an executable statement. Conditions don't use C<if>:
+
+ b lib/MyModule.pm:237 $x > 30
+ b /usr/lib/perl5/site_perl/CGI.pm:100 ++$count100 < 11
+
=item b subname [condition]
X<breakpoint>
X<debugger command, b>
@@ -341,6 +360,42 @@
Delete all installed breakpoints.
+=item disable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+=item disable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Disable the breakpoint so it won't stop the execution of the program.
+Breakpoints are enabled by default and can be re-enabled using the C<enable>
+command.
+
+This is done for a breakpoint in the current file.
+
+=item enable [file]:[line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+=item enable [line]
+X<breakpoint>
+X<debugger command, disable>
+X<disable>
+
+Enable the breakpoint so it will stop the execution of the program.
+
+This is done for a breakpoint in the current file.
+
=item a [line] command
X<debugger command, a>
@@ -591,7 +646,6 @@
Display all loaded modules and their versions.
-
=item man [manpage]
X<debugger command, man>
@@ -629,7 +683,7 @@
X<debugger option, recallCommand>
X<debugger option, ShellBang>
-The characters used to recall command or spawn shell. By
+The characters used to recall a command or spawn a shell. By
default, both are set to C<!>, which is unfortunate.
=item C<pager>
@@ -788,6 +842,19 @@
size of strings found in variables in the package. This does not
include lexicals in a module's file scope, or lost in closures.
+=item C<HistFile>
+X<debugger option, history, HistFile>
+
+The path of the file from which the history (assuming a usable
+Term::ReadLine backend) will be read on the debugger's startup, and to which
+it will be saved on shutdown (for persistence across sessions). Similar in
+concept to Bash's C<.bash_history> file.
+
+=item C<HistSize>
+X<debugger option, history, HistSize>
+
+The count of the saved lines in the history (assuming C<HistFile> above).
+
=back
After the rc file is read, the debugger reads the C<$ENV{PERLDB_OPTS}>
@@ -923,9 +990,9 @@
Here's an example of what a stack backtrace via C<T> command might
look like:
- $ = main::infested called from file `Ambulation.pm' line 10
- @ = Ambulation::legs(1, 2, 3, 4) called from file `camel_flea' line 7
- $ = main::pests('bactrian', 4) called from file `camel_flea' line 4
+ $ = main::infested called from file 'Ambulation.pm' line 10
+ @ = Ambulation::legs(1, 2, 3, 4) called from file 'camel_flea' line 7
+ $ = main::pests('bactrian', 4) called from file 'camel_flea' line 4
The left-hand character up there indicates the context in which the
function was called, with C<$> and C<@> meaning scalar or list
@@ -998,7 +1065,7 @@
breakpoint on the I<load> of some module:
DB<7> b load f:/perllib/lib/Carp.pm
- Will stop on load of `f:/perllib/lib/Carp.pm'.
+ Will stop on load of 'f:/perllib/lib/Carp.pm'.
and then restart the debugger using the C<R> command (if possible). One can use C<b
compile subname> for the same purpose.
@@ -1104,19 +1171,16 @@
If you wish to supply an alternative debugger for Perl to run,
invoke your script with a colon and a package argument given to the
-B<-d> flag. Perl's alternative debuggers include the Perl profiler,
-L<Devel::DProf>, which is included with the standard Perl
+B<-d> flag. Perl's alternative debuggers include a Perl profiler,
+L<Devel::NYTProf>, which is available separately as a CPAN
distribution. To profile your Perl program in the file F<mycode.pl>,
just type:
- $ perl -d:DProf mycode.pl
+ $ perl -d:NYTProf mycode.pl
-When the script terminates the profiler will dump the profile
-information to a file called F<tmon.out>. A tool like B<dprofpp>,
-also supplied with the standard Perl distribution, can be used to
-interpret the information in that profile. More powerful profilers,
-such as C<Devel::NYTProf> are available from the CPAN: see L<perlperf>
-for details.
+When the script terminates the profiler will create a database of the
+profile information that you can turn into reports using the profiler's
+tools. See <perlperf> for details.
=head1 Debugging Regular Expressions
X<regular expression, debugging>
@@ -1146,8 +1210,7 @@
L<perldebguts>,
L<re>,
L<DB>,
-L<Devel::DProf>,
-L<dprofpp>,
+L<Devel::NYTProf>,
L<Dumpvalue>,
and
L<perlrun>.
Property changes on: trunk/contrib/perl/pod/perldebug.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldelta.pod
===================================================================
--- trunk/contrib/perl/pod/perldelta.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldelta.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -2,52 +2,24 @@
=head1 NAME
-perldelta - what is new for perl v5.14.2
+perldelta - what is new for perl v5.18.1
=head1 DESCRIPTION
-This document describes differences between the 5.14.1 release and
-the 5.14.2 release.
+This document describes differences between the 5.18.0 release and the 5.18.1
+release.
-If you are upgrading from an earlier release such as 5.14.0, first read
-L<perl5141delta>, which describes differences between 5.14.0 and
-5.14.1.
+If you are upgrading from an earlier release such as 5.16.0, first read
+L<perl5180delta>, which describes differences between 5.16.0 and 5.18.0.
-=head1 Core Enhancements
-
-No changes since 5.14.0.
-
-=head1 Security
-
-=head2 C<File::Glob::bsd_glob()> memory error with GLOB_ALTDIRFUNC (CVE-2011-2728).
-
-Calling C<File::Glob::bsd_glob> with the unsupported flag GLOB_ALTDIRFUNC would
-cause an access violation / segfault. A Perl program that accepts a flags value from
-an external source could expose itself to denial of service or arbitrary code
-execution attacks. There are no known exploits in the wild. The problem has been
-corrected by explicitly disabling all unsupported flags and setting unused function
-pointers to null. Bug reported by Clément Lecigne.
-
-=head2 C<Encode> decode_xs n-byte heap-overflow (CVE-2011-2939)
-
-A bug in C<Encode> could, on certain inputs, cause the heap to overflow.
-This problem has been corrected. Bug reported by Robert Zacek.
-
=head1 Incompatible Changes
-There are no changes intentionally incompatible with 5.14.0. If any
-exist, they are bugs and reports are welcome.
+There are no changes intentionally incompatible with 5.18.0
+If any exist, they are bugs, and we request that you submit a
+report. See L</Reporting Bugs> below.
-=head1 Deprecations
-
-There have been no deprecations since 5.14.0.
-
=head1 Modules and Pragmata
-=head2 New Modules and Pragmata
-
-None
-
=head2 Updated Modules and Pragmata
=over 4
@@ -54,184 +26,187 @@
=item *
-L<CPAN> has been upgraded from version 1.9600 to version 1.9600_01.
+B has been upgraded from 1.42 to 1.42_01, fixing bugs related to lexical
+subroutines.
-L<CPAN::Distribution> has been upgraded from version 1.9602 to 1.9602_01.
-
-Backported bugfixes from CPAN version 1.9800. Ensures proper
-detection of C<configure_requires> prerequisites from CPAN Meta files
-in the case where C<dynamic_config> is true. [rt.cpan.org #68835]
-
-Also ensures that C<configure_requires> is only checked in META files,
-not MYMETA files, so protect against MYMETA generation that drops
-C<configure_requires>.
-
=item *
-L<Encode> has been upgraded from version 2.42 to 2.42_01.
+Digest::SHA has been upgraded from 5.84 to 5.84_01, fixing a crashing bug.
+[RT #118649]
-See L</Security>.
-
=item *
-L<File::Glob> has been upgraded from version 1.12 to version 1.13.
+Module::CoreList has been upgraded from 2.89 to 2.96.
-See L</Security>.
+=back
-=item *
+=head1 Platform Support
-L<PerlIO::scalar> has been upgraded from version 0.11 to 0.11_01.
+=head2 Platform-Specific Notes
-It fixes a problem with C<< open my $fh, ">", \$scalar >> not working if
-C<$scalar> is a copy-on-write scalar.
+=over 4
-=back
+=item AIX
-=head2 Removed Modules and Pragmata
+A rarely-encounted configuration bug in the AIX hints file has been corrected.
-None
+=item MidnightBSD
-=head1 Platform Support
+After a patch to the relevant hints file, perl should now build correctly on
+MidnightBSD 0.4-RELEASE.
-=head2 New Platforms
+=back
-None
+=head1 Selected Bug Fixes
-=head2 Discontinued Platforms
+=over 4
-None
+=item *
-=head2 Platform-Specific Notes
+Starting in v5.18.0, a construct like C</[#](?{})/x> would have its C<#>
+incorrectly interpreted as a comment. The code block would be skipped,
+unparsed. This has been corrected.
-=over 4
+=item *
-=item HP-UX PA-RISC/64 now supports gcc-4.x
+A number of memory leaks related to the new, experimental regexp bracketed
+character class feature have been plugged.
-A fix to correct the socketsize now makes the test suite pass on HP-UX
-PA-RISC for 64bitall builds.
+=item *
-=item Building on OS X 10.7 Lion and Xcode 4 works again
+The OP allocation code now returns correctly aligned memory in all cases
+for C<struct pmop>. Previously it could return memory only aligned to a
+4-byte boundary, which is not correct for an ithreads build with 64 bit IVs
+on some 32 bit platforms. Notably, this caused the build to fail completely
+on sparc GNU/Linux. [RT #118055]
-The build system has been updated to work with the build tools under Mac OS X
-10.7.
+=item *
-=back
+The debugger's C<man> command been fixed. It was broken in the v5.18.0
+release. The C<man> command is aliased to the names C<doc> and C<perldoc> -
+all now work again.
-=head1 Bug Fixes
+=item *
-=over 4
+C<@_> is now correctly visible in the debugger, fixing a regression
+introduced in v5.18.0's debugger. [RT #118169]
=item *
-In @INC filters (subroutines returned by subroutines in @INC), $_ used to
-misbehave: If returned from a subroutine, it would not be copied, but the
-variable itself would be returned; and freeing $_ (e.g., with C<undef *_>)
-would cause perl to crash. This has been fixed [perl #91880].
+Fixed a small number of regexp constructions that could either fail to
+match or crash perl when the string being matched against was
+allocated above the 2GB line on 32-bit systems. [RT #118175]
=item *
-Perl 5.10.0 introduced some faulty logic that made "U*" in the middle of
-a pack template equivalent to "U0" if the input string was empty. This has
-been fixed [perl #90160].
+Perl v5.16 inadvertently introduced a bug whereby calls to XSUBs that were
+not visible at compile time were treated as lvalues and could be assigned
+to, even when the subroutine was not an lvalue sub. This has been fixed.
+[perl #117947]
=item *
-C<caller> no longer leaks memory when called from the DB package if
-C<@DB::args> was assigned to after the first call to C<caller>. L<Carp>
-was triggering this bug [perl #97010].
+Perl v5.18 inadvertently introduced a bug whereby dual-vars (i.e.
+variables with both string and numeric values, such as C<$!> ) where the
+truthness of the variable was determined by the numeric value rather than
+the string value. [RT #118159]
=item *
-C<utf8::decode> had a nasty bug that would modify copy-on-write scalars'
-string buffers in place (i.e., skipping the copy). This could result in
-hashes having two elements with the same key [perl #91834].
+Perl v5.18 inadvertently introduced a bug whereby interpolating mixed up-
+and down-graded UTF-8 strings in a regex could result in malformed UTF-8
+in the pattern: specifically if a downgraded character in the range
+C<\x80..\xff> followed a UTF-8 string, e.g.
-=item *
+ utf8::upgrade( my $u = "\x{e5}");
+ utf8::downgrade(my $d = "\x{e5}");
+ /$u$d/
-Localising a tied variable used to make it read-only if it contained a
-copy-on-write string.
+[perl #118297].
=item *
-Elements of restricted hashes (see the L<fields> pragma) containing
-copy-on-write values couldn't be deleted, nor could such hashes be cleared
-(C<%hash = ()>).
+Lexical constants (C<my sub a() { 42 }>) no longer crash when inlined.
=item *
-Locking a hash element that is a glob copy no longer causes subsequent
-assignment to it to corrupt the glob.
+Parameter prototypes attached to lexical subroutines are now respected when
+compiling sub calls without parentheses. Previously, the prototypes were
+honoured only for calls I<with> parentheses. [RT #116735]
=item *
-A panic involving the combination of the regular expression modifiers
-C</aa> introduced in 5.14.0 and the C<\b> escape sequence has been
-fixed [perl #95964].
+Syntax errors in lexical subroutines in combination with calls to the same
+subroutines no longer cause crashes at compile time.
-=back
+=item *
-=head1 Known Problems
+The dtrace sub-entry probe now works with lexical subs, instead of
+crashing [perl #118305].
-This is a list of some significant unfixed bugs, which are regressions
-from 5.12.0.
+=item *
-=over 4
+Undefining an inlinable lexical subroutine (C<my sub foo() { 42 } undef
+&foo>) would result in a crash if warnings were turned on.
=item *
-C<PERL_GLOBAL_STRUCT> is broken.
+Deep recursion warnings no longer crash lexical subroutines. [RT #118521]
-Since perl 5.14.0, building with C<-DPERL_GLOBAL_STRUCT> hasn't been
-possible. This means that perl currently doesn't work on any platforms that
-require it to be built this way, including Symbian.
+=back
-While C<PERL_GLOBAL_STRUCT> now works again on recent development versions of
-perl, it actually working on Symbian again hasn't been verified.
+=head1 Acknowledgements
-We'd be very interested in hearing from anyone working with Perl on Symbian.
+Perl 5.18.1 represents approximately 2 months of development since Perl 5.18.0
+and contains approximately 8,400 lines of changes across 60 files from 12
+authors.
-=back
+Perl continues to flourish into its third decade thanks to a vibrant community
+of users and developers. The following people are known to have contributed the
+improvements that became Perl 5.18.1:
-=head1 Acknowledgements
+Chris 'BinGOs' Williams, Craig A. Berry, Dagfinn Ilmari Mannsåker, David
+Mitchell, Father Chrysostomos, Karl Williamson, Lukas Mai, Nicholas Clark,
+Peter Martini, Ricardo Signes, Shlomi Fish, Tony Cook.
-Perl 5.14.2 represents approximately three months of development since
-Perl 5.14.1 and contains approximately 1200 lines of changes
-across 61 files from 9 authors.
+The list above is almost certainly incomplete as it is automatically generated
+from version control history. In particular, it does not include the names of
+the (very much appreciated) contributors who reported issues to the Perl bug
+tracker.
-Perl continues to flourish into its third decade thanks to a vibrant
-community of users and developers. The following people are known to
-have contributed the improvements that became Perl 5.14.2:
+Many of the changes included in this version originated in the CPAN modules
+included in Perl's core. We're grateful to the entire CPAN community for
+helping Perl to flourish.
-Craig A. Berry, David Golden, Father Chrysostomos, Florian Ragwitz, H.Merijn
-Brand, Karl Williamson, Nicholas Clark, Pau Amma and Ricardo Signes.
+For a more complete list of all of Perl's historical contributors, please see
+the F<AUTHORS> file in the Perl source distribution.
=head1 Reporting Bugs
-If you find what you think is a bug, you might check the articles
-recently posted to the comp.lang.perl.misc newsgroup and the perl
-bug database at http://rt.perl.org/perlbug/ . There may also be
-information at http://www.perl.org/ , the Perl Home Page.
+If you find what you think is a bug, you might check the articles recently
+posted to the comp.lang.perl.misc newsgroup and the perl bug database at
+http://rt.perl.org/perlbug/ . There may also be information at
+http://www.perl.org/ , the Perl Home Page.
-If you believe you have an unreported bug, please run the L<perlbug>
-program included with your release. Be sure to trim your bug down
-to a tiny but sufficient test case. Your bug report, along with the
-output of C<perl -V>, will be sent off to perlbug at perl.org to be
-analysed by the Perl porting team.
+If you believe you have an unreported bug, please run the L<perlbug> program
+included with your release. Be sure to trim your bug down to a tiny but
+sufficient test case. Your bug report, along with the output of C<perl -V>,
+will be sent off to perlbug at perl.org to be analysed by the Perl porting team.
If the bug you are reporting has security implications, which make it
-inappropriate to send to a publicly archived mailing list, then please send
-it to perl5-security-report at perl.org. This points to a closed subscription
-unarchived mailing list, which includes all the core committers, who be able
-to help assess the impact of issues, figure out a resolution, and help
+inappropriate to send to a publicly archived mailing list, then please send it
+to perl5-security-report at perl.org. This points to a closed subscription
+unarchived mailing list, which includes all the core committers, who will be
+able to help assess the impact of issues, figure out a resolution, and help
co-ordinate the release of patches to mitigate or fix the problem across all
-platforms on which Perl is supported. Please only use this address for
-security issues in the Perl core, not for modules independently
-distributed on CPAN.
+platforms on which Perl is supported. Please only use this address for
+security issues in the Perl core, not for modules independently distributed on
+CPAN.
=head1 SEE ALSO
-The F<Changes> file for an explanation of how to view exhaustive details
-on what changed.
+The F<Changes> file for an explanation of how to view exhaustive details on
+what changed.
The F<INSTALL> file for how to build Perl.
Property changes on: trunk/contrib/perl/pod/perldelta.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldiag.pod
===================================================================
--- trunk/contrib/perl/pod/perldiag.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldiag.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -20,10 +20,10 @@
If a message can be controlled by the C<warnings> pragma, its warning
category is included with the classification letter in the description
-below.
+below. E.g. C<(W closed)> means a warning in the C<closed> category.
Optional warnings are enabled by using the C<warnings> pragma or the B<-w>
-and B<-W> switches. Warnings may be captured by setting C<$SIG{__WARN__}>
+and B<-W> switches. Warnings may be captured by setting C<$SIG{__WARN__}>
to a reference to a routine that will be called on each warning instead
of printing it. See L<perlvar>.
@@ -85,13 +85,13 @@
=item Ambiguous use of %s resolved as %s
-(W ambiguous)(S) You said something that may not be interpreted the way
+(S ambiguous) You said something that may not be interpreted the way
you thought. Normally it's pretty easy to disambiguate it by supplying
a missing quote, operator, parenthesis pair or declaration.
=item Ambiguous use of %c resolved as operator %c
-(W ambiguous) C<%>, C<&>, and C<*> are both infix operators (modulus,
+(S ambiguous) C<%>, C<&>, and C<*> are both infix operators (modulus,
bitwise and, and multiplication) I<and> initial special characters
(denoting hashes, subroutines and typeglobs), and you said something
like C<*foo * foo> that might be interpreted as either of them. We
@@ -104,7 +104,7 @@
(W ambiguous) You wrote something like C<@{foo}>, which might be
asking for the variable C<@foo>, or it might be calling a function
named foo, and dereferencing it as an array reference. If you wanted
-the varable, you can just write C<@foo>. If you wanted to call the
+the variable, you can just write C<@foo>. If you wanted to call the
function, write C<@{foo()}> ... or you could just not have a variable
and a function with the same name, and save yourself a lot of trouble.
@@ -112,41 +112,29 @@
=item Ambiguous use of %c{%s{...}} resolved to %c%s{...}
-(W ambiguous) You wrote something like C<${foo[2]}> (where foo
-represents the name of a Perl keyword), which might be looking for
-element number 2 of the array named C<@foo>, in which case please write
-C<$foo[2]>, or you might have meant to pass an anonymous arrayref to
-the function named foo, and then do a scalar deref on the value it
-returns. If you meant that, write C<${foo([2])}>.
+(W ambiguous) You wrote something like C<${foo[2]}> (where foo represents
+the name of a Perl keyword), which might be looking for element number
+2 of the array named C<@foo>, in which case please write C<$foo[2]>, or you
+might have meant to pass an anonymous arrayref to the function named
+foo, and then do a scalar deref on the value it returns. If you meant
+that, write C<${foo([2])}>.
In regular expressions, the C<${foo[2]}> syntax is sometimes necessary
to disambiguate between array subscripts and character classes.
-C</$length[2345]/>, for instance, will be interpreted as C<$length>
-followed by the character class C<[2345]>. If an array subscript is what
-you want, you can avoid the warning by changing C</${length[2345]}/>
-to the unsightly C</${\$length[2345]}/>, by renaming your array to
-something that does not coincide with a built-in keyword, or by
-simply turning off warnings with C<no warnings 'ambiguous';>.
+C</$length[2345]/>, for instance, will be interpreted as C<$length> followed
+by the character class C<[2345]>. If an array subscript is what you
+want, you can avoid the warning by changing C</${length[2345]}/> to the
+unsightly C</${\$length[2345]}/>, by renaming your array to something
+that does not coincide with a built-in keyword, or by simply turning
+off warnings with C<no warnings 'ambiguous';>.
=item Ambiguous use of -%s resolved as -&%s()
-(W ambiguous) You wrote something like C<-foo>, which might be the
+(S ambiguous) You wrote something like C<-foo>, which might be the
string C<"-foo">, or a call to the function C<foo>, negated. If you meant
the string, just write C<"-foo">. If you meant the function call,
write C<-foo()>.
-=item Ambiguous use of 's//le...' resolved as 's// le...'; Rewrite as 's//el' if you meant 'use locale rules and evaluate rhs as an expression'. In Perl 5.16, it will be resolved the other way
-
-(W deprecated, ambiguous) You wrote a pattern match with substitution
-immediately followed by "le". In Perl 5.14 and earlier, this is
-resolved as meaning to take the result of the substitution, and see if
-it is stringwise less-than-or-equal-to what follows in the expression.
-Having the "le" immediately following a pattern is deprecated behavior,
-so in Perl 5.16, this expression will be resolved as meaning to do the
-pattern match using the rules of the current locale, and evaluate the
-rhs as an expression when doing the substitution. In 5.14, if you want
-the latter interpretation, you can simply write "el" instead.
-
=item '|' and '<' may not both be specified on command line
(F) An error peculiar to VMS. Perl does its own command line
@@ -218,12 +206,13 @@
=item Argument list not closed for PerlIO layer "%s"
-(W layer) When pushing a layer with arguments onto the Perl I/O system you
-forgot the ) that closes the argument list. (Layers take care of transforming
-data between external and internal representations.) Perl stopped parsing
-the layer list at this point and did not attempt to push this layer.
-If your program didn't explicitly request the failing operation, it may be
-the result of the value of the environment variable PERLIO.
+(W layer) When pushing a layer with arguments onto the Perl I/O
+system you forgot the ) that closes the argument list. (Layers
+take care of transforming data between external and internal
+representations.) Perl stopped parsing the layer list at this
+point and did not attempt to push this layer. If your program
+didn't explicitly request the failing operation, it may be the
+result of the value of the environment variable PERLIO.
=item Array @%s missing the @ in argument %d of %s()
@@ -230,14 +219,27 @@
(D deprecated) Really old Perl let you omit the @ on array names in some
spots. This is now heavily deprecated.
+=item A sequence of multiple spaces in a charnames alias definition is deprecated
+
+(D) You defined a character name which had multiple space characters in
+a row. Change them to single spaces. Usually these names are defined
+in the C<:alias> import argument to C<use charnames>, but they could be
+defined by a translator installed into C<$^H{charnames}>. See
+L<charnames/CUSTOM ALIASES>.
+
=item assertion botched: %s
-(P) The malloc package that comes with Perl had an internal failure.
+(X) The malloc package that comes with Perl had an internal failure.
=item Assertion failed: file "%s"
-(P) A general assertion failed. The file in question must be examined.
+(X) A general assertion failed. The file in question must be examined.
+=item Assigning non-zero to $[ is no longer possible
+
+(F) When the "array_base" feature is disabled (e.g., under C<use v5.16;>)
+the special variable C<$[>, which is deprecated, is now a fixed zero value.
+
=item Assignment to both a list and a scalar
(F) If you assign to a conditional operator, the 2nd and 3rd arguments
@@ -246,8 +248,8 @@
=item A thread exited while %d threads were running
-(W threads)(S) When using threaded Perl, a thread (not necessarily the main
-thread) exited while there were still other threads running.
+(W threads)(S) When using threaded Perl, a thread (not necessarily
+the main thread) exited while there were still other threads running.
Usually it's a good idea first to collect the return values of the
created threads by joining them, and only then to exit from the main
thread. See L<threads>.
@@ -260,7 +262,7 @@
=item Attempt to bless into a reference
(F) The CLASSNAME argument to the bless() operator is expected to be
-the name of the package to bless the resulting object into. You've
+the name of the package to bless the resulting object into. You've
supplied instead a reference to something: perhaps you wrote
bless $self, $proto;
@@ -275,6 +277,13 @@
bless $self, "$proto";
+=item Attempt to clear deleted array
+
+(S debugging) An array was assigned to when it was being freed.
+Freed values are not supposed to be visible to Perl code. This
+can also happen if XS code calls C<av_clear> from a custom magic
+callback on the array.
+
=item Attempt to delete disallowed key '%s' from a restricted hash
(F) The failing code attempted to delete from a restricted hash a key
@@ -287,20 +296,20 @@
=item Attempt to free non-arena SV: 0x%x
-(P internal) All SV objects are supposed to be allocated from arenas
+(S internal) All SV objects are supposed to be allocated from arenas
that will be garbage collected on exit. An SV was discovered to be
outside any of those arenas.
-=item Attempt to free nonexistent shared string
+=item Attempt to free nonexistent shared string '%s'%s
-(P internal) Perl maintains a reference-counted internal table of
+(S internal) Perl maintains a reference-counted internal table of
strings to optimize the storage and access of hash keys and other
strings. This indicates someone tried to decrement the reference count
of a string that can no longer be found in the table.
-=item Attempt to free temp prematurely
+=item Attempt to free temp prematurely: SV 0x%x
-(W debugging) Mortalized values are supposed to be freed by the
+(S debugging) Mortalized values are supposed to be freed by the
free_tmps() routine. This indicates that something else is freeing the
SV before the free_tmps() routine gets a chance, which means that the
free_tmps() routine will be freeing an unreferenced scalar when it does
@@ -308,11 +317,11 @@
=item Attempt to free unreferenced glob pointers
-(P internal) The reference counts got screwed up on symbol aliases.
+(S internal) The reference counts got screwed up on symbol aliases.
-=item Attempt to free unreferenced scalar
+=item Attempt to free unreferenced scalar: SV 0x%x
-(W internal) Perl went to decrement the reference count of a scalar to
+(S internal) Perl went to decrement the reference count of a scalar to
see if it would go to 0, and discovered that it had already gone to 0
earlier, and should have been freed, and in fact, probably was freed.
This could indicate that SvREFCNT_dec() was called too many times, or
@@ -344,9 +353,10 @@
=item Attempt to set length of freed array
-(W) You tried to set the length of an array which has been freed. You
-can do this by storing a reference to the scalar representing the last index
-of an array and later assigning through that reference. For example
+(W misc) You tried to set the length of an array which has
+been freed. You can do this by storing a reference to the
+scalar representing the last index of an array and later
+assigning through that reference. For example
$r = do {my @a; \$#a};
$$r = 503
@@ -359,18 +369,23 @@
=item Attribute "locked" is deprecated
-(D deprecated) You have used the attributes pragma to modify the "locked"
-attribute on a code reference. The :locked attribute is obsolete, has had no
-effect since 5005 threads were removed, and will be removed in a future
-release of Perl 5.
+(D deprecated) You have used the attributes pragma to modify the
+"locked" attribute on a code reference. The :locked attribute is
+obsolete, has had no effect since 5005 threads were removed, and
+will be removed in a future release of Perl 5.
=item Attribute "unique" is deprecated
-(D deprecated) You have used the attributes pragma to modify the "unique"
-attribute on an array, hash or scalar reference. The :unique attribute has
-had no effect since Perl 5.8.8, and will be removed in a future release
-of Perl 5.
+(D deprecated) You have used the attributes pragma to modify
+the "unique" attribute on an array, hash or scalar reference.
+The :unique attribute has had no effect since Perl 5.8.8, and
+will be removed in a future release of Perl 5.
+=item av_reify called on tied array
+
+(S debugging) This indicates that something went wrong and Perl got I<very>
+confused about C<@_> or C<@DB::args> being tied.
+
=item Bad arg length for %s, is %u, should be %d
(F) You passed a buffer of the wrong size to one of msgctl(), semctl()
@@ -393,11 +408,11 @@
=item Bad free() ignored
(S malloc) An internal routine called free() on something that had never
-been malloc()ed in the first place. Mandatory, but can be disabled by
+been malloc()ed in the first place. Mandatory, but can be disabled by
setting environment variable C<PERL_BADFREE> to 0.
This message can be seen quite often with DB_File on systems with "hard"
-dynamic linking, like C<AIX> and C<OS/2>. It is a bug of C<Berkeley DB>
+dynamic linking, like C<AIX> and C<OS/2>. It is a bug of C<Berkeley DB>
which is left unnoticed if C<DB> uses I<forgiving> system malloc().
=item Bad hash
@@ -410,7 +425,7 @@
of Perl. Check the #! line, or manually feed your script into
Perl yourself.
-=item Bad name after %s::
+=item Bad name after %s
(F) You started to name a symbol by using a package prefix, and then
didn't finish the symbol. In particular, you can't interpolate outside
@@ -431,9 +446,9 @@
=item Bad realloc() ignored
-(S malloc) An internal routine called realloc() on something that had
-never been malloc()ed in the first place. Mandatory, but can be disabled
-by setting the environment variable C<PERL_BADFREE> to 1.
+(S malloc) An internal routine called realloc() on something that
+had never been malloc()ed in the first place. Mandatory, but can
+be disabled by setting the environment variable C<PERL_BADFREE> to 1.
=item Bad symbol for array
@@ -445,7 +460,6 @@
(P) An internal request asked to add a dirhandle entry to something
that wasn't a symbol table entry.
-
=item Bad symbol for filehandle
(P) An internal request asked to add a filehandle entry to something
@@ -522,19 +536,21 @@
(W unopened) You tried binmode() on a filehandle that was never opened.
Check your control flow and number of arguments.
-=item "\b{" is deprecated; use "\b\{" instead
+=item "\b{" is deprecated; use "\b\{" or "\b[{]" instead in regex; marked by <-- HERE in m/%s/
-=item "\B{" is deprecated; use "\B\{" instead
+=item "\B{" is deprecated; use "\B\{" or "\B[{]" instead in regex; marked by <-- HERE in m/%s/
-(W deprecated, regexp) Use of an unescaped "{" immediately following a
+(W deprecated) Use of an unescaped "{" immediately following a
C<\b> or C<\B> is now deprecated so as to reserve its use for Perl
-itself in a future release.
+itself in a future release. You can either precede the brace with a
+backslash, or enclose it in square brackets; the latter is the way to go
+if the pattern delimiters are C<{}>.
=item Bit vector size > 32 non-portable
(W portable) Using bit vector sizes larger than 32 is non-portable.
-=item Bizarre copy of %s in %s
+=item Bizarre copy of %s
(P) Perl detected an attempt to copy an internal value that is not
copiable.
@@ -545,6 +561,11 @@
iterate over %ENV, it encountered a logical name or symbol definition
which was too long, so it was truncated to the string shown.
+=item Bizarre SvTYPE [%d]
+
+(P) When starting a new thread or return values from a thread, Perl
+encountered an invalid data type.
+
=item Callback called exit
(F) A subroutine invoked from an external package via call_sv()
@@ -575,12 +596,12 @@
=item Cannot convert a reference to %s to typeglob
-(F) You manipulated Perl's symbol table directly, stored a reference in it,
-then tried to access that symbol via conventional Perl syntax. The access
-triggers Perl to autovivify that typeglob, but it there is no legal conversion
-from that type of reference to a typeglob.
+(F) You manipulated Perl's symbol table directly, stored a reference
+in it, then tried to access that symbol via conventional Perl syntax.
+The access triggers Perl to autovivify that typeglob, but it there is
+no legal conversion from that type of reference to a typeglob.
-=item Cannot copy to %s in %s
+=item Cannot copy to %s
(P) Perl detected an attempt to copy a value to an internal type that cannot
be directly assigned to.
@@ -590,6 +611,18 @@
(S io) You tried to apply an encoding that did not exist to a filehandle,
either with open() or binmode().
+=item Cannot set tied @DB::args
+
+(F) C<caller> tried to set C<@DB::args>, but found it tied. Tying C<@DB::args>
+is not supported. (Before this error was added, it used to crash.)
+
+=item Cannot tie unreifiable array
+
+(P) You somehow managed to call C<tie> on an array that does not
+keep a reference count on its arguments and cannot be made to
+do so. Such arrays are not even supposed to be accessible to
+Perl code, but are only used internally.
+
=item Can only compress unsigned integers in pack
(F) An argument to pack("w",...) was not an integer. The BER compressed
@@ -604,7 +637,7 @@
=item Can't "break" in a loop topicalizer
(F) You called C<break>, but you're in a C<foreach> block rather than
-a C<given> block. You probably meant to use C<next> or C<last>.
+a C<given> block. You probably meant to use C<next> or C<last>.
=item Can't "break" outside a given block
@@ -640,7 +673,7 @@
=item Can't chdir to %s
-(F) You called C<perl -x/foo/bar>, but C</foo/bar> is not a directory
+(F) You called C<perl -x/foo/bar>, but F</foo/bar> is not a directory
that you can chdir to, possibly because it doesn't exist.
=item Can't check filesystem of script "%s" for nosuid
@@ -678,10 +711,17 @@
(F) Only scalar, array, and hash variables may be declared as "my", "our" or
"state" variables. They must have ordinary identifiers as names.
+=item Can't "default" outside a topicalizer
+
+(F) You have used a C<default> block that is neither inside a
+C<foreach> loop nor a C<given> block. (Note that this error is
+issued on exit from the C<default> block, so you won't get the
+error if you use an explicit C<continue>.)
+
=item Can't do inplace edit: %s is not a regular file
(S inplace) You tried to use the B<-i> switch on a special file, such as
-a file in /dev, or a FIFO. The file was ignored.
+a file in /dev, a FIFO or an uneditable directory. The file was ignored.
=item Can't do inplace edit on %s: %s
@@ -700,12 +740,6 @@
characters and Perl was unable to create a unique filename during
inplace editing with the B<-i> switch. The file was ignored.
-=item Can't do {n,m} with n > m in regex; marked by <-- HERE in m/%s/
-
-(F) Minima must be less than or equal to maxima. If you really want your
-regexp to match something 0 times, just put {0}. The <-- HERE shows in the
-regular expression about where the problem was discovered. See L<perlre>.
-
=item Can't do waitpid with flags
(F) This machine doesn't have either waitpid() or wait4(), so only
@@ -753,9 +787,9 @@
=item Can't find %s character property "%s"
(F) You used C<\p{}> or C<\P{}> but the character property by that name
-could not be found. Maybe you misspelled the name of the property?
+could not be found. Maybe you misspelled the name of the property?
See L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available properties.
+for a complete list of available official properties.
=item Can't find label %s
@@ -791,11 +825,11 @@
(F) You may have tried to use C<\p> which means a Unicode
property (for example C<\p{Lu}> matches all uppercase
-letters). If you did mean to use a Unicode property, see
+letters). If you did mean to use a Unicode property, see
L<perluniprops/Properties accessible through \p{} and \P{}>
-for a complete list of available properties. If you didn't
-mean to use a Unicode property, escape the C<\p>, either by C<\\p>
-(just the C<\p>) or by C<\Q\p> (the rest of the string, or
+for a complete list of available properties. If you didn't
+mean to use a Unicode property, escape the C<\p>, either by
+C<\\p> (just the C<\p>) or by C<\Q\p> (the rest of the string, or
until C<\E>).
=item Can't fork: %s
@@ -898,20 +932,20 @@
=item Can't load '%s' for module %s
-(F) The module you tried to load failed to load a dynamic extension. This
-may either mean that you upgraded your version of perl to one that is
-incompatible with your old dynamic extensions (which is known to happen
-between major versions of perl), or (more likely) that your dynamic
-extension was built against an older version of the library that is
-installed on your system. You may need to rebuild your old dynamic
-extensions.
+(F) The module you tried to load failed to load a dynamic extension.
+This may either mean that you upgraded your version of perl to one
+that is incompatible with your old dynamic extensions (which is known
+to happen between major versions of perl), or (more likely) that your
+dynamic extension was built against an older version of the library
+that is installed on your system. You may need to rebuild your old
+dynamic extensions.
=item Can't localize lexical variable %s
(F) You used local on a variable name that was previously declared as a
-lexical variable using "my" or "state". This is not allowed. If you want to
-localize a package variable of the same name, qualify it with the
-package name.
+lexical variable using "my" or "state". This is not allowed. If you
+want to localize a package variable of the same name, qualify it with
+the package name.
=item Can't localize through a reference
@@ -922,11 +956,11 @@
=item Can't locate %s
-(F) You said to C<do> (or C<require>, or C<use>) a file that couldn't be
-found. Perl looks for the file in all the locations mentioned in @INC,
-unless the file name included the full path to the file. Perhaps you
-need to set the PERL5LIB or PERL5OPT environment variable to say where
-the extra library is, or maybe the script needs to add the library name
+(F) You said to C<do> (or C<require>, or C<use>) a file that couldn't be found.
+Perl looks for the file in all the locations mentioned in @INC, unless
+the file name included the full path to the file. Perhaps you need
+to set the PERL5LIB or PERL5OPT environment variable to say where the
+extra library is, or maybe the script needs to add the library name
to @INC. Or maybe you just misspelled the name of the file. See
L<perlfunc/require> and L<lib>.
@@ -940,7 +974,7 @@
=item Can't locate loadable object for module %s in @INC
(F) The module you loaded is trying to load an external library, like
-for example, C<foo.so> or C<bar.dll>, but the L<DynaLoader> module was
+for example, F<foo.so> or F<bar.dll>, but the L<DynaLoader> module was
unable to locate this library. See L<DynaLoader>.
=item Can't locate object method "%s" via package "%s"
@@ -959,11 +993,20 @@
(F) You tried to use in open() a PerlIO layer that does not exist,
e.g. open(FH, ">:nosuchlayer", "somefile").
-=item Can't make list assignment to \%ENV on this system
+=item Can't make list assignment to %ENV on this system
(F) List assignment to %ENV is not supported on some systems, notably
VMS.
+=item Can't make loaded symbols global on this platform while loading %s
+
+(W) A module passed the flag 0x01 to DynaLoader::dl_load_file() to request
+that symbols from the stated file are made available globally within the
+process, but that functionality is not available on this platform. Whilst
+the module likely will still work, this may prevent the perl interpreter
+from loading other XS-based extensions which need to link directly to
+functions defined in the C or XS code in the stated file.
+
=item Can't modify %s in %s
(F) You aren't allowed to assign to the item indicated, or otherwise try
@@ -993,14 +1036,23 @@
though, because the inner curlies will be considered a block that loops
once. See L<perlfunc/next>.
+=item Can't open %s
+
+(F) You tried to run a perl built with MAD support with
+the PERL_XMLDUMP environment variable set, but the file
+named by that variable could not be opened.
+
=item Can't open %s: %s
(S inplace) The implicit opening of a file through use of the C<< <> >>
filehandle, either implicitly under the C<-n> or C<-p> command-line
-switches, or explicitly, failed for the indicated reason. Usually this
-is because you don't have read permission for a file which you named on
-the command line.
+switches, or explicitly, failed for the indicated reason. Usually
+this is because you don't have read permission for a file which
+you named on the command line.
+(F) You tried to call perl with the B<-e> switch, but F</dev/null> (or
+your operating system's equivalent) could not be opened.
+
=item Can't open a reference
(W io) You tried to open a scalar reference for reading or writing,
@@ -1042,7 +1094,7 @@
redirection, and couldn't open the pipe into which to send data destined
for stdout.
-=item Can't open perl script%s
+=item Can't open perl script "%s": %s
(F) The script you specified can't be opened for the indicated reason.
@@ -1083,11 +1135,18 @@
(P) An error peculiar to VMS. Perl thought stdin was a pipe, and tried
to reopen it to accept binary data. Alas, it failed.
+=item Can't reset %ENV on this system
+
+(F) You called C<reset('E')> or similar, which tried to reset
+all variables in the current package beginning with "E". In
+the main package, that includes %ENV. Resetting %ENV is not
+supported on some systems, notably VMS.
+
=item Can't resolve method "%s" overloading "%s" in package "%s"
-(F|P) Error resolving overloading specified by a method name (as opposed
-to a subroutine reference): no such method callable via the package. If
-the method name is C<???>, this is an internal error.
+(F)(P) Error resolving overloading specified by a method name (as
+opposed to a subroutine reference): no such method callable via the
+package. If the method name is C<???>, this is an internal error.
=item Can't return %s from lvalue subroutine
@@ -1102,11 +1161,11 @@
=item Can't return %s to lvalue scalar context
-(F) You tried to return a complete array or hash from an lvalue subroutine,
-but you called the subroutine in a way that made Perl think you meant
-to return only one value. You probably meant to write parentheses around
-the call to the subroutine, which tell Perl that the call should be in
-list context.
+(F) You tried to return a complete array or hash from an lvalue
+subroutine, but you called the subroutine in a way that made Perl
+think you meant to return only one value. You probably meant to
+write parentheses around the call to the subroutine, which tell
+Perl that the call should be in list context.
=item Can't stat script "%s"
@@ -1116,7 +1175,7 @@
=item Can't take log of %g
(F) For ordinary real numbers, you can't take the logarithm of a
-negative number or zero. There's a Math::Complex package that comes
+negative number or zero. There's a Math::Complex package that comes
standard with Perl, though, if you really want to do that for the
negative numbers.
@@ -1139,6 +1198,11 @@
specialized, however, that they cannot be interconverted. This message
indicates that such a conversion was attempted.
+=item Can't use '%c' after -mname
+
+(F) You tried to call perl with the B<-m> switch, but you put something
+other than "=" after the module name.
+
=item Can't use anonymous symbol table for method lookup
(F) The internal routine that does method lookup was handed a symbol
@@ -1157,8 +1221,8 @@
=item Can't use %! because Errno.pm is not available
-(F) The first time the %! hash is used, perl automatically loads the
-Errno.pm module. The Errno module is expected to tie the %! hash to
+(F) The first time the C<%!> hash is used, perl automatically loads the
+Errno.pm module. The Errno module is expected to tie the %! hash to
provide symbolic names for C<$!> errno values.
=item Can't use both '<' and '>' after type '%c' in %s
@@ -1203,8 +1267,13 @@
=item Can't use string ("%s") as %s ref while "strict refs" in use
-(F) Only hard references are allowed by "strict refs". Symbolic
-references are disallowed. See L<perlref>.
+(F) You've told Perl to dereference a string, something which
+C<use strict> blocks to prevent it happening accidentally. See
+L<perlref/"Symbolic references">. This can be triggered by an C<@> or C<$>
+in a double-quoted string immediately before interpolating a variable,
+for example in C<"user @$twitter_id">, which says to treat the contents
+of C<$twitter_id> as an array reference; use a C<\> to have a literal C<@>
+symbol followed by the contents of C<$twitter_id>: C<"user \@$twitter_id">.
=item Can't use subscript on %s
@@ -1221,18 +1290,18 @@
value that prints out looking like SCALAR(0xdecaf). Use the $1 form
instead.
-=item Can't use "when" outside a topicalizer
+=item Can't weaken a nonreference
+(F) You attempted to weaken something that was not a reference. Only
+references can be weakened.
+
+=item Can't "when" outside a topicalizer
+
(F) You have used a when() block that is neither inside a C<foreach>
-loop nor a C<given> block. (Note that this error is issued on exit
+loop nor a C<given> block. (Note that this error is issued on exit
from the C<when> block, so you won't get the error if the match fails,
or if you use an explicit C<continue>.)
-=item Can't weaken a nonreference
-
-(F) You attempted to weaken something that was not a reference. Only
-references can be weakened.
-
=item Can't x= to read-only value
(F) You tried to repeat a constant value (often the undefined value)
@@ -1241,12 +1310,13 @@
=item Character following "\c" must be ASCII
-(F|W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character.
-It is planned to make this fatal in all instances in Perl 5.16. In the
+(F)(W deprecated, syntax) In C<\cI<X>>, I<X> must be an ASCII character.
+It is planned to make this fatal in all instances in Perl v5.20. In the
cases where it isn't fatal, the character this evaluates to is
derived by exclusive or'ing the code point of this character with 0x40.
-Note that non-alphabetic ASCII characters are discouraged here as well.
+Note that non-alphabetic ASCII characters are discouraged here as well,
+and using non-printable ones will be deprecated starting in v5.18.
=item Character in 'C' format wrapped in pack
@@ -1269,9 +1339,9 @@
pack("U0W", $x)
-where $x is either less than 0 or more than 255. However, C<U0>-mode expects
-all values to fall in the interval [0, 255], so Perl behaved as if you
-meant:
+where $x is either less than 0 or more than 255. However, C<U0>-mode
+expects all values to fall in the interval [0, 255], so Perl behaved
+as if you meant:
pack("U0W", $x & 255)
@@ -1297,8 +1367,8 @@
unpack("H", "\x{2a1}")
where the format expects to process a byte (a character with a value
-below 256), but a higher value was provided instead. Perl uses the value
-modulus 256 instead, as if you had provided:
+below 256), but a higher value was provided instead. Perl uses the
+value modulus 256 instead, as if you had provided:
unpack("H", "\x{a1}")
@@ -1309,7 +1379,7 @@
pack("u", "\x{1f3}b")
where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
+value below 256), but some of the characters had a higher value. Perl
uses the character values modulus 256 instead, as if you had provided:
pack("u", "\x{f3}b")
@@ -1321,7 +1391,7 @@
unpack("s", "\x{1f3}b")
where the format expects to process a sequence of bytes (character with a
-value below 256), but some of the characters had a higher value. Perl
+value below 256), but some of the characters had a higher value. Perl
uses the character values modulus 256 instead, as if you had provided:
unpack("s", "\x{f3}b")
@@ -1331,7 +1401,7 @@
(D deprecated, syntax) The C<\cI<X>> construct is intended to be a way
to specify non-printable characters. You used it with a "{" which
evaluates to ";", which is printable. It is planned to remove the
-ability to specify a semi-colon this way in Perl 5.16. Just use a
+ability to specify a semi-colon this way in Perl 5.20. Just use a
semi-colon or a backslash-semi-colon without the "\c".
=item "\c%c" is more clearly written simply as "%s"
@@ -1341,6 +1411,10 @@
written as simply itself, perhaps preceded by a backslash for non-word
characters.
+=item Cloning substitution context is unimplemented
+
+(F) Creating a new thread inside the C<s///> operator is not supported.
+
=item close() on unopened filehandle %s
(W unopened) You tried to close a filehandle that was never opened.
@@ -1358,21 +1432,23 @@
=item Code missing after '/'
-(F) You had a (sub-)template that ends with a '/'. There must be another
-template code following the slash. See L<perlfunc/pack>.
+(F) You had a (sub-)template that ends with a '/'. There must be
+another template code following the slash. See L<perlfunc/pack>.
=item Code point 0x%X is not Unicode, may not be portable
-=item Code point 0x%X is not Unicode, no properties match it; all inverse properties do
+=item Code point 0x%X is not Unicode, all \p{} matches fail; all \P{} matches
+succeed
-(W utf8, non_unicode) You had a code point above the Unicode maximum of U+10FFFF.
+(S utf8, non_unicode) You had a code point above the Unicode maximum
+of U+10FFFF.
-Perl allows strings to contain a superset of Unicode code
-points, up to the limit of what is storable in an unsigned integer on
-your system, but these may not be accepted by other languages/systems.
-At one time, it was legal in some standards to have code points up to
-0x7FFF_FFFF, but not higher. Code points above 0xFFFF_FFFF require
-larger than a 32 bit word.
+Perl allows strings to contain a superset of Unicode code points, up
+to the limit of what is storable in an unsigned integer on your system,
+but these may not be accepted by other languages/systems. At one time,
+it was legal in some standards to have code points up to 0x7FFF_FFFF,
+but not higher. Code points above 0xFFFF_FFFF require larger than a
+32 bit word.
None of the Unicode or Perl-defined properties will match a non-Unicode
code point. For example,
@@ -1385,11 +1461,24 @@
will match.
+This may be counterintuitive at times, as both these fail:
+
+ chr(0x110000) =~ /\p{ASCII_Hex_Digit=True}/ # Fails.
+ chr(0x110000) =~ /\p{ASCII_Hex_Digit=False}/ # Also fails!
+
+and both these succeed:
+
+ chr(0x110000) =~ /\P{ASCII_Hex_Digit=True}/ # Succeeds.
+ chr(0x110000) =~ /\P{ASCII_Hex_Digit=False}/ # Also succeeds!
+
=item %s: Command not found
-(A) You've accidentally run your script through B<csh> instead of Perl.
-Check the #! line, or manually feed your script into Perl yourself.
+(A) You've accidentally run your script through B<csh> or another shell
+shell instead of Perl. Check the #! line, or manually feed your script
+into Perl yourself. The #! line at the top of your file could look like
+ #!/usr/bin/perl -w
+
=item Compilation failed in require
(F) Perl could not compile a file specified in a C<require> statement.
@@ -1410,25 +1499,25 @@
=item cond_broadcast() called on unlocked variable
-(W threads) Within a thread-enabled program, you tried to call
-cond_broadcast() on a variable which wasn't locked. The cond_broadcast()
-function is used to wake up another thread that is waiting in a
-cond_wait(). To ensure that the signal isn't sent before the other thread
-has a chance to enter the wait, it is usual for the signaling thread
-first to wait for a lock on variable. This lock attempt will only succeed
-after the other thread has entered cond_wait() and thus relinquished the
-lock.
+(W threads) Within a thread-enabled program, you tried to
+call cond_broadcast() on a variable which wasn't locked.
+The cond_broadcast() function is used to wake up another thread
+that is waiting in a cond_wait(). To ensure that the signal isn't
+sent before the other thread has a chance to enter the wait, it
+is usual for the signaling thread first to wait for a lock on
+variable. This lock attempt will only succeed after the other
+thread has entered cond_wait() and thus relinquished the lock.
=item cond_signal() called on unlocked variable
-(W threads) Within a thread-enabled program, you tried to call
-cond_signal() on a variable which wasn't locked. The cond_signal()
-function is used to wake up another thread that is waiting in a
-cond_wait(). To ensure that the signal isn't sent before the other thread
-has a chance to enter the wait, it is usual for the signaling thread
-first to wait for a lock on variable. This lock attempt will only succeed
-after the other thread has entered cond_wait() and thus relinquished the
-lock.
+(W threads) Within a thread-enabled program, you tried to
+call cond_signal() on a variable which wasn't locked. The
+cond_signal() function is used to wake up another thread that
+is waiting in a cond_wait(). To ensure that the signal isn't
+sent before the other thread has a chance to enter the wait, it
+is usual for the signaling thread first to wait for a lock on
+variable. This lock attempt will only succeed after the other
+thread has entered cond_wait() and thus relinquished the lock.
=item connect() on closed socket %s
@@ -1436,35 +1525,38 @@
to check the return value of your socket() call? See
L<perlfunc/connect>.
-=item Constant(%s)%s: %s
+=item Constant(%s): Call to &{$^H{%s}} did not return a defined value
+(F) The subroutine registered to handle constant overloading
+(see L<overload>) or a custom charnames handler (see
+L<charnames/CUSTOM TRANSLATORS>) returned an undefined value.
+
+=item Constant(%s): $^H{%s} is not defined
+
+(F) The parser found inconsistencies while attempting to define an
+overloaded constant. Perhaps you forgot to load the corresponding
+L<overload> pragma?.
+
+=item Constant(%s) unknown
+
(F) The parser found inconsistencies either while attempting to define
an overloaded constant, or when trying to find the character name
specified in the C<\N{...}> escape. Perhaps you forgot to load the
-corresponding C<overload> or C<charnames> pragma? See L<charnames> and
-L<overload>.
+corresponding L<overload> pragma?.
-=item Constant(%s)%s: %s in regex; marked by <-- HERE in m/%s/
-
-(F) The parser found inconsistencies while attempting to find
-the character name specified in the C<\N{...}> escape. Perhaps you
-forgot to load the corresponding C<charnames> pragma?
-See L<charnames>.
-
-
=item Constant is not %s reference
(F) A constant value (perhaps declared using the C<use constant> pragma)
is being dereferenced, but it amounts to the wrong type of reference.
-The message indicates the type of reference that was expected. This
+The message indicates the type of reference that was expected. This
usually indicates a syntax error in dereferencing the constant value.
See L<perlsub/"Constant Functions"> and L<constant>.
=item Constant subroutine %s redefined
-(S) You redefined a subroutine which had previously been
-eligible for inlining. See L<perlsub/"Constant Functions"> for
-commentary and workarounds.
+(W redefine)(S) You redefined a subroutine which had previously
+been eligible for inlining. See L<perlsub/"Constant Functions">
+for commentary and workarounds.
=item Constant subroutine %s undefined
@@ -1474,9 +1566,19 @@
=item Copy method did not return a reference
-(F) The method which overloads "=" is buggy. See
+(F) The method which overloads "=" is buggy. See
L<overload/Copy Constructor>.
+=item &CORE::%s cannot be called directly
+
+(F) You tried to call a subroutine in the C<CORE::> namespace
+with C<&foo> syntax or through a reference. Some subroutines
+in this package cannot yet be called that way, but must be
+called as barewords. Something like this will work:
+
+ BEGIN { *shove = \&CORE::push; }
+ shove @array, 1,2,3; # pushes on to @array
+
=item CORE::%s is not a keyword
(F) The CORE:: namespace is reserved for Perl keywords.
@@ -1495,6 +1597,13 @@
(P) The malloc package that comes with Perl had an internal failure.
+=item Corrupted regexp opcode %d > %d
+
+(F)
+This is either an error in Perl, or, if you're using one, your
+L<custom regular expression engine|perlreapi>. If not the latter,
+report the problem through the L<perlbug> utility.
+
=item Count after length/code in unpack
(F) You had an unpack template indicating a counted-length string, but
@@ -1501,6 +1610,8 @@
you have also specified an explicit size for the string. See
L<perlfunc/pack>.
+=item Deep recursion on anonymous subroutine
+
=item Deep recursion on subroutine "%s"
(W recursion) This subroutine has called itself (directly or indirectly)
@@ -1519,17 +1630,35 @@
=item defined(%hash) is deprecated
-(D deprecated) defined() is not usually useful on hashes because it
-checks for an undefined I<scalar> value. If you want to see if the hash
-is empty, just use C<if (%hash) { # not empty }> for example.
+(D deprecated) C<defined()> is not usually right on hashes and has been
+discouraged since 5.004.
-=item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in m/%s/
+Although C<defined %hash> is false on a plain not-yet-used hash, it
+becomes true in several non-obvious circumstances, including iterators,
+weak references, stash names, even remaining true after C<undef %hash>.
+These things make C<defined %hash> fairly useless in practice.
-(F) You used something like C<(?(DEFINE)...|..)> which is illegal. The
+If a check for non-empty is what you wanted then just put it in boolean
+context (see L<perldata/Scalar values>):
+
+ if (%hash) {
+ # not empty
+ }
+
+If you had C<defined %Foo::Bar::QUUX> to check whether such a package
+variable exists then that's never really been reliable, and isn't
+a good way to enquire about the features of a package, or whether
+it's loaded, etc.
+
+
+=item (?(DEFINE)....) does not allow branches in regex; marked by <-- HERE in
+m/%s/
+
+(F) You used something like C<(?(DEFINE)...|..)> which is illegal. The
most likely cause of this error is that you left out a parenthesis inside
of the C<....> part.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item %s defines neither package nor VERSION--version check failed
@@ -1543,22 +1672,14 @@
long for Perl to handle. You have to be seriously twisted to write code
that triggers this error.
-=item Deprecated character in \N{...}; marked by <-- HERE in \N{%s<-- HERE %s
-
-(D deprecated) Just about anything is legal for the C<...> in C<\N{...}>.
-But starting in 5.12, non-reasonable ones that don't look like names
-are deprecated. A reasonable name begins with an alphabetic character
-and continues with any combination of alphanumerics, dashes, spaces,
-parentheses or colons.
-
=item Deprecated use of my() in false conditional
-(D deprecated) You used a declaration similar to C<my $x if 0>.
-There has been a long-standing bug in Perl that causes a lexical variable
+(D deprecated) You used a declaration similar to C<my $x if 0>. There
+has been a long-standing bug in Perl that causes a lexical variable
not to be cleared at scope exit when its declaration includes a false
-conditional. Some people have exploited this bug to achieve a kind of
-static variable. Since we intend to fix this bug, we don't want people
-relying on this behavior. You can achieve a similar static effect by
+conditional. Some people have exploited this bug to achieve a kind of
+static variable. Since we intend to fix this bug, we don't want people
+relying on this behavior. You can achieve a similar static effect by
declaring the variable in a separate block outside the function, eg
sub f { my $x if 0; return $x++ }
@@ -1567,8 +1688,8 @@
{ my $x; sub f { return $x++ } }
-Beginning with perl 5.9.4, you can also use C<state> variables to
-have lexicals that are initialized only once (see L<feature>):
+Beginning with perl 5.9.4, you can also use C<state> variables to have
+lexicals that are initialized only once (see L<feature>):
sub f { state $x; return $x++ }
@@ -1575,8 +1696,8 @@
=item DESTROY created new reference to dead object '%s'
(F) A DESTROY() method created a new reference to the object which is
-just being DESTROYed. Perl is confused, and prefers to abort rather than
-to create a dangling reference.
+just being DESTROYed. Perl is confused, and prefers to abort rather
+than to create a dangling reference.
=item Did not produce a valid header
@@ -1618,7 +1739,7 @@
=item %s does not define %s::VERSION--version check failed
(F) You said something like "use Module 42" but the Module did not
-define a C<$VERSION.>
+define a C<$VERSION>.
=item '/' does not take a repeat count
@@ -1660,20 +1781,20 @@
=item Duplicate modifier '%c' after '%c' in %s
-(W) You have applied the same modifier more than once after a type
-in a pack template. See L<perlfunc/pack>.
+(W unpack) You have applied the same modifier more than once after a
+type in a pack template. See L<perlfunc/pack>.
=item elseif should be elsif
-(S syntax) There is no keyword "elseif" in Perl because Larry thinks it's
-ugly. Your code will be interpreted as an attempt to call a method named
-"elseif" for the class returned by the following block. This is
+(S syntax) There is no keyword "elseif" in Perl because Larry thinks
+it's ugly. Your code will be interpreted as an attempt to call a method
+named "elseif" for the class returned by the following block. This is
unlikely to be what you want.
-=item Empty %s
+=item Empty \%c{} in regex; marked by <-- HERE in m/%s/
(F) C<\p> and C<\P> are used to introduce a named Unicode property, as
-described in L<perlunicode> and L<perlre>. You used C<\p> or C<\P> in
+described in L<perlunicode> and L<perlre>. You used C<\p> or C<\P> in
a regular expression without specifying the property name.
=item entering effective %s failed
@@ -1685,7 +1806,7 @@
(F) You're running under taint mode, and the C<%ENV> variable has been
aliased to another hash, so it doesn't reflect anymore the state of the
-program's environment. This is potentially insecure.
+program's environment. This is potentially insecure.
=item Error converting file specification %s
@@ -1695,13 +1816,30 @@
an invalid file specification to Perl, or you've found a case the
conversion routines don't handle. Drat.
-=item %s: Eval-group in insecure regular expression
+=item Escape literal pattern white space under /x
+(D deprecated) You compiled a regular expression pattern with C</x> to
+ignore white space, and you used, as a literal, one of the characters
+that Perl plans to eventually treat as white space. The character must
+be escaped somehow, or it will work differently on a future Perl that
+does treat it as white space. The easiest way is to insert a backslash
+immediately before it, or to enclose it with square brackets. This
+change is to bring Perl into conformance with Unicode recommendations.
+Here are the five characters that generate this warning:
+U+0085 NEXT LINE,
+U+200E LEFT-TO-RIGHT MARK,
+U+200F RIGHT-TO-LEFT MARK,
+U+2028 LINE SEPARATOR,
+and
+U+2029 PARAGRAPH SEPARATOR.
+
+=item Eval-group in insecure regular expression
+
(F) Perl detected tainted data when trying to compile a regular
expression that contains the C<(?{ ... })> zero-width assertion, which
is unsafe. See L<perlre/(?{ code })>, and L<perlsec>.
-=item %s: Eval-group not allowed at runtime, use re 'eval'
+=item Eval-group not allowed at runtime, use re 'eval' in regex m/%s/
(F) Perl tried to compile a regular expression containing the
C<(?{ ... })> zero-width assertion at run time, as it would when the
@@ -1711,18 +1849,19 @@
interpolated string at run time and using that in an eval(). See
L<perlre/(?{ code })>.
-=item %s: Eval-group not allowed, use re 'eval'
+=item Eval-group not allowed, use re 'eval' in regex m/%s/
(F) A regular expression contained the C<(?{ ... })> zero-width
assertion, but that construct is only allowed when the C<use re 'eval'>
pragma is in effect. See L<perlre/(?{ code })>.
-=item EVAL without pos change exceeded limit in regex; marked by <-- HERE in m/%s/
+=item EVAL without pos change exceeded limit in regex; marked by <-- HERE in
+m/%s/
(F) You used a pattern that nested too many EVAL calls without consuming
-any text. Restructure the pattern so that text is consumed.
+any text. Restructure the pattern so that text is consumed.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item Excessively long <> operator
@@ -1735,7 +1874,7 @@
=item exec? I'm not *that* kind of operating system
(F) The C<exec> function is not implemented on some systems, e.g., Symbian
-OS. See L<perlport>.
+OS. See L<perlport>.
=item Execution of %s aborted due to compilation errors.
@@ -1767,6 +1906,25 @@
(W exiting) You are exiting a substitution by unconventional means, such
as a return, a goto, or a loop control statement.
+=item Expecting close bracket in regex; marked by <-- HERE in m/%s/
+
+(F)
+You wrote something like
+
+ (?13
+
+to denote a capturing group of the form
+L<C<(?I<PARNO>)>|perlre/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>,
+but omitted the C<")">.
+
+=item Experimental "%s" subs not enabled
+
+(F) To use lexical subs, you must first enable them:
+
+ no warnings 'experimental::lexical_subs';
+ use feature 'lexical_subs';
+ my sub foo { ... }
+
=item Explicit blessing to '' (assuming package main)
(W misc) You are blessing a reference to a zero length string. This has
@@ -1790,7 +1948,7 @@
(W regexp) A character class range must start and end at a literal
character, not another character class like C<\d> or C<[:alpha:]>. The "-"
in your false range is interpreted as a literal "-". Consider quoting the
-"-", "\-". The <-- HERE shows in the regular expression about where the
+"-", "\-". The <-- HERE shows whereabouts in the regular expression the
problem was discovered. See L<perlre>.
=item Fatal VMS error (status=%d) at %s, line %d
@@ -1812,9 +1970,9 @@
=item Field too wide in 'u' format in pack
-(W pack) Each line in an uuencoded string start with a length indicator
-which can't encode values above 63. So there is no point in asking for
-a line length bigger than that. Perl will behave as if you specified
+(W pack) Each line in an uuencoded string starts with a length indicator
+which can't encode values above 63. So there is no point in asking for
+a line length bigger than that. Perl will behave as if you specified
C<u63> as the format.
=item Filehandle %s opened only for input
@@ -1836,13 +1994,13 @@
=item Filehandle %s reopened as %s only for input
(W io) You opened for reading a filehandle that got the same filehandle id
-as STDOUT or STDERR. This occurred because you closed STDOUT or STDERR
+as STDOUT or STDERR. This occurred because you closed STDOUT or STDERR
previously.
=item Filehandle STDIN reopened as %s only for output
(W io) You opened for writing a filehandle that got the same filehandle id
-as STDIN. This occurred because you closed STDIN previously.
+as STDIN. This occurred because you closed STDIN previously.
=item Final $ should be \$ or $name
@@ -1917,6 +2075,13 @@
forget to check the return value of your socket() call? See
L<perlfunc/getsockopt>.
+=item given is experimental
+
+(S experimental::smartmatch) C<given> depends on both a lexical C<$_> and
+smartmatch, both of which are experimental, so its behavior may change or
+even be removed in any future release of perl.
+See the explanation under L<perlsyn/Experimental Details on given and when>.
+
=item Global symbol "%s" requires explicit package name
(F) You've said "use strict" or "use strict vars", which indicates
@@ -1926,15 +2091,15 @@
=item glob failed (%s)
-(W glob) Something went wrong with the external program(s) used for
-C<glob> and C<< <*.c> >>. Usually, this means that you supplied a
-C<glob> pattern that caused the external program to fail and exit with a
+(S glob) Something went wrong with the external program(s) used
+for C<glob> and C<< <*.c> >>. Usually, this means that you supplied a C<glob>
+pattern that caused the external program to fail and exit with a
nonzero status. If the message indicates that the abnormal exit
-resulted in a coredump, this may also mean that your csh (C shell) is
-broken. If so, you should change all of the csh-related variables in
-config.sh: If you have tcsh, make the variables refer to it as if it
-were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them all
-empty (except that C<d_csh> should be C<'undef'>) so that Perl will
+resulted in a coredump, this may also mean that your csh (C shell)
+is broken. If so, you should change all of the csh-related variables
+in config.sh: If you have tcsh, make the variables refer to it as
+if it were csh (e.g. C<full_csh='/usr/bin/tcsh'>); otherwise, make them
+all empty (except that C<d_csh> should be C<'undef'>) so that Perl will
think csh is missing. In either case, after editing config.sh, run
C<./Configure -S> and rebuild Perl.
@@ -1949,15 +2114,13 @@
(W overflow) You called C<gmtime> with a number that was larger than
it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
+date. This warning is also triggered with NaN (the special
not-a-number value).
=item gmtime(%f) too small
(W overflow) You called C<gmtime> with a number that was smaller than
-it can reliably handle and C<gmtime> probably returned the wrong
-date. This warning is also triggered with nan (the special
-not-a-number value).
+it can reliably handle and C<gmtime> probably returned the wrong date.
=item Got an error from DosAllocMem
@@ -1969,11 +2132,24 @@
(F) Unlike with "next" or "last", you're not allowed to goto an
unspecified destination. See L<perlfunc/goto>.
+=item Goto undefined subroutine%s
+
+(F) You tried to call a subroutine with C<goto &sub> syntax, but
+the indicated subroutine hasn't been defined, or if it was, it
+has since been undefined.
+
=item ()-group starts with a count
(F) A ()-group started with a count. A count is supposed to follow
something: a template character or a ()-group. See L<perlfunc/pack>.
+=item Group name must start with a non-digit word character in regex; marked by
+<-- HERE in m/%s/
+
+(F) Group names must follow the rules for perl identifiers, meaning
+they must start with a non-digit word character. A common cause of
+this error is using (?&0) instead of (?0). See L<perlre>.
+
=item %s had compilation errors.
(F) The final summary message when a C<perl -c> fails.
@@ -1994,26 +2170,6 @@
(F) The parser has given up trying to parse the program after 10 errors.
Further error messages would likely be uninformative.
-=item Having no space between pattern and following word is deprecated
-
-(D syntax)
-
-You had a word that isn't a regex modifier immediately following a
-pattern without an intervening space. If you are trying to use the C</le>
-flags on a substitution, use C</el> instead. Otherwise, add white space
-between the pattern and following word to eliminate the warning. As an
-example of the latter, the two constructs:
-
- $a =~ m/$foo/sand $bar
- $a =~ m/$foo/s and $bar
-
-both currently mean the same thing, but it is planned to disallow the first
-form in Perl 5.16. And,
-
- $a =~ m/$foo/and $bar
-
-will be disallowed too.
-
=item Hexadecimal number > 0xffffffff non-portable
(W portable) The hexadecimal number you specified is larger than 2**32-1
@@ -2020,6 +2176,16 @@
(4294967295) and therefore non-portable between systems. See
L<perlport> for more on portability concerns.
+=item -i used with no filenames on the command line, reading from STDIN
+
+(S inplace) The C<-i> option was passed on the command line, indicating
+that the script is intended to edit files inplace, but no files were
+given. This is usually a mistake, since editing STDIN inplace doesn't
+make sense, and can be confusing because it can make perl look like
+it is hanging when it is really just trying to read from STDIN. You
+should either pass a filename to edit, or remove C<-i> from the command
+line. See L<perlrun> for more details.
+
=item Identifier too long
(F) Perl limits identifiers (names for variables, functions, etc.) to
@@ -2027,11 +2193,11 @@
names (like C<$A::B>). You've exceeded Perl's limits. Future versions
of Perl are likely to eliminate these arbitrary limitations.
-=item Ignoring zero length \N{} in character class
+=item Ignoring zero length \N{} in character class in regex; marked by <-- HERE in m/%s/
-(W) Named Unicode character escapes (\N{...}) may return a
-zero length sequence. When such an escape is used in a character class
-its behaviour is not well defined. Check that the correct escape has
+(W regexp) Named Unicode character escapes C<(\N{...})> may return a zero-length
+sequence. When such an escape is used in a character class its
+behaviour is not well defined. Check that the correct escape has
been used, and the correct charname handler is in scope.
=item Illegal binary digit %s
@@ -2044,6 +2210,11 @@
binary number. Interpretation of the binary number stopped before the
offending digit.
+=item Illegal character after '_' in prototype for %s : %s
+
+(W illegalproto) An illegal character was found in a prototype declaration.
+Legal characters in prototypes are $, @, %, *, ;, [, ], &, \, and +.
+
=item Illegal character \%o (carriage return)
(F) Perl normally treats carriage returns in the program text as it
@@ -2060,11 +2231,11 @@
=item Illegal declaration of anonymous subroutine
(F) When using the C<sub> keyword to construct an anonymous subroutine,
-you must always specify a block of code. See L<perlsub>.
+you must always specify a block of code. See L<perlsub>.
=item Illegal declaration of subroutine %s
-(F) A subroutine was not declared correctly. See L<perlsub>.
+(F) A subroutine was not declared correctly. See L<perlsub>.
=item Illegal division by zero
@@ -2097,6 +2268,17 @@
(W digit) You may have tried to use an 8 or 9 in an octal number.
Interpretation of the octal number stopped before the 8 or 9.
+=item Illegal pattern in regex; marked by <-- HERE in m/%s/
+
+(F)
+You wrote something like
+
+ (?+foo)
+
+The C<"+"> is valid only when followed by digits, indicating a
+capturing group. See
+L<C<(?I<PARNO>)>|perlre/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>.
+
=item Illegal switch in PERL5OPT: -%c
(X) The PERL5OPT environment variable may only be used to set the
@@ -2126,8 +2308,37 @@
Failure of user callbacks dispatched using the C<G_KEEPERR> flag could
also result in this warning. See L<perlcall/G_KEEPERR>.
-=item Inconsistent hierarchy during C3 merge of class '%s': merging failed on parent '%s'
+=item In '(*VERB...)', splitting the initial '(*' is deprecated in regex; marked by <-- HERE in m/%s/
+(D regexp, deprecated)
+The two-character sequence C<"(*"> in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the C<"("> and the C<"*">, but you separated them.
+Due to an accident of implementation, this prohibition was not enforced,
+but we do plan to forbid it in a future Perl version. This message
+serves as giving you fair warning of this pending change.
+
+=item In '(?...)', splitting the initial '(?' is deprecated in regex; marked by <-- HERE in m/%s/
+
+(D regexp, deprecated)
+The two-character sequence C<"(?"> in this context in a regular
+expression pattern should be an indivisible token, with nothing
+intervening between the C<"("> and the C<"?">, but you separated them.
+Due to an accident of implementation, this prohibition was not enforced,
+but we do plan to forbid it in a future Perl version. This message
+serves as giving you fair warning of this pending change.
+
+=item Incomplete expression within '(?[ ])' in regex; marked by <-- HERE in m/%s/
+
+(F)
+There was a syntax error within the C<(?[ ])>. This can happen if the
+expression inside the construct was completely empty, or if there are
+too many or few operands for the number of operators. Perl is not smart
+enough to give you a more precise indication as to what is wrong.
+
+=item Inconsistent hierarchy during C3 merge of class '%s': merging failed on
+parent '%s'
+
(F) The method resolution order (MRO) of the given class is not
C3-consistent, and you have enabled the C3 MRO for this class. See the C3
documentation in L<mro> for more information.
@@ -2141,18 +2352,19 @@
=item Infinite recursion in regex; marked by <-- HERE in m/%s/
(F) You used a pattern that references itself without consuming any input
-text. You should check the pattern to ensure that recursive patterns
+text. You should check the pattern to ensure that recursive patterns
either consume text or fail.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item Initialization of state variables in list context currently forbidden
-(F) Currently the implementation of "state" only permits the initialization
-of scalar variables in scalar context. Re-write C<state ($a) = 42> as
-C<state $a = 42> to change from list to scalar context. Constructions such
-as C<state (@a) = foo()> will be supported in a future perl release.
+(F) Currently the implementation of "state" only permits the
+initialization of scalar variables in scalar context. Re-write
+C<state ($a) = 42> as C<state $a = 42> to change from list to scalar
+context. Constructions such as C<state (@a) = foo()> will be
+supported in a future perl release.
=item Insecure dependency in %s
@@ -2186,7 +2398,6 @@
function, i.e. C<\p{IsFoo}> or C<\p{InFoo}>.
See L<perlunicode/User-Defined Character Properties> and L<perlsec>.
-
=item Integer overflow in format string for %s
(F) The indexes and widths specified in the format string of C<printf()>
@@ -2195,7 +2406,7 @@
=item Integer overflow in %s number
-(W overflow) The hexadecimal, octal or binary number you have specified
+(S overflow) The hexadecimal, octal or binary number you have specified
either as a literal or as an argument to hex() or oct() is too big for
your architecture, and has been converted to a floating point number.
On a 32-bit architecture the largest hexadecimal, octal or binary number
@@ -2205,19 +2416,29 @@
internally--subject to loss of precision errors in subsequent
operations.
+=item Integer overflow in srand
+
+(S overflow) The number you have passed to srand is too big to fit
+in your architecture's integer representation. The number has been
+replaced with the largest integer supported (0xFFFFFFFF on 32-bit
+architectures). This means you may be getting less randomness than
+you expect, because different random seeds above the maximum will
+return the same sequence of random numbers.
+
=item Integer overflow in version
-(F) Some portion of a version initialization is too large for the
-size of integers for your architecture. This is not a warning
-because there is no rational reason for a version to try and use a
-element larger than typically 2**32. This is usually caused by
-trying to use some odd mathematical operation as a version, like
-100/9.
+=item Integer overflow in version %d
+(W overflow) Some portion of a version initialization is too large for
+the size of integers for your architecture. This is not a warning
+because there is no rational reason for a version to try and use an
+element larger than typically 2**32. This is usually caused by trying
+to use some odd mathematical operation as a version, like 100/9.
+
=item Internal disaster in regex; marked by <-- HERE in m/%s/
(P) Something went badly wrong in the regular expression parser.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item Internal inconsistency in tracking vforks
@@ -2231,8 +2452,8 @@
=item Internal urp in regex; marked by <-- HERE in m/%s/
-(P) Something went badly awry in the regular expression parser. The
-<-- HERE shows in the regular expression about where the problem was
+(P) Something went badly awry in the regular expression parser. The
+<-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item %s (...) interpreted as function
@@ -2252,26 +2473,60 @@
(F) The indicated attributes for a subroutine or variable were not
recognized by Perl or by a user-supplied handler. See L<attributes>.
+=item Invalid [] range "%*.*s" in regex; marked by <-- HERE in m/%s/
+
+(F)
+You wrote something like
+
+ [z-a]
+
+in a regular expression pattern. Ranges must be specified with the
+lowest code point first. Instead write
+
+ [a-z]
+
+=item Invalid character in \N{...}; marked by <-- HERE in \N{%s}
+
+(F) Only certain characters are valid for character names. The
+indicated one isn't. See L<charnames/CUSTOM ALIASES>.
+
+=item Invalid character in charnames alias definition; marked by <-- HERE in '%s
+
+(F) You tried to create a custom alias for a character name, with
+the C<:alias> option to C<use charnames> and the specified character in
+the indicated name isn't valid. See L<charnames/CUSTOM ALIASES>.
+
=item Invalid conversion in %s: "%s"
(W printf) Perl does not understand the given format conversion. See
L<perlfunc/sprintf>.
-=item Invalid escape in the specified encoding in regex; marked by <-- HERE in m/%s/
+=item Invalid escape in the specified encoding in regex; marked by <-- HERE in
+m/%s/
(W regexp) The numeric escape (for example C<\xHH>) of value < 256
didn't correspond to a single character through the conversion
from the encoding specified by the encoding pragma.
The escape was replaced with REPLACEMENT CHARACTER (U+FFFD) instead.
-The <-- HERE shows in the regular expression about where the
+The <-- HERE shows whereabouts in the regular expression the
escape was discovered.
=item Invalid hexadecimal number in \N{U+...}
+=item Invalid hexadecimal number in \N{U+...} in regex; marked by <-- HERE in
+m/%s/
+
(F) The character constant represented by C<...> is not a valid hexadecimal
number. Either it is empty, or you tried to use a character other than
0 - 9 or A - F, a - f in a hexadecimal number.
+=item Invalid module name %s with -%c option: contains single ':'
+
+(F) The module argument to perl's B<-m> and B<-M> command-line options
+cannot contain single colons in the module name, but only in the
+arguments after "=". In other words, B<-MFoo::Bar=:baz> is ok, but
+B<-MFoo:Bar=baz> is not.
+
=item Invalid mro name: '%s'
(F) You tried to C<mro::set_mro("classname", "foo")> or C<use mro 'foo'>,
@@ -2279,12 +2534,24 @@
the only valid ones supported are C<dfs> and C<c3>, unless you have loaded
a module that is a MRO plugin. See L<mro> and L<perlmroapi>.
+=item Invalid negative number (%s) in chr
+
+(W utf8) You passed a negative number to C<chr>. Negative numbers are
+not valid characters numbers, so it return the Unicode replacement
+character (U+FFFD).
+
+=item invalid option -D%c, use -D'' to see choices
+
+(S debugging) Perl was called with invalid debugger flags. Call perl
+with the B<-D> option with no flags to see the list of acceptable values.
+See also L<perlrun/-Dletters>.
+
=item Invalid [] range "%s" in regex; marked by <-- HERE in m/%s/
(F) The range specified in a character class had a minimum character
greater than the maximum character. One possibility is that you forgot the
C<{}> from your ending C<\x{}> - C<\x> without the curly braces can go only
-up to C<ff>. The <-- HERE shows in the regular expression about where the
+up to C<ff>. The <-- HERE shows whereabouts in the regular expression the
problem was discovered. See L<perlre>.
=item Invalid range "%s" in transliteration operator
@@ -2308,7 +2575,7 @@
=item Invalid strict version format (%s)
-(F) A version number did not meet the "strict" criteria for versions.
+(F) A version number did not meet the "strict" criteria for versions.
A "strict" version number is a positive decimal number (integer or
decimal-fraction) without exponentiation or else a dotted-decimal
v-string with a leading 'v' character and at least three components.
@@ -2319,27 +2586,28 @@
(F) The given character is not a valid pack or unpack type.
See L<perlfunc/pack>.
+
(W) The given character is not a valid pack or unpack type but used to be
silently ignored.
=item Invalid version format (%s)
-(F) A version number did not meet the "lax" criteria for versions.
+(F) A version number did not meet the "lax" criteria for versions.
A "lax" version number is a positive decimal number (integer or
decimal-fraction) without exponentiation or else a dotted-decimal
-v-string. If the v-string has fewer than three components, it must
-have a leading 'v' character. Otherwise, the leading 'v' is optional.
-Both decimal and dotted-decimal versions may have a trailing "alpha"
-component separated by an underscore character after a fractional or
-dotted-decimal component. The parenthesized text indicates which
-criteria were not met. See the L<version> module for more details on
-allowed version formats.
+v-string. If the v-string has fewer than three components, it
+must have a leading 'v' character. Otherwise, the leading 'v' is
+optional. Both decimal and dotted-decimal versions may have a
+trailing "alpha" component separated by an underscore character
+after a fractional or dotted-decimal component. The parenthesized
+text indicates which criteria were not met. See the L<version> module
+for more details on allowed version formats.
=item Invalid version object
-(F) The internal structure of the version object was invalid. Perhaps
-the internals were modified directly in some way or an arbitrary reference
-was blessed into the "version" class.
+(F) The internal structure of the version object was invalid.
+Perhaps the internals were modified directly in some way or
+an arbitrary reference was blessed into the "version" class.
=item ioctl is not implemented
@@ -2365,33 +2633,33 @@
=item $* is no longer supported
(D deprecated, syntax) The special variable C<$*>, deprecated in older
-perls, has been removed as of 5.9.0 and is no longer supported. In
+perls, has been removed as of 5.9.0 and is no longer supported. In
previous versions of perl the use of C<$*> enabled or disabled multi-line
matching within a string.
Instead of using C<$*> you should use the C</m> (and maybe C</s>) regexp
-modifiers. You can enable C</m> for a lexical scope (even a whole file)
-with C<use re '/m'>. (In older versions: when C<$*> was set to a true value
+modifiers. You can enable C</m> for a lexical scope (even a whole file)
+with C<use re '/m'>. (In older versions: when C<$*> was set to a true value
then all regular expressions behaved as if they were written using C</m>.)
=item $# is no longer supported
(D deprecated, syntax) The special variable C<$#>, deprecated in older
-perls, has been removed as of 5.9.3 and is no longer supported. You
+perls, has been removed as of 5.9.3 and is no longer supported. You
should use the printf/sprintf functions instead.
-=item `%s' is not a code reference
+=item '%s' is not a code reference
-(W overload) The second (fourth, sixth, ...) argument of overload::constant
-needs to be a code reference. Either an anonymous subroutine, or a reference
-to a subroutine.
+(W overload) The second (fourth, sixth, ...) argument of
+overload::constant needs to be a code reference. Either
+an anonymous subroutine, or a reference to a subroutine.
-=item `%s' is not an overloadable type
+=item '%s' is not an overloadable type
(W overload) You tried to overload a constant type the overload package is
unaware of.
-=item junk on end of regexp
+=item Junk on end of regexp in regex m/%s/
(P) The regular expression parser is confused.
@@ -2421,16 +2689,29 @@
=item length/code after end of string in unpack
(F) While unpacking, the string buffer was already used up when an unpack
-length/code combination tried to obtain more data. This results in
-an undefined value for the length. See L<perlfunc/pack>.
+length/code combination tried to obtain more data. This results in
+an undefined value for the length. See L<perlfunc/pack>.
+=item length() used on %s
+
+(W syntax) You used length() on either an array or a hash when you
+probably wanted a count of the items.
+
+Array size can be obtained by doing:
+
+ scalar(@array);
+
+The number of items in a hash can be obtained by doing:
+
+ scalar(keys %hash);
+
=item Lexing code attempted to stuff non-Latin-1 character into Latin-1 input
(F) An extension is attempting to insert text into the current parse
-(using L<lex_stuff_pvn|perlapi/lex_stuff_pvn> or similar), but tried to insert a character
-that couldn't be part of the current input. This is an inherent pitfall
-of the stuffing mechanism, and one of the reasons to avoid it. Where it
-is necessary to stuff, stuffing only plain ASCII is recommended.
+(using L<lex_stuff_pvn|perlapi/lex_stuff_pvn> or similar), but tried to insert a character that
+couldn't be part of the current input. This is an inherent pitfall
+of the stuffing mechanism, and one of the reasons to avoid it. Where
+it is necessary to stuff, stuffing only plain ASCII is recommended.
=item Lexing code internal error (%s)
@@ -2443,11 +2724,17 @@
to check the return value of your socket() call? See
L<perlfunc/listen>.
+=item List form of piped open not implemented
+
+(F) On some platforms, notably Windows, the three-or-more-arguments
+form of C<open> does not support pipes, such as C<open($pipe, '|-', @args)>.
+Use the two-argument C<open($pipe, '|prog arg1 arg2...')> form instead.
+
=item localtime(%f) too large
(W overflow) You called C<localtime> with a number that was larger
than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
+wrong date. This warning is also triggered with NaN (the special
not-a-number value).
=item localtime(%f) too small
@@ -2454,43 +2741,47 @@
(W overflow) You called C<localtime> with a number that was smaller
than it can reliably handle and C<localtime> probably returned the
-wrong date. This warning is also triggered with nan (the special
-not-a-number value).
+wrong date.
=item Lookbehind longer than %d not implemented in regex m/%s/
(F) There is currently a limit on the length of string which lookbehind can
-handle. This restriction may be eased in a future release.
+handle. This restriction may be eased in a future release.
=item Lost precision when %s %f by 1
-(W) The value you attempted to increment or decrement by one is too large
-for the underlying floating point representation to store accurately,
-hence the target of C<++> or C<--> is unchanged. Perl issues this warning
-because it has already switched from integers to floating point when values
-are too large for integers, and now even floating point is insufficient.
-You may wish to switch to using L<Math::BigInt> explicitly.
+(W imprecision) The value you attempted to increment or decrement by one
+is too large for the underlying floating point representation to store
+accurately, hence the target of C<++> or C<--> is unchanged. Perl issues this
+warning because it has already switched from integers to floating point
+when values are too large for integers, and now even floating point is
+insufficient. You may wish to switch to using L<Math::BigInt> explicitly.
-=item lstat() on filehandle %s
+=item lstat() on filehandle%s
(W io) You tried to do an lstat on a filehandle. What did you mean
by that? lstat() makes sense only on filenames. (Perl did a fstat()
instead on the filehandle.)
+=item lvalue attribute %s already-defined subroutine
+
+(W misc) Although L<attributes.pm|attributes> allows this, turning the lvalue
+attribute on or off on a Perl subroutine that is already defined
+does not always work properly. It may or may not do what you
+want, depending on what code is inside the subroutine, with exact
+details subject to change between Perl versions. Only do this
+if you really know what you are doing.
+
=item lvalue attribute ignored after the subroutine has been defined
-(W misc) Making a subroutine an lvalue subroutine after it has been defined
-by declaring the subroutine with an lvalue attribute is not
-possible. To make the subroutine an lvalue subroutine add the
-lvalue attribute to the definition, or put the declaration before
-the definition.
+(W misc) Using the C<:lvalue> declarative syntax to make a Perl
+subroutine an lvalue subroutine after it has been defined is
+not permitted. To make the subroutine an lvalue subroutine,
+add the lvalue attribute to the definition, or put the C<sub
+foo :lvalue;> declaration before the definition.
-=item Lvalue subs returning %s not implemented yet
+See also L<attributes.pm|attributes>.
-(F) Due to limitations in the current implementation, array and hash
-values cannot be returned in subroutines used in lvalue context. See
-L<perlsub/"Lvalue subroutines">.
-
=item Malformed integer in [] in pack
(F) Between the brackets enclosing a numeric repeat count only digits
@@ -2524,12 +2815,12 @@
=item Malformed UTF-8 character (%s)
-(S utf8) (F) Perl detected a string that didn't comply with UTF-8
+(S utf8)(F) Perl detected a string that didn't comply with UTF-8
encoding rules, even though it had the UTF8 flag on.
One possible cause is that you set the UTF8 flag yourself for data that
you thought to be in UTF-8 but it wasn't (it was for example legacy
-8-bit data). To guard against this, you can use Encode::decode_utf8.
+8-bit data). To guard against this, you can use Encode::decode_utf8.
If you use the C<:encoding(UTF-8)> PerlIO layer for input, invalid byte
sequences are handled gracefully, but if you use C<:utf8>, the flag is
@@ -2538,8 +2829,16 @@
See also L<Encode/"Handling Malformed Data">.
-=item Malformed UTF-8 returned by \N
+=item Malformed UTF-8 character immediately after '%s'
+(F) You said C<use utf8>, but the program file doesn't comply with UTF-8
+encoding rules. The message prints out the properly encoded characters
+just before the first bad one. If C<utf8> warnings are enabled, a
+warning is generated that gives more details about the type of
+malformation.
+
+=item Malformed UTF-8 returned by \N{%s} immediately after '%s'
+
(F) The charnames handler returned malformed UTF-8.
=item Malformed UTF-8 string in '%c' format in unpack
@@ -2566,16 +2865,16 @@
(W regexp) The pattern you've specified would be an infinite loop if the
regular expression engine didn't specifically check for that. The <-- HERE
-shows in the regular expression about where the problem was discovered.
+shows whereabouts in the regular expression the problem was discovered.
See L<perlre>.
=item Maximal count of pending signals (%u) exceeded
-(F) Perl aborted due to too high a number of signals pending. This
+(F) Perl aborted due to too high a number of signals pending. This
usually indicates that your operating system tried to deliver signals
too fast (with a very high priority), starving the perl process from
resources it would need to reach a point where it can process signals
-safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.)
+safely. (See L<perlipc/"Deferred Signals (Safe Signals)">.)
=item "%s" may clash with future reserved word
@@ -2583,7 +2882,7 @@
interpreter, especially if the word that is being warned about is
"use" or "my".
-=item % may not be used in pack
+=item '%' may not be used in pack
(F) You can't pack a string by supplying a checksum, because the
checksumming process loses information, and you can't go the other way.
@@ -2621,6 +2920,8 @@
=item Missing braces on \N{}
+=item Missing braces on \N{} in regex; marked by <-- HERE in m/%s/
+
(F) Wrong syntax of character name literal C<\N{charname}> within
double-quotish context. This can also happen when there is a space
(or comment) between the C<\N> and the C<{> in a regex with the C</x> modifier.
@@ -2647,7 +2948,7 @@
(F) A double-quoted string ended with "\c", without the required control
character name.
-=item Missing name in "my sub"
+=item Missing name in "%s sub"
(F) The reserved syntax for lexically scoped subroutines requires that
they have a name with which they can be found.
@@ -2663,7 +2964,7 @@
(S syntax) This is an educated guess made in conjunction with the message
"%s found where operator expected". Often the missing operator is a comma.
-=item Missing right brace on %s
+=item Missing right brace on \%c{} in regex; marked by <-- HERE in m/%s/
(F) Missing right brace in C<\x{...}>, C<\p{...}>, C<\P{...}>, or C<\N{...}>.
@@ -2673,7 +2974,7 @@
The traditional one has it followed by a name enclosed in braces,
meaning the character (or sequence of characters) given by that
-name. Thus C<\N{ASTERISK}> is another way of writing C<*>, valid in both
+name. Thus C<\N{ASTERISK}> is another way of writing C<*>, valid in both
double-quoted strings and regular expression patterns. In patterns,
it doesn't have the meaning an unescaped C<*> does.
@@ -2719,10 +3020,10 @@
Yet another way is to assign to a C<foreach> loop I<VAR> when I<VAR>
is aliased to a constant in the look I<LIST>:
- $x = 1;
- foreach my $n ($x, 2) {
- $n *= 2; # modifies the $x, but fails on attempt to modify the 2
- }
+ $x = 1;
+ foreach my $n ($x, 2) {
+ $n *= 2; # modifies the $x, but fails on attempt to
+ } # modify the 2
=item Modification of non-creatable array value attempted, %s
@@ -2747,7 +3048,7 @@
=item More than one argument to '%s' open
-(F) The C<open> function has been asked to open multiple files. This
+(F) The C<open> function has been asked to open multiple files. This
can happen if you are trying to open a pipe to a command that takes a
list of arguments, but have forgotten to specify a piped open mode.
See L<perlfunc/open> for details.
@@ -2790,7 +3091,8 @@
the same; if a program uses $c only once but also uses any of the others it
will not trigger this warning.
-=item \N in a character class must be a named character: \N{...}
+=item \N in a character class must be a named character: \N{...} in regex;
+marked by <-- HERE in m/%s/
(F) The new (5.12) meaning of C<\N> as C<[^\n]> is not valid in a bracketed
character class, for the same reason that C<.> in a character class loses
@@ -2797,7 +3099,7 @@
its specialness: it matches almost everything, which is probably not
what you want.
-=item \N{NAME} must be resolved by the lexer
+=item \N{NAME} must be resolved by the lexer in regex; marked by <-- HERE in m/%s/
(F) When compiling a regex pattern, an unresolved named character or
sequence was encountered. This can happen in any of several ways that
@@ -2828,6 +3130,25 @@
/\N {SPACE}/x; # Wrong!
/\N{SPACE}/x; # ok
+=item Need exactly 3 octal digits in regex; marked by <-- HERE in m/%s/
+
+(F) Within S<C<(?[ ])>>, all constants interpreted as octal need to be
+exactly 3 digits long. This helps catch some ambiguities. If your
+constant is too short, add leading zeros, like
+
+ (?[ [ \078 ] ]) # Syntax error!
+ (?[ [ \0078 ] ]) # Works
+ (?[ [ \007 8 ] ]) # Clearer
+
+The maximum number this construct can express is C<\777>. If you
+need a larger one, you need to use L<\o{}|perlrebackslash/Octal escapes>
+instead. If you meant two separate things, you need to separate them
+
+ (?[ [ \7776 ] ]) # Syntax error!
+ (?[ [ \o{7776} ] ]) # One meaning
+ (?[ [ \777 6 ] ]) # Another meaning
+ (?[ [ \777 \006 ] ]) # Still another
+
=item Negative '/' count in unpack
(F) The length count obtained from a length/code unpack operation was
@@ -2845,9 +3166,9 @@
=item Nested quantifiers in regex; marked by <-- HERE in m/%s/
-(F) You can't quantify a quantifier without intervening parentheses. So
-things like ** or +* or ?* are illegal. The <-- HERE shows in the regular
-expression about where the problem was discovered.
+(F) You can't quantify a quantifier without intervening parentheses.
+So things like ** or +* or ?* are illegal. The <-- HERE shows
+whereabouts in the regular expression the problem was discovered.
Note that the minimal matching quantifiers, C<*?>, C<+?>, and
C<??> appear to be nested quantifiers, but aren't. See L<perlre>.
@@ -2870,23 +3191,33 @@
will be another way to do what you want that is, if not secure, at least
securable. See L<perlsec>.
+=item No code specified for -%c
+
+(F) Perl's B<-e> and B<-E> command-line options require an argument. If
+you want to run an empty program, pass the empty string as a separate
+argument or run a program consisting of a single 0 or 1:
+
+ perl -e ""
+ perl -e0
+ perl -e1
+
=item No comma allowed after %s
-(F) A list operator that has a filehandle or "indirect object" is not
-allowed to have a comma between that and the following arguments.
+(F) A list operator that has a filehandle or "indirect object" is
+not allowed to have a comma between that and the following arguments.
Otherwise it'd be just another one of the arguments.
-One possible cause for this is that you expected to have imported a
-constant to your name space with B<use> or B<import> while no such
-importing took place, it may for example be that your operating system
-does not support that particular constant. Hopefully you did use an
-explicit import list for the constants you expect to see; please see
-L<perlfunc/use> and L<perlfunc/import>. While an explicit import list
-would probably have caught this error earlier it naturally does not
-remedy the fact that your operating system still does not support that
-constant. Maybe you have a typo in the constants of the symbol import
-list of B<use> or B<import> or in the constant name at the line where
-this error was triggered?
+One possible cause for this is that you expected to have imported
+a constant to your name space with B<use> or B<import> while no such
+importing took place, it may for example be that your operating
+system does not support that particular constant. Hopefully you did
+use an explicit import list for the constants you expect to see;
+please see L<perlfunc/use> and L<perlfunc/import>. While an
+explicit import list would probably have caught this error earlier
+it naturally does not remedy the fact that your operating system
+still does not support that constant. Maybe you have a typo in
+the constants of the symbol import list of B<use> or B<import> or in the
+constant name at the line where this error was triggered?
=item No command into which to pipe on command line
@@ -2913,6 +3244,11 @@
module) didn't define a C<DB::sub> routine to be called at the beginning
of each ordinary subroutine call.
+=item No directory specified for -I
+
+(F) The B<-I> command-line switch requires a directory name as part of the
+I<same> argument. Use B<-Ilib>, for instance. B<-I lib> won't work.
+
=item No error file after 2> or 2>> on command line
(F) An error peculiar to VMS. Perl handles its own command line
@@ -2922,7 +3258,7 @@
=item No group ending character '%c' found in template
(F) A pack or unpack template has an opening '(' or '[' without its
-matching counterpart. See L<perlfunc/pack>.
+matching counterpart. See L<perlfunc/pack>.
=item No input file after < on command line
@@ -2935,7 +3271,7 @@
(F) C<next::method> found no further instances of this method name
in the remaining packages of the MRO of this class. If you don't want
it throwing an exception, use C<maybe::next::method>
-or C<next::can>. See L<mro>.
+or C<next::can>. See L<mro>.
=item "no" not allowed in expression
@@ -2975,16 +3311,12 @@
(F) Configure didn't find anything resembling the setreuid() call for
your system.
-=item No %s specified for -%c
-
-(F) The indicated command line switch needs a mandatory argument, but
-you haven't specified one.
-
=item No such class field "%s" in variable %s of type %s
-(F) You tried to access a key from a hash through the indicated typed variable
-but that key is not allowed by the package of the same type. The indicated
-package has restricted the set of allowed keys using the L<fields> pragma.
+(F) You tried to access a key from a hash through the indicated typed
+variable but that key is not allowed by the package of the same type.
+The indicated package has restricted the set of allowed keys using the
+L<fields> pragma.
=item No such class %s
@@ -3015,11 +3347,6 @@
use the ref() function to find out what kind of ref it really was. See
also L<perlref>.
-=item Not a format reference
-
-(F) I'm not sure how you managed to generate a reference to an anonymous
-format, but this indicates you did, and that it didn't exist.
-
=item Not a GLOB reference
(F) Perl was trying to evaluate a reference to a "typeglob" (that is, a
@@ -3086,18 +3413,43 @@
F<SYS$TIMEZONE_DIFFERENTIAL> to translate to the number of seconds which
need to be added to UTC to get local time.
+=item Non-hex character in regex; marked by <-- HERE in m/%s/
+
+(F)
+In a regular expression, there was a non-hexadecimal character where
+a hex one was expected, like
+
+ (?[ [ \xDG ] ])
+ (?[ [ \x{DEKA} ] ])
+
=item Non-octal character '%c'. Resolved as "%s"
-(W digit) In parsing an octal numeric constant, a character was
-unexpectedly encountered that isn't octal. The resulting value is as
-indicated.
+(W digit) In parsing an octal numeric constant, a character was
+unexpectedly encountered that isn't octal. The resulting value
+is as indicated.
+=item Non-octal character in regex; marked by <-- HERE in m/%s/
+
+(F)
+In a regular expression, there was a non-octal character where
+an octal one was expected, like
+
+ (?[ [ \o{1278} ] ])
+
=item Non-string passed as bitmask
(W misc) A number has been passed as a bitmask argument to select().
Use the vec() function to construct the file descriptor bitmasks for
-select. See L<perlfunc/select>.
+select. See L<perlfunc/select>.
+=item (?[...]) not valid in locale in regex; marked by <-- HERE in m/%s/
+
+(F)
+C<(?[...])> cannot be used within the scope of a C<S<use locale>> or
+with an C</l> regular expression modifier, as that would require
+deferring to run-time the calculation of what it should evaluate to, and
+it is regex compile-time only.
+
=item Null filename used
(F) You can't require the null filename, especially because on many
@@ -3105,7 +3457,7 @@
=item NULL OP IN RUN
-(P debugging) Some internal routine called run() with a null opcode
+(S debugging) Some internal routine called run() with a null opcode
pointer.
=item Null picture in formline
@@ -3137,14 +3489,16 @@
=item Number with no digits
(F) Perl was looking for a number but found nothing that looked like
-a number. This happens, for example with C<\o{}>, with no number between
+a number. This happens, for example with C<\o{}>, with no number between
the braces.
-=item Octal number in vector unsupported
+=item "my %s" used in sort comparison
-(F) Numbers with a leading C<0> are not currently allowed in vectors.
-The octal number interpretation of such numbers may be supported in a
-future version.
+(W syntax) The package variables $a and $b are used for sort comparisons.
+You used $a or $b in as an operand to the C<< <=> >> or C<cmp> operator inside a
+sort comparison block, and the variable had earlier been declared as a
+lexical variable. Either qualify the sort variable with the package
+name, or rename the lexical variable.
=item Octal number > 037777777777 non-portable
@@ -3155,7 +3509,7 @@
=item Odd number of arguments for overload::constant
(W overload) The call to overload::constant contained an odd number of
-arguments. The arguments should come in pairs.
+arguments. The arguments should come in pairs.
=item Odd number of elements in anonymous hash
@@ -3169,7 +3523,7 @@
=item Offset outside string
-(F|W layer) You tried to do a read/write/send/recv/seek operation
+(F)(W layer) You tried to do a read/write/send/recv/seek operation
with an offset pointing outside the buffer. This is difficult to
imagine. The sole exceptions to this are that zero padding will
take place when going past the end of the string when either
@@ -3188,6 +3542,12 @@
(W unopened) You tried to invoke a file test operator on a filehandle
that isn't open. Check your control flow. See also L<perlfunc/-X>.
+=item Strings with code points over 0xFF may not be mapped into in-memory file handles
+
+(W utf8) You tried to open a reference to a scalar for read or append
+where the scalar contained code points over 0xFF. In-memory files
+model on-disk files and can only contain bytes.
+
=item oops: oopsAV
(S internal) An internal warning that the grammar is screwed up.
@@ -3198,7 +3558,7 @@
=item Opening dirhandle %s also as a file
-(W io, deprecated) You used open() to associate a filehandle to
+(D io, deprecated) You used open() to associate a filehandle to
a symbol (glob or scalar) that already holds a dirhandle.
Although legal, this idiom might render your code confusing
and is deprecated.
@@ -3205,11 +3565,21 @@
=item Opening filehandle %s also as a directory
-(W io, deprecated) You used opendir() to associate a dirhandle to
+(D io, deprecated) You used opendir() to associate a dirhandle to
a symbol (glob or scalar) that already holds a filehandle.
Although legal, this idiom might render your code confusing
and is deprecated.
+=item Operand with no preceding operator in regex; marked by <-- HERE in m/%s/
+
+(F)
+You wrote something like
+
+ (?[ \p{Digit} \p{Thai} ])
+
+There are two operands, but no operator giving how you want to combine
+them.
+
=item Operation "%s": no method found, %s
(F) An attempt was made to perform an overloaded operation for which no
@@ -3219,10 +3589,9 @@
=item Operation "%s" returns its argument for non-Unicode code point 0x%X
-(W utf8, non_unicode) You performed an operation requiring Unicode
-semantics on a code
-point that is not in Unicode, so what it should do is not defined. Perl
-has chosen to have it do nothing, and warn you.
+(S utf8, non_unicode) You performed an operation requiring Unicode
+semantics on a code point that is not in Unicode, so what it should do
+is not defined. Perl has chosen to have it do nothing, and warn you.
If the operation shown is "ToFold", it means that case-insensitive
matching in a regular expression was done on the code point.
@@ -3232,12 +3601,12 @@
=item Operation "%s" returns its argument for UTF-16 surrogate U+%X
-(W utf8, surrogate) You performed an operation requiring Unicode
-semantics on a Unicode
-surrogate. Unicode frowns upon the use of surrogates for anything but
-storing strings in UTF-16, but semantics are (reluctantly) defined for
-the surrogates, and they are to do nothing for this operation. Because
-the use of surrogates can be dangerous, Perl warns.
+(S utf8, surrogate) You performed an operation requiring Unicode
+semantics on a Unicode surrogate. Unicode frowns upon the use of
+surrogates for anything but storing strings in UTF-16, but semantics
+are (reluctantly) defined for the surrogates, and they are to do
+nothing for this operation. Because the use of surrogates can be
+dangerous, Perl warns.
If the operation shown is "ToFold", it means that case-insensitive
matching in a regular expression was done on the code point.
@@ -3278,13 +3647,13 @@
=item Out of memory during "large" request for %s
(F) The malloc() function returned 0, indicating there was insufficient
-remaining memory (or virtual memory) to satisfy the request. However,
+remaining memory (or virtual memory) to satisfy the request. However,
the request was judged large enough (compile-time default is 64K), so a
possibility to shut down by trapping this error is granted.
=item Out of memory during request for %s
-(X|F) The malloc() function returned 0, indicating there was
+(X)(F) The malloc() function returned 0, indicating there was
insufficient remaining memory (or virtual memory) to satisfy the
request.
@@ -3320,19 +3689,24 @@
=item '@' outside of string with malformed UTF-8 in unpack
(F) You had a template that specified an absolute position outside
-the string being unpacked. The string being unpacked was also invalid
-UTF-8. See L<perlfunc/pack>.
+the string being unpacked. The string being unpacked was also invalid
+UTF-8. See L<perlfunc/pack>.
+=item overload arg '%s' is invalid
+
+(W overload) The L<overload> pragma was passed an argument it did not
+recognize. Did you mistype an operator?
+
=item Overloaded dereference did not return a reference
(F) An object with an overloaded dereference operator was dereferenced,
-but the overloaded operation did not return a reference. See
+but the overloaded operation did not return a reference. See
L<overload>.
=item Overloaded qr did not return a REGEXP
(F) An object with a C<qr> overload was used as part of a match, but the
-overloaded operation didn't return a compiled regexp. See L<overload>.
+overloaded operation didn't return a compiled regexp. See L<overload>.
=item %s package attribute may clash with future reserved word: %s
@@ -3362,15 +3736,21 @@
platform. Earlier checks mean that it should not be possible to
enter this branch on this platform.
-=item panic: ck_grep
+=item panic: child pseudo-process was never scheduled
+(P) A child pseudo-process in the ithreads implementation on Windows
+was not scheduled within the time period allowed and therefore was not
+able to initialize properly.
+
+=item panic: ck_grep, type=%u
+
(P) Failed an internal consistency check trying to compile a grep.
-=item panic: ck_split
+=item panic: ck_split, type=%u
(P) Failed an internal consistency check trying to compile a split.
-=item panic: corrupt saved stack index
+=item panic: corrupt saved stack index %ld
(P) The savestack was requested to restore more localized values than
there are in the savestack.
@@ -3380,13 +3760,6 @@
(P) Failed an internal consistency check while trying to reset a weak
reference.
-=item panic: Devel::DProf inconsistent subroutine return
-
-(P) Devel::DProf called a subroutine that exited using goto(LABEL),
-last(LABEL) or next(LABEL). Leaving that way a subroutine called from
-an XSUB will lead very probably to a crash of the interpreter. This is
-a bug that will hopefully one day get fixed.
-
=item panic: die %s
(P) We popped the context stack to an eval context, and then discovered
@@ -3411,7 +3784,7 @@
(P) The library function frexp() failed, making printf("%f") impossible.
-=item panic: goto
+=item panic: goto, type=%u, ix=%ld
(P) We popped the context stack to a context with the specified label,
and then discovered it wasn't a context we know how to do a goto in.
@@ -3419,22 +3792,15 @@
=item panic: gp_free failed to free glob pointer
(P) The internal routine used to clear a typeglob's entries tried
-repeatedly, but each time something re-created entries in the glob. Most
-likely the glob contains an object with a reference back to the glob and a
-destructor that adds a new object to the glob.
+repeatedly, but each time something re-created entries in the glob.
+Most likely the glob contains an object with a reference back to
+the glob and a destructor that adds a new object to the glob.
-=item panic: hfreeentries failed to free hash
+=item panic: INTERPCASEMOD, %s
-(P) The internal routine used to clear a hash's entries tried repeatedly,
-but each time something added more entries to the hash. Most likely the hash
-contains an object with a reference back to the hash and a destructor that
-adds a new object to the hash.
-
-=item panic: INTERPCASEMOD
-
(P) The lexer got into a bad state at a case modifier.
-=item panic: INTERPCONCAT
+=item panic: INTERPCONCAT, %s
(P) The lexer got into a bad state parsing a string with brackets.
@@ -3442,7 +3808,7 @@
(F) forked child returned an incomprehensible message about its errno.
-=item panic: last
+=item panic: last, type=%u
(P) We popped the context stack to a block context, and then discovered
it wasn't a block context.
@@ -3452,7 +3818,7 @@
(P) A writable lexical variable became read-only somehow within the
scope.
-=item panic: leave_scope inconsistency
+=item panic: leave_scope inconsistency %u
(P) The savestack probably got out of sync. At least, there was an
invalid enum on the top of it.
@@ -3462,7 +3828,7 @@
(P) Failed an internal consistency check while trying to reset all weak
references to an object.
-=item panic: malloc
+=item panic: malloc, %s
(P) Something requested a negative number of bytes of malloc.
@@ -3470,12 +3836,12 @@
(P) Something tried to allocate more memory than possible.
-=item panic: pad_alloc
+=item panic: pad_alloc, %p!=%p
(P) The compiler got confused about which scratch pad it was allocating
and freeing temporaries and lexicals from.
-=item panic: pad_free curpad
+=item panic: pad_free curpad, %p!=%p
(P) The compiler got confused about which scratch pad it was allocating
and freeing temporaries and lexicals from.
@@ -3484,7 +3850,7 @@
(P) An invalid scratch pad offset was detected internally.
-=item panic: pad_reset curpad
+=item panic: pad_reset curpad, %p!=%p
(P) The compiler got confused about which scratch pad it was allocating
and freeing temporaries and lexicals from.
@@ -3493,7 +3859,7 @@
(P) An invalid scratch pad offset was detected internally.
-=item panic: pad_swipe curpad
+=item panic: pad_swipe curpad, %p!=%p
(P) The compiler got confused about which scratch pad it was allocating
and freeing temporaries and lexicals from.
@@ -3502,7 +3868,7 @@
(P) An invalid scratch pad offset was detected internally.
-=item panic: pp_iter
+=item panic: pp_iter, type=%u
(P) The foreach iterator got called in a non-loop context frame.
@@ -3511,38 +3877,55 @@
(P) The internal pp_match() routine was called with invalid operational
data.
-=item panic: pp_split
+=item panic: pp_split, pm=%p, s=%p
(P) Something terrible went wrong in setting up for the split.
-=item panic: realloc
+=item panic: realloc, %s
(P) Something requested a negative number of bytes of realloc.
-=item panic: restartop
+=item panic: reference miscount on nsv in sv_replace() (%d != 1)
+(P) The internal sv_replace() function was handed a new SV with a
+reference count other than 1.
+
+=item panic: restartop in %s
+
(P) Some internal routine requested a goto (or something like it), and
didn't supply the destination.
-=item panic: return
+=item panic: return, type=%u
(P) We popped the context stack to a subroutine or eval context, and
then discovered it wasn't a subroutine or eval context.
-=item panic: scan_num
+=item panic: scan_num, %s
(P) scan_num() got called on something that wasn't a number.
+=item panic: Sequence (?{...}): no code block found
+
+(P) while compiling a pattern that has embedded (?{}) or (??{}) code
+blocks, perl couldn't locate the code block that should have already been
+seen and compiled by perl before control passed to the regex compiler.
+
=item panic: sv_chop %s
(P) The sv_chop() routine was passed a position that is not within the
scalar's string buffer.
-=item panic: sv_insert
+=item panic: sv_insert, midend=%p, bigend=%p
(P) The sv_insert() routine was told to remove more string than there
was string.
+=item panic: strxfrm() gets absurd - a => %u, ab => %u
+
+(P) The interpreter's sanity check of the C function strxfrm() failed.
+In your current locale the returned transformation of the string "ab" is
+shorter than that of the string "a", which makes no sense.
+
=item panic: top_env
(P) The compiler attempted to do a goto, or something weird like that.
@@ -3562,24 +3945,10 @@
(P) Something tried to call utf16_to_utf8_reversed with an odd (as opposed
to even) byte length.
-=item panic: yylex
+=item panic: yylex, %s
(P) The lexer got into a bad state while processing a case modifier.
-=item Parsing code internal error (%s)
-
-(F) Parsing code supplied by an extension violated the parser's API in
-a detectable way.
-
-=item Pattern subroutine nesting without pos change exceeded limit in regex; marked by <-- HERE in m/%s/
-
-(F) You used a pattern that uses too many nested subpattern calls without
-consuming any text. Restructure the pattern so text is consumed before the
-nesting limit is exceeded.
-
-The <-- HERE shows in the regular expression about where the problem was
-discovered.
-
=item Parentheses missing around "%s" list
(W parenthesis) You said something like
@@ -3592,6 +3961,32 @@
Remember that "my", "our", "local" and "state" bind tighter than comma.
+=item Parsing code internal error (%s)
+
+(F) Parsing code supplied by an extension violated the parser's API in
+a detectable way.
+
+=item Passing malformed UTF-8 to "%s" is deprecated
+
+(D deprecated, utf8) This message indicates a bug either in the Perl
+core or in XS code. Such code was trying to find out if a character,
+allegedly stored internally encoded as UTF-8, was of a given type, such
+as being punctuation or a digit. But the character was not encoded in
+legal UTF-8. The C<%s> is replaced by a string that can be used by
+knowledgeable people to determine what the type being checked against
+was. If C<utf8> warnings are enabled, a further message is raised,
+giving details of the malformation.
+
+=item Pattern subroutine nesting without pos change exceeded limit in regex;
+marked by <-- HERE in m/%s/
+
+(F) You used a pattern that uses too many nested subpattern calls without
+consuming any text. Restructure the pattern so text is consumed before
+the nesting limit is exceeded.
+
+The <-- HERE shows whereabouts in the regular expression the problem was
+discovered.
+
=item C<-p> destination: %s
(F) An error occurred during the implicit output invoked by the C<-p>
@@ -3604,13 +3999,14 @@
"Can't locate object method \"%s\" via package \"%s\"". It often means
that a method requires a package that has not been loaded.
-=item Perl folding rules are not up-to-date for 0x%x; please use the perlbug utility to report
+=item Perl folding rules are not up-to-date for 0x%X; please use the perlbug
+utility to report; in regex; marked by <-- HERE in m/%s/
-(W regex, deprecated) You used a regular expression with
+(D regexp, deprecated) You used a regular expression with
case-insensitive matching, and there is a bug in Perl in which the
built-in regular expression folding rules are not accurate. This may
lead to incorrect results. Please report this as a bug using the
-"perlbug" utility. (This message is marked deprecated, so that it by
+L<perlbug> utility. (This message is marked deprecated, so that it by
default will be turned-on.)
=item Perl_my_%s() not available
@@ -3620,6 +4016,15 @@
conversion functions. This is only a problem when you're using the
'<' or '>' modifiers in (un)pack templates. See L<perlfunc/pack>.
+=item Perl %s required (did you mean %s?)--this is only %s, stopped
+
+(F) The code you are trying to run has asked for a newer version of
+Perl than you are running. Perhaps C<use 5.10> was written instead
+of C<use 5.010> or C<use v5.10>. Without the leading C<v>, the number is
+interpreted as a decimal, with every three digits after the
+decimal point representing a part of the version number. So 5.10
+is equivalent to v5.100.
+
=item Perl %s required--this is only version %s, stopped
(F) The module in question uses features of a version of Perl more
@@ -3628,13 +4033,21 @@
=item PERL_SH_DIR too long
-(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
+(F) An error peculiar to OS/2. PERL_SH_DIR is the directory to find the
C<sh>-shell in. See "PERL_SH_DIR" in L<perlos2>.
=item PERL_SIGNALS illegal: "%s"
-See L<perlrun/PERL_SIGNALS> for legal values.
+(X) See L<perlrun/PERL_SIGNALS> for legal values.
+=item Perls since %s too modern--this is %s, stopped
+
+(F) The code you are trying to run claims it will not run
+on the version of Perl you are using because it is too new.
+Maybe the code needs to be updated, or maybe it is simply
+wrong and the version check should just be removed.
+
+
=item perl: warning: Setting locale failed.
(S) The whole warning message will look something like:
@@ -3657,6 +4070,27 @@
time you run Perl. How to really fix the problem can be found in
L<perllocale> section B<LOCALE PROBLEMS>.
+=item perl: warning: Non hex character in '$ENV{PERL_HASH_SEED}', seed only partially set
+
+(W) PERL_HASH_SEED should match /^\s*(?:0x)?[0-9a-fA-F]+\s*\z/ but it
+contained a non hex character. This could mean you are not using the hash
+seed you think you are.
+
+=item perl: warning: strange setting in '$ENV{PERL_PERTURB_KEYS}': '%s'
+
+(W) Perl was run with the environment variable PERL_PERTURB_KEYS defined
+but containing an unexpected value. The legal values of this setting
+are as follows.
+
+ Numeric | String | Result
+ --------+---------------+-----------------------------------------
+ 0 | NO | Disables key traversal randomization
+ 1 | RANDOM | Enables full key traversal randomization
+ 2 | DETERMINISTIC | Enables repeatable key traversal randomization
+
+Both numeric and string values are accepted, but note that string values are
+case sensitive. The default for this setting is "RANDOM" or 1.
+
=item pid %x not a child
(W exec) A warning peculiar to VMS. Waitpid() was asked to wait for a
@@ -3670,7 +4104,7 @@
=item POSIX class [:%s:] unknown in regex; marked by <-- HERE in m/%s/
(F) The class in the character class [: :] syntax is unknown. The <-- HERE
-shows in the regular expression about where the problem was discovered.
+shows whereabouts in the regular expression the problem was discovered.
Note that the POSIX character classes do B<not> have the C<is> prefix
the corresponding C interfaces have: in other words, it's C<[[:print:]]>,
not C<isprint>. See L<perlre>.
@@ -3680,31 +4114,34 @@
(F) Your system has POSIX getpgrp(), which takes no argument, unlike
the BSD version, which takes a pid.
-=item POSIX syntax [%s] belongs inside character classes in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [%c %c] belongs inside character classes in regex; marked by
+<-- HERE in m/%s/
(W regexp) The character class constructs [: :], [= =], and [. .] go
I<inside> character classes, the [] are part of the construct, for example:
/[012[:alpha:]345]/. Note that [= =] and [. .] are not currently
-implemented; they are simply placeholders for future extensions and will
-cause fatal errors. The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+implemented; they are simply placeholders for future extensions and
+will cause fatal errors. The <-- HERE shows whereabouts in the regular
+expression the problem was discovered. See L<perlre>.
-=item POSIX syntax [. .] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [. .] is reserved for future extensions in regex; marked by
+<-- HERE in m/%s/
-(F regexp) Within regular expression character classes ([]) the syntax
-beginning with "[." and ending with ".]" is reserved for future extensions.
-If you need to represent those character sequences inside a regular
-expression character class, just quote the square brackets with the
-backslash: "\[." and ".\]". The <-- HERE shows in the regular expression
-about where the problem was discovered. See L<perlre>.
+(F) Within regular expression character classes ([]) the syntax beginning
+with "[." and ending with ".]" is reserved for future extensions. If you
+need to represent those character sequences inside a regular expression
+character class, just quote the square brackets with the backslash: "\[."
+and ".\]". The <-- HERE shows whereabouts in the regular expression the
+problem was discovered. See L<perlre>.
-=item POSIX syntax [= =] is reserved for future extensions in regex; marked by <-- HERE in m/%s/
+=item POSIX syntax [= =] is reserved for future extensions in regex; marked by
+<-- HERE in m/%s/
(F) Within regular expression character classes ([]) the syntax beginning
with "[=" and ending with "=]" is reserved for future extensions. If you
need to represent those character sequences inside a regular expression
character class, just quote the square brackets with the backslash: "\[="
-and "=\]". The <-- HERE shows in the regular expression about where the
+and "=\]". The <-- HERE shows whereabouts in the regular expression the
problem was discovered. See L<perlre>.
=item Possible attempt to put comments in qw() list
@@ -3767,7 +4204,7 @@
if ($x & $y == 0) { ... }
This expression is actually equivalent to C<$x & ($y == 0)>, due to the
-higher precedence of C<==>. This is probably not what you want. (If you
+higher precedence of C<==>. This is probably not what you want. (If you
really meant to write this, disable the warning, or, better, put the
parentheses explicitly and write C<$x & ($y == 0)>).
@@ -3787,8 +4224,8 @@
=item Possible unintended interpolation of %s in string
-(W ambiguous) You said something like `@foo' in a double-quoted string
-but there was no array C<@foo> in scope at the time. If you wanted a
+(W ambiguous) You said something like '@foo' in a double-quoted string
+but there was no array C<@foo> in scope at the time. If you wanted a
literal @foo, then write it as \@foo; otherwise find out what happened
to the array you apparently lost track of.
@@ -3829,10 +4266,21 @@
L<perlipc/"Signals">. See also "Process terminated by SIGTERM/SIGINT"
in L<perlos2>.
+=item Property '%s' is unknown in regex; marked by <-- HERE in m/%s/
+
+(F)
+The named property which you specified via C<\p> or C<\P> is not one
+known to Perl. Perhaps you misspelled the name? See
+L<perluniprops/Properties accessible through \p{} and \P{}>
+for a complete list of available official properties. If it is a
+L<user-defined property|perlunicode/User-Defined Character Properties>
+it must have been defined by the time the regular expression is
+compiled.
+
=item Prototype after '%c' for %s : %s
-(W illegalproto) A character follows % or @ in a prototype. This is useless,
-since % and @ gobble the rest of the subroutine arguments.
+(W illegalproto) A character follows % or @ in a prototype. This is
+useless, since % and @ gobble the rest of the subroutine arguments.
=item Prototype mismatch: %s vs %s
@@ -3868,19 +4316,25 @@
case of that character is not in Latin1, in that locale it doesn't
change when upper cased.
+=item Quantifier {n,m} with n > m can't match in regex
+
+(W regexp) Minima should be less than or equal to maxima. If you really
+want your regexp to match something 0 times, just put {0}.
+
=item Quantifier follows nothing in regex; marked by <-- HERE in m/%s/
-(F) You started a regular expression with a quantifier. Backslash it if you
-meant it literally. The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+(F) You started a regular expression with a quantifier. Backslash it if
+you meant it literally. The <-- HERE shows whereabouts in the regular
+expression the problem was discovered. See L<perlre>.
=item Quantifier in {,} bigger than %d in regex; marked by <-- HERE in m/%s/
-(F) There is currently a limit to the size of the min and max values of the
-{min,max} construct. The <-- HERE shows in the regular expression about where
-the problem was discovered. See L<perlre>.
+(F) There is currently a limit to the size of the min and max values of
+the {min,max} construct. The <-- HERE shows whereabouts in the regular
+expression the problem was discovered. See L<perlre>.
-=item Quantifier unexpected on zero-length expression; marked by <-- HERE in m/%s/
+=item Quantifier unexpected on zero-length expression in regex; marked by <--
+HERE in m/%s/
(W regexp) You applied a regular expression quantifier in a place where
it makes no sense, such as on a zero-width assertion. Try putting the
@@ -3888,9 +4342,14 @@
"abc" provided that it is followed by three repetitions of "xyz" is
C</abc(?=(?:xyz){3})/>, not C</abc(?=xyz){3}/>.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
+=item Quantifier {n,m} with n > m can't match in regex; marked by <-- HERE in m/%s/
+
+(W regexp) Minima should be less than or equal to maxima. If you really
+want your regexp to match something 0 times, just put {0}.
+
=item Range iterator outside integer range
(F) One (or both) of the numeric arguments to the range operator ".."
@@ -3927,10 +4386,17 @@
=item Recompile perl with B<-D>DEBUGGING to use B<-D> switch
-(F debugging) You can't use the B<-D> option unless the code to produce
+(S debugging) You can't use the B<-D> option unless the code to produce
the desired output is compiled into Perl, which entails some overhead,
which is why it's currently left out of your copy.
+=item Recursive call to Perl_load_module in PerlIO_find_layer
+
+(P) It is currently not permitted to load modules when creating
+a filehandle inside an %INC hook. This can happen with C<open my
+$fh, '<', \$scalar>, which implicitly loads PerlIO::scalar. Try
+loading PerlIO::scalar explicitly first.
+
=item Recursive inheritance detected in package '%s'
(F) While calculating the method resolution order (MRO) of a package, Perl
@@ -3943,15 +4409,15 @@
=item refcnt_inc: fd %d%s
-(P) Perl's I/O implementation failed an internal consistency check. If
+(P) Perl's I/O implementation failed an internal consistency check. If
you see this message, something is very wrong.
=item Reference found where even-sized list expected
(W misc) You gave a single reference where Perl was expecting a list
-with an even number of elements (for assignment to a hash). This usually
-means that you used the anon hash constructor when you meant to use
-parens. In any case, a hash requires key/value B<pairs>.
+with an even number of elements (for assignment to a hash). This
+usually means that you used the anon hash constructor when you meant
+to use parens. In any case, a hash requires key/value B<pairs>.
%hash = { one => 1, two => 2, }; # WRONG
%hash = [ qw/ an anon array / ]; # WRONG
@@ -3963,26 +4429,21 @@
(W misc) You have attempted to weaken a reference that is already weak.
Doing so has no effect.
-=item Reference miscount in sv_replace()
+=item Reference to invalid group 0 in regex; marked by <-- HERE in m/%s/
-(W internal) The internal sv_replace() function was handed a new SV with
-a reference count other than 1.
+(F) You used C<\g0> or similar in a regular expression. You may refer
+to capturing parentheses only with strictly positive integers
+(normal backreferences) or with strictly negative integers (relative
+backreferences). Using 0 does not make sense.
-=item Reference to invalid group 0
-
-(F) You used C<\g0> or similar in a regular expression. You may refer to
-capturing parentheses only with strictly positive integers (normal
-backreferences) or with strictly negative integers (relative
-backreferences). Using 0 does not make sense.
-
=item Reference to nonexistent group in regex; marked by <-- HERE in m/%s/
(F) You used something like C<\7> in your regular expression, but there are
-not at least seven sets of capturing parentheses in the expression. If
+not at least seven sets of capturing parentheses in the expression. If
you wanted to have the character with ordinal 7 inserted into the regular
expression, prepend zeroes to make it three digits long: C<\007>
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item Reference to nonexistent named group in regex; marked by <-- HERE in m/%s/
@@ -3989,19 +4450,20 @@
(F) You used something like C<\k'NAME'> or C<< \k<NAME> >> in your regular
expression, but there is no corresponding named capturing parentheses
-such as C<(?'NAME'...)> or C<< (?<NAME>...) >>. Check if the name has been
+such as C<(?'NAME'...)> or C<< (?<NAME>...) >>. Check if the name has been
spelled correctly both in the backreference and the declaration.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
-=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE in m/%s/
+=item Reference to nonexistent or unclosed group in regex; marked by <-- HERE
+in m/%s/
(F) You used something like C<\g{-7}> in your regular expression, but there
are not at least seven sets of closed capturing parentheses in the
expression before where the C<\g{-7}> was located.
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered.
=item regexp memory corruption
@@ -4016,10 +4478,11 @@
(F syntax, regexp) The regular expression pattern had too many occurrences
of the specified modifier. Remove the extraneous ones.
-=item Regexp modifier "%c" may not appear after the "-"
+=item Regexp modifier "%c" may not appear after the "-" in regex; marked by <--
+HERE in m/%s/
-(F regexp) Turning off the given modifier has the side effect of turning
-on another one. Perl currently doesn't allow this. Reword the regular
+(F) Turning off the given modifier has the side effect of turning on
+another one. Perl currently doesn't allow this. Reword the regular
expression to use the modifier you want to turn on (and place it before
the minus), instead of the one you want to turn off.
@@ -4029,7 +4492,7 @@
mutually exclusive modifiers. Retain only the modifier that is
supposed to be there.
-=item Regexp out of space
+=item Regexp out of space in regex m/%s/
(P) A "can't happen" error, because safemalloc() should have caught it
earlier.
@@ -4038,14 +4501,23 @@
(F) Your format contains the ~~ repeat-until-blank sequence and a
numeric field that will never go blank so that the repetition never
-terminates. You might use ^# instead. See L<perlform>.
+terminates. You might use ^# instead. See L<perlform>.
=item Replacement list is longer than search list
(W misc) You have used a replacement list that is longer than the
-search list. So the additional elements in the replacement list
+search list. So the additional elements in the replacement list
are meaningless.
+=item '%s' resolved to '\o{%s}%d'
+
+(W misc, regexp) You wrote something like C<\08>, or C<\179> in a
+double-quotish string. All but the last digit is treated as a single
+character, specified in octal. The last digit is the next character in
+the string. To tell Perl that this is indeed what you want, you can use
+the C<\o{ }> syntax, or use exactly three digits to specify the octal
+for the character.
+
=item Reversed %s= operator
(W syntax) You wrote your assignment operator backwards. The = must
@@ -4058,10 +4530,11 @@
=item Scalars leaked: %d
-(P) Something went wrong in Perl's internal bookkeeping of scalars:
-not all scalar variables were deallocated by the time Perl exited.
-What this usually indicates is a memory leak, which is of course bad,
-especially if the Perl program is intended to be long-running.
+(S internal) Something went wrong in Perl's internal bookkeeping
+of scalars: not all scalar variables were deallocated by the time
+Perl exited. What this usually indicates is a memory leak, which
+is of course bad, especially if the Perl program is intended to be
+long-running.
=item Scalar value @%s[%s] better written as $%s[%s]
@@ -4111,7 +4584,7 @@
The question mark is also used as part of the ternary operator (as in
C<foo ? 0 : 1>) leading to some ambiguous constructions being wrongly
-parsed. One way to disambiguate the parsing is to put parentheses around
+parsed. One way to disambiguate the parsing is to put parentheses around
the conditional expression, i.e. C<(foo) ? 0 : 1>.
=item seekdir() attempted on invalid dirhandle %s
@@ -4154,20 +4627,20 @@
=item Sequence (? incomplete in regex; marked by <-- HERE in m/%s/
-(F) A regular expression ended with an incomplete extension (?. The <-- HERE
-shows in the regular expression about where the problem was discovered. See
-L<perlre>.
+(F) A regular expression ended with an incomplete extension (?. The
+<-- HERE shows whereabouts in the regular expression the problem was
+discovered. See L<perlre>.
=item Sequence (?%s...) not implemented in regex; marked by <-- HERE in m/%s/
-(F) A proposed regular expression extension has the character reserved but
-has not yet been written. The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+(F) A proposed regular expression extension has the character reserved
+but has not yet been written. The <-- HERE shows whereabouts in the
+regular expression the problem was discovered. See L<perlre>.
=item Sequence (?%s...) not recognized in regex; marked by <-- HERE in m/%s/
(F) You used a regular expression extension that doesn't make sense. The
-<-- HERE shows in the regular expression about where the problem was
+<-- HERE shows whereabouts in the regular expression the problem was
discovered. This happens when using the C<(?^...)> construct to tell
Perl to use the default regular expression modifiers, and you
redundantly specify a default modifier. For other
@@ -4178,19 +4651,16 @@
(F) The regular expression expects a mandatory argument following the escape
sequence and this has been omitted or incorrectly written.
-=item Sequence (?#... not terminated in regex; marked by <-- HERE in m/%s/
+=item Sequence (?#... not terminated in regex m/%s/
(F) A regular expression comment must be terminated by a closing
-parenthesis. Embedded parentheses aren't allowed. The <-- HERE shows in
-the regular expression about where the problem was discovered. See
+parenthesis. Embedded parentheses aren't allowed. See
L<perlre>.
-=item Sequence (?{...}) not terminated or not {}-balanced in regex; marked by <-- HERE in m/%s/
+=item Sequence (?{...}) not terminated with ')'
-(F) If the contents of a (?{...}) clause contain braces, they must balance
-for Perl to detect the end of the clause properly. The <-- HERE shows in
-the regular expression about where the problem was discovered. See
-L<perlre>.
+(F) The end of the perl code contained within the {...} must be
+followed immediately by a ')'.
=item Z<>500 Server error
@@ -4198,21 +4668,21 @@
=item Server error
-(A) This is the error message generally seen in a browser window when trying
-to run a CGI program (including SSI) over the web. The actual error text
-varies widely from server to server. The most frequently-seen variants
-are "500 Server error", "Method (something) not permitted", "Document
-contains no data", "Premature end of script headers", and "Did not
-produce a valid header".
+(A) This is the error message generally seen in a browser window
+when trying to run a CGI program (including SSI) over the web. The
+actual error text varies widely from server to server. The most
+frequently-seen variants are "500 Server error", "Method (something)
+not permitted", "Document contains no data", "Premature end of script
+headers", and "Did not produce a valid header".
B<This is a CGI error, not a Perl error>.
-You need to make sure your script is executable, is accessible by the
-user CGI is running the script under (which is probably not the user
-account you tested it under), does not rely on any environment variables
-(like PATH) from the user it isn't running under, and isn't in a
-location where the CGI server can't find it, basically, more or less.
-Please see the following for more information:
+You need to make sure your script is executable, is accessible by
+the user CGI is running the script under (which is probably not the
+user account you tested it under), does not rely on any environment
+variables (like PATH) from the user it isn't running under, and isn't
+in a location where the CGI server can't find it, basically, more or
+less. Please see the following for more information:
http://www.perl.org/CGI_MetaFAQ.html
http://www.htmlhelp.org/faq/cgifaq.html
@@ -4288,6 +4758,27 @@
(W signal) The signal handler named in %SIG doesn't, in fact, exist.
Perhaps you put it into the wrong package?
+=item Slab leaked from cv %p
+
+(S) If you see this message, then something is seriously wrong with the
+internal bookkeeping of op trees. An op tree needed to be freed after
+a compilation error, but could not be found, so it was leaked instead.
+
+=item sleep(%u) too large
+
+(W overflow) You called C<sleep> with a number that was larger than
+it can reliably handle and C<sleep> probably slept for less time than
+requested.
+
+=item Smartmatch is experimental
+
+(S experimental::smartmatch) This warning is emitted if you
+use the smartmatch (C<~~>) operator. This is currently an experimental
+feature, and its details are subject to change in future releases of
+Perl. Particularly, its current behavior is noticed for being
+unnecessarily complex and unintuitive, and is very likely to be
+overhauled.
+
=item Smart matching a non-overloaded object breaks encapsulation
(F) You should not use the C<~~> operator on an object that does not
@@ -4301,22 +4792,29 @@
=item Sort subroutine didn't return single value
-(F) A sort comparison subroutine may not return a list value with more
-or less than one element. See L<perlfunc/sort>.
+(F) A sort comparison subroutine written in XS must return exactly one
+item. See L<perlfunc/sort>.
+=item Source filters apply only to byte streams
+
+(F) You tried to activate a source filter (usually by loading a
+source filter module) within a string passed to C<eval>. This is
+not permitted under the C<unicode_eval> feature. Consider using
+C<evalbytes> instead. See L<feature>.
+
=item splice() offset past end of array
(W misc) You attempted to specify an offset that was past the end of
-the array passed to splice(). Splicing will instead commence at the end
-of the array, rather than past it. If this isn't what you want, try
-explicitly pre-extending the array by assigning $#array = $offset. See
-L<perlfunc/splice>.
+the array passed to splice(). Splicing will instead commence at the
+end of the array, rather than past it. If this isn't what you want,
+try explicitly pre-extending the array by assigning $#array = $offset.
+See L<perlfunc/splice>.
=item Split loop
(P) The split was looping infinitely. (Obviously, a split shouldn't
iterate more times than there are characters of input, which is what
-happened.) See L<perlfunc/split>.
+happened.) See L<perlfunc/split>.
=item Statement unlikely to be reached
@@ -4332,6 +4830,14 @@
sense to try to declare one with a package qualifier on the front. Use
local() if you want to localize a package variable.
+=item "state %s" used in sort comparison
+
+(W syntax) The package variables $a and $b are used for sort comparisons.
+You used $a or $b in as an operand to the C<< <=> >> or C<cmp> operator inside a
+sort comparison block, and the variable had earlier been declared as a
+lexical variable. Either qualify the sort variable with the package
+name, or rename the lexical variable.
+
=item stat() on unopened filehandle %s
(W unopened) You tried to use the stat() function on a filehandle that
@@ -4343,6 +4849,44 @@
stubs. Stubs should never be implicitly created, but explicit calls to
C<can> may break this.
+=item Subroutine "&%s" is not available
+
+(W closure) During compilation, an inner named subroutine or eval is
+attempting to capture an outer lexical subroutine that is not currently
+available. This can happen for one of two reasons. First, the lexical
+subroutine may be declared in an outer anonymous subroutine that has not
+yet been created. (Remember that named subs are created at compile time,
+while anonymous subs are created at run-time.) For example,
+
+ sub { my sub a {...} sub f { \&a } }
+
+At the time that f is created, it can't capture the current the "a" sub,
+since the anonymous subroutine hasn't been created yet. Conversely, the
+following won't give a warning since the anonymous subroutine has by now
+been created and is live:
+
+ sub { my sub a {...} eval 'sub f { \&a }' }->();
+
+The second situation is caused by an eval accessing a variable that has
+gone out of scope, for example,
+
+ sub f {
+ my sub a {...}
+ sub { eval '\&a' }
+ }
+ f()->();
+
+Here, when the '\&a' in the eval is being compiled, f() is not currently
+being executed, so its &a is not available for capture.
+
+=item "%s" subroutine &%s masks earlier declaration in same %s
+
+(W misc) A "my" or "state" subroutine has been redeclared in the
+current scope or statement, effectively eliminating all access to
+the previous instance. This is almost always a typographical error.
+Note that the earlier subroutine will still exist until the end of
+the scope or until all closure references to it are destroyed.
+
=item Subroutine %s redefined
(W redefine) You redefined a subroutine. To suppress this warning, say
@@ -4373,7 +4917,7 @@
=item substr outside of string
-(W substr),(F) You tried to reference a substr() that pointed outside of
+(W substr)(F) You tried to reference a substr() that pointed outside of
a string. That is, the absolute value of the offset was larger than the
length of the string. See L<perlfunc/substr>. This warning is fatal if
substr is used in an lvalue context (as the left hand side of an
@@ -4384,23 +4928,24 @@
(P) Perl tried to force the upgrade of an SV to a type which was actually
inferior to its current type.
-=item Switch (?(condition)... contains too many branches in regex; marked by <-- HERE in m/%s/
+=item Switch (?(condition)... contains too many branches in regex; marked by
+<-- HERE in m/%s/
-(F) A (?(condition)if-clause|else-clause) construct can have at most two
-branches (the if-clause and the else-clause). If you want one or both to
-contain alternation, such as using C<this|that|other>, enclose it in
-clustering parentheses:
+(F) A (?(condition)if-clause|else-clause) construct can have at most
+two branches (the if-clause and the else-clause). If you want one or
+both to contain alternation, such as using C<this|that|other>, enclose
+it in clustering parentheses:
(?(condition)(?:this|that|other)|else-clause)
-The <-- HERE shows in the regular expression about where the problem was
-discovered. See L<perlre>.
+The <-- HERE shows whereabouts in the regular expression the problem
+was discovered. See L<perlre>.
=item Switch condition not recognized in regex; marked by <-- HERE in m/%s/
(F) If the argument to the (?(...)if-clause|else-clause) construct is
-a number, it can be only a number. The <-- HERE shows in the regular
-expression about where the problem was discovered. See L<perlre>.
+a number, it can be only a number. The <-- HERE shows whereabouts in
+the regular expression the problem was discovered. See L<perlre>.
=item switching effective %s is not implemented
@@ -4430,10 +4975,9 @@
Occasionally the line number may be misleading, and once in a blue moon
the only way to figure out what's triggering the error is to call
C<perl -c> repeatedly, chopping away half the program each time to see
-if the error went away. Sort of the cybernetic version of S<20
-questions>.
+if the error went away. Sort of the cybernetic version of S<20 questions>.
-=item syntax error at line %d: `%s' unexpected
+=item syntax error at line %d: '%s' unexpected
(A) You've accidentally run your script through the Bourne shell instead
of Perl. Check the #! line, or manually feed your script into Perl
@@ -4453,6 +4997,12 @@
(W unopened) You tried to read from a filehandle that was never opened.
+=item Syntax error in (?[...]) in regex m/%s/
+
+(F)
+Perl could not figure out what you meant inside this construct; this
+notifies you that it is giving up trying.
+
=item System V %s is not implemented on this machine
(F) You tried to do something with a function beginning with "sem",
@@ -4498,9 +5048,9 @@
...
This is to prevent the problem of one module changing the array base out
-from under another module inadvertently. See L<perlvar/$[>.
+from under another module inadvertently. See L<perlvar/$[> and L<arybase>.
-=item The crypt() function is unimplemented due to excessive paranoia
+=item The crypt() function is unimplemented due to excessive paranoia.
(F) Configure couldn't find the crypt() function on your machine,
probably because your vendor didn't supply it, probably because they
@@ -4508,6 +5058,41 @@
will continue to pretend that it is. And if you quote me on that, I
will deny it.
+=item The lexical_subs feature is experimental
+
+(S experimental::lexical_subs) This warning is emitted if you
+declare a sub with C<my> or C<state>. Simply suppress the warning
+if you want to use the feature, but know that in doing so you
+are taking the risk of using an experimental feature which may
+change or be removed in a future Perl version:
+
+ no warnings "experimental::lexical_subs";
+ use feature "lexical_subs";
+ my sub foo { ... }
+
+=item The regex_sets feature is experimental
+
+(S experimental::regex_sets) This warning is emitted if you
+use the syntax S<C<(?[ ])>> in a regular expression.
+The details of this feature are subject to change.
+if you want to use it, but know that in doing so you
+are taking the risk of using an experimental feature which may
+change in a future Perl version, you can do this to silence the
+warning:
+
+ no warnings "experimental::regex_sets";
+
+=item The %s feature is experimental
+
+(S experimental) This warning is emitted if you enable an experimental
+feature via C<use feature>. Simply suppress the warning if you want
+to use the feature, but know that in doing so you are taking the risk
+of using an experimental feature which may change or be removed in a
+future Perl version:
+
+ no warnings "experimental::lexical_subs";
+ use feature "lexical_subs";
+
=item The %s function is unimplemented
(F) The function indicated isn't implemented on this architecture, according
@@ -4536,6 +5121,14 @@
target of the change to
%ENV which produced the warning.
+=item This Perl has not been built with support for randomized hash key traversal but something called Perl_hv_rand_set().
+
+(F) Something has attempted to use an internal API call which
+depends on Perl being compiled with the default support for randomized hash
+key traversal, but this Perl has been compiled without it. You should
+report this warning to the relevant upstream party, or recompile perl
+with default options.
+
=item thread failed to start: %s
(W threads)(S) The entry point function of threads->create() failed for some reason.
@@ -4547,16 +5140,16 @@
=item "-T" is on the #! line, it must also be used on the command line
-(X) The #! line (or local equivalent) in a Perl script contains the
-B<-T> option (or the B<-t> option), but Perl was not invoked with B<-T> in its command line.
-This is an error because, by the time Perl discovers a B<-T> in a
-script, it's too late to properly taint everything from the environment.
-So Perl gives up.
+(X) The #! line (or local equivalent) in a Perl script contains
+the B<-T> option (or the B<-t> option), but Perl was not invoked with
+B<-T> in its command line. This is an error because, by the time
+Perl discovers a B<-T> in a script, it's too late to properly taint
+everything from the environment. So Perl gives up.
If the Perl script is being executed as a command using the #!
-mechanism (or its local equivalent), this error can usually be fixed by
-editing the #! line so that the B<-%c> option is a part of Perl's first
-argument: e.g. change C<perl -n -%c> to C<perl -%c -n>.
+mechanism (or its local equivalent), this error can usually be
+fixed by editing the #! line so that the B<-%c> option is a part of
+Perl's first argument: e.g. change C<perl -n -%c> to C<perl -%c -n>.
If the Perl script is being executed as C<perl scriptname>, then the
B<-%c> option must appear on the command line: C<perl -%c scriptname>.
@@ -4582,13 +5175,14 @@
(X) The #! line (or local equivalent) in a Perl script contains the
B<-M>, B<-m> or B<-C> option.
-In the case of B<-M> and B<-m>, this is an error because those options are
-not intended for use inside scripts. Use the C<use> pragma instead.
+In the case of B<-M> and B<-m>, this is an error because those options
+are not intended for use inside scripts. Use the C<use> pragma instead.
-The B<-C> option only works if it is specified on the command line as well
-(with the same sequence of letters or numbers following). Either specify
-this option on the command line, or, if your system supports it, make your
-script executable and run it directly instead of passing it to perl.
+The B<-C> option only works if it is specified on the command line as
+well (with the same sequence of letters or numbers following). Either
+specify this option on the command line, or, if your system supports
+it, make your script executable and run it directly instead of passing
+it to perl.
=item Too late to run %s block
@@ -4621,6 +5215,14 @@
(F) The regular expression ends with an unbackslashed backslash.
Backslash it. See L<perlre>.
+=item Trailing white-space in a charnames alias definition is deprecated
+
+(D) You defined a character name which ended in a space character.
+Remove the trailing space(s). Usually these names are defined in the
+C<:alias> import argument to C<use charnames>, but they could be defined
+by a translator installed into C<$^H{charnames}>.
+See L<charnames/CUSTOM ALIASES>.
+
=item Transliteration pattern not terminated
(F) The lexer couldn't find the interior delimiter of a tr/// or tr[][]
@@ -4635,7 +5237,7 @@
=item '%s' trapped by operation mask
(F) You tried to use an operator from a Safe compartment in which it's
-disallowed. See L<Safe>.
+disallowed. See L<Safe>.
=item truncate not implemented
@@ -4642,6 +5244,13 @@
(F) Your machine doesn't implement a file truncation mechanism that
Configure knows about.
+=item Type of arg %d to &CORE::%s must be %s
+
+(F) The subroutine in question in the CORE package requires its argument
+to be a hard reference to data of the specified type. Overloading is
+ignored, so a reference to an object that is not the specified type, but
+nonetheless has overloading to handle it, will still not be accepted.
+
=item Type of arg %d to %s must be %s (not %s)
(F) This function requires the argument in that position to be of a
@@ -4659,28 +5268,30 @@
(F) Your machine doesn't implement the umask function and you tried to
use it to restrict permissions for yourself (EXPR & 0700).
-=item Unable to create sub named "%s"
-
-(F) You attempted to create or access a subroutine with an illegal name.
-
=item Unbalanced context: %d more PUSHes than POPs
-(W internal) The exit code detected an internal inconsistency in how
+(S internal) The exit code detected an internal inconsistency in how
many execution contexts were entered and left.
=item Unbalanced saves: %d more saves than restores
-(W internal) The exit code detected an internal inconsistency in how
+(S internal) The exit code detected an internal inconsistency in how
many values were temporarily localized.
=item Unbalanced scopes: %d more ENTERs than LEAVEs
-(W internal) The exit code detected an internal inconsistency in how
+(S internal) The exit code detected an internal inconsistency in how
many blocks were entered and left.
+=item Unbalanced string table refcount: (%d) for "%s"
+
+(S internal) On exit, Perl found some strings remaining in the shared
+string table used for copy on write and for hash keys. The entries
+should have been freed, so this indicates a bug somewhere.
+
=item Unbalanced tmps: %d more allocs than frees
-(W internal) The exit code detected an internal inconsistency in how
+(S internal) The exit code detected an internal inconsistency in how
many mortal scalars were allocated and freed.
=item Undefined format "%s" called
@@ -4729,18 +5340,69 @@
(F) The unexec() routine failed for some reason. See your local FSF
representative, who probably put it there in the first place.
+=item Unexpected '(' with no preceding operator in regex; marked by <-- HERE in m/%s/
+
+(F)
+You had something like this:
+
+ (?[ \p{Digit} ( \p{Lao} + \p{Thai} ) ])
+
+There should be an operator before the C<"(">, as there's no indication
+as to how the digits are to be combined with the characters in the Lao
+and Thai scripts.
+
+=item Unexpected ')' in regex; marked by <-- HERE in m/%s/
+
+(F)
+You had something like this:
+
+ (?[ ( \p{Digit} + ) ])
+
+The C<")"> is out-of-place. Something apparently was supposed to be
+combined with the digits, or the C<"+"> shouldn't be there, or something
+like that. Perl can't figure out what was intended.
+
+=item Unexpected binary operator '%c' with no preceding operand in regex; marked by <-- HERE in m/%s/
+
+(F)
+You had something like this:
+
+ (?[ | \p{Digit} ])
+
+where the C<"|"> is a binary operator with an operand on the right, but
+no operand on the left.
+
+=item Unexpected character in regex; marked by <-- HERE in m/%s/
+
+(F)
+You had something like this:
+
+ (?[ z ])
+
+Within C<(?[ ])>, no literal characters are allowed unless they are
+within an inner pair of square brackets, like
+
+ (?[ [ z ] ])
+
+Another possibility is that you forgot a backslash. Perl isn't smart
+enough to figure out what you really meant.
+
+=item Unexpected constant lvalue entersub entry via type/targ %d:%d
+
+(P) When compiling a subroutine call in lvalue context, Perl failed an
+internal consistency check. It encountered a malformed op tree.
+
=item Unicode non-character U+%X is illegal for open interchange
-(W utf8, nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are
-defined by the
-Unicode standard to be non-characters. Those are legal codepoints, but are
-reserved for internal use; so, applications shouldn't attempt to exchange
-them. If you know what you are doing you can turn
-off this warning by C<no warnings 'nonchar';>.
+(S utf8, nonchar) Certain codepoints, such as U+FFFE and U+FFFF, are
+defined by the Unicode standard to be non-characters. Those are
+legal codepoints, but are reserved for internal use; so, applications
+shouldn't attempt to exchange them. If you know what you are doing
+you can turn off this warning by C<no warnings 'nonchar';>.
=item Unicode surrogate U+%X is illegal in UTF-8
-(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
+(S utf8, surrogate) You had a UTF-16 surrogate in a context where they are
not considered acceptable. These code points, between U+D800 and
U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl
internally allows all unsigned integer code points (up to the size limit
@@ -4754,6 +5416,21 @@
(F) There are no byte-swapping functions for a machine with this byte
order.
+=item Unknown charname '%s'
+
+(F) The name you used inside C<\N{}> is unknown to Perl. Check the
+spelling. You can say C<use charnames ":loose"> to not have to be
+so precise about spaces, hyphens, and capitalization on standard Unicode
+names. (Any custom aliases that have been created must be specified
+exactly, regardless of whether C<:loose> is used or not.) This error may
+also happen if the C<\N{}> is not in the scope of the corresponding
+C<S<use charnames>>.
+
+=item Unknown error
+
+(P) Perl was about to print an error message in C<$@>, but the C<$@> variable
+did not exist, even after an attempt to create it.
+
=item Unknown open() mode '%s'
(F) The second argument of 3-argument open() is not among the list
@@ -4780,22 +5457,37 @@
(W) You tried to use an unknown subpragma of the "re" pragma.
+=item Unknown regex modifier "%s"
+
+(F) Alphanumerics immediately following the closing delimiter
+of a regular expression pattern are interpreted by Perl as modifier
+flags for the regex. One of the ones you specified is invalid. One way
+this can happen is if you didn't put in white space between the end of
+the regex and a following alphanumeric operator:
+
+ if ($a =~ /foo/and $bar == 3) { ... }
+
+The C<"a"> is a valid modifier flag, but the C<"n"> is not, and raises
+this error. Likely what was meant instead was:
+
+ if ($a =~ /foo/ and $bar == 3) { ... }
+
=item Unknown switch condition (?(%s in regex; marked by <-- HERE in m/%s/
(F) The condition part of a (?(condition)if-clause|else-clause) construct
-is not known. The condition must be one of the following:
+is not known. The condition must be one of the following:
- (1) (2) ... true if 1st, 2nd, etc., capture matched
- (<NAME>) ('NAME') true if named capture matched
- (?=...) (?<=...) true if subpattern matches
- (?!...) (?<!...) true if subpattern fails to match
- (?{ CODE }) true if code returns a true value
- (R) true if evaluating inside recursion
- (R1) (R2) ... true if directly inside capture group 1, 2, etc.
- (R&NAME) true if directly inside named capture
- (DEFINE) always false; for defining named subpatterns
+ (1) (2) ... true if 1st, 2nd, etc., capture matched
+ (<NAME>) ('NAME') true if named capture matched
+ (?=...) (?<=...) true if subpattern matches
+ (?!...) (?<!...) true if subpattern fails to match
+ (?{ CODE }) true if code returns a true value
+ (R) true if evaluating inside recursion
+ (R1) (R2) ... true if directly inside capture group 1, 2, etc.
+ (R&NAME) true if directly inside named capture
+ (DEFINE) always false; for defining named subpatterns
-The <-- HERE shows in the regular expression about where the problem was
+The <-- HERE shows whereabouts in the regular expression the problem was
discovered. See L<perlre>.
=item Unknown Unicode option letter '%c'
@@ -4816,7 +5508,7 @@
=item Unknown warnings category '%s'
-(F) An error issued by the C<warnings> pragma. You specified a warnings
+(F) An error issued by the C<warnings> pragma. You specified a warnings
category that is unknown to perl at this point.
Note that if you want to enable a warnings category registered by a
@@ -4823,19 +5515,42 @@
module (e.g. C<use warnings 'File::Find'>), you must have loaded this
module first.
-=item unmatched [ in regex; marked by <-- HERE in m/%s/
+=item Unmatched '%c' in POSIX class in regex; marked by <-- HERE in m/%s/
-(F) The brackets around a character class must match. If you wish to
+You had something like this:
+
+ (?[ [:alnum] ])
+
+There should be a second C<":">, like this:
+
+ (?[ [:alnum:] ])
+
+=item Unmatched [ in regex; marked by <-- HERE in m/%s/
+
+(F) The brackets around a character class must match. If you wish to
include a closing bracket in a character class, backslash it or put it
-first. The <-- HERE shows in the regular expression about where the problem
-was discovered. See L<perlre>.
+first. The <-- HERE shows whereabouts in the regular expression the
+problem was discovered. See L<perlre>.
-=item unmatched ( in regex; marked by <-- HERE in m/%s/
+=item Unmatched '[' in POSIX class in regex; marked by <-- HERE in m/%s/
+(F)
+You had something like this:
+
+ (?[ [:digit: ])
+
+That should be written:
+
+ (?[ [:digit:] ])
+
+=item Unmatched ( in regex; marked by <-- HERE in m/%s/
+
+=item Unmatched ) in regex; marked by <-- HERE in m/%s/
+
(F) Unbackslashed parentheses must always be balanced in regular
-expressions. If you're a vi user, the % key is valuable for finding the
-matching parenthesis. The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+expressions. If you're a vi user, the % key is valuable for finding
+the matching parenthesis. The <-- HERE shows whereabouts in the
+regular expression the problem was discovered. See L<perlre>.
=item Unmatched right %s bracket
@@ -4857,12 +5572,20 @@
in your Perl script (or eval) near the specified column. Perhaps you tried
to run a compressed script, a binary program, or a directory as a Perl program.
-=item Unrecognized escape \%c in character class passed through in regex; marked by <-- HERE in m/%s/
+=item Unrecognized escape \%c in character class in regex; marked by <-- HERE in m/%s/
+(F)
+You used a backslash-character combination which is not recognized by
+Perl inside character classes. This is a fatal error when the character
+class is used within C<(?[ ])>.
+
+=item Unrecognized escape \%c in character class passed through in regex;
+marked by <-- HERE in m/%s/
+
(W regexp) You used a backslash-character combination which is not
recognized by Perl inside character classes. The character was
understood literally, but this may change in a future version of Perl.
-The <-- HERE shows in the regular expression about where the
+The <-- HERE shows whereabouts in the regular expression the
escape was discovered.
=item Unrecognized escape \%c passed through
@@ -4874,10 +5597,9 @@
=item Unrecognized escape \%s passed through in regex; marked by <-- HERE in m/%s/
(W regexp) You used a backslash-character combination which is not
-recognized by Perl. The character(s) were understood literally, but this may
-change in a future version of Perl.
-The <-- HERE shows in the regular expression about where the
-escape was discovered.
+recognized by Perl. The character(s) were understood literally, but
+this may change in a future version of Perl. The <-- HERE shows
+whereabouts in the regular expression the escape was discovered.
=item Unrecognized signal name "%s"
@@ -4911,7 +5633,7 @@
(F) Your version of executable does not support forking.
Note that under some systems, like OS/2, there may be different flavors
-of Perl executables, some of which may support fork, some not. Try
+of Perl executables, some of which may support fork, some not. Try
changing the name you call Perl by to C<perl_>, C<perl__>, and so on.
=item Unsupported script encoding %s
@@ -4944,10 +5666,22 @@
compressed integer format and could not be converted to an integer.
See L<perlfunc/pack>.
+=item Unterminated delimiter for here document
+
+(F) This message occurs when a here document label has an initial
+quotation mark but the final quotation mark is missing. Perhaps
+you wrote:
+
+ <<"foo
+
+instead of:
+
+ <<"foo"
+
=item Unterminated \g{...} pattern in regex; marked by <-- HERE in m/%s/
(F) You missed a close brace on a \g{..} pattern (group reference) in
-a regular expression. Fix the pattern and retry.
+a regular expression. Fix the pattern and retry.
=item Unterminated <> operator
@@ -4959,12 +5693,12 @@
=item Unterminated verb pattern argument in regex; marked by <-- HERE in m/%s/
(F) You used a pattern of the form C<(*VERB:ARG)> but did not terminate
-the pattern with a C<)>. Fix the pattern and retry.
+the pattern with a C<)>. Fix the pattern and retry.
=item Unterminated verb pattern in regex; marked by <-- HERE in m/%s/
(F) You used a pattern of the form C<(*VERB)> but did not terminate
-the pattern with a C<)>. Fix the pattern and retry.
+the pattern with a C<)>. Fix the pattern and retry.
=item untie attempted while %d inner references still exist
@@ -4981,8 +5715,49 @@
(F) You called a Win32 function with incorrect arguments.
See L<Win32> for more information.
-=item Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in m/%s/
+=item $[ used in %s (did you mean $] ?)
+(W syntax) You used C<$[> in a comparison, such as:
+
+ if ($[ > 5.006) {
+ ...
+ }
+
+You probably meant to use C<$]> instead. C<$[> is the base for indexing
+arrays. C<$]> is the Perl version number in decimal.
+
+=item Use \\x{...} for more than two hex characters in regex; marked by <-- HERE in m/%s/
+
+(F)
+In a regular expression, you said something like
+
+ (?[ [ \xBEEF ] ])
+
+Perl isn't sure if you meant this
+
+ (?[ [ \x{BEEF} ] ])
+
+or if you meant this
+
+ (?[ [ \x{BE} E F ] ])
+
+You need to add either braces or blanks to disambiguate.
+
+=item Use of each() on hash after insertion without resetting hash iterator results in undefined behavior
+
+(S internal) The behavior of C<each()> after insertion is undefined, it may
+skip items, or visit items more than once. Consider using C<keys()> instead
+of C<each()>.
+
+=item Useless assignment to a temporary
+
+(W misc) You assigned to an lvalue subroutine, but what
+the subroutine returned was a temporary scalar about to
+be discarded, so the assignment had no effect.
+
+=item Useless (?-%s) - don't use /%s modifier in regex; marked by <-- HERE in
+m/%s/
+
(W regexp) You have used an internal modifier such as (?-o) that has no
meaning unless removed from the entire regexp:
@@ -4992,13 +5767,13 @@
if ($string =~ /$pattern/) { ... }
-The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+The <-- HERE shows whereabouts in the regular expression the problem was
+discovered. See L<perlre>.
=item Useless localization of %s
-(W syntax) The localization of lvalues such as C<local($x=10)> is
-legal, but in fact the local() currently has no effect. This may change at
+(W syntax) The localization of lvalues such as C<local($x=10)> is legal,
+but in fact the local() currently has no effect. This may change at
some point in the future, but in the meantime such code is discouraged.
=item Useless (?%s) - use /%s modifier in regex; marked by <-- HERE in m/%s/
@@ -5012,15 +5787,45 @@
if ($string =~ /$pattern/o) { ... }
-The <-- HERE shows in the regular expression about
-where the problem was discovered. See L<perlre>.
+The <-- HERE shows whereabouts in the regular expression the problem was
+discovered. See L<perlre>.
=item Useless use of /d modifier in transliteration operator
(W misc) You have used the /d modifier where the searchlist has the
-same length as the replacelist. See L<perlop> for more information
+same length as the replacelist. See L<perlop> for more information
about the /d modifier.
+=item Useless use of '\'; doesn't escape metacharacter '%c'
+
+(D deprecated) You wrote a regular expression pattern something like
+one of these:
+
+ m{ \x\{FF\} }x
+ m{foo\{1,3\}}
+ qr(foo\(bar\))
+ s[foo\[a-z\]bar][baz]
+
+The interior braces, square brackets, and parentheses are treated as
+metacharacters even though they are backslashed; instead write:
+
+ m{ \x{FF} }x
+ m{foo{1,3}}
+ qr(foo(bar))
+ s[foo[a-z]bar][baz]
+
+The backslashes have no effect when a regular expression pattern is
+delimitted by C<{}>, C<[]>, or C<()>, which ordinarily are
+metacharacters, and the delimiters are also used, paired, within the
+interior of the pattern. It is planned that a future Perl release will
+change the meaning of constructs like these so that the backslashes
+will have an effect, so remove them from your code.
+
+=item Useless use of \E
+
+(W misc) You have a \E in a double-quotish string without a C<\U>,
+C<\L> or C<\Q> preceding it.
+
=item Useless use of %s in void context
(W void) You did something without a side effect in a context that does
@@ -5063,7 +5868,7 @@
=item Useless use of "re" pragma
-(W) You did C<use re;> without any arguments. That isn't very useful.
+(W) You did C<use re;> without any arguments. That isn't very useful.
=item Useless use of sort in scalar context
@@ -5073,15 +5878,35 @@
This is not very useful, and perl currently optimizes this away.
+=item Useless use of (?-p) in regex; marked by <-- HERE in m/%s/
+
+(W regexp)
+The C<p> modifier cannot be turned off once set. Trying to do so is
+futile.
+
=item Useless use of %s with no values
(W syntax) You used the push() or unshift() function with no arguments
-apart from the array, like C<push(@x)> or C<unshift(@foo)>. That won't
-usually have any effect on the array, so is completely useless. It's
+apart from the array, like C<push(@x)> or C<unshift(@foo)>. That won't
+usually have any effect on the array, so is completely useless. It's
possible in principle that push(@tied_array) could have some effect
-if the array is tied to a class which implements a PUSH method. If so,
+if the array is tied to a class which implements a PUSH method. If so,
you can write it as C<push(@tied_array,())> to avoid this warning.
+=item Useless (%s%c) - %suse /%c modifier in regex; marked by <-- HERE in m/%s/
+
+(W regexp)
+The C</g> and C</o> regular expression modifiers are global and can't be
+turned off once set; hence things like C<(?g)> or C<(?-o:)> do nothing.
+
+=item Useless (%sc) - %suse /gc modifier in regex; marked by <-- HERE in m/%s/
+
+(W regexp)
+The C</c> regular expression modifier is global, can't be turned off
+once set, and doesn't do anything without the C</g> modifier being
+specified as well; hence things like C<(?c)> or C<(?-c:)> do nothing,
+nor do thing like C<(?gc)> nor C<(?-gc:)> .
+
=item "use" not allowed in expression
(F) The "use" keyword is recognized and executed at compile time, and
@@ -5090,7 +5915,7 @@
=item Use of assignment to $[ is deprecated
(D deprecated) The C<$[> variable (index of the first element in an array)
-is deprecated. See L<perlvar/"$[">.
+is deprecated. See L<perlvar/"$[">.
=item Use of bare << to mean <<"" is deprecated
@@ -5203,17 +6028,22 @@
it already went past any symlink you are presumably trying to look for.
The operation returned C<undef>. Use a filename instead.
+=item Use of my $_ is experimental
+
+(S experimental::lexical_topic) Lexical $_ is an experimental feature and
+its behavior may change or even be removed in any future release of perl.
+See the explanation under L<perlvar/$_>.
+
=item Use of %s on a handle without * is deprecated
-(D deprecated) You used C<tie>, C<tied> or C<untie> on a scalar but that
-scalar happens to hold a typeglob, which means its filehandle will
-be tied. If you mean to tie a handle, use an explicit * as in
-C<tie *$handle>.
+(D deprecated) You used C<tie>, C<tied> or C<untie> on a scalar but that scalar
+happens to hold a typeglob, which means its filehandle will be tied. If
+you mean to tie a handle, use an explicit * as in C<tie *$handle>.
-This is a long-standing bug that will be removed in Perl 5.16, as
-there is currently no way to tie the scalar itself when it holds
-a typeglob, and no way to untie a scalar that has had a typeglob
-assigned to it.
+This was a long-standing bug that was removed in Perl 5.16, as there was
+no way to tie the scalar itself when it held a typeglob, and no way to
+untie a scalar that had had a typeglob assigned to it. If you see this
+message, you must be using an older version.
=item Use of ?PATTERN? without explicit operator is deprecated
@@ -5224,17 +6054,6 @@
instead, explicitly using the C<m> operator: the question mark delimiter
still invokes match-once behaviour.
-=item Use of qw(...) as parentheses is deprecated
-
-(D deprecated) You have something like C<foreach $x qw(a b c) {...}>,
-using a C<qw(...)> list literal where a parenthesised expression is
-expected. Historically the parser fooled itself into thinking that
-C<qw(...)> literals were always enclosed in parentheses, and as a result
-you could sometimes omit parentheses around them. (You could never do
-the C<foreach qw(a b c) {...}> that you might have expected, though.)
-The parser no longer lies to itself in this way. Wrap the list literal
-in parentheses, like C<foreach $x (qw(a b c)) {...}>.
-
=item Use of reference "%s" as array index
(W misc) You tried to use a reference as an array index; this probably
@@ -5246,14 +6065,11 @@
however, because you can overload the numification and stringification
operators and then you presumably know what you are doing.
-=item Use of reserved word "%s" is deprecated
+=item Use of state $_ is experimental
-(D deprecated) The indicated bareword is a reserved word. Future
-versions of perl may use it as a keyword, so you're better off either
-explicitly quoting the word in a manner appropriate for its context of
-use, or using a different name altogether. The warning can be
-suppressed for subroutine names by either adding a C<&> prefix, or using
-a package qualifier, e.g. C<&our()>, or C<Foo::our()>.
+(S experimental::lexical_topic) Lexical $_ is an experimental feature and
+its behavior may change or even be removed in any future release of perl.
+See the explanation under L<perlvar/$_>.
=item Use of tainted arguments in %s is deprecated
@@ -5268,54 +6084,47 @@
defined. It was interpreted as a "" or a 0, but maybe it was a mistake.
To suppress this warning assign a defined value to your variables.
-To help you figure out what was undefined, perl will try to tell you the
-name of the variable (if any) that was undefined. In some cases it cannot
-do this, so it also tells you what operation you used the undefined value
-in. Note, however, that perl optimizes your program and the operation
-displayed in the warning may not necessarily appear literally in your
-program. For example, C<"that $foo"> is usually optimized into C<"that "
-. $foo>, and the warning will refer to the C<concatenation (.)> operator,
-even though there is no C<.> in your program.
+To help you figure out what was undefined, perl will try to tell you
+the name of the variable (if any) that was undefined. In some cases
+it cannot do this, so it also tells you what operation you used the
+undefined value in. Note, however, that perl optimizes your program
+anid the operation displayed in the warning may not necessarily appear
+literally in your program. For example, C<"that $foo"> is usually
+optimized into C<"that " . $foo>, and the warning will refer to the
+C<concatenation (.)> operator, even though there is no C<.> in
+your program.
=item Using a hash as a reference is deprecated
(D deprecated) You tried to use a hash as a reference, as in
C<< %foo->{"bar"} >> or C<< %$ref->{"hello"} >>. Versions of perl <= 5.6.1
-used to allow this syntax, but shouldn't have. It is now deprecated, and will
-be removed in a future version.
+used to allow this syntax, but shouldn't have. It is now
+deprecated, and will be removed in a future version.
=item Using an array as a reference is deprecated
(D deprecated) You tried to use an array as a reference, as in
C<< @foo->[23] >> or C<< @$ref->[99] >>. Versions of perl <= 5.6.1 used to
-allow this syntax, but shouldn't have. It is now deprecated, and will be
-removed in a future version.
+allow this syntax, but shouldn't have. It is now deprecated,
+and will be removed in a future version.
-=item Using just the first character returned by \N{} in character class
+=item Using just the first character returned by \N{} in character class in
+regex; marked by <-- HERE in m/%s/
-(W) A charnames handler may return a sequence of more than one character.
-Currently all but the first one are discarded when used in a regular
-expression pattern bracketed character class.
+(W regexp) A charnames handler may return a sequence of more than one
+character. Currently all but the first one are discarded when used in
+a regular expression pattern bracketed character class.
=item Using !~ with %s doesn't make sense
(F) Using the C<!~> operator with C<s///r>, C<tr///r> or C<y///r> is
currently reserved for future use, as the exact behaviour has not
-been decided. (Simply returning the boolean opposite of the
+been decided. (Simply returning the boolean opposite of the
modified string is usually not particularly useful.)
-=item User-defined case-mapping '%s' is deprecated
-
-(W deprecated) You defined a function, such as C<ToLower> that overrides
-the standard case mapping, such as C<lc()> gives. This feature is being
-deprecated due to its many issues, as documented in
-L<perlunicode/User-Defined Case Mappings (for serious hackers only)>.
-It is planned to remove this feature in Perl 5.16. A CPAN module
-providing improved functionality is being prepared.
-
=item UTF-16 surrogate U+%X
-(W utf8, surrogate) You had a UTF-16 surrogate in a context where they are
+(S utf8, surrogate) You had a UTF-16 surrogate in a context where they are
not considered acceptable. These code points, between U+D800 and
U+DFFF (inclusive), are used by Unicode only for UTF-16. However, Perl
internally allows all unsigned integer code points (up to the size limit
@@ -5344,15 +6153,15 @@
(W closure) During compilation, an inner named subroutine or eval is
attempting to capture an outer lexical that is not currently available.
-This can happen for one of two reasons. First, the outer lexical may be
+This can happen for one of two reasons. First, the outer lexical may be
declared in an outer anonymous subroutine that has not yet been created.
(Remember that named subs are created at compile time, while anonymous
-subs are created at run-time.) For example,
+subs are created at run-time.) For example,
sub { my $a; sub f { $a } }
At the time that f is created, it can't capture the current value of $a,
-since the anonymous subroutine hasn't been created yet. Conversely,
+since the anonymous subroutine hasn't been created yet. Conversely,
the following won't give a warning since the anonymous subroutine has by
now been created and is live:
@@ -5372,13 +6181,13 @@
=item Variable "%s" is not imported%s
-(W misc) With "use strict" in effect, you referred to a global variable
+(S misc) With "use strict" in effect, you referred to a global variable
that you apparently thought was imported from another module, because
something else of the same name (usually a subroutine) is exported by
that module. It usually means you put the wrong funny character on the
front of your variable.
-=item Variable length lookbehind not implemented in m/%s/
+=item Variable length lookbehind not implemented in regex m/%s/
(F) Lookbehind is allowed only for subexpressions whose length is fixed and
known at compile time. See L<perlre>.
@@ -5389,7 +6198,7 @@
current scope or statement, effectively eliminating all access to the
previous instance. This is almost always a typographical error. Note
that the earlier variable will still exist until the end of the scope
-or until all closure referents to it are destroyed.
+or until all closure references to it are destroyed.
=item Variable syntax
@@ -5414,16 +6223,23 @@
reference variables in outer subroutines are created, they
are automatically rebound to the current values of such variables.
-=item Verb pattern '%s' has a mandatory argument in regex; marked by <-- HERE in m/%s/
+=item vector argument not supported with alpha versions
-(F) You used a verb pattern that requires an argument. Supply an argument
-or check that you are using the right verb.
+(S printf) The %vd (s)printf format does not support version objects
+with alpha parts.
-=item Verb pattern '%s' may not have an argument in regex; marked by <-- HERE in m/%s/
+=item Verb pattern '%s' has a mandatory argument in regex; marked by <-- HERE
+in m/%s/
-(F) You used a verb pattern that is not allowed an argument. Remove the
+(F) You used a verb pattern that requires an argument. Supply an
argument or check that you are using the right verb.
+=item Verb pattern '%s' may not have an argument in regex; marked by <-- HERE
+in m/%s/
+
+(F) You used a verb pattern that is not allowed an argument. Remove the
+argument or check that you are using the right verb.
+
=item Version number must be a constant number
(P) The attempt to translate a C<use Module n.n LIST> statement into
@@ -5465,6 +6281,14 @@
So put in parentheses to say what you really mean.
+=item when is experimental
+
+(S experimental::smartmatch) C<when> depends on smartmatch, which is
+experimental. Additionally, it has several special cases that may
+not be immediately obvious, and their behavior may change or
+even be removed in any future release of perl.
+See the explanation under L<perlsyn/Experimental Details on given and when>.
+
=item Wide character in %s
(S utf8) Perl met a wide character (>255) when it wasn't expecting
@@ -5477,10 +6301,11 @@
=item Within []-length '%c' not allowed
-(F) The count in the (un)pack template may be replaced by C<[TEMPLATE]> only if
-C<TEMPLATE> always matches the same amount of packed bytes that can be
-determined from the template alone. This is not possible if it contains any
-of the codes @, /, U, u, w or a *-length. Redesign the template.
+(F) The count in the (un)pack template may be replaced by C<[TEMPLATE]>
+only if C<TEMPLATE> always matches the same amount of packed bytes that
+can be determined from the template alone. This is not possible if
+it contains any of the codes @, /, U, u, w or a *-length. Redesign
+the template.
=item write() on closed filehandle %s
@@ -5489,9 +6314,9 @@
=item %s "\x%X" does not map to Unicode
-(F) When reading in different encodings Perl tries to map everything
+(F) When reading in different encodings, Perl tries to map everything
into Unicode characters. The bytes you read in are not legal in
-this encoding, for example
+this encoding. For example
utf8 "\xE4" does not map to Unicode
@@ -5532,6 +6357,6 @@
=head1 SEE ALSO
-L<warnings>, L<perllexwarn>.
+L<warnings>, L<perllexwarn>, L<diagnostics>.
=cut
Property changes on: trunk/contrib/perl/pod/perldiag.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perldoc.pod
===================================================================
--- trunk/contrib/perl/pod/perldoc.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldoc.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perldoc.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perldsc.pod
===================================================================
--- trunk/contrib/perl/pod/perldsc.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perldsc.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -5,20 +5,9 @@
=head1 DESCRIPTION
-The single feature most sorely lacking in the Perl programming language
-prior to its 5.0 release was complex data structures. Even without direct
-language support, some valiant programmers did manage to emulate them, but
-it was hard work and not for the faint of heart. You could occasionally
-get away with the C<$m{$AoA,$b}> notation borrowed from B<awk> in which the
-keys are actually more like a single concatenated string C<"$AoA$b">, but
-traversal and sorting were difficult. More desperate programmers even
-hacked Perl's internal symbol table directly, a strategy that proved hard
-to develop and maintain--to put it mildly.
+Perl lets us have complex data structures. You can write something like
+this and all of a sudden, you'd have an array with three dimensions!
-The 5.0 release of Perl let us have complex data structures. You
-may now write something like this and all of a sudden, you'd have an array
-with three dimensions!
-
for $x (1 .. 10) {
for $y (1 .. 10) {
for $z (1 .. 10) {
@@ -309,11 +298,8 @@
X<array of arrays, debugging> X<hash of arrays, debugging>
X<array of hashes, debugging> X<hash of hashes, debugging>
-Before version 5.002, the standard Perl debugger didn't do a very nice job of
-printing out complex data structures. With 5.002 or above, the
-debugger includes several new features, including command line editing as
-well as the C<x> command to dump out complex data structures. For
-example, given the assignment to $AoA above, here's the debugger output:
+You can use the debugger's C<x> command to dump out complex data structures.
+For example, given the assignment to $AoA above, here's the debugger output:
DB<1> x $AoA
$AoA = ARRAY(0x13b5a0)
@@ -842,6 +828,3 @@
=head1 AUTHOR
Tom Christiansen <F<tchrist at perl.com>>
-
-Last update:
-Wed Oct 23 04:57:50 MET DST 1996
Property changes on: trunk/contrib/perl/pod/perldsc.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perldtrace.pod (from rev 6437, vendor/perl/5.18.1/pod/perldtrace.pod)
===================================================================
--- trunk/contrib/perl/pod/perldtrace.pod (rev 0)
+++ trunk/contrib/perl/pod/perldtrace.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,236 @@
+=head1 NAME
+
+perldtrace - Perl's support for DTrace
+
+=head1 SYNOPSIS
+
+ # dtrace -Zn 'perl::sub-entry, perl::sub-return { trace(copyinstr(arg0)) }'
+ dtrace: description 'perl::sub-entry, perl::sub-return ' matched 10 probes
+
+ # perl -E 'sub outer { inner(@_) } sub inner { say shift } outer("hello")'
+ hello
+
+ (dtrace output)
+ CPU ID FUNCTION:NAME
+ 0 75915 Perl_pp_entersub:sub-entry BEGIN
+ 0 75915 Perl_pp_entersub:sub-entry import
+ 0 75922 Perl_pp_leavesub:sub-return import
+ 0 75922 Perl_pp_leavesub:sub-return BEGIN
+ 0 75915 Perl_pp_entersub:sub-entry outer
+ 0 75915 Perl_pp_entersub:sub-entry inner
+ 0 75922 Perl_pp_leavesub:sub-return inner
+ 0 75922 Perl_pp_leavesub:sub-return outer
+
+=head1 DESCRIPTION
+
+DTrace is a framework for comprehensive system- and application-level
+tracing. Perl is a DTrace I<provider>, meaning it exposes several
+I<probes> for instrumentation. You can use these in conjunction
+with kernel-level probes, as well as probes from other providers
+such as MySQL, in order to diagnose software defects, or even just
+your application's bottlenecks.
+
+Perl must be compiled with the C<-Dusedtrace> option in order to
+make use of the provided probes. While DTrace aims to have no
+overhead when its instrumentation is not active, Perl's support
+itself cannot uphold that guarantee, so it is built without DTrace
+probes under most systems. One notable exception is that Mac OS X
+ships a F</usr/bin/perl> with DTrace support enabled.
+
+=head1 HISTORY
+
+=over 4
+
+=item 5.10.1
+
+Perl's initial DTrace support was added, providing C<sub-entry> and
+C<sub-return> probes.
+
+=item 5.14.0
+
+The C<sub-entry> and C<sub-return> probes gain a fourth argument: the
+package name of the function.
+
+=item 5.16.0
+
+The C<phase-change> probe was added.
+
+=item 5.18.0
+
+The C<op-entry>, C<loading-file>, and C<loaded-file> probes were added.
+
+=back
+
+=head1 PROBES
+
+=over 4
+
+=item sub-entry(SUBNAME, FILE, LINE, PACKAGE)
+
+Traces the entry of any subroutine. Note that all of the variables
+refer to the subroutine that is being invoked; there is currently
+no way to get ahold of any information about the subroutine's
+I<caller> from a DTrace action.
+
+ :*perl*::sub-entry {
+ printf("%s::%s entered at %s line %d\n",
+ copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
+
+=item sub-return(SUBNAME, FILE, LINE, PACKAGE)
+
+Traces the exit of any subroutine. Note that all of the variables
+refer to the subroutine that is returning; there is currently no
+way to get ahold of any information about the subroutine's I<caller>
+from a DTrace action.
+
+ :*perl*::sub-return {
+ printf("%s::%s returned at %s line %d\n",
+ copyinstr(arg3), copyinstr(arg0), copyinstr(arg1), arg2);
+ }
+
+=item phase-change(NEWPHASE, OLDPHASE)
+
+Traces changes to Perl's interpreter state. You can internalize this
+as tracing changes to Perl's C<${^GLOBAL_PHASE}> variable, especially
+since the values for C<NEWPHASE> and C<OLDPHASE> are the strings that
+C<${^GLOBAL_PHASE}> reports.
+
+ :*perl*::phase-change {
+ printf("Phase changed from %s to %s\n",
+ copyinstr(arg1), copyinstr(arg0));
+ }
+
+=item op-entry(OPNAME)
+
+Traces the execution of each opcode in the Perl runloop. This probe
+is fired before the opcode is executed. When the Perl debugger is
+enabled, the DTrace probe is fired I<after> the debugger hooks (but
+still before the opcode itself is executed).
+
+ :*perl*::op-entry {
+ printf("About to execute opcode %s\n", copyinstr(arg0));
+ }
+
+=item loading-file(FILENAME)
+
+Fires when Perl is about to load an individual file, whether from
+C<use>, C<require>, or C<do>. This probe fires before the file is
+read from disk. The filename argument is converted to local filesystem
+paths instead of providing C<Module::Name>-style names.
+
+ :*perl*:loading-file {
+ printf("About to load %s\n", copyinstr(arg0));
+ }
+
+=item loaded-file(FILENAME)
+
+Fires when Perl has successfully loaded an individual file, whether
+from C<use>, C<require>, or C<do>. This probe fires after the file
+is read from disk and its contentss evaluated. The filename argument
+is converted to local filesystem paths instead of providing
+C<Module::Name>-style names.
+
+ :*perl*:loaded-file {
+ printf("Successfully loaded %s\n", copyinstr(arg0));
+ }
+
+=back
+
+=head1 EXAMPLES
+
+=over 4
+
+=item Most frequently called functions
+
+ # dtrace -qZn 'sub-entry { @[strjoin(strjoin(copyinstr(arg3),"::"),copyinstr(arg0))] = count() } END {trunc(@, 10)}'
+
+ Class::MOP::Attribute::slots 400
+ Try::Tiny::catch 411
+ Try::Tiny::try 411
+ Class::MOP::Instance::inline_slot_access 451
+ Class::MOP::Class::Immutable::Trait:::around 472
+ Class::MOP::Mixin::AttributeCore::has_initializer 496
+ Class::MOP::Method::Wrapped::__ANON__ 544
+ Class::MOP::Package::_package_stash 737
+ Class::MOP::Class::initialize 1128
+ Class::MOP::get_metaclass_by_name 1204
+
+=item Trace function calls
+
+ # dtrace -qFZn 'sub-entry, sub-return { trace(copyinstr(arg0)) }'
+
+ 0 -> Perl_pp_entersub BEGIN
+ 0 <- Perl_pp_leavesub BEGIN
+ 0 -> Perl_pp_entersub BEGIN
+ 0 -> Perl_pp_entersub import
+ 0 <- Perl_pp_leavesub import
+ 0 <- Perl_pp_leavesub BEGIN
+ 0 -> Perl_pp_entersub BEGIN
+ 0 -> Perl_pp_entersub dress
+ 0 <- Perl_pp_leavesub dress
+ 0 -> Perl_pp_entersub dirty
+ 0 <- Perl_pp_leavesub dirty
+ 0 -> Perl_pp_entersub whiten
+ 0 <- Perl_pp_leavesub whiten
+ 0 <- Perl_dounwind BEGIN
+
+=item Function calls during interpreter cleanup
+
+ # dtrace -Zn 'phase-change /copyinstr(arg0) == "END"/ { self->ending = 1 } sub-entry /self->ending/ { trace(copyinstr(arg0)) }'
+
+ CPU ID FUNCTION:NAME
+ 1 77214 Perl_pp_entersub:sub-entry END
+ 1 77214 Perl_pp_entersub:sub-entry END
+ 1 77214 Perl_pp_entersub:sub-entry cleanup
+ 1 77214 Perl_pp_entersub:sub-entry _force_writable
+ 1 77214 Perl_pp_entersub:sub-entry _force_writable
+
+=item System calls at compile time
+
+ # dtrace -qZn 'phase-change /copyinstr(arg0) == "START"/ { self->interesting = 1 } phase-change /copyinstr(arg0) == "RUN"/ { self->interesting = 0 } syscall::: /self->interesting/ { @[probefunc] = count() } END { trunc(@, 3) }'
+
+ lseek 310
+ read 374
+ stat64 1056
+
+=item Perl functions that execute the most opcodes
+
+ # dtrace -qZn 'sub-entry { self->fqn = strjoin(copyinstr(arg3), strjoin("::", copyinstr(arg0))) } op-entry /self->fqn != ""/ { @[self->fqn] = count() } END { trunc(@, 3) }'
+
+ warnings::unimport 4589
+ Exporter::Heavy::_rebuild_cache 5039
+ Exporter::import 14578
+
+=back
+
+=head1 REFERENCES
+
+=over 4
+
+=item DTrace Dynamic Tracing Guide
+
+L<http://dtrace.org/guide/preface.html>
+
+=item DTrace: Dynamic Tracing in Oracle Solaris, Mac OS X and FreeBSD
+
+L<http://www.amazon.com/DTrace-Dynamic-Tracing-Solaris-FreeBSD/dp/0132091518/>
+
+=back
+
+=head1 SEE ALSO
+
+=over 4
+
+=item L<Devel::DTrace::Provider>
+
+This CPAN module lets you create application-level DTrace probes written in
+Perl.
+
+=back
+
+=head1 AUTHORS
+
+Shawn M Moore C<sartak at gmail.com>
+
+=cut
Modified: trunk/contrib/perl/pod/perlebcdic.pod
===================================================================
--- trunk/contrib/perl/pod/perlebcdic.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlebcdic.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -7,7 +7,7 @@
=head1 DESCRIPTION
An exploration of some of the issues facing Perl programmers
-on EBCDIC based computers. We do not cover localization,
+on EBCDIC based computers. We do not cover localization,
internationalization, or multi-byte character set issues other
than some discussion of UTF-8 and UTF-EBCDIC.
@@ -23,16 +23,16 @@
The American Standard Code for Information Interchange (ASCII or US-ASCII) is a
set of
-integers running from 0 to 127 (decimal) that imply character
-interpretation by the display and other systems of computers.
-The range 0..127 can be covered by setting the bits in a 7-bit binary
-digit, hence the set is sometimes referred to as "7-bit ASCII".
-ASCII was described by the American National Standards Institute
-document ANSI X3.4-1986. It was also described by ISO 646:1991
-(with localization for currency symbols). The full ASCII set is
-given in the table below as the first 128 elements. Languages that
-can be written adequately with the characters in ASCII include
-English, Hawaiian, Indonesian, Swahili and some Native American
+integers running from 0 to 127 (decimal) that imply character
+interpretation by the display and other systems of computers.
+The range 0..127 can be covered by setting the bits in a 7-bit binary
+digit, hence the set is sometimes referred to as "7-bit ASCII".
+ASCII was described by the American National Standards Institute
+document ANSI X3.4-1986. It was also described by ISO 646:1991
+(with localization for currency symbols). The full ASCII set is
+given in the table below as the first 128 elements. Languages that
+can be written adequately with the characters in ASCII include
+English, Hawaiian, Indonesian, Swahili and some Native American
languages.
There are many character sets that extend the range of integers
@@ -41,21 +41,21 @@
=head2 ISO 8859
-The ISO 8859-$n are a collection of character code sets from the
-International Organization for Standardization (ISO) each of which
-adds characters to the ASCII set that are typically found in European
-languages many of which are based on the Roman, or Latin, alphabet.
+The ISO 8859-$n are a collection of character code sets from the
+International Organization for Standardization (ISO), each of which
+adds characters to the ASCII set that are typically found in European
+languages, many of which are based on the Roman, or Latin, alphabet.
=head2 Latin 1 (ISO 8859-1)
-A particular 8-bit extension to ASCII that includes grave and acute
-accented Latin characters. Languages that can employ ISO 8859-1
-include all the languages covered by ASCII as well as Afrikaans,
-Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian,
-Portuguese, Spanish, and Swedish. Dutch is covered albeit without
-the ij ligature. French is covered too but without the oe ligature.
+A particular 8-bit extension to ASCII that includes grave and acute
+accented Latin characters. Languages that can employ ISO 8859-1
+include all the languages covered by ASCII as well as Afrikaans,
+Albanian, Basque, Catalan, Danish, Faroese, Finnish, Norwegian,
+Portuguese, Spanish, and Swedish. Dutch is covered albeit without
+the ij ligature. French is covered too but without the oe ligature.
German can use ISO 8859-1 but must do so without German-style
-quotation marks. This set is based on Western European extensions
+quotation marks. This set is based on Western European extensions
to ASCII and is commonly encountered in world wide web work.
In IBM character code set identification terminology ISO 8859-1 is
also known as CCSID 819 (or sometimes 0819 or even 00819).
@@ -62,7 +62,7 @@
=head2 EBCDIC
-The Extended Binary Coded Decimal Interchange Code refers to a
+The Extended Binary Coded Decimal Interchange Code refers to a
large collection of single- and multi-byte coded character sets that are
different from ASCII or ISO 8859-1 and are all slightly different from each
other; they typically run on host computers. The EBCDIC encodings derive from
@@ -71,19 +71,19 @@
characters [a-z] and [A-Z], but there were gaps within each Latin alphabet
range.
-Some IBM EBCDIC character sets may be known by character code set
+Some IBM EBCDIC character sets may be known by character code set
identification numbers (CCSID numbers) or code page numbers.
Perl can be compiled on platforms that run any of three commonly used EBCDIC
character sets, listed below.
-=head2 The 13 variant characters
+=head3 The 13 variant characters
Among IBM EBCDIC character code sets there are 13 characters that
are often mapped to different integer values. Those characters
are known as the 13 "variant" characters and are:
- \ [ ] { } ^ ~ ! # | $ @ `
+ \ [ ] { } ^ ~ ! # | $ @ `
When Perl is compiled for a platform, it looks at some of these characters to
guess which EBCDIC character set the platform uses, and adapts itself
@@ -92,26 +92,30 @@
mistakenly and silently choose one of the three.
They are:
-=head2 0037
+=over
-Character code set ID 0037 is a mapping of the ASCII plus Latin-1
-characters (i.e. ISO 8859-1) to an EBCDIC set. 0037 is used
-in North American English locales on the OS/400 operating system
-that runs on AS/400 computers. CCSID 0037 differs from ISO 8859-1
+=item B<0037>
+
+Character code set ID 0037 is a mapping of the ASCII plus Latin-1
+characters (i.e. ISO 8859-1) to an EBCDIC set. 0037 is used
+in North American English locales on the OS/400 operating system
+that runs on AS/400 computers. CCSID 0037 differs from ISO 8859-1
in 237 places, in other words they agree on only 19 code point values.
-=head2 1047
+=item B<1047>
-Character code set ID 1047 is also a mapping of the ASCII plus
-Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 1047 is
-used under Unix System Services for OS/390 or z/OS, and OpenEdition
+Character code set ID 1047 is also a mapping of the ASCII plus
+Latin-1 characters (i.e. ISO 8859-1) to an EBCDIC set. 1047 is
+used under Unix System Services for OS/390 or z/OS, and OpenEdition
for VM/ESA. CCSID 1047 differs from CCSID 0037 in eight places.
-=head2 POSIX-BC
+=item B<POSIX-BC>
The EBCDIC code page in use on Siemens' BS2000 system is distinct from
1047 and 0037. It is identified below as the POSIX-BC set.
+=back
+
=head2 Unicode code points versus EBCDIC code points
In Unicode terminology a I<code point> is the number assigned to a
@@ -218,7 +222,7 @@
to get four files containing "Hello World!\n" in ASCII, CP 0037 EBCDIC,
ISO 8859-1 (Latin-1) (in this example identical to ASCII since only ASCII
-characters were printed), and
+characters were printed), and
UTF-EBCDIC (in this example identical to normal EBCDIC since only characters
that don't differ between EBCDIC and UTF-EBCDIC were printed). See the
documentation of Encode::PerlIO for details.
@@ -230,21 +234,18 @@
The following tables list the ASCII and Latin 1 ordered sets including
the subsets: C0 controls (0..31), ASCII graphics (32..7e), delete (7f),
-C1 controls (80..9f), and Latin-1 (a.k.a. ISO 8859-1) (a0..ff). In the
-table non-printing control character names as well as the Latin 1
-extensions to ASCII have been labelled with character names roughly
-corresponding to I<The Unicode Standard, Version 3.0> albeit with
-substitutions such as s/LATIN// and s/VULGAR// in all cases,
-s/CAPITAL LETTER// in some cases, and s/SMALL LETTER ([A-Z])/\l$1/
-in some other cases. The "names" of the controls listed here are
-the Unicode Version 1 names, except for the few that don't have names, in which
-case the names in the Wikipedia article were used
-(L<http://en.wikipedia.org/wiki/C0_and_C1_control_codes>).
-The differences between the 0037 and 1047 sets are
-flagged with ***. The differences between the 1047 and POSIX-BC sets
-are flagged with ###. All ord() numbers listed are decimal. If you
-would rather see this table listing octal values then run the table
-(that is, the pod version of this document since this recipe may not
+C1 controls (80..9f), and Latin-1 (a.k.a. ISO 8859-1) (a0..ff). In the
+table names of the Latin 1
+extensions to ASCII have been labelled with character names roughly
+corresponding to I<The Unicode Standard, Version 6.1> albeit with
+substitutions such as s/LATIN// and s/VULGAR// in all cases, s/CAPITAL
+LETTER// in some cases, and s/SMALL LETTER ([A-Z])/\l$1/ in some other
+cases. Controls are listed using their Unicode 6.1 abbreviatons.
+The differences between the 0037 and 1047 sets are
+flagged with **. The differences between the 1047 and POSIX-BC sets
+are flagged with ##. All ord() numbers listed are decimal. If you
+would rather see this table listing octal values, then run the table
+(that is, the pod source text of this document, since this recipe may not
work with a pod2_other_format translation) through:
=over 4
@@ -253,8 +254,8 @@
=back
- perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-9.03o%-9.03o%-9.03o%.03o\n",$1,$2,$3,$4,$5)}' \
+ perl -ne 'if(/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
+ -e '{printf("%s%-5.03o%-5.03o%-5.03o%.03o\n",$1,$2,$3,$4,$5)}' \
perlebcdic.pod
If you want to retain the UTF-x code points then in script form you
@@ -268,19 +269,19 @@
open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
while (<FH>) {
- if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
+ if (/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
{
if ($7 ne '' && $9 ne '') {
printf(
- "%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%-3o.%.03o\n",
+ "%s%-5.03o%-5.03o%-5.03o%-5.03o%-3o.%-5o%-3o.%.03o\n",
$1,$2,$3,$4,$5,$6,$7,$8,$9);
}
elsif ($7 ne '') {
- printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-3o.%-5o%.03o\n",
+ printf("%s%-5.03o%-5.03o%-5.03o%-5.03o%-3o.%-5o%.03o\n",
$1,$2,$3,$4,$5,$6,$7,$8);
}
else {
- printf("%s%-9.03o%-9.03o%-9.03o%-9.03o%-9.03o%.03o\n",
+ printf("%s%-5.03o%-5.03o%-5.03o%-5.03o%-5.03o%.03o\n",
$1,$2,$3,$4,$5,$6,$8);
}
}
@@ -295,8 +296,8 @@
=back
- perl -ne 'if(/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
- -e '{printf("%s%-9.02X%-9.02X%-9.02X%.02X\n",$1,$2,$3,$4,$5)}' \
+ perl -ne 'if(/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)/)' \
+ -e '{printf("%s%-5.02X%-5.02X%-5.02X%.02X\n",$1,$2,$3,$4,$5)}' \
perlebcdic.pod
Or, in order to retain the UTF-x code points in hexadecimal:
@@ -309,19 +310,19 @@
open(FH,"<perlebcdic.pod") or die "Could not open perlebcdic.pod: $!";
while (<FH>) {
- if (/(.{43})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
+ if (/(.{29})(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\d+)\.?(\d*)\s+(\d+)\.?(\d*)/)
{
if ($7 ne '' && $9 ne '') {
printf(
- "%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X.%02X\n",
+ "%s%-5.02X%-5.02X%-5.02X%-5.02X%-2X.%-6.02X%02X.%02X\n",
$1,$2,$3,$4,$5,$6,$7,$8,$9);
}
elsif ($7 ne '') {
- printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-2X.%-6.02X%02X\n",
+ printf("%s%-5.02X%-5.02X%-5.02X%-5.02X%-2X.%-6.02X%02X\n",
$1,$2,$3,$4,$5,$6,$7,$8);
}
else {
- printf("%s%-9.02X%-9.02X%-9.02X%-9.02X%-9.02X%02X\n",
+ printf("%s%-5.02X%-5.02X%-5.02X%-5.02X%-5.02X%02X\n",
$1,$2,$3,$4,$5,$6,$8);
}
}
@@ -328,265 +329,267 @@
}
- ISO 8859-1 CCSID CCSID CCSID 1047
- chr CCSID 0819 0037 1047 POSIX-BC UTF-8 UTF-EBCDIC
- ----------------------------------------------------------------------------------------------
- <NULL> 0 0 0 0 0 0
- <START OF HEADING> 1 1 1 1 1 1
- <START OF TEXT> 2 2 2 2 2 2
- <END OF TEXT> 3 3 3 3 3 3
- <END OF TRANSMISSION> 4 55 55 55 4 55
- <ENQUIRY> 5 45 45 45 5 45
- <ACKNOWLEDGE> 6 46 46 46 6 46
- <BELL> 7 47 47 47 7 47
- <BACKSPACE> 8 22 22 22 8 22
- <HORIZONTAL TABULATION> 9 5 5 5 9 5
- <LINE FEED> 10 37 21 21 10 21 ***
- <VERTICAL TABULATION> 11 11 11 11 11 11
- <FORM FEED> 12 12 12 12 12 12
- <CARRIAGE RETURN> 13 13 13 13 13 13
- <SHIFT OUT> 14 14 14 14 14 14
- <SHIFT IN> 15 15 15 15 15 15
- <DATA LINK ESCAPE> 16 16 16 16 16 16
- <DEVICE CONTROL ONE> 17 17 17 17 17 17
- <DEVICE CONTROL TWO> 18 18 18 18 18 18
- <DEVICE CONTROL THREE> 19 19 19 19 19 19
- <DEVICE CONTROL FOUR> 20 60 60 60 20 60
- <NEGATIVE ACKNOWLEDGE> 21 61 61 61 21 61
- <SYNCHRONOUS IDLE> 22 50 50 50 22 50
- <END OF TRANSMISSION BLOCK> 23 38 38 38 23 38
- <CANCEL> 24 24 24 24 24 24
- <END OF MEDIUM> 25 25 25 25 25 25
- <SUBSTITUTE> 26 63 63 63 26 63
- <ESCAPE> 27 39 39 39 27 39
- <FILE SEPARATOR> 28 28 28 28 28 28
- <GROUP SEPARATOR> 29 29 29 29 29 29
- <RECORD SEPARATOR> 30 30 30 30 30 30
- <UNIT SEPARATOR> 31 31 31 31 31 31
- <SPACE> 32 64 64 64 32 64
- ! 33 90 90 90 33 90
- " 34 127 127 127 34 127
- # 35 123 123 123 35 123
- $ 36 91 91 91 36 91
- % 37 108 108 108 37 108
- & 38 80 80 80 38 80
- ' 39 125 125 125 39 125
- ( 40 77 77 77 40 77
- ) 41 93 93 93 41 93
- * 42 92 92 92 42 92
- + 43 78 78 78 43 78
- , 44 107 107 107 44 107
- - 45 96 96 96 45 96
- . 46 75 75 75 46 75
- / 47 97 97 97 47 97
- 0 48 240 240 240 48 240
- 1 49 241 241 241 49 241
- 2 50 242 242 242 50 242
- 3 51 243 243 243 51 243
- 4 52 244 244 244 52 244
- 5 53 245 245 245 53 245
- 6 54 246 246 246 54 246
- 7 55 247 247 247 55 247
- 8 56 248 248 248 56 248
- 9 57 249 249 249 57 249
- : 58 122 122 122 58 122
- ; 59 94 94 94 59 94
- < 60 76 76 76 60 76
- = 61 126 126 126 61 126
- > 62 110 110 110 62 110
- ? 63 111 111 111 63 111
- @ 64 124 124 124 64 124
- A 65 193 193 193 65 193
- B 66 194 194 194 66 194
- C 67 195 195 195 67 195
- D 68 196 196 196 68 196
- E 69 197 197 197 69 197
- F 70 198 198 198 70 198
- G 71 199 199 199 71 199
- H 72 200 200 200 72 200
- I 73 201 201 201 73 201
- J 74 209 209 209 74 209
- K 75 210 210 210 75 210
- L 76 211 211 211 76 211
- M 77 212 212 212 77 212
- N 78 213 213 213 78 213
- O 79 214 214 214 79 214
- P 80 215 215 215 80 215
- Q 81 216 216 216 81 216
- R 82 217 217 217 82 217
- S 83 226 226 226 83 226
- T 84 227 227 227 84 227
- U 85 228 228 228 85 228
- V 86 229 229 229 86 229
- W 87 230 230 230 87 230
- X 88 231 231 231 88 231
- Y 89 232 232 232 89 232
- Z 90 233 233 233 90 233
- [ 91 186 173 187 91 173 *** ###
- \ 92 224 224 188 92 224 ###
- ] 93 187 189 189 93 189 ***
- ^ 94 176 95 106 94 95 *** ###
- _ 95 109 109 109 95 109
- ` 96 121 121 74 96 121 ###
- a 97 129 129 129 97 129
- b 98 130 130 130 98 130
- c 99 131 131 131 99 131
- d 100 132 132 132 100 132
- e 101 133 133 133 101 133
- f 102 134 134 134 102 134
- g 103 135 135 135 103 135
- h 104 136 136 136 104 136
- i 105 137 137 137 105 137
- j 106 145 145 145 106 145
- k 107 146 146 146 107 146
- l 108 147 147 147 108 147
- m 109 148 148 148 109 148
- n 110 149 149 149 110 149
- o 111 150 150 150 111 150
- p 112 151 151 151 112 151
- q 113 152 152 152 113 152
- r 114 153 153 153 114 153
- s 115 162 162 162 115 162
- t 116 163 163 163 116 163
- u 117 164 164 164 117 164
- v 118 165 165 165 118 165
- w 119 166 166 166 119 166
- x 120 167 167 167 120 167
- y 121 168 168 168 121 168
- z 122 169 169 169 122 169
- { 123 192 192 251 123 192 ###
- | 124 79 79 79 124 79
- } 125 208 208 253 125 208 ###
- ~ 126 161 161 255 126 161 ###
- <DELETE> 127 7 7 7 127 7
- <PADDING CHARACTER> 128 32 32 32 194.128 32
- <HIGH OCTET PRESET> 129 33 33 33 194.129 33
- <BREAK PERMITTED HERE> 130 34 34 34 194.130 34
- <NO BREAK HERE> 131 35 35 35 194.131 35
- <INDEX> 132 36 36 36 194.132 36
- <NEXT LINE> 133 21 37 37 194.133 37 ***
- <START OF SELECTED AREA> 134 6 6 6 194.134 6
- <END OF SELECTED AREA> 135 23 23 23 194.135 23
- <CHARACTER TABULATION SET> 136 40 40 40 194.136 40
- <CHARACTER TABULATION WITH JUSTIFICATION> 137 41 41 41 194.137 41
- <LINE TABULATION SET> 138 42 42 42 194.138 42
- <PARTIAL LINE FORWARD> 139 43 43 43 194.139 43
- <PARTIAL LINE BACKWARD> 140 44 44 44 194.140 44
- <REVERSE LINE FEED> 141 9 9 9 194.141 9
- <SINGLE SHIFT TWO> 142 10 10 10 194.142 10
- <SINGLE SHIFT THREE> 143 27 27 27 194.143 27
- <DEVICE CONTROL STRING> 144 48 48 48 194.144 48
- <PRIVATE USE ONE> 145 49 49 49 194.145 49
- <PRIVATE USE TWO> 146 26 26 26 194.146 26
- <SET TRANSMIT STATE> 147 51 51 51 194.147 51
- <CANCEL CHARACTER> 148 52 52 52 194.148 52
- <MESSAGE WAITING> 149 53 53 53 194.149 53
- <START OF GUARDED AREA> 150 54 54 54 194.150 54
- <END OF GUARDED AREA> 151 8 8 8 194.151 8
- <START OF STRING> 152 56 56 56 194.152 56
- <SINGLE GRAPHIC CHARACTER INTRODUCER> 153 57 57 57 194.153 57
- <SINGLE CHARACTER INTRODUCER> 154 58 58 58 194.154 58
- <CONTROL SEQUENCE INTRODUCER> 155 59 59 59 194.155 59
- <STRING TERMINATOR> 156 4 4 4 194.156 4
- <OPERATING SYSTEM COMMAND> 157 20 20 20 194.157 20
- <PRIVACY MESSAGE> 158 62 62 62 194.158 62
- <APPLICATION PROGRAM COMMAND> 159 255 255 95 194.159 255 ###
- <NON-BREAKING SPACE> 160 65 65 65 194.160 128.65
- <INVERTED EXCLAMATION MARK> 161 170 170 170 194.161 128.66
- <CENT SIGN> 162 74 74 176 194.162 128.67 ###
- <POUND SIGN> 163 177 177 177 194.163 128.68
- <CURRENCY SIGN> 164 159 159 159 194.164 128.69
- <YEN SIGN> 165 178 178 178 194.165 128.70
- <BROKEN BAR> 166 106 106 208 194.166 128.71 ###
- <SECTION SIGN> 167 181 181 181 194.167 128.72
- <DIAERESIS> 168 189 187 121 194.168 128.73 *** ###
- <COPYRIGHT SIGN> 169 180 180 180 194.169 128.74
- <FEMININE ORDINAL INDICATOR> 170 154 154 154 194.170 128.81
- <LEFT POINTING GUILLEMET> 171 138 138 138 194.171 128.82
- <NOT SIGN> 172 95 176 186 194.172 128.83 *** ###
- <SOFT HYPHEN> 173 202 202 202 194.173 128.84
- <REGISTERED TRADE MARK SIGN> 174 175 175 175 194.174 128.85
- <MACRON> 175 188 188 161 194.175 128.86 ###
- <DEGREE SIGN> 176 144 144 144 194.176 128.87
- <PLUS-OR-MINUS SIGN> 177 143 143 143 194.177 128.88
- <SUPERSCRIPT TWO> 178 234 234 234 194.178 128.89
- <SUPERSCRIPT THREE> 179 250 250 250 194.179 128.98
- <ACUTE ACCENT> 180 190 190 190 194.180 128.99
- <MICRO SIGN> 181 160 160 160 194.181 128.100
- <PARAGRAPH SIGN> 182 182 182 182 194.182 128.101
- <MIDDLE DOT> 183 179 179 179 194.183 128.102
- <CEDILLA> 184 157 157 157 194.184 128.103
- <SUPERSCRIPT ONE> 185 218 218 218 194.185 128.104
- <MASC. ORDINAL INDICATOR> 186 155 155 155 194.186 128.105
- <RIGHT POINTING GUILLEMET> 187 139 139 139 194.187 128.106
- <FRACTION ONE QUARTER> 188 183 183 183 194.188 128.112
- <FRACTION ONE HALF> 189 184 184 184 194.189 128.113
- <FRACTION THREE QUARTERS> 190 185 185 185 194.190 128.114
- <INVERTED QUESTION MARK> 191 171 171 171 194.191 128.115
- <A WITH GRAVE> 192 100 100 100 195.128 138.65
- <A WITH ACUTE> 193 101 101 101 195.129 138.66
- <A WITH CIRCUMFLEX> 194 98 98 98 195.130 138.67
- <A WITH TILDE> 195 102 102 102 195.131 138.68
- <A WITH DIAERESIS> 196 99 99 99 195.132 138.69
- <A WITH RING ABOVE> 197 103 103 103 195.133 138.70
- <CAPITAL LIGATURE AE> 198 158 158 158 195.134 138.71
- <C WITH CEDILLA> 199 104 104 104 195.135 138.72
- <E WITH GRAVE> 200 116 116 116 195.136 138.73
- <E WITH ACUTE> 201 113 113 113 195.137 138.74
- <E WITH CIRCUMFLEX> 202 114 114 114 195.138 138.81
- <E WITH DIAERESIS> 203 115 115 115 195.139 138.82
- <I WITH GRAVE> 204 120 120 120 195.140 138.83
- <I WITH ACUTE> 205 117 117 117 195.141 138.84
- <I WITH CIRCUMFLEX> 206 118 118 118 195.142 138.85
- <I WITH DIAERESIS> 207 119 119 119 195.143 138.86
- <CAPITAL LETTER ETH> 208 172 172 172 195.144 138.87
- <N WITH TILDE> 209 105 105 105 195.145 138.88
- <O WITH GRAVE> 210 237 237 237 195.146 138.89
- <O WITH ACUTE> 211 238 238 238 195.147 138.98
- <O WITH CIRCUMFLEX> 212 235 235 235 195.148 138.99
- <O WITH TILDE> 213 239 239 239 195.149 138.100
- <O WITH DIAERESIS> 214 236 236 236 195.150 138.101
- <MULTIPLICATION SIGN> 215 191 191 191 195.151 138.102
- <O WITH STROKE> 216 128 128 128 195.152 138.103
- <U WITH GRAVE> 217 253 253 224 195.153 138.104 ###
- <U WITH ACUTE> 218 254 254 254 195.154 138.105
- <U WITH CIRCUMFLEX> 219 251 251 221 195.155 138.106 ###
- <U WITH DIAERESIS> 220 252 252 252 195.156 138.112
- <Y WITH ACUTE> 221 173 186 173 195.157 138.113 *** ###
- <CAPITAL LETTER THORN> 222 174 174 174 195.158 138.114
- <SMALL LETTER SHARP S> 223 89 89 89 195.159 138.115
- <a WITH GRAVE> 224 68 68 68 195.160 139.65
- <a WITH ACUTE> 225 69 69 69 195.161 139.66
- <a WITH CIRCUMFLEX> 226 66 66 66 195.162 139.67
- <a WITH TILDE> 227 70 70 70 195.163 139.68
- <a WITH DIAERESIS> 228 67 67 67 195.164 139.69
- <a WITH RING ABOVE> 229 71 71 71 195.165 139.70
- <SMALL LIGATURE ae> 230 156 156 156 195.166 139.71
- <c WITH CEDILLA> 231 72 72 72 195.167 139.72
- <e WITH GRAVE> 232 84 84 84 195.168 139.73
- <e WITH ACUTE> 233 81 81 81 195.169 139.74
- <e WITH CIRCUMFLEX> 234 82 82 82 195.170 139.81
- <e WITH DIAERESIS> 235 83 83 83 195.171 139.82
- <i WITH GRAVE> 236 88 88 88 195.172 139.83
- <i WITH ACUTE> 237 85 85 85 195.173 139.84
- <i WITH CIRCUMFLEX> 238 86 86 86 195.174 139.85
- <i WITH DIAERESIS> 239 87 87 87 195.175 139.86
- <SMALL LETTER eth> 240 140 140 140 195.176 139.87
- <n WITH TILDE> 241 73 73 73 195.177 139.88
- <o WITH GRAVE> 242 205 205 205 195.178 139.89
- <o WITH ACUTE> 243 206 206 206 195.179 139.98
- <o WITH CIRCUMFLEX> 244 203 203 203 195.180 139.99
- <o WITH TILDE> 245 207 207 207 195.181 139.100
- <o WITH DIAERESIS> 246 204 204 204 195.182 139.101
- <DIVISION SIGN> 247 225 225 225 195.183 139.102
- <o WITH STROKE> 248 112 112 112 195.184 139.103
- <u WITH GRAVE> 249 221 221 192 195.185 139.104 ###
- <u WITH ACUTE> 250 222 222 222 195.186 139.105
- <u WITH CIRCUMFLEX> 251 219 219 219 195.187 139.106
- <u WITH DIAERESIS> 252 220 220 220 195.188 139.112
- <y WITH ACUTE> 253 141 141 141 195.189 139.113
- <SMALL LETTER thorn> 254 142 142 142 195.190 139.114
- <y WITH DIAERESIS> 255 223 223 223 195.191 139.115
+ ISO
+ 8859-1 POS-
+ CCSID CCSID CCSID IX-
+ chr 0819 0037 1047 BC UTF-8 UTF-EBCDIC
+ ---------------------------------------------------------------------
+ <NUL> 0 0 0 0 0 0
+ <SOH> 1 1 1 1 1 1
+ <STX> 2 2 2 2 2 2
+ <ETX> 3 3 3 3 3 3
+ <EOT> 4 55 55 55 4 55
+ <ENQ> 5 45 45 45 5 45
+ <ACK> 6 46 46 46 6 46
+ <BEL> 7 47 47 47 7 47
+ <BS> 8 22 22 22 8 22
+ <HT> 9 5 5 5 9 5
+ <LF> 10 37 21 21 10 21 **
+ <VT> 11 11 11 11 11 11
+ <FF> 12 12 12 12 12 12
+ <CR> 13 13 13 13 13 13
+ <SO> 14 14 14 14 14 14
+ <SI> 15 15 15 15 15 15
+ <DLE> 16 16 16 16 16 16
+ <DC1> 17 17 17 17 17 17
+ <DC2> 18 18 18 18 18 18
+ <DC3> 19 19 19 19 19 19
+ <DC4> 20 60 60 60 20 60
+ <NAK> 21 61 61 61 21 61
+ <SYN> 22 50 50 50 22 50
+ <ETB> 23 38 38 38 23 38
+ <CAN> 24 24 24 24 24 24
+ <EOM> 25 25 25 25 25 25
+ <SUB> 26 63 63 63 26 63
+ <ESC> 27 39 39 39 27 39
+ <FS> 28 28 28 28 28 28
+ <GS> 29 29 29 29 29 29
+ <RS> 30 30 30 30 30 30
+ <US> 31 31 31 31 31 31
+ <SPACE> 32 64 64 64 32 64
+ ! 33 90 90 90 33 90
+ " 34 127 127 127 34 127
+ # 35 123 123 123 35 123
+ $ 36 91 91 91 36 91
+ % 37 108 108 108 37 108
+ & 38 80 80 80 38 80
+ ' 39 125 125 125 39 125
+ ( 40 77 77 77 40 77
+ ) 41 93 93 93 41 93
+ * 42 92 92 92 42 92
+ + 43 78 78 78 43 78
+ , 44 107 107 107 44 107
+ - 45 96 96 96 45 96
+ . 46 75 75 75 46 75
+ / 47 97 97 97 47 97
+ 0 48 240 240 240 48 240
+ 1 49 241 241 241 49 241
+ 2 50 242 242 242 50 242
+ 3 51 243 243 243 51 243
+ 4 52 244 244 244 52 244
+ 5 53 245 245 245 53 245
+ 6 54 246 246 246 54 246
+ 7 55 247 247 247 55 247
+ 8 56 248 248 248 56 248
+ 9 57 249 249 249 57 249
+ : 58 122 122 122 58 122
+ ; 59 94 94 94 59 94
+ < 60 76 76 76 60 76
+ = 61 126 126 126 61 126
+ > 62 110 110 110 62 110
+ ? 63 111 111 111 63 111
+ @ 64 124 124 124 64 124
+ A 65 193 193 193 65 193
+ B 66 194 194 194 66 194
+ C 67 195 195 195 67 195
+ D 68 196 196 196 68 196
+ E 69 197 197 197 69 197
+ F 70 198 198 198 70 198
+ G 71 199 199 199 71 199
+ H 72 200 200 200 72 200
+ I 73 201 201 201 73 201
+ J 74 209 209 209 74 209
+ K 75 210 210 210 75 210
+ L 76 211 211 211 76 211
+ M 77 212 212 212 77 212
+ N 78 213 213 213 78 213
+ O 79 214 214 214 79 214
+ P 80 215 215 215 80 215
+ Q 81 216 216 216 81 216
+ R 82 217 217 217 82 217
+ S 83 226 226 226 83 226
+ T 84 227 227 227 84 227
+ U 85 228 228 228 85 228
+ V 86 229 229 229 86 229
+ W 87 230 230 230 87 230
+ X 88 231 231 231 88 231
+ Y 89 232 232 232 89 232
+ Z 90 233 233 233 90 233
+ [ 91 186 173 187 91 173 ** ##
+ \ 92 224 224 188 92 224 ##
+ ] 93 187 189 189 93 189 **
+ ^ 94 176 95 106 94 95 ** ##
+ _ 95 109 109 109 95 109
+ ` 96 121 121 74 96 121 ##
+ a 97 129 129 129 97 129
+ b 98 130 130 130 98 130
+ c 99 131 131 131 99 131
+ d 100 132 132 132 100 132
+ e 101 133 133 133 101 133
+ f 102 134 134 134 102 134
+ g 103 135 135 135 103 135
+ h 104 136 136 136 104 136
+ i 105 137 137 137 105 137
+ j 106 145 145 145 106 145
+ k 107 146 146 146 107 146
+ l 108 147 147 147 108 147
+ m 109 148 148 148 109 148
+ n 110 149 149 149 110 149
+ o 111 150 150 150 111 150
+ p 112 151 151 151 112 151
+ q 113 152 152 152 113 152
+ r 114 153 153 153 114 153
+ s 115 162 162 162 115 162
+ t 116 163 163 163 116 163
+ u 117 164 164 164 117 164
+ v 118 165 165 165 118 165
+ w 119 166 166 166 119 166
+ x 120 167 167 167 120 167
+ y 121 168 168 168 121 168
+ z 122 169 169 169 122 169
+ { 123 192 192 251 123 192 ##
+ | 124 79 79 79 124 79
+ } 125 208 208 253 125 208 ##
+ ~ 126 161 161 255 126 161 ##
+ <DEL> 127 7 7 7 127 7
+ <PAD> 128 32 32 32 194.128 32
+ <HOP> 129 33 33 33 194.129 33
+ <BPH> 130 34 34 34 194.130 34
+ <NBH> 131 35 35 35 194.131 35
+ <IND> 132 36 36 36 194.132 36
+ <NEL> 133 21 37 37 194.133 37 **
+ <SSA> 134 6 6 6 194.134 6
+ <ESA> 135 23 23 23 194.135 23
+ <HTS> 136 40 40 40 194.136 40
+ <HTJ> 137 41 41 41 194.137 41
+ <VTS> 138 42 42 42 194.138 42
+ <PLD> 139 43 43 43 194.139 43
+ <PLU> 140 44 44 44 194.140 44
+ <RI> 141 9 9 9 194.141 9
+ <SS2> 142 10 10 10 194.142 10
+ <SS3> 143 27 27 27 194.143 27
+ <DCS> 144 48 48 48 194.144 48
+ <PU1> 145 49 49 49 194.145 49
+ <PU2> 146 26 26 26 194.146 26
+ <STS> 147 51 51 51 194.147 51
+ <CCH> 148 52 52 52 194.148 52
+ <MW> 149 53 53 53 194.149 53
+ <SPA> 150 54 54 54 194.150 54
+ <EPA> 151 8 8 8 194.151 8
+ <SOS> 152 56 56 56 194.152 56
+ <SGC> 153 57 57 57 194.153 57
+ <SCI> 154 58 58 58 194.154 58
+ <CSI> 155 59 59 59 194.155 59
+ <ST> 156 4 4 4 194.156 4
+ <OSC> 157 20 20 20 194.157 20
+ <PM> 158 62 62 62 194.158 62
+ <APC> 159 255 255 95 194.159 255 ##
+ <NON-BREAKING SPACE> 160 65 65 65 194.160 128.65
+ <INVERTED "!" > 161 170 170 170 194.161 128.66
+ <CENT SIGN> 162 74 74 176 194.162 128.67 ##
+ <POUND SIGN> 163 177 177 177 194.163 128.68
+ <CURRENCY SIGN> 164 159 159 159 194.164 128.69
+ <YEN SIGN> 165 178 178 178 194.165 128.70
+ <BROKEN BAR> 166 106 106 208 194.166 128.71 ##
+ <SECTION SIGN> 167 181 181 181 194.167 128.72
+ <DIAERESIS> 168 189 187 121 194.168 128.73 ** ##
+ <COPYRIGHT SIGN> 169 180 180 180 194.169 128.74
+ <FEMININE ORDINAL> 170 154 154 154 194.170 128.81
+ <LEFT POINTING GUILLEMET> 171 138 138 138 194.171 128.82
+ <NOT SIGN> 172 95 176 186 194.172 128.83 ** ##
+ <SOFT HYPHEN> 173 202 202 202 194.173 128.84
+ <REGISTERED TRADE MARK> 174 175 175 175 194.174 128.85
+ <MACRON> 175 188 188 161 194.175 128.86 ##
+ <DEGREE SIGN> 176 144 144 144 194.176 128.87
+ <PLUS-OR-MINUS SIGN> 177 143 143 143 194.177 128.88
+ <SUPERSCRIPT TWO> 178 234 234 234 194.178 128.89
+ <SUPERSCRIPT THREE> 179 250 250 250 194.179 128.98
+ <ACUTE ACCENT> 180 190 190 190 194.180 128.99
+ <MICRO SIGN> 181 160 160 160 194.181 128.100
+ <PARAGRAPH SIGN> 182 182 182 182 194.182 128.101
+ <MIDDLE DOT> 183 179 179 179 194.183 128.102
+ <CEDILLA> 184 157 157 157 194.184 128.103
+ <SUPERSCRIPT ONE> 185 218 218 218 194.185 128.104
+ <MASC. ORDINAL INDICATOR> 186 155 155 155 194.186 128.105
+ <RIGHT POINTING GUILLEMET> 187 139 139 139 194.187 128.106
+ <FRACTION ONE QUARTER> 188 183 183 183 194.188 128.112
+ <FRACTION ONE HALF> 189 184 184 184 194.189 128.113
+ <FRACTION THREE QUARTERS> 190 185 185 185 194.190 128.114
+ <INVERTED QUESTION MARK> 191 171 171 171 194.191 128.115
+ <A WITH GRAVE> 192 100 100 100 195.128 138.65
+ <A WITH ACUTE> 193 101 101 101 195.129 138.66
+ <A WITH CIRCUMFLEX> 194 98 98 98 195.130 138.67
+ <A WITH TILDE> 195 102 102 102 195.131 138.68
+ <A WITH DIAERESIS> 196 99 99 99 195.132 138.69
+ <A WITH RING ABOVE> 197 103 103 103 195.133 138.70
+ <CAPITAL LIGATURE AE> 198 158 158 158 195.134 138.71
+ <C WITH CEDILLA> 199 104 104 104 195.135 138.72
+ <E WITH GRAVE> 200 116 116 116 195.136 138.73
+ <E WITH ACUTE> 201 113 113 113 195.137 138.74
+ <E WITH CIRCUMFLEX> 202 114 114 114 195.138 138.81
+ <E WITH DIAERESIS> 203 115 115 115 195.139 138.82
+ <I WITH GRAVE> 204 120 120 120 195.140 138.83
+ <I WITH ACUTE> 205 117 117 117 195.141 138.84
+ <I WITH CIRCUMFLEX> 206 118 118 118 195.142 138.85
+ <I WITH DIAERESIS> 207 119 119 119 195.143 138.86
+ <CAPITAL LETTER ETH> 208 172 172 172 195.144 138.87
+ <N WITH TILDE> 209 105 105 105 195.145 138.88
+ <O WITH GRAVE> 210 237 237 237 195.146 138.89
+ <O WITH ACUTE> 211 238 238 238 195.147 138.98
+ <O WITH CIRCUMFLEX> 212 235 235 235 195.148 138.99
+ <O WITH TILDE> 213 239 239 239 195.149 138.100
+ <O WITH DIAERESIS> 214 236 236 236 195.150 138.101
+ <MULTIPLICATION SIGN> 215 191 191 191 195.151 138.102
+ <O WITH STROKE> 216 128 128 128 195.152 138.103
+ <U WITH GRAVE> 217 253 253 224 195.153 138.104 ##
+ <U WITH ACUTE> 218 254 254 254 195.154 138.105
+ <U WITH CIRCUMFLEX> 219 251 251 221 195.155 138.106 ##
+ <U WITH DIAERESIS> 220 252 252 252 195.156 138.112
+ <Y WITH ACUTE> 221 173 186 173 195.157 138.113 ** ##
+ <CAPITAL LETTER THORN> 222 174 174 174 195.158 138.114
+ <SMALL LETTER SHARP S> 223 89 89 89 195.159 138.115
+ <a WITH GRAVE> 224 68 68 68 195.160 139.65
+ <a WITH ACUTE> 225 69 69 69 195.161 139.66
+ <a WITH CIRCUMFLEX> 226 66 66 66 195.162 139.67
+ <a WITH TILDE> 227 70 70 70 195.163 139.68
+ <a WITH DIAERESIS> 228 67 67 67 195.164 139.69
+ <a WITH RING ABOVE> 229 71 71 71 195.165 139.70
+ <SMALL LIGATURE ae> 230 156 156 156 195.166 139.71
+ <c WITH CEDILLA> 231 72 72 72 195.167 139.72
+ <e WITH GRAVE> 232 84 84 84 195.168 139.73
+ <e WITH ACUTE> 233 81 81 81 195.169 139.74
+ <e WITH CIRCUMFLEX> 234 82 82 82 195.170 139.81
+ <e WITH DIAERESIS> 235 83 83 83 195.171 139.82
+ <i WITH GRAVE> 236 88 88 88 195.172 139.83
+ <i WITH ACUTE> 237 85 85 85 195.173 139.84
+ <i WITH CIRCUMFLEX> 238 86 86 86 195.174 139.85
+ <i WITH DIAERESIS> 239 87 87 87 195.175 139.86
+ <SMALL LETTER eth> 240 140 140 140 195.176 139.87
+ <n WITH TILDE> 241 73 73 73 195.177 139.88
+ <o WITH GRAVE> 242 205 205 205 195.178 139.89
+ <o WITH ACUTE> 243 206 206 206 195.179 139.98
+ <o WITH CIRCUMFLEX> 244 203 203 203 195.180 139.99
+ <o WITH TILDE> 245 207 207 207 195.181 139.100
+ <o WITH DIAERESIS> 246 204 204 204 195.182 139.101
+ <DIVISION SIGN> 247 225 225 225 195.183 139.102
+ <o WITH STROKE> 248 112 112 112 195.184 139.103
+ <u WITH GRAVE> 249 221 221 192 195.185 139.104 ##
+ <u WITH ACUTE> 250 222 222 222 195.186 139.105
+ <u WITH CIRCUMFLEX> 251 219 219 219 195.187 139.106
+ <u WITH DIAERESIS> 252 220 220 220 195.188 139.112
+ <y WITH ACUTE> 253 141 141 141 195.189 139.113
+ <SMALL LETTER thorn> 254 142 142 142 195.190 139.114
+ <y WITH DIAERESIS> 255 223 223 223 195.191 139.115
If you would rather see the above table in CCSID 0037 order rather than
ASCII + Latin-1 order then run the table through:
@@ -598,14 +601,14 @@
=back
perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
+ -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
-e '{push(@l,$_)}' \
-e 'END{print map{$_->[0]}' \
-e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,52,3)]}@l;}' perlebcdic.pod
+ -e ' map{[$_,substr($_,34,3)]}@l;}' perlebcdic.pod
If you would rather see it in CCSID 1047 order then change the number
-52 in the last line to 61, like this:
+34 in the last line to 39, like this:
=over 4
@@ -614,14 +617,14 @@
=back
perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
+ -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
-e '{push(@l,$_)}' \
-e 'END{print map{$_->[0]}' \
-e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,61,3)]}@l;}' perlebcdic.pod
+ -e ' map{[$_,substr($_,39,3)]}@l;}' perlebcdic.pod
If you would rather see it in POSIX-BC order then change the number
-61 in the last line to 70, like this:
+39 in the last line to 44, like this:
=over 4
@@ -630,17 +633,17 @@
=back
perl \
- -ne 'if(/.{43}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}\s{6,8}\d{1,3}/)'\
+ -ne 'if(/.{29}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}\s{2,4}\d{1,3}/)'\
-e '{push(@l,$_)}' \
-e 'END{print map{$_->[0]}' \
-e ' sort{$a->[1] <=> $b->[1]}' \
- -e ' map{[$_,substr($_,70,3)]}@l;}' perlebcdic.pod
+ -e ' map{[$_,substr($_,44,3)]}@l;}' perlebcdic.pod
=head1 IDENTIFYING CHARACTER CODE SETS
-To determine the character set you are running under from perl one
-could use the return value of ord() or chr() to test one or more
+To determine the character set you are running under from perl one
+could use the return value of ord() or chr() to test one or more
character values. For example:
$is_ascii = "A" eq chr(65);
@@ -671,12 +674,12 @@
$is_ascii = "\n" ne chr(10); # ILL ADVISED
Obviously the first of these will fail to distinguish most ASCII platforms
-from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC platform since "\r" eq
-chr(13) under all of those coded character sets. But note too that
-because "\n" is chr(13) and "\r" is chr(10) on the Macintosh (which is an
+from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC platform since "\r" eq
+chr(13) under all of those coded character sets. But note too that
+because "\n" is chr(13) and "\r" is chr(10) on the Macintosh (which is an
ASCII platform) the second C<$is_ascii> test will lead to trouble there.
-To determine whether or not perl was built under an EBCDIC
+To determine whether or not perl was built under an EBCDIC
code page you can use the Config module like so:
use Config;
@@ -684,20 +687,25 @@
=head1 CONVERSIONS
+=head2 C<utf8::unicode_to_native()> and C<utf8::native_to_unicode()>
+
+These functions take an input numeric code point in one encoding and
+return what its equivalent value is in the other.
+
=head2 tr///
-In order to convert a string of characters from one character set to
+In order to convert a string of characters from one character set to
another a simple list of numbers, such as in the right columns in the
-above table, along with perl's tr/// operator is all that is needed.
+above table, along with perl's tr/// operator is all that is needed.
The data in the table are in ASCII/Latin1 order, hence the EBCDIC columns
-provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily
+provide easy-to-use ASCII/Latin1 to EBCDIC operations that are also easily
reversed.
For example, to convert ASCII/Latin1 to code page 037 take the output of the
second numbers column from the output of recipe 2 (modified to add '\'
-characters) and use it in tr/// like so:
+characters), and use it in tr/// like so:
- $cp_037 =
+ $cp_037 =
'\x00\x01\x02\x03\x37\x2D\x2E\x2F\x16\x05\x25\x0B\x0C\x0D\x0E\x0F' .
'\x10\x11\x12\x13\x3C\x3D\x32\x26\x18\x19\x3F\x27\x1C\x1D\x1E\x1F' .
'\x40\x5A\x7F\x7B\x5B\x6C\x50\x7D\x4D\x5D\x5C\x4E\x6B\x60\x4B\x61' .
@@ -739,7 +747,7 @@
available from the shell or from the C library. Consult your system's
documentation for information on iconv.
-On OS/390 or z/OS see the iconv(1) manpage. One way to invoke the iconv
+On OS/390 or z/OS see the iconv(1) manpage. One way to invoke the iconv
shell utility from within perl would be to:
# OS/390 or z/OS example
@@ -758,7 +766,7 @@
=head1 OPERATOR DIFFERENCES
-The C<..> range operator treats certain character ranges with
+The C<..> range operator treats certain character ranges with
care on EBCDIC platforms. For example the following array
will have twenty six elements on either an EBCDIC platform
or an ASCII platform:
@@ -766,13 +774,13 @@
@alphabet = ('A'..'Z'); # $#alphabet == 25
The bitwise operators such as & ^ | may return different results
-when operating on string or character data in a perl program running
+when operating on string or character data in a perl program running
on an EBCDIC platform than when run on an ASCII platform. Here is
an example adapted from the one in L<perlop>:
# EBCDIC-based examples
print "j p \n" ^ " a h"; # prints "JAPH\n"
- print "JA" | " ph\n"; # prints "japh\n"
+ print "JA" | " ph\n"; # prints "japh\n"
print "JAPH\nJunk" & "\277\277\277\277\277"; # prints "japh\n";
print 'p N$' ^ " E<H\n"; # prints "Perl\n";
@@ -784,45 +792,45 @@
thirty three characters that result depend on which code page you are
using. The table below uses the standard acronyms for the controls.
The POSIX-BC and 1047 sets are
-identical throughout this range and differ from the 0037 set at only
+identical throughout this range and differ from the 0037 set at only
one spot (21 decimal). Note that the C<LINE FEED> character
-may be generated by C<\cJ> on ASCII platforms but by C<\cU> on 1047 or POSIX-BC
-platforms and cannot be generated as a C<"\c.letter."> control character on
+may be generated by C<\cJ> on ASCII platforms but by C<\cU> on 1047 or POSIX-BC
+platforms and cannot be generated as a C<"\c.letter."> control character on
0037 platforms. Note also that C<\c\> cannot be the final element in a string
or regex, as it will absorb the terminator. But C<\c\I<X>> is a C<FILE
SEPARATOR> concatenated with I<X> for all I<X>.
- chr ord 8859-1 0037 1047 && POSIX-BC
+ chr ord 8859-1 0037 1047 && POSIX-BC
-----------------------------------------------------------------------
- \c? 127 <DEL> " "
+ \c? 127 <DEL> " "
\c@ 0 <NUL> <NUL> <NUL>
- \cA 1 <SOH> <SOH> <SOH>
+ \cA 1 <SOH> <SOH> <SOH>
\cB 2 <STX> <STX> <STX>
\cC 3 <ETX> <ETX> <ETX>
- \cD 4 <EOT> <ST> <ST>
- \cE 5 <ENQ> <HT> <HT>
- \cF 6 <ACK> <SSA> <SSA>
- \cG 7 <BEL> <DEL> <DEL>
- \cH 8 <BS> <EPA> <EPA>
- \cI 9 <HT> <RI> <RI>
- \cJ 10 <LF> <SS2> <SS2>
+ \cD 4 <EOT> <ST> <ST>
+ \cE 5 <ENQ> <HT> <HT>
+ \cF 6 <ACK> <SSA> <SSA>
+ \cG 7 <BEL> <DEL> <DEL>
+ \cH 8 <BS> <EPA> <EPA>
+ \cI 9 <HT> <RI> <RI>
+ \cJ 10 <LF> <SS2> <SS2>
\cK 11 <VT> <VT> <VT>
- \cL 12 <FF> <FF> <FF>
- \cM 13 <CR> <CR> <CR>
+ \cL 12 <FF> <FF> <FF>
+ \cM 13 <CR> <CR> <CR>
\cN 14 <SO> <SO> <SO>
\cO 15 <SI> <SI> <SI>
- \cP 16 <DLE> <DLE> <DLE>
+ \cP 16 <DLE> <DLE> <DLE>
\cQ 17 <DC1> <DC1> <DC1>
\cR 18 <DC2> <DC2> <DC2>
- \cS 19 <DC3> <DC3> <DC3>
- \cT 20 <DC4> <OSC> <OSC>
- \cU 21 <NAK> <NEL> <LF> ***
+ \cS 19 <DC3> <DC3> <DC3>
+ \cT 20 <DC4> <OSC> <OSC>
+ \cU 21 <NAK> <NEL> <LF> **
\cV 22 <SYN> <BS> <BS>
- \cW 23 <ETB> <ESA> <ESA>
+ \cW 23 <ETB> <ESA> <ESA>
\cX 24 <CAN> <CAN> <CAN>
\cY 25 <EOM> <EOM> <EOM>
- \cZ 26 <SUB> <PU2> <PU2>
- \c[ 27 <ESC> <SS3> <SS3>
+ \cZ 26 <SUB> <PU2> <PU2>
+ \c[ 27 <ESC> <SS3> <SS3>
\c\X 28 <FS>X <FS>X <FS>X
\c] 29 <GS> <GS> <GS>
\c^ 30 <RS> <RS> <RS>
@@ -834,7 +842,7 @@
=item chr()
-chr() must be given an EBCDIC code number argument to yield a desired
+chr() must be given an EBCDIC code number argument to yield a desired
character return value on an EBCDIC platform. For example:
$CAPITAL_LETTER_A = chr(193);
@@ -848,7 +856,7 @@
=item pack()
-The c and C templates for pack() are dependent upon character set
+The c and C templates for pack() are dependent upon character set
encoding. Examples of usage on EBCDIC include:
$foo = pack("CCCC",193,194,195,196);
@@ -864,13 +872,13 @@
One must be careful with scalars and strings that are passed to
print that contain ASCII encodings. One common place
for this to occur is in the output of the MIME type header for
-CGI script writing. For example, many perl programming guides
+CGI script writing. For example, many perl programming guides
recommend something similar to:
- print "Content-type:\ttext/html\015\012\015\012";
+ print "Content-type:\ttext/html\015\012\015\012";
# this may be wrong on EBCDIC
-Under the IBM OS/390 USS Web Server or WebSphere on z/OS for example
+Under the IBM OS/390 USS Web Server or WebSphere on z/OS for example
you should instead write that as:
print "Content-type:\ttext/html\r\n\r\n"; # OK for DGW et al
@@ -877,7 +885,7 @@
That is because the translation from EBCDIC to ASCII is done
by the web server in this case (such code will not be appropriate for
-the Macintosh however). Consult your web server's documentation for
+the Macintosh however). Consult your web server's documentation for
further details.
=item printf()
@@ -890,7 +898,7 @@
=item sort()
-EBCDIC sort results may differ from ASCII sort results especially for
+EBCDIC sort results may differ from ASCII sort results especially for
mixed case strings. This is discussed in more detail below.
=item sprintf()
@@ -908,10 +916,10 @@
=head1 REGULAR EXPRESSION DIFFERENCES
-As of perl 5.005_03 the letter range regular expressions such as
-[A-Z] and [a-z] have been especially coded to not pick up gap
-characters. For example, characters such as E<ocirc> C<o WITH CIRCUMFLEX>
-that lie between I and J would not be matched by the
+As of perl 5.005_03 the letter range regular expressions such as
+[A-Z] and [a-z] have been especially coded to not pick up gap
+characters. For example, characters such as E<ocirc> C<o WITH CIRCUMFLEX>
+that lie between I and J would not be matched by the
regular expression range C</[H-K]/>. This works in
the other direction, too, if either of the range end points is
explicitly numeric: C<[\x89-\x91]> will match C<\x8e>, even
@@ -918,9 +926,9 @@
though C<\x89> is C<i> and C<\x91 > is C<j>, and C<\x8e>
is a gap character from the alphabetic viewpoint.
-If you do want to match the alphabet gap characters in a single octet
-regular expression try matching the hex or octal code such
-as C</\313/> on EBCDIC or C</\364/> on ASCII platforms to
+If you do want to match the alphabet gap characters in a single octet
+regular expression try matching the hex or octal code such
+as C</\313/> on EBCDIC or C</\364/> on ASCII platforms to
have your regular expression match C<o WITH CIRCUMFLEX>.
Another construct to be wary of is the inappropriate use of hex or
@@ -953,8 +961,8 @@
}
The above would be adequate if the concern was only with numeric code points.
-However, the concern may be with characters rather than code points
-and on an EBCDIC platform it may be desirable for constructs such as
+However, the concern may be with characters rather than code points
+and on an EBCDIC platform it may be desirable for constructs such as
C<if (is_print_ascii("A")) {print "A is a printable character\n";}> to print
out the expected message. One way to represent the above collection
of character classification subs that is capable of working across the
@@ -964,7 +972,7 @@
my $char = substr(shift,0,1);
if (ord('^')==94) { # ascii
return $char =~ /[\000-\037]/;
- }
+ }
if (ord('^')==176) { # 0037
return $char =~ /[\000-\003\067\055-\057\026\005\045\013-\023\074\075\062\046\030\031\077\047\034-\037]/;
}
@@ -1000,7 +1008,7 @@
return $char =~ /[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\377]/;
}
if (ord('^')==106) { # posix-bc
- return $char =~
+ return $char =~
/[\040-\045\006\027\050-\054\011\012\033\060\061\032\063-\066\010\070-\073\040\024\076\137]/;
}
}
@@ -1011,21 +1019,21 @@
return $char =~ /[\240-\377]/;
}
if (ord('^')==176) { # 0037
- return $char =~
+ return $char =~
/[\101\252\112\261\237\262\152\265\275\264\232\212\137\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
}
if (ord('^')==95) { # 1047
return $char =~
- /[\101\252\112\261\237\262\152\265\273\264\232\212\260\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\272\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
+ /[\101\252\112\261\237\262\152\265\273\264\232\212\260\312\257\274\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\375\376\373\374\272\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\335\336\333\334\215\216\337]/;
}
if (ord('^')==106) { # posix-bc
- return $char =~
+ return $char =~
/[\101\252\260\261\237\262\320\265\171\264\232\212\272\312\257\241\220\217\352\372\276\240\266\263\235\332\233\213\267\270\271\253\144\145\142\146\143\147\236\150\164\161-\163\170\165-\167\254\151\355\356\353\357\354\277\200\340\376\335\374\255\256\131\104\105\102\106\103\107\234\110\124\121-\123\130\125-\127\214\111\315\316\313\317\314\341\160\300\336\333\334\215\216\337]/;
}
}
-Note however that only the C<Is_ascii_print()> sub is really independent
-of coded character set. Another way to write C<Is_latin_1()> would be
+Note however that only the C<Is_ascii_print()> sub is really independent
+of coded character set. Another way to write C<Is_latin_1()> would be
to use the characters in the range explicitly:
sub Is_latin_1 {
@@ -1033,7 +1041,7 @@
$char =~ /[ ¡¢£¤¥¦§¨©ª«¬®¯°±²³´µ¶·¸¹º»¼½¾¿ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖ×ØÙÚÛÜÝÞßàáâãäåæçèéêëìíîïðñòóôõö÷øùúûüýþÿ]/;
}
-Although that form may run into trouble in network transit (due to the
+Although that form may run into trouble in network transit (due to the
presence of 8 bit characters) or on non ISO-Latin character sets.
=head1 SOCKETS
@@ -1057,12 +1065,12 @@
The property of lowercase before uppercase letters in EBCDIC is
even carried to the Latin 1 EBCDIC pages such as 0037 and 1047.
-An example would be that E<Euml> C<E WITH DIAERESIS> (203) comes
-before E<euml> C<e WITH DIAERESIS> (235) on an ASCII platform, but
-the latter (83) comes before the former (115) on an EBCDIC platform.
-(Astute readers will note that the uppercase version of E<szlig>
-C<SMALL LETTER SHARP S> is simply "SS" and that the upper case version of
-E<yuml> C<y WITH DIAERESIS> is not in the 0..255 range but it is
+An example would be that E<Euml> C<E WITH DIAERESIS> (203) comes
+before E<euml> C<e WITH DIAERESIS> (235) on an ASCII platform, but
+the latter (83) comes before the former (115) on an EBCDIC platform.
+(Astute readers will note that the uppercase version of E<szlig>
+C<SMALL LETTER SHARP S> is simply "SS" and that the upper case version of
+E<yuml> C<y WITH DIAERESIS> is not in the 0..255 range but it is
at U+x0178 in Unicode, or C<"\x{178}"> in a Unicode enabled Perl).
The sort order will cause differences between results obtained on
@@ -1081,21 +1089,21 @@
If the data are primarily UPPERCASE non Latin 1 then apply tr/[a-z]/[A-Z]/
then sort(). If the data are primarily lowercase non Latin 1 then
apply tr/[A-Z]/[a-z]/ before sorting. If the data are primarily UPPERCASE
-and include Latin-1 characters then apply:
+and include Latin-1 characters then apply:
- tr/[a-z]/[A-Z]/;
- tr/[àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ]/[ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ/;
- s/ß/SS/g;
+ tr/[a-z]/[A-Z]/;
+ tr/[àáâãäåæçèéêëìíîïðñòóôõöøùúûüýþ]/[ÀÁÂÃÄÅÆÇÈÉÊËÌÍÎÏÐÑÒÓÔÕÖØÙÚÛÜÝÞ/;
+ s/ß/SS/g;
-then sort(). Do note however that such Latin-1 manipulation does not
-address the E<yuml> C<y WITH DIAERESIS> character that will remain at
-code point 255 on ASCII platforms, but 223 on most EBCDIC platforms
-where it will sort to a place less than the EBCDIC numerals. With a
+then sort(). Do note however that such Latin-1 manipulation does not
+address the E<yuml> C<y WITH DIAERESIS> character that will remain at
+code point 255 on ASCII platforms, but 223 on most EBCDIC platforms
+where it will sort to a place less than the EBCDIC numerals. With a
Unicode-enabled Perl you might try:
tr/^?/\x{178}/;
-The strategy of mono casing data before sorting does not preserve the case
+The strategy of mono casing data before sorting does not preserve the case
of the data and may not be acceptable for that reason.
=head2 Convert, sort data, then re convert.
@@ -1110,15 +1118,15 @@
=head1 TRANSFORMATION FORMATS
-There are a variety of ways of transforming data with an intra character set
-mapping that serve a variety of purposes. Sorting was discussed in the
-previous section and a few of the other more popular mapping techniques are
+There are a variety of ways of transforming data with an intra character set
+mapping that serve a variety of purposes. Sorting was discussed in the
+previous section and a few of the other more popular mapping techniques are
discussed next.
=head2 URL decoding and encoding
Note that some URLs have hexadecimal ASCII code points in them in an
-attempt to overcome character or protocol limitation issues. For example
+attempt to overcome character or protocol limitation issues. For example
the tilde character is not on every keyboard hence a URL of the form:
http://www.pvhp.com/~pvhp/
@@ -1154,7 +1162,7 @@
);
$url =~ s/%([0-9a-fA-F]{2})/pack("c",$a2e_1047[hex($1)])/ge;
-Conversely, here is a partial solution for the task of encoding such
+Conversely, here is a partial solution for the task of encoding such
a URL under the 1047 code page:
$url = 'http://www.pvhp.com/~pvhp/';
@@ -1177,11 +1185,11 @@
92,247, 83, 84, 85, 86, 87, 88, 89, 90,178,212,214,210,211,213,
48, 49, 50, 51, 52, 53, 54, 55, 56, 57,179,219,220,217,218,159
);
- # The following regular expression does not address the
- # mappings for: ('.' => '%2E', '/' => '%2F', ':' => '%3A')
+ # The following regular expression does not address the
+ # mappings for: ('.' => '%2E', '/' => '%2F', ':' => '%3A')
$url =~ s/([\t "#%&\(\),;<=>\?\@\[\\\]^`{|}~])/sprintf("%%%02X",$e2a_1047[ord($1)])/ge;
-where a more complete solution would split the URL into components
+where a more complete solution would split the URL into components
and apply a full s/// substitution only to the appropriate parts.
In the remaining examples a @e2a or @a2e array may be employed
@@ -1190,8 +1198,8 @@
=head2 uu encoding and decoding
-The C<u> template to pack() or unpack() will render EBCDIC data in EBCDIC
-characters equivalent to their ASCII counterparts. For example, the
+The C<u> template to pack() or unpack() will render EBCDIC data in EBCDIC
+characters equivalent to their ASCII counterparts. For example, the
following will print "Yes indeed\n" on either an ASCII or EBCDIC computer:
$all_byte_chrs = '';
@@ -1240,8 +1248,8 @@
# This QP encoder works on ASCII only
$qp_string =~ s/([=\x00-\x1F\x80-\xFF])/sprintf("=%02X",ord($1))/ge;
-Whereas a QP encoder that works on both ASCII and EBCDIC platforms
-would look somewhat like the following (where the EBCDIC branch @e2a
+Whereas a QP encoder that works on both ASCII and EBCDIC platforms
+would look somewhat like the following (where the EBCDIC branch @e2a
array is omitted for brevity):
if (ord('A') == 65) { # ASCII
@@ -1256,7 +1264,7 @@
s/([^ !"\#\$%&'()*+,\-.\/0-9:;<>?\@A-Z[\\\]^_`a-z{|}~$delete])/sprintf("=%02X",$e2a[ord($1)])/ge;
(although in production code the substitutions might be done
-in the EBCDIC branch with the @e2a array and separately in the
+in the EBCDIC branch with the @e2a array and separately in the
ASCII branch without the expense of the identity map).
Such QP strings can be decoded with:
@@ -1265,7 +1273,7 @@
$string =~ s/=([0-9A-Fa-f][0-9A-Fa-f])/chr hex $1/ge;
$string =~ s/=[\n\r]+$//;
-Whereas a QP decoder that works on both ASCII and EBCDIC platforms
+Whereas a QP decoder that works on both ASCII and EBCDIC platforms
would look somewhat like the following (where the @a2e array is
omitted for brevity):
@@ -1276,13 +1284,13 @@
The practice of shifting an alphabet one or more characters for encipherment
dates back thousands of years and was explicitly detailed by Gaius Julius
-Caesar in his B<Gallic Wars> text. A single alphabet shift is sometimes
+Caesar in his B<Gallic Wars> text. A single alphabet shift is sometimes
referred to as a rotation and the shift amount is given as a number $n after
-the string 'rot' or "rot$n". Rot0 and rot26 would designate identity maps
-on the 26-letter English version of the Latin alphabet. Rot13 has the
-interesting property that alternate subsequent invocations are identity maps
-(thus rot13 is its own non-trivial inverse in the group of 26 alphabet
-rotations). Hence the following is a rot13 encoder and decoder that will
+the string 'rot' or "rot$n". Rot0 and rot26 would designate identity maps
+on the 26-letter English version of the Latin alphabet. Rot13 has the
+interesting property that alternate subsequent invocations are identity maps
+(thus rot13 is its own non-trivial inverse in the group of 26 alphabet
+rotations). Hence the following is a rot13 encoder and decoder that will
work on ASCII and EBCDIC platforms:
#!/usr/local/bin/perl
@@ -1299,7 +1307,7 @@
=head1 Hashing order and checksums
-To the extent that it is possible to write code that depends on
+To the extent that it is possible to write code that depends on
hashing order there may be differences between hashes as stored
on an ASCII-based platform and hashes stored on an EBCDIC-based platform.
XXX
@@ -1306,14 +1314,14 @@
=head1 I18N AND L10N
-Internationalization (I18N) and localization (L10N) are supported at least
-in principle even on EBCDIC platforms. The details are system-dependent
+Internationalization (I18N) and localization (L10N) are supported at least
+in principle even on EBCDIC platforms. The details are system-dependent
and discussed under the L<perlebcdic/OS ISSUES> section below.
=head1 MULTI-OCTET CHARACTER SETS
-Perl may work with an internal UTF-EBCDIC encoding form for wide characters
-on EBCDIC platforms in a manner analogous to the way that it works with
+Perl may work with an internal UTF-EBCDIC encoding form for wide characters
+on EBCDIC platforms in a manner analogous to the way that it works with
the UTF-8 internal encoding form on ASCII based platforms.
Legacy multi byte EBCDIC code pages XXX.
@@ -1320,7 +1328,7 @@
=head1 OS ISSUES
-There may be a few system-dependent issues
+There may be a few system-dependent issues
of concern to EBCDIC Perl programmers.
=head2 OS/400
@@ -1347,8 +1355,8 @@
=item chcp
-B<chcp> is supported as a shell utility for displaying and changing
-one's code page. See also L<chcp>.
+B<chcp> is supported as a shell utility for displaying and changing
+one's code page. See also L<chcp(1)>.
=item dataset access
@@ -1375,10 +1383,6 @@
=back
-=head2 VM/ESA?
-
-XXX.
-
=head2 POSIX-BC?
XXX.
@@ -1385,16 +1389,16 @@
=head1 BUGS
-This pod document contains literal Latin 1 characters and may encounter
-translation difficulties. In particular one popular nroff implementation
-was known to strip accented characters to their unaccented counterparts
-while attempting to view this document through the B<pod2man> program
-(for example, you may see a plain C<y> rather than one with a diaeresis
+This pod document contains literal Latin 1 characters and may encounter
+translation difficulties. In particular one popular nroff implementation
+was known to strip accented characters to their unaccented counterparts
+while attempting to view this document through the B<pod2man> program
+(for example, you may see a plain C<y> rather than one with a diaeresis
as in E<yuml>). Another nroff truncated the resultant manpage at
the first occurrence of 8 bit characters.
Not all shells will allow multiple C<-e> string arguments to perl to
-be concatenated together properly as recipes 0, 2, 4, 5, and 6 might
+be concatenated together properly as recipes 0, 2, 4, 5, and 6 might
seem to imply.
=head1 SEE ALSO
@@ -1413,13 +1417,13 @@
B<ASCII: American Standard Code for Information Infiltration> Tom Jennings,
September 1999.
-B<The Unicode Standard, Version 3.0> The Unicode Consortium, Lisa Moore ed.,
-ISBN 0-201-61633-5, Addison Wesley Developers Press, February 2000.
+B<The Unicode Standard, Version 3.0> The Unicode Consortium, Lisa Moore ed.,
+ISBN 0-201-61633-5, Addison Wesley Developers Press, February 2000.
-B<CDRA: IBM - Character Data Representation Architecture -
-Reference and Registry>, IBM SC09-2190-00, December 1996.
+B<CDRA: IBM - Character Data Representation Architecture -
+Reference and Registry>, IBM SC09-2190-00, December 1996.
-"Demystifying Character Sets", Andrea Vine, Multilingual Computing
+"Demystifying Character Sets", Andrea Vine, Multilingual Computing
& Technology, B<#26 Vol. 10 Issue 4>, August/September 1999;
ISSN 1523-0309; Multilingual Computing Inc. Sandpoint ID, USA.
@@ -1436,11 +1440,11 @@
=head1 AUTHOR
-Peter Prymmer pvhp at best.com wrote this in 1999 and 2000
-with CCSID 0819 and 0037 help from Chris Leach and
-AndrE<eacute> Pirard A.Pirard at ulg.ac.be as well as POSIX-BC
+Peter Prymmer pvhp at best.com wrote this in 1999 and 2000
+with CCSID 0819 and 0037 help from Chris Leach and
+AndrE<eacute> Pirard A.Pirard at ulg.ac.be as well as POSIX-BC
help from Thomas Dorner Thomas.Dorner at start.de.
-Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and
-Joe Smith. Trademarks, registered trademarks, service marks and
-registered service marks used in this document are the property of
+Thanks also to Vickie Cooper, Philip Newton, William Raffloer, and
+Joe Smith. Trademarks, registered trademarks, service marks and
+registered service marks used in this document are the property of
their respective owners.
Property changes on: trunk/contrib/perl/pod/perlebcdic.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlembed.pod
===================================================================
--- trunk/contrib/perl/pod/perlembed.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlembed.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -490,7 +490,7 @@
SvREFCNT_dec(command);
*match_list = get_av("array", 0);
- num_matches = av_len(*match_list) + 1;
+ num_matches = av_top_index(*match_list) + 1;
return num_matches;
}
@@ -1114,18 +1114,4 @@
Copyright (C) 1995, 1996, 1997, 1998 Doug MacEachern and Jon Orwant. All
Rights Reserved.
-Permission is granted to make and distribute verbatim copies of this
-documentation provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-documentation under the conditions for verbatim copying, provided also
-that they are marked clearly as modified versions, that the authors'
-names and title are unchanged (though subtitles and additional
-authors' names may be added), and that the entire resulting derived
-work is distributed under the terms of a permission notice identical
-to this one.
-
-Permission is granted to copy and distribute translations of this
-documentation into another language, under the above conditions for
-modified versions.
+This document may be distributed under the same terms as Perl itself.
Property changes on: trunk/contrib/perl/pod/perlembed.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlexperiment.pod (from rev 6437, vendor/perl/5.18.1/pod/perlexperiment.pod)
===================================================================
--- trunk/contrib/perl/pod/perlexperiment.pod (rev 0)
+++ trunk/contrib/perl/pod/perlexperiment.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,334 @@
+=head1 NAME
+
+perlexperiment - A listing of experimental features in Perl
+
+=head1 DESCRIPTION
+
+This document lists the current and past experimental features in the perl
+core. Although all of these are documented with their appropriate topics,
+this succinct listing gives you an overview and basic facts about their
+status.
+
+So far we've merely tried to find and list the experimental features and infer
+their inception, versions, etc. There's a lot of speculation here.
+
+=head2 Current experiments
+
+=over 8
+
+=item -Dusemultiplicity -Duseithreads
+
+Introduced in Perl 5.6.0
+
+=item Long Doubles Still Don't Work In Solaris
+
+Introduced in Perl 5.7.0
+
+=item C<our> can now have an experimental optional attribute C<unique>
+
+Introduced in Perl 5.8.0
+
+Deprecated in Perl 5.10.0
+
+=item Linux abstract Unix domain sockets
+
+Introduced in Perl 5.9.2
+
+See also L<Socket>
+
+=item L<Pod::HTML2Pod|Pod::HTML2Pod>
+
+=item L<Pod::PXML|Pod::PXML>
+
+=item The <:pop> IO pseudolayer
+
+See also L<perlrun>
+
+=item The <:win32> IO pseudolayer
+
+See also L<perlrun>
+
+=item MLDBM
+
+See also L<perldsc>
+
+=item internal functions with M flag
+
+See also L<perlguts>
+
+=item lex_start API
+
+Introduced in Perl 5.13.7
+
+=item internal API for C<%^H>
+
+Introduced in Perl 5.13.7
+
+See also C<cophh_> in L<perlapi>.
+
+=item alloccopstash
+
+Introduced in Perl 5.18.0
+
+=item av_create_and_push
+
+=item av_create_and_unshift_one
+
+=item av_create_and_unshift_one
+
+=item cop_store_label
+
+Introduced in Perl 5.16.0
+
+=item PL_keyword_plugin
+
+=item gv_fetchmethod_*_flags
+
+Introduced in Perl 5.16.0
+
+=item hv_iternext_flags
+
+=item lex_bufutf8
+
+=item lex_discard_to
+
+=item lex_grow_linestr
+
+=item lex_next_chunk
+
+=item lex_peek_unichar
+
+=item lex_read_space
+
+=item lex_read_to
+
+=item lex_read_unichar
+
+=item lex_stuff_pv
+
+=item lex_stuff_pvn
+
+=item lex_stuff_pvs
+
+=item lex_stuff_sv
+
+=item lex_unstuff
+
+=item op_scope
+
+=item op_lvalue
+
+=item parse_fullstmt
+
+=item parse_stmtseq
+
+=item PL_parser-E<gt>bufend
+
+=item PL_parser-E<gt>bufptr
+
+=item PL_parser-E<gt>linestart
+
+=item PL_parser-E<gt>linestr
+
+=item Perl_signbit
+
+=item pad_findmy
+
+=item sv_utf8_decode
+
+=item sv_utf8_downgrade
+
+=item bytes_from_utf8
+
+=item bytes_to_utf8
+
+=item utf8_to_bytes
+
+=item Lvalue subroutines
+
+Introduced in Perl 5.6.0
+
+See also L<perlsub>
+
+=item There is an C<installhtml> target in the Makefile.
+
+=item Unicode in Perl on EBCDIC
+
+=item C<(?{code})>
+
+See also L<perlre>
+
+=item C<(??{ code })>
+
+See also L<perlre>
+
+=item Smart match (C<~~>)
+
+Introduced in Perl 5.10.0
+
+Modified in Perl 5.10.1, 5.12.0
+
+=item Lexical C<$_>
+
+Introduced in Perl 5.10.0
+
+=item Backtracking control verbs
+
+C<(*ACCEPT)>
+
+Introduced in: Perl 5.10
+
+See also: L<perlre/"Special Backtracking Control Verbs">
+
+=item Code expressions, conditional expressions, and independent expressions in regexes
+
+
+=item gv_try_downgrade
+
+See also L<perlintern>
+
+=item Experimental Support for Sun Studio Compilers for Linux OS
+
+See also L<perllinux>
+
+=item Pluggable keywords
+
+See L<perlapi/PL_keyword_plugin> for the mechanism.
+
+Introduced in: Perl 5.11.2
+
+=item Array and hash container functions accept references
+
+Introduced in Perl 5.14.0
+
+=item Lexical subroutines
+
+Introduced in: Perl 5.18
+
+See also: L<perlsub/Lexical Subroutines>
+
+=item Regular Expression Set Operations
+
+Introduced in: Perl 5.18
+
+See also: L<perlrecharclass/Extended Bracketed Character Classes>
+
+=back
+
+=head2 Accepted features
+
+These features were so wildly successful and played so well with others that
+we decided to remove their experimental status and admit them as full, stable
+features in the world of Perl, lavishing all the benefits and luxuries thereof.
+They are also awarded +5 Stability and +3 Charisma.
+
+=over 8
+
+=item The C<\N> regex character class
+
+The C<\N> character class, not to be confused with the named character
+sequence C<\N{NAME}>, denotes any non-newline character in a regular
+expression.
+
+Introduced in: Perl 5.12
+
+=item fork() emulation
+
+Introduced in Perl 5.6.1
+
+See also L<perlfork>
+
+=item DB module
+
+Introduced in Perl 5.6.0
+
+See also L<perldebug>, L<perldebtut>
+
+=item Weak references
+
+Introduced in Perl 5.6.0
+
+=item Internal file glob
+
+Introduced in Perl 5.6.0
+
+=item die accepts a reference
+
+Introduced in Perl 5.005
+
+=item 64-bit support
+
+Introduced in Perl 5.005
+
+=back
+
+=head2 Removed features
+
+These features are no longer considered experimental and their functionality
+has disappeared. It's your own fault if you wrote production programs using
+these features after we explicitly told you not to (see L<perlpolicy>).
+
+=over 8
+
+=item C<legacy>
+
+The experimental C<legacy> pragma was swallowed by the C<feature> pragma.
+
+Introduced in: 5.11.2
+
+Removed in: 5.11.3
+
+=item Assertions
+
+The C<-A> command line switch
+
+Introduced in Perl 5.9.0
+
+Removed in Perl 5.9.5
+
+=item Test::Harness::Straps
+
+Moved from Perl 5.10.1 to CPAN
+
+=item GetOpt::Long Options can now take multiple values at once (experimental)
+
+C<Getopt::Long> upgraded to version 2.35
+
+Removed in Perl 5.8.8
+
+=item The pseudo-hash data type
+
+Introduced in Perl 5.6.0
+
+Removed in Perl 5.9.0
+
+=item 5.005-style threading
+
+Introduced in Perl 5.005
+
+Removed in Perl 5.10
+
+=item perlcc
+
+Introduced in Perl 5.005
+
+Moved from Perl 5.9.0 to CPAN
+
+=back
+
+=head1 AUTHORS
+
+brian d foy C<< <brian.d.foy at gmail.com> >>
+
+SE<eacute>bastien Aperghis-Tramoni C<< <saper at cpan.org> >>
+
+=head1 COPYRIGHT
+
+Copyright 2010, brian d foy C<< <brian.d.foy at gmail.com> >>
+
+=head1 LICENSE
+
+You can use and redistribute this document under the same terms as Perl
+itself.
+
+=cut
Index: trunk/contrib/perl/pod/perlfaq.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq1.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq1.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq1.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq1.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq2.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq2.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq2.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq2.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq3.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq3.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq3.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq3.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq4.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq4.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq4.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq4.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq5.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq5.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq5.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq5.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq6.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq6.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq6.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq6.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq7.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq7.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq7.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq7.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq8.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq8.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq8.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq8.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfaq9.pod
===================================================================
--- trunk/contrib/perl/pod/perlfaq9.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfaq9.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfaq9.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlfilter.pod
===================================================================
--- trunk/contrib/perl/pod/perlfilter.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfilter.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlfilter.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlfork.pod
===================================================================
--- trunk/contrib/perl/pod/perlfork.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfork.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -78,10 +78,12 @@
=item kill()
C<kill('KILL', ...)> can be used to terminate a pseudo-process by
-passing it the ID returned by fork(). This should not be used except
+passing it the ID returned by fork(). The outcome of kill on a pseudo-process
+is unpredictable and it should not be used except
under dire circumstances, because the operating system may not
guarantee integrity of the process resources when a running thread is
-terminated. Note that using C<kill('KILL', ...)> on a
+terminated. The process which implements the pseudo-processes can be blocked
+and the Perl interpreter hangs. Note that using C<kill('KILL', ...)> on a
pseudo-process() may typically cause memory leaks, because the thread
that implements the pseudo-process does not get a chance to clean up
its resources.
@@ -307,6 +309,12 @@
=back
+=head1 PORTABILITY CAVEATS
+
+In portable Perl code, C<kill(9, $child)> must not be used on forked processes.
+Killing a forked process is unsafe and has unpredictable results.
+See L</kill()>, above.
+
=head1 BUGS
=over 8
Property changes on: trunk/contrib/perl/pod/perlfork.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlform.pod
===================================================================
--- trunk/contrib/perl/pod/perlform.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlform.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -393,7 +393,7 @@
yourself if necessary.
Here's another strategy: Open a pipe to yourself, using C<open(MYSELF, "|-")>
-(see L<perlfunc/"open FILEHANDLE">) and always write() to MYSELF instead of STDOUT.
+(see L<perlfunc/open>) and always write() to MYSELF instead of STDOUT.
Have your child process massage its STDIN to rearrange headers and footers
however you like. Not very convenient, but doable.
@@ -400,7 +400,7 @@
=head2 Accessing Formatting Internals
X<format, internals>
-For low-level access to the formatting mechanism. you may use formline()
+For low-level access to the formatting mechanism, you may use formline()
and access C<$^A> (the $ACCUMULATOR variable) directly.
For example:
@@ -409,7 +409,7 @@
@<<< @||| @>>>
END
- print "Wow, I just stored `$^A' in the accumulator!\n";
+ print "Wow, I just stored '$^A' in the accumulator!\n";
Or to make an swrite() subroutine, which is to write() what sprintf()
is to printf(), do this:
@@ -440,7 +440,7 @@
Lexical variables (declared with "my") are not visible within a
format unless the format is declared within the scope of the lexical
-variable. (They weren't visible at all before version 5.001.)
+variable.
If a program's environment specifies an LC_NUMERIC locale and C<use
locale> is in effect when the format is declared, the locale is used
Property changes on: trunk/contrib/perl/pod/perlform.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlfunc.pod
===================================================================
--- trunk/contrib/perl/pod/perlfunc.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlfunc.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -107,18 +107,29 @@
=item Functions for SCALARs or strings
X<scalar> X<string> X<character>
-C<chomp>, C<chop>, C<chr>, C<crypt>, C<hex>, C<index>, C<lc>, C<lcfirst>,
-C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
+=for Pod::Functions =String
+
+C<chomp>, C<chop>, C<chr>, C<crypt>, C<fc>, C<hex>, C<index>, C<lc>,
+C<lcfirst>, C<length>, C<oct>, C<ord>, C<pack>, C<q//>, C<qq//>, C<reverse>,
C<rindex>, C<sprintf>, C<substr>, C<tr///>, C<uc>, C<ucfirst>, C<y///>
+C<fc> is available only if the C<"fc"> feature is enabled or if it is
+prefixed with C<CORE::>. The C<"fc"> feature is enabled automatically
+with a C<use v5.16> (or higher) declaration in the current scope.
+
+
=item Regular expressions and pattern matching
X<regular expression> X<regex> X<regexp>
-C<m//>, C<pos>, C<quotemeta>, C<s///>, C<split>, C<study>, C<qr//>
+=for Pod::Functions =Regexp
+C<m//>, C<pos>, C<qr//>, C<quotemeta>, C<s///>, C<split>, C<study>
+
=item Numeric functions
X<numeric> X<number> X<trigonometric> X<trigonometry>
+=for Pod::Functions =Math
+
C<abs>, C<atan2>, C<cos>, C<exp>, C<hex>, C<int>, C<log>, C<oct>, C<rand>,
C<sin>, C<sqrt>, C<srand>
@@ -125,34 +136,51 @@
=item Functions for real @ARRAYs
X<array>
+=for Pod::Functions =ARRAY
+
C<each>, C<keys>, C<pop>, C<push>, C<shift>, C<splice>, C<unshift>, C<values>
=item Functions for list data
X<list>
+=for Pod::Functions =LIST
+
C<grep>, C<join>, C<map>, C<qw//>, C<reverse>, C<sort>, C<unpack>
=item Functions for real %HASHes
X<hash>
+=for Pod::Functions =HASH
+
C<delete>, C<each>, C<exists>, C<keys>, C<values>
=item Input and output functions
X<I/O> X<input> X<output> X<dbm>
+=for Pod::Functions =I/O
+
C<binmode>, C<close>, C<closedir>, C<dbmclose>, C<dbmopen>, C<die>, C<eof>,
C<fileno>, C<flock>, C<format>, C<getc>, C<print>, C<printf>, C<read>,
-C<readdir>, C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>, C<syscall>,
-C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>, C<truncate>,
-C<warn>, C<write>
+C<readdir>, C<readline> C<rewinddir>, C<say>, C<seek>, C<seekdir>, C<select>,
+C<syscall>, C<sysread>, C<sysseek>, C<syswrite>, C<tell>, C<telldir>,
+C<truncate>, C<warn>, C<write>
+C<say> is available only if the C<"say"> feature is enabled or if it is
+prefixed with C<CORE::>. The C<"say"> feature is enabled automatically
+with a C<use v5.10> (or higher) declaration in the current scope.
+
=item Functions for fixed-length data or records
-C<pack>, C<read>, C<syscall>, C<sysread>, C<syswrite>, C<unpack>, C<vec>
+=for Pod::Functions =Binary
+C<pack>, C<read>, C<syscall>, C<sysread>, C<sysseek>, C<syswrite>, C<unpack>,
+C<vec>
+
=item Functions for filehandles, files, or directories
X<file> X<filehandle> X<directory> X<pipe> X<link> X<symlink>
+=for Pod::Functions =File
+
C<-I<X>>, C<chdir>, C<chmod>, C<chown>, C<chroot>, C<fcntl>, C<glob>,
C<ioctl>, C<link>, C<lstat>, C<mkdir>, C<open>, C<opendir>,
C<readlink>, C<rename>, C<rmdir>, C<stat>, C<symlink>, C<sysopen>,
@@ -161,44 +189,65 @@
=item Keywords related to the control flow of your Perl program
X<control flow>
-C<caller>, C<continue>, C<die>, C<do>, C<dump>, C<eval>, C<exit>,
-C<goto>, C<last>, C<next>, C<redo>, C<return>, C<sub>, C<wantarray>
+=for Pod::Functions =Flow
-=item Keywords related to the switch feature
+C<break>, C<caller>, C<continue>, C<die>, C<do>,
+C<dump>, C<eval>, C<evalbytes> C<exit>,
+C<__FILE__>, C<goto>, C<last>, C<__LINE__>, C<next>, C<__PACKAGE__>,
+C<redo>, C<return>, C<sub>, C<__SUB__>, C<wantarray>
-C<break>, C<continue>, C<default, >C<given>, C<when>
+C<break> is available only if you enable the experimental C<"switch">
+feature or use the C<CORE::> prefix. The C<"switch"> feature also enables
+the C<default>, C<given> and C<when> statements, which are documented in
+L<perlsyn/"Switch Statements">. The C<"switch"> feature is enabled
+automatically with a C<use v5.10> (or higher) declaration in the current
+scope. In Perl v5.14 and earlier, C<continue> required the C<"switch">
+feature, like the other keywords.
-These are available only if you enable the C<"switch"> feature.
-See L<feature> and L<perlsyn/"Switch statements">.
-Alternately, include a C<use v5.10> or later to the current scope.
+C<evalbytes> is only available with the C<"evalbytes"> feature (see
+L<feature>) or if prefixed with C<CORE::>. C<__SUB__> is only available
+with the C<"current_sub"> feature or if prefixed with C<CORE::>. Both
+the C<"evalbytes"> and C<"current_sub"> features are enabled automatically
+with a C<use v5.16> (or higher) declaration in the current scope.
=item Keywords related to scoping
+=for Pod::Functions =Namespace
+
C<caller>, C<import>, C<local>, C<my>, C<our>, C<package>, C<state>, C<use>
-C<state> is available only if the C<"state"> feature is enabled. See
-L<feature>. Alternately, include a C<use v5.10> or later to the current scope.
+C<state> is available only if the C<"state"> feature is enabled or if it is
+prefixed with C<CORE::>. The C<"state"> feature is enabled automatically
+with a C<use v5.10> (or higher) declaration in the current scope.
=item Miscellaneous functions
-C<defined>, C<dump>, C<eval>, C<formline>, C<local>, C<my>, C<our>,
-C<reset>, C<scalar>, C<state>, C<undef>, C<wantarray>
+=for Pod::Functions =Misc
+C<defined>, C<formline>, C<lock>, C<prototype>, C<reset>, C<scalar>, C<undef>
+
=item Functions for processes and process groups
X<process> X<pid> X<process id>
+=for Pod::Functions =Process
+
C<alarm>, C<exec>, C<fork>, C<getpgrp>, C<getppid>, C<getpriority>, C<kill>,
-C<pipe>, C<qx//>, C<setpgrp>, C<setpriority>, C<sleep>, C<system>,
+C<pipe>, C<qx//>, C<readpipe>, C<setpgrp>,
+C<setpriority>, C<sleep>, C<system>,
C<times>, C<wait>, C<waitpid>
=item Keywords related to Perl modules
X<module>
+=for Pod::Functions =Modules
+
C<do>, C<import>, C<no>, C<package>, C<require>, C<use>
=item Keywords related to classes and object-orientation
X<object> X<class> X<package>
+=for Pod::Functions =Objects
+
C<bless>, C<dbmclose>, C<dbmopen>, C<package>, C<ref>, C<tie>, C<tied>,
C<untie>, C<use>
@@ -205,6 +254,8 @@
=item Low-level socket functions
X<socket> X<sock>
+=for Pod::Functions =Socket
+
C<accept>, C<bind>, C<connect>, C<getpeername>, C<getsockname>,
C<getsockopt>, C<listen>, C<recv>, C<send>, C<setsockopt>, C<shutdown>,
C<socket>, C<socketpair>
@@ -212,6 +263,8 @@
=item System V interprocess communication functions
X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>
+=for Pod::Functions =SysV
+
C<msgctl>, C<msgget>, C<msgrcv>, C<msgsnd>, C<semctl>, C<semget>, C<semop>,
C<shmctl>, C<shmget>, C<shmread>, C<shmwrite>
@@ -218,6 +271,8 @@
=item Fetching user and group info
X<user> X<group> X<password> X<uid> X<gid> X<passwd> X</etc/passwd>
+=for Pod::Functions =User
+
C<endgrent>, C<endhostent>, C<endnetent>, C<endpwent>, C<getgrent>,
C<getgrgid>, C<getgrnam>, C<getlogin>, C<getpwent>, C<getpwnam>,
C<getpwuid>, C<setgrent>, C<setpwent>
@@ -225,6 +280,8 @@
=item Fetching network info
X<network> X<protocol> X<host> X<hostname> X<IP> X<address> X<service>
+=for Pod::Functions =Network
+
C<endprotoent>, C<endservent>, C<gethostbyaddr>, C<gethostbyname>,
C<gethostent>, C<getnetbyaddr>, C<getnetbyname>, C<getnetent>,
C<getprotobyname>, C<getprotobynumber>, C<getprotoent>,
@@ -234,24 +291,20 @@
=item Time-related functions
X<time> X<date>
+=for Pod::Functions =Time
+
C<gmtime>, C<localtime>, C<time>, C<times>
-=item Functions new in perl5
-X<perl5>
+=item Non-function keywords
-C<abs>, C<bless>, C<break>, C<chomp>, C<chr>, C<continue>, C<default>,
-C<exists>, C<formline>, C<given>, C<glob>, C<import>, C<lc>, C<lcfirst>,
-C<lock>, C<map>, C<my>, C<no>, C<our>, C<prototype>, C<qr//>, C<qw//>, C<qx//>,
-C<readline>, C<readpipe>, C<ref>, C<sub>*, C<sysopen>, C<tie>, C<tied>, C<uc>,
-C<ucfirst>, C<untie>, C<use>, C<when>
+=for Pod::Functions =!Non-functions
-* C<sub> was a keyword in Perl 4, but in Perl 5 it is an
-operator, which can be used in expressions.
+C<and>, C<AUTOLOAD>, C<BEGIN>, C<CHECK>, C<cmp>, C<CORE>, C<__DATA__>,
+C<default>, C<DESTROY>, C<else>, C<elseif>, C<elsif>, C<END>, C<__END__>,
+C<eq>, C<for>, C<foreach>, C<ge>, C<given>, C<gt>, C<if>, C<INIT>, C<le>,
+C<lt>, C<ne>, C<not>, C<or>, C<UNITCHECK>, C<unless>, C<until>, C<when>,
+C<while>, C<x>, C<xor>
-=item Functions obsoleted in perl5
-
-C<dbmclose>, C<dbmopen>
-
=back
=head2 Portability
@@ -298,6 +351,8 @@
=item -X
+=for Pod::Functions a file test (-r, -x, etc)
+
A file test, where X is one of the letters listed below. This unary
operator takes one argument, either a filename, a filehandle, or a dirhandle,
and tests the associated file to see if something is true about it. If the
@@ -339,7 +394,8 @@
-M Script start time minus file modification time, in days.
-A Same for access time.
- -C Same for inode change time (Unix, may differ for other platforms)
+ -C Same for inode change time (Unix, may differ for other
+ platforms)
Example:
@@ -354,8 +410,8 @@
following a minus are interpreted as file tests.
These operators are exempt from the "looks like a function rule" described
-above. That is, an opening parenthesis after the operator does not affect
-how much of the following code constitutes the argument. Put the opening
+above. That is, an opening parenthesis after the operator does not affect
+how much of the following code constitutes the argument. Put the opening
parentheses before the operator to separate it from code that follows (this
applies only to operators with higher precedence than unary operators, of
course):
@@ -386,7 +442,7 @@
access(2) family of system calls. Also note that the C<-x> and C<-X> may
under this pragma return true even if there are no execute permission
bits set (nor any extra execute permission ACLs). This strangeness is
-due to the underlying system calls' definitions. Note also that, due to
+due to the underlying system calls' definitions. Note also that, due to
the implementation of C<use filetest 'access'>, the C<_> special
filehandle won't cache the results of the file tests when this pragma is
in effect. Read the documentation for the C<filetest> pragma for more
@@ -424,17 +480,26 @@
print "Text\n" if -T _;
print "Binary\n" if -B _;
-As of Perl 5.9.1, as a form of purely syntactic sugar, you can stack file
+As of Perl 5.10.0, as a form of purely syntactic sugar, you can stack file
test operators, in a way that C<-f -w -x $file> is equivalent to
-C<-x $file && -w _ && -f _>. (This is only fancy fancy: if you use
+C<-x $file && -w _ && -f _>. (This is only fancy fancy: if you use
the return value of C<-f $file> as an argument to another filetest
operator, no special magic will happen.)
+Portability issues: L<perlport/-X>.
+
+To avoid confusing would-be users of your code with mysterious
+syntax errors, put something like this at the top of your script:
+
+ use 5.010; # so filetest ops can stack
+
=item abs VALUE
X<abs> X<absolute>
=item abs
+=for Pod::Functions absolute value function
+
Returns the absolute value of its argument.
If VALUE is omitted, uses C<$_>.
@@ -441,6 +506,8 @@
=item accept NEWSOCKET,GENERICSOCKET
X<accept>
+=for Pod::Functions accept an incoming socket connect
+
Accepts an incoming socket connect, just as accept(2)
does. Returns the packed address if it succeeded, false otherwise.
See the example in L<perlipc/"Sockets: Client/Server Communication">.
@@ -456,9 +523,11 @@
=item alarm
+=for Pod::Functions schedule a SIGALRM
+
Arranges to have a SIGALRM delivered to this process after the
specified number of wallclock seconds has elapsed. If SECONDS is not
-specified, the value stored in C<$_> is used. (On some machines,
+specified, the value stored in C<$_> is used. (On some machines,
unfortunately, the elapsed time may be up to one second less or more
than you specified because of how seconds are counted, and process
scheduling may delay the delivery of the signal even further.)
@@ -473,7 +542,7 @@
distribution) provides ualarm(). You may also use Perl's four-argument
version of select() leaving the first three arguments undefined, or you
might be able to use the C<syscall> interface to access setitimer(2) if
-your system supports it. See L<perlfaq8> for details.
+your system supports it. See L<perlfaq8> for details.
It is usually a mistake to intermix C<alarm> and C<sleep> calls, because
C<sleep> may be internally implemented on your system with C<alarm>.
@@ -500,9 +569,13 @@
For more information see L<perlipc>.
+Portability issues: L<perlport/alarm>.
+
=item atan2 Y,X
X<atan2> X<arctangent> X<tan> X<tangent>
+=for Pod::Functions arctangent of Y/X in the range -PI to PI
+
Returns the arctangent of Y/X in the range -PI to PI.
For the tangent operation, you may use the C<Math::Trig::tan>
@@ -513,9 +586,13 @@
The return value for C<atan2(0,0)> is implementation-defined; consult
your atan2(3) manpage for more information.
+Portability issues: L<perlport/atan2>.
+
=item bind SOCKET,NAME
X<bind>
+=for Pod::Functions binds an address to a socket
+
Binds a network address to a socket, just as bind(2)
does. Returns true if it succeeded, false otherwise. NAME should be a
packed address of the appropriate type for the socket. See the examples in
@@ -526,6 +603,8 @@
=item binmode FILEHANDLE
+=for Pod::Functions prepare binary files for I/O
+
Arranges for FILEHANDLE to be read or written in "binary" or "text"
mode on systems where the run-time libraries distinguish between
binary and text files. If FILEHANDLE is an expression, the value is
@@ -542,16 +621,16 @@
like images, for example.
If LAYER is present it is a single string, but may contain multiple
-directives. The directives alter the behaviour of the filehandle.
+directives. The directives alter the behaviour of the filehandle.
When LAYER is present, using binmode on a text file makes sense.
If LAYER is omitted or specified as C<:raw> the filehandle is made
-suitable for passing binary data. This includes turning off possible CRLF
+suitable for passing binary data. This includes turning off possible CRLF
translation and marking it as bytes (as opposed to Unicode characters).
Note that, despite what may be implied in I<"Programming Perl"> (the
Camel, 3rd edition) or elsewhere, C<:raw> is I<not> simply the inverse of C<:crlf>.
Other layers that would affect the binary nature of the stream are
-I<also> disabled. See L<PerlIO>, L<perlrun>, and the discussion about the
+I<also> disabled. See L<PerlIO>, L<perlrun>, and the discussion about the
PERLIO environment variable.
The C<:bytes>, C<:crlf>, C<:utf8>, and any other directives of the
@@ -568,7 +647,7 @@
To mark FILEHANDLE as UTF-8, use C<:utf8> or C<:encoding(UTF-8)>.
C<:utf8> just marks the data as UTF-8 without further checking,
while C<:encoding(UTF-8)> checks the data for actually being valid
-UTF-8. More details can be found in L<PerlIO::encoding>.
+UTF-8. More details can be found in L<PerlIO::encoding>.
In general, binmode() should be called after open() but before any I/O
is done on the filehandle. Calling binmode() normally flushes any
@@ -591,7 +670,7 @@
All variants of Unix, Mac OS (old and new), and Stream_LF files on VMS use
a single character to end each line in the external representation of text
(even though that single character is CARRIAGE RETURN on old, pre-Darwin
-flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other
+flavors of Mac OS, and is LINE FEED on Unix and most VMS files). In other
systems like OS/2, DOS, and the various flavors of MS-Windows, your program
sees a C<\n> as a simple C<\cJ>, but what's stored in text files are the
two characters C<\cM\cJ>. That means that if you don't use binmode() on
@@ -612,22 +691,25 @@
in L<perlvar> for how to manually set your input and output
line-termination sequences.
+Portability issues: L<perlport/binmode>.
+
=item bless REF,CLASSNAME
X<bless>
=item bless REF
+=for Pod::Functions create an object
+
This function tells the thingy referenced by REF that it is now an object
in the CLASSNAME package. If CLASSNAME is omitted, the current package
is used. Because a C<bless> is often the last thing in a constructor,
it returns the reference for convenience. Always use the two-argument
version if a derived class might inherit the function doing the blessing.
-See L<perltoot> and L<perlobj> for more about the blessing (and blessings)
-of objects.
+See L<perlobj> for more about the blessing (and blessings) of objects.
Consider always blessing objects in CLASSNAMEs that are mixed case.
Namespaces with all lowercase names are considered reserved for
-Perl pragmata. Builtin types have all uppercase names. To prevent
+Perl pragmata. Builtin types have all uppercase names. To prevent
confusion, you may wish to avoid such package names as well. Make sure
that CLASSNAME is a true value.
@@ -635,11 +717,14 @@
=item break
+=for Pod::Functions +switch break out of a C<given> block
+
Break out of a C<given()> block.
-This keyword is enabled by the C<"switch"> feature: see
-L<feature> for more information. Alternately, include a C<use
-v5.10> or later to the current scope.
+This keyword is enabled by the C<"switch"> feature; see L<feature> for
+more information on C<"switch">. You can also access it by prefixing it
+with C<CORE::>. Alternatively, include a C<use v5.10> or later to the
+current scope.
=item caller EXPR
X<caller> X<call stack> X<stack> X<stack trace>
@@ -646,6 +731,8 @@
=item caller
+=for Pod::Functions get context of the current subroutine call
+
Returns the context of the current subroutine call. In scalar context,
returns the caller's package name if there I<is> a caller (that is, if
we're in a subroutine or C<eval> or C<require>) and the undefined value
@@ -676,14 +763,17 @@
subroutine happens to have been deleted from the symbol table.
C<$hasargs> is true if a new instance of C<@_> was set up for the frame.
C<$hints> and C<$bitmask> contain pragmatic hints that the caller was
-compiled with. The C<$hints> and C<$bitmask> values are subject to change
-between versions of Perl, and are not meant for external use.
+compiled with. C<$hints> corresponds to C<$^H>, and C<$bitmask>
+corresponds to C<${^WARNING_BITS}>. The
+C<$hints> and C<$bitmask> values are subject
+to change between versions of Perl, and are not meant for external use.
C<$hinthash> is a reference to a hash containing the value of C<%^H> when the
-caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
+caller was compiled, or C<undef> if C<%^H> was empty. Do not modify the values
of this hash, as they are the actual values stored in the optree.
-Furthermore, when called from within the DB package, caller returns more
+Furthermore, when called from within the DB package in
+list context, and with an argument, caller returns more
detailed information: it sets the list variable C<@DB::args> to be the
arguments with which the subroutine was invoked.
@@ -694,18 +784,18 @@
previous time C<caller> was called.
Be aware that setting C<@DB::args> is I<best effort>, intended for
-debugging or generating backtraces, and should not be relied upon. In
+debugging or generating backtraces, and should not be relied upon. In
particular, as C<@_> contains aliases to the caller's arguments, Perl does
not take a copy of C<@_>, so C<@DB::args> will contain modifications the
subroutine makes to C<@_> or its contents, not the original values at call
-time. C<@DB::args>, like C<@_>, does not hold explicit references to its
+time. C<@DB::args>, like C<@_>, does not hold explicit references to its
elements, so under certain cases its elements may have become freed and
-reallocated for other variables or temporary values. Finally, a side effect
+reallocated for other variables or temporary values. Finally, a side effect
of the current implementation is that the effects of C<shift @_> can
I<normally> be undone (but not C<pop @_> or other splicing, I<and> not if a
reference to C<@_> has been taken, I<and> subject to the caveat about reallocated
elements), so C<@DB::args> is actually a hybrid of the current state and
-initial state of C<@_>. Buyer beware.
+initial state of C<@_>. Buyer beware.
=item chdir EXPR
X<chdir>
@@ -718,12 +808,14 @@
=item chdir
-Changes the working directory to EXPR, if possible. If EXPR is omitted,
+=for Pod::Functions change your current working directory
+
+Changes the working directory to EXPR, if possible. If EXPR is omitted,
changes to the directory specified by C<$ENV{HOME}>, if set; if not,
-changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
-variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
-neither is set, C<chdir> does nothing. It returns true on success,
-false otherwise. See the example under C<die>.
+changes to the directory specified by C<$ENV{LOGDIR}>. (Under VMS, the
+variable C<$ENV{SYS$LOGIN}> is also checked, and used if it is set.) If
+neither is set, C<chdir> does nothing. It returns true on success,
+false otherwise. See the example under C<die>.
On systems that support fchdir(2), you may pass a filehandle or
directory handle as the argument. On systems that don't support fchdir(2),
@@ -732,6 +824,8 @@
=item chmod LIST
X<chmod> X<permission> X<mode>
+=for Pod::Functions changes the permissions on a list of files
+
Changes the permissions of a list of files. The first element of the
list must be the numeric mode, which should probably be an octal
number, and which definitely should I<not> be a string of octal digits:
@@ -761,6 +855,8 @@
chmod S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH|S_IXOTH, @executables;
# Identical to the chmod 0755 of the example above.
+Portability issues: L<perlport/chmod>.
+
=item chomp VARIABLE
X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>
@@ -768,6 +864,8 @@
=item chomp
+=for Pod::Functions remove a trailing record separator from a string
+
This safer version of L</chop> removes any trailing string
that corresponds to the current value of C<$/> (also known as
$INPUT_RECORD_SEPARATOR in the C<English> module). It returns the total
@@ -810,6 +908,8 @@
=item chop
+=for Pod::Functions remove the last character from a string
+
Chops off the last character of a string and returns the character
chopped. It is much more efficient than C<s/.$//s> because it neither
scans nor copies the string. If VARIABLE is omitted, chops C<$_>.
@@ -828,6 +928,8 @@
=item chown LIST
X<chown> X<owner> X<user> X<group>
+=for Pod::Functions change the ownership on a list of files
+
Changes the owner (and group) of a list of files. The first two
elements of the list must be the I<numeric> uid and gid, in that
order. A value of -1 in either position is interpreted by most
@@ -864,11 +966,15 @@
use POSIX qw(sysconf _PC_CHOWN_RESTRICTED);
$can_chown_giveaway = not sysconf(_PC_CHOWN_RESTRICTED);
+Portability issues: L<perlport/chmod>.
+
=item chr NUMBER
X<chr> X<character> X<ASCII> X<Unicode>
=item chr
+=for Pod::Functions get character this number represents
+
Returns the character represented by that NUMBER in the character set.
For example, C<chr(65)> is C<"A"> in either ASCII or Unicode, and
chr(0x263a) is a Unicode smiley face.
@@ -891,6 +997,8 @@
=item chroot
+=for Pod::Functions make directory new root for path lookups
+
This function works like the system call by the same name: it makes the
named directory the new root directory for all further pathnames that
begin with a C</> by your process and all its children. (It doesn't
@@ -898,11 +1006,15 @@
reasons, this call is restricted to the superuser. If FILENAME is
omitted, does a C<chroot> to C<$_>.
+Portability issues: L<perlport/chroot>.
+
=item close FILEHANDLE
X<close>
=item close
+=for Pod::Functions close file (or pipe or socket) handle
+
Closes the file or pipe associated with the filehandle, flushes the IO
buffers, and closes the system file descriptor. Returns true if those
operations succeed and if no error was reported by any PerlIO
@@ -911,7 +1023,7 @@
You don't have to close FILEHANDLE if you are immediately going to do
another C<open> on it, because C<open> closes it for you. (See
-C<open>.) However, an explicit C<close> on an input file resets the line
+L<open|/open FILEHANDLE>.) However, an explicit C<close> on an input file resets the line
counter (C<$.>), while the implicit close done by C<open> does not.
If the filehandle came from a piped open, C<close> returns false if one of
@@ -948,6 +1060,8 @@
=item closedir DIRHANDLE
X<closedir>
+=for Pod::Functions close directory handle
+
Closes a directory opened by C<opendir> and returns the success of that
system call.
@@ -954,6 +1068,8 @@
=item connect SOCKET,NAME
X<connect>
+=for Pod::Functions connect to a remote socket
+
Attempts to connect to a remote socket, just like connect(2).
Returns true if it succeeded, false otherwise. NAME should be a
packed address of the appropriate type for the socket. See the examples in
@@ -964,7 +1080,10 @@
=item continue
-C<continue> is actually a flow control statement rather than a function. If
+=for Pod::Functions optional trailing block in a while or foreach
+
+When followed by a BLOCK, C<continue> is actually a
+flow control statement rather than a function. If
there is a C<continue> BLOCK attached to a BLOCK (typically in a C<while> or
C<foreach>), it is always executed just before the conditional is about to
be evaluated again, just like the third part of a C<for> loop in C. Thus
@@ -991,10 +1110,12 @@
empty one, logically enough, so C<next> goes directly back
to check the condition at the top of the loop.
-If the C<"switch"> feature is enabled, C<continue> is also a function that
+When there is no BLOCK, C<continue> is a function that
falls through the current C<when> or C<default> block instead of iterating
a dynamically enclosing C<foreach> or exiting a lexically enclosing C<given>.
-See L<feature> and L<perlsyn/"Switch statements"> for more
+In Perl 5.14 and earlier, this form of C<continue> was
+only available when the C<"switch"> feature was enabled.
+See L<feature> and L<perlsyn/"Switch Statements"> for more
information.
=item cos EXPR
@@ -1002,6 +1123,8 @@
=item cos
+=for Pod::Functions cosine function
+
Returns the cosine of EXPR (expressed in radians). If EXPR is omitted,
takes the cosine of C<$_>.
@@ -1014,6 +1137,8 @@
X<crypt> X<digest> X<hash> X<salt> X<plaintext> X<password>
X<decrypt> X<cryptography> X<passwd> X<encrypt>
+=for Pod::Functions one-way passwd-style encryption
+
Creates a digest string exactly like the crypt(3) function in the C
library (assuming that you actually have a version there that has not
been extirpated as a potential munition).
@@ -1046,7 +1171,7 @@
Traditionally the result is a string of 13 bytes: two first bytes of
the salt, followed by 11 bytes from the set C<[./0-9A-Za-z]>, and only
-the first eight bytes of PLAINTEXT mattered. But alternative
+the first eight bytes of PLAINTEXT mattered. But alternative
hashing schemes (like MD5), higher level security schemes (like C2),
and implementations on non-Unix platforms may produce different
strings.
@@ -1089,24 +1214,36 @@
(on that copy). If that works, good. If not, crypt() dies with
C<Wide character in crypt>.
+Portability issues: L<perlport/crypt>.
+
=item dbmclose HASH
X<dbmclose>
+=for Pod::Functions breaks binding on a tied dbm file
+
[This function has been largely superseded by the C<untie> function.]
Breaks the binding between a DBM file and a hash.
+Portability issues: L<perlport/dbmclose>.
+
=item dbmopen HASH,DBNAME,MASK
X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>
-[This function has been largely superseded by the C<tie> function.]
+=for Pod::Functions create binding on a tied dbm file
+[This function has been largely superseded by the
+L<tie|/tie VARIABLE,CLASSNAME,LIST> function.]
+
This binds a dbm(3), ndbm(3), sdbm(3), gdbm(3), or Berkeley DB file to a
hash. HASH is the name of the hash. (Unlike normal C<open>, the first
argument is I<not> a filehandle, even though it looks like one). DBNAME
is the name of the database (without the F<.dir> or F<.pag> extension if
any). If the database does not exist, it is created with protection
-specified by MASK (as modified by the C<umask>). If your system supports
+specified by MASK (as modified by the C<umask>). To prevent creation of
+the database if it doesn't exist, you may specify a MODE
+of 0, and the function will return a false value if it
+can't find an existing database. If your system supports
only the older DBM functions, you may make only one C<dbmopen> call in your
program. In older versions of Perl, if your system had neither DBM nor
ndbm, calling C<dbmopen> produced a fatal error; it now falls back to
@@ -1139,17 +1276,15 @@
dbmopen(%NS_Hist, "$ENV{HOME}/.netscape/history.db")
or die "Can't open netscape history file: $!";
-=item default BLOCK
+Portability issues: L<perlport/dbmopen>.
-Within a C<foreach> or a C<given>, a C<default> BLOCK acts like a C<when>
-that's always true. Only available after Perl 5.10, and only if the
-C<switch> feature has been requested. See L</when>.
-
=item defined EXPR
X<defined> X<undef> X<undefined>
=item defined
+=for Pod::Functions test whether a value, variable, or function is defined
+
Returns a Boolean value telling whether EXPR has a value other than
the undefined value C<undef>. If EXPR is not present, C<$_> is
checked.
@@ -1212,6 +1347,8 @@
=item delete EXPR
X<delete>
+=for Pod::Functions deletes a value from a hash
+
Given an expression that specifies an element or slice of a hash, C<delete>
deletes the specified elements from that hash so that exists() on that element
no longer returns true. Setting a hash element to the undefined value does
@@ -1243,9 +1380,9 @@
of composite types">.
%hash = (foo => 11, bar => 22, baz => 33);
- $scalar = delete $hash{foo}; # $scalar is 11
- $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
- @array = delete @hash{qw(foo bar baz)}; # @array is (undef,undef,33)
+ $scalar = delete $hash{foo}; # $scalar is 11
+ $scalar = delete @hash{qw(foo bar)}; # $scalar is 22
+ @array = delete @hash{qw(foo baz)}; # @array is (undef,33)
The following (inefficiently) deletes all the values of %HASH and @ARRAY:
@@ -1285,10 +1422,12 @@
=item die LIST
X<die> X<throw> X<exception> X<raise> X<$@> X<abort>
-C<die> raises an exception. Inside an C<eval> the error message is stuffed
+=for Pod::Functions raise an exception or bail out
+
+C<die> raises an exception. Inside an C<eval> the error message is stuffed
into C<$@> and the C<eval> is terminated with the undefined value.
If the exception is outside of all enclosing C<eval>s, then the uncaught
-exception prints LIST to C<STDERR> and exits with a non-zero value. If you
+exception prints LIST to C<STDERR> and exits with a non-zero value. If you
need to exit the process with a specific exit code, see L</exit>.
Equivalent examples:
@@ -1338,7 +1477,8 @@
exit 255; # last resort
The intent is to squeeze as much possible information about the likely cause
-into the limited space of the system exit code. However, as C<$!> is the value
+into the limited space of the system exit
+code. However, as C<$!> is the value
of C's C<errno>, which can be set by any system call, this means that the value
of the exit code used by C<die> can be non-predictable, so should not be relied
upon, other than to be non-zero.
@@ -1357,7 +1497,8 @@
eval { ... ; die Some::Module::Exception->new( FOO => "bar" ) };
if (my $ev_err = $@) {
- if (blessed($ev_err) && $ev_err->isa("Some::Module::Exception")) {
+ if (blessed($ev_err)
+ && $ev_err->isa("Some::Module::Exception")) {
# handle Some::Module::Exception
}
else {
@@ -1391,10 +1532,12 @@
=item do BLOCK
X<do> X<block>
+=for Pod::Functions turn a BLOCK into a TERM
+
Not really a function. Returns the value of the last command in the
sequence of commands indicated by BLOCK. When modified by the C<while> or
C<until> loop modifier, executes the BLOCK once before testing the loop
-condition. (On other statements the loop modifiers test the conditional
+condition. (On other statements the loop modifiers test the conditional
first.)
C<do BLOCK> does I<not> count as a loop, so the loop control statements
@@ -1404,8 +1547,8 @@
=item do SUBROUTINE(LIST)
X<do>
-This form of subroutine call is deprecated. SUBROUTINE can be a bareword,
-a scalar variable or a subroutine beginning with C<&>.
+This form of subroutine call is deprecated. SUBROUTINE can be a bareword
+or scalar variable.
=item do EXPR
X<do>
@@ -1415,11 +1558,12 @@
do 'stat.pl';
-is just like
+is largely like
eval `cat stat.pl`;
-except that it's more efficient and concise, keeps track of the current
+except that it's more concise, runs no external processes, keeps track of
+the current
filename for error messages, searches the C<@INC> directories, and updates
C<%INC> if the file is found. See L<perlvar/@INC> and L<perlvar/%INC> for
these variables. It also differs in that code evaluated with C<do FILENAME>
@@ -1454,8 +1598,12 @@
=item dump LABEL
X<dump> X<core> X<undump>
+=item dump EXPR
+
=item dump
+=for Pod::Functions create an immediate core dump
+
This function causes an immediate core dump. See also the B<-u>
command-line switch in L<perlrun>, which does the same thing.
Primarily this is so that you can use the B<undump> program (not
@@ -1464,7 +1612,9 @@
program. When the new binary is executed it will begin by executing
a C<goto LABEL> (with all the restrictions that C<goto> suffers).
Think of it as a goto with an intervening core dump and reincarnation.
-If C<LABEL> is omitted, restarts the program from the top.
+If C<LABEL> is omitted, restarts the program from the top. The
+C<dump EXPR> form, available starting in Perl 5.18.0, allows a name to be
+computed at run time, being otherwise identical to C<dump LABEL>.
B<WARNING>: Any files opened at the time of the dump will I<not>
be open any more when the program is reincarnated, with possible
@@ -1471,10 +1621,17 @@
resulting confusion by Perl.
This function is now largely obsolete, mostly because it's very hard to
-convert a core file into an executable. That's why you should now invoke
+convert a core file into an executable. That's why you should now invoke
it as C<CORE::dump()>, if you don't want to be warned against a possible
typo.
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+C<dump ("foo")."bar"> will cause "bar" to be part of the argument to
+C<dump>.
+
+Portability issues: L<perlport/dump>.
+
=item each HASH
X<each> X<hash, iterator>
@@ -1483,29 +1640,38 @@
=item each EXPR
-When called in list context, returns a 2-element list consisting of the key
-and value for the next element of a hash, or the index and value for the
-next element of an array, so that you can iterate over it. When called in
-scalar context, returns only the key (not the value) in a hash, or the index
-in an array.
+=for Pod::Functions retrieve the next key/value pair from a hash
+When called on a hash in list context, returns a 2-element list
+consisting of the key and value for the next element of a hash. In Perl
+5.12 and later only, it will also return the index and value for the next
+element of an array so that you can iterate over it; older Perls consider
+this a syntax error. When called in scalar context, returns only the key
+(not the value) in a hash, or the index in an array.
+
Hash entries are returned in an apparently random order. The actual random
-order is subject to change in future versions of Perl, but it is
-guaranteed to be in the same order as either the C<keys> or C<values>
-function would produce on the same (unmodified) hash. Since Perl
-5.8.2 the ordering can be different even between different runs of Perl
-for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
After C<each> has returned all entries from the hash or array, the next
call to C<each> returns the empty list in list context and C<undef> in
-scalar context. The next call following that one restarts iteration. Each
-hash or array has its own internal iterator, accessed by C<each>, C<keys>,
-and C<values>. The iterator is implicitly reset when C<each> has reached
-the end as just described; it can be explicitly reset by calling C<keys> or
-C<values> on the hash or array. If you add or delete a hash's elements
-while iterating over it, entries may be skipped or duplicated--so don't do
-that. Exception: It is always safe to delete the item most recently
-returned by C<each()>, so the following code works properly:
+scalar context; the next call following I<that> one restarts iteration.
+Each hash or array has its own internal iterator, accessed by C<each>,
+C<keys>, and C<values>. The iterator is implicitly reset when C<each> has
+reached the end as just described; it can be explicitly reset by calling
+C<keys> or C<values> on the hash or array. If you add or delete a hash's
+elements while iterating over it, entries may be skipped or duplicated--so
+don't do that. Exception: In the current implementation, it is always safe
+to delete the item most recently returned by C<each()>, so the following
+code works properly:
while (($key, $value) = each %hash) {
print $key, "\n";
@@ -1526,6 +1692,22 @@
while (($key,$value) = each $hashref) { ... }
+As of Perl 5.18 you can use a bare C<each> in a C<while> loop,
+which will set C<$_> on every iteration.
+
+ while(each %ENV) {
+ print "$_=$ENV{$_}\n";
+ }
+
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.012; # so keys/values/each work on arrays
+ use 5.014; # so keys/values/each work on scalars (experimental)
+ use 5.018; # so each assigns to $_ in a lone while test
+
See also C<keys>, C<values>, and C<sort>.
=item eof FILEHANDLE
@@ -1537,6 +1719,8 @@
=item eof
+=for Pod::Functions test a filehandle for its end
+
Returns 1 if the next read on FILEHANDLE will return end of file I<or> if
FILEHANDLE is not open. FILEHANDLE may be an expression whose value
gives the real filehandle. (Note that this function actually
@@ -1574,7 +1758,7 @@
print "--------------\n";
}
print;
- last if eof(); # needed if we're reading from a terminal
+ last if eof(); # needed if we're reading from a terminal
}
Practical hint: you almost never need to use C<eof> in Perl, because the
@@ -1589,15 +1773,31 @@
=item eval
+=for Pod::Functions catch exceptions or compile and run code
+
In the first form, the return value of EXPR is parsed and executed as if it
were a little Perl program. The value of the expression (which is itself
determined within scalar context) is first parsed, and if there were no
-errors, executed in the lexical context of the current Perl program, so
-that any variable settings or subroutine and format definitions remain
-afterwards. Note that the value is parsed every time the C<eval> executes.
+errors, executed as a block within the lexical context of the current Perl
+program. This means, that in particular, any outer lexical variables are
+visible to it, and any package variable settings or subroutine and format
+definitions remain afterwards.
+
+Note that the value is parsed every time the C<eval> executes.
If EXPR is omitted, evaluates C<$_>. This form is typically used to
delay parsing and subsequent execution of the text of EXPR until run time.
+If the C<unicode_eval> feature is enabled (which is the default under a
+C<use 5.16> or higher declaration), EXPR or C<$_> is treated as a string of
+characters, so C<use utf8> declarations have no effect, and source filters
+are forbidden. In the absence of the C<unicode_eval> feature, the string
+will sometimes be treated as characters and sometimes as bytes, depending
+on the internal encoding, and source filters activated within the C<eval>
+exhibit the erratic, but historical, behaviour of affecting some outer file
+scope that is still compiling. See also the L</evalbytes> keyword, which
+always treats its input as a byte stream and works properly with source
+filters, and the L<feature> pragma.
+
In the second form, the code within the BLOCK is parsed only once--at the
same time the code surrounding the C<eval> itself was parsed--and executed
within the context of the current Perl program. This form is typically
@@ -1617,12 +1817,12 @@
If there is a syntax error or runtime error, or a C<die> statement is
executed, C<eval> returns C<undef> in scalar context
-or an empty list--or, for syntax errors, a list containing a single
-undefined value--in list context, and C<$@> is set to the error
-message. The discrepancy in the return values in list context is
-considered a bug by some, and will probably be fixed in a future
-release. If there was no error, C<$@> is guaranteed to be the empty
-string. Beware that using C<eval> neither silences Perl from printing
+or an empty list in list context, and C<$@> is set to the error
+message. (Prior to 5.16, a bug caused C<undef> to be returned
+in list context for syntax errors, but not for runtime errors.)
+If there was no error, C<$@> is set to the empty string. A
+control flow operator like C<last> or C<goto> can bypass the setting of
+C<$@>. Beware that using C<eval> neither silences Perl from printing
warnings to STDERR, nor does it stuff the text of warning messages into C<$@>.
To do either of those, you have to use the C<$SIG{__WARN__}> facility, or
turn off warnings inside the BLOCK or EXPR using S<C<no warnings 'all'>>.
@@ -1635,7 +1835,7 @@
If you want to trap errors when loading an XS module, some problems with
the binary interface (such as Perl version skew) may be fatal even with
-C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See L<perlrun>.
+C<eval> unless C<$ENV{PERL_DL_NONLAZY}> is set. See L<perlrun>.
If the code to be executed doesn't vary, you may use the eval-BLOCK
form to trap run-time errors without incurring the penalty of
@@ -1702,7 +1902,7 @@
in case 6.
Before Perl 5.14, the assignment to C<$@> occurred before restoration
-of localised variables, which means that for your code to run on older
+of localized variables, which means that for your code to run on older
versions, a temporary is required if you want to mask some but not all
errors:
@@ -1710,10 +1910,10 @@
{
my $e;
{
- local $@; # protect existing $@
- eval { test_repugnancy() };
- # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
- $@ =~ /nefarious/ and $e = $@;
+ local $@; # protect existing $@
+ eval { test_repugnancy() };
+ # $@ =~ /nefarious/ and die $@; # Perl 5.14 and higher only
+ $@ =~ /nefarious/ and $e = $@;
}
die $e if defined $e
}
@@ -1721,16 +1921,36 @@
C<eval BLOCK> does I<not> count as a loop, so the loop control statements
C<next>, C<last>, or C<redo> cannot be used to leave or restart the block.
-An C<eval ''> executed within the C<DB> package doesn't see the usual
+An C<eval ''> executed within a subroutine defined
+in the C<DB> package doesn't see the usual
surrounding lexical scope, but rather the scope of the first non-DB piece
-of code that called it. You don't normally need to worry about this unless
+of code that called it. You don't normally need to worry about this unless
you are writing a Perl debugger.
+=item evalbytes EXPR
+X<evalbytes>
+
+=item evalbytes
+
+=for Pod::Functions +evalbytes similar to string eval, but intend to parse a bytestream
+
+This function is like L</eval> with a string argument, except it always
+parses its argument, or C<$_> if EXPR is omitted, as a string of bytes. A
+string containing characters whose ordinal value exceeds 255 results in an
+error. Source filters activated within the evaluated code apply to the
+code itself.
+
+This function is only available under the C<evalbytes> feature, a
+C<use v5.16> (or higher) declaration, or with a C<CORE::> prefix. See
+L<feature> for more information.
+
=item exec LIST
X<exec> X<execute>
=item exec PROGRAM LIST
+=for Pod::Functions abandon this program to run another
+
The C<exec> function executes a system command I<and never returns>;
use C<system> instead of C<exec> if you want it to return. It fails and
returns false only if the command does not exist I<and> it is executed
@@ -1737,10 +1957,10 @@
directly instead of via your system's command shell (see below).
Since it's a common mistake to use C<exec> instead of C<system>, Perl
-warns you if there is a following statement that isn't C<die>, C<warn>,
-or C<exit> (if C<-w> is set--but you always do that, right?). If you
-I<really> want to follow an C<exec> with some other statement, you
-can use one of these styles to avoid the warning:
+warns you if C<exec> is called in void context and if there is a following
+statement that isn't C<die>, C<warn>, or C<exit> (if C<-w> is set--but
+you always do that, right?). If you I<really> want to follow an C<exec>
+with some other statement, you can use one of these styles to avoid the warning:
exec ('foo') or print STDERR "couldn't exec foo: $!";
{ exec ('foo') }; print STDERR "couldn't exec foo: $!";
@@ -1793,18 +2013,22 @@
it tried to run a program named I<"echo surprise">, didn't find it, and set
C<$?> to a non-zero value indicating failure.
-Beginning with v5.6.0, Perl attempts to flush all files opened for
-output before the exec, but this may not be supported on some platforms
-(see L<perlport>). To be safe, you may need to set C<$|> ($AUTOFLUSH
-in English) or call the C<autoflush()> method of C<IO::Handle> on any
-open handles to avoid lost output.
+Perl attempts to flush all files opened for output before the exec,
+but this may not be supported on some platforms (see L<perlport>).
+To be safe, you may need to set C<$|> ($AUTOFLUSH in English) or
+call the C<autoflush()> method of C<IO::Handle> on any open handles
+to avoid lost output.
Note that C<exec> will not call your C<END> blocks, nor will it invoke
C<DESTROY> methods on your objects.
+Portability issues: L<perlport/exec>.
+
=item exists EXPR
X<exists> X<autovivification>
+=for Pod::Functions test whether a hash key is present
+
Given an expression that specifies an element of a hash, returns true if the
specified element in the hash has ever been initialized, even if the
corresponding value is undefined.
@@ -1847,7 +2071,7 @@
if (exists &{$ref->{A}{B}{$key}}) { }
-Although the mostly deeply nested array or hash will not spring into
+Although the most deeply nested array or hash element will not spring into
existence just because its existence was tested, any intervening ones will.
Thus C<< $ref->{"A"} >> and C<< $ref->{"A"}->{"B"} >> will spring
into existence due to the existence test for the $key element above.
@@ -1872,6 +2096,8 @@
=item exit
+=for Pod::Functions terminate this program
+
Evaluates EXPR and exits immediately with that value. Example:
$ans = <STDIN>;
@@ -1892,21 +2118,79 @@
defined C<END> routines first, but these C<END> routines may not
themselves abort the exit. Likewise any object destructors that need to
be called are called before the real exit. C<END> routines and destructors
-can change the exit status by modifying C<$?>. If this is a problem, you
-can call C<POSIX:_exit($status)> to avoid END and destructor processing.
+can change the exit status by modifying C<$?>. If this is a problem, you
+can call C<POSIX::_exit($status)> to avoid END and destructor processing.
See L<perlmod> for details.
+Portability issues: L<perlport/exit>.
+
=item exp EXPR
X<exp> X<exponential> X<antilog> X<antilogarithm> X<e>
=item exp
+=for Pod::Functions raise I<e> to a power
+
Returns I<e> (the natural logarithm base) to the power of EXPR.
If EXPR is omitted, gives C<exp($_)>.
+=item fc EXPR
+X<fc> X<foldcase> X<casefold> X<fold-case> X<case-fold>
+
+=item fc
+
+=for Pod::Functions +fc return casefolded version of a string
+
+Returns the casefolded version of EXPR. This is the internal function
+implementing the C<\F> escape in double-quoted strings.
+
+Casefolding is the process of mapping strings to a form where case
+differences are erased; comparing two strings in their casefolded
+form is effectively a way of asking if two strings are equal,
+regardless of case.
+
+Roughly, if you ever found yourself writing this
+
+ lc($this) eq lc($that) # Wrong!
+ # or
+ uc($this) eq uc($that) # Also wrong!
+ # or
+ $this =~ /^\Q$that\E\z/i # Right!
+
+Now you can write
+
+ fc($this) eq fc($that)
+
+And get the correct results.
+
+Perl only implements the full form of casefolding,
+but you can access the simple folds using L<Unicode::UCD/casefold()> and
+L<Unicode::UCD/prop_invmap()>.
+For further information on casefolding, refer to
+the Unicode Standard, specifically sections 3.13 C<Default Case Operations>,
+4.2 C<Case-Normative>, and 5.18 C<Case Mappings>,
+available at L<http://www.unicode.org/versions/latest/>, as well as the
+Case Charts available at L<http://www.unicode.org/charts/case/>.
+
+If EXPR is omitted, uses C<$_>.
+
+This function behaves the same way under various pragma, such as in a locale,
+as L</lc> does.
+
+While the Unicode Standard defines two additional forms of casefolding,
+one for Turkic languages and one that never maps one character into multiple
+characters, these are not provided by the Perl core; However, the CPAN module
+C<Unicode::Casing> may be used to provide an implementation.
+
+This keyword is available only when the C<"fc"> feature is enabled,
+or when prefixed with C<CORE::>; See L<feature>. Alternately,
+include a C<use v5.16> or later to the current scope.
+
=item fcntl FILEHANDLE,FUNCTION,SCALAR
X<fcntl>
+=for Pod::Functions file control system call
+
Implements the fcntl(2) function. You'll probably have to say
use Fcntl;
@@ -1941,9 +2225,20 @@
$flags = fcntl(REMOTE, F_SETFL, $flags | O_NONBLOCK)
or die "Can't set flags for the socket: $!\n";
+Portability issues: L<perlport/fcntl>.
+
+=item __FILE__
+X<__FILE__>
+
+=for Pod::Functions the name of the current source file
+
+A special token that returns the name of the file in which it occurs.
+
=item fileno FILEHANDLE
X<fileno>
+=for Pod::Functions return file descriptor from filehandle
+
Returns the file descriptor for a filehandle, or undefined if the
filehandle is not open. If there is no real file descriptor at the OS
level, as can happen with filehandles connected to memory objects via
@@ -1964,6 +2259,8 @@
=item flock FILEHANDLE,OPERATION
X<flock> X<lock> X<locking>
+=for Pod::Functions lock an entire file with an advisory lock
+
Calls flock(2), or an emulation of it, on FILEHANDLE. Returns true
for success, false on failure. Produces a fatal error if used on a
machine that doesn't implement flock(2), fcntl(2) locking, or lockf(3).
@@ -2013,7 +2310,8 @@
Here's a mailbox appender for BSD systems.
- use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants
+ # import LOCK_* and SEEK_END constants
+ use Fcntl qw(:flock SEEK_END);
sub lock {
my ($fh) = @_;
@@ -2041,9 +2339,13 @@
See also L<DB_File> for other flock() examples.
+Portability issues: L<perlport/flock>.
+
=item fork
X<fork> X<child> X<parent>
+=for Pod::Functions create a new process just like this one
+
Does a fork(2) system call to create a new process running the
same program at the same point. It returns the child pid to the
parent process, C<0> to the child process, or C<undef> if the fork is
@@ -2053,7 +2355,7 @@
example, using copy-on-write technology on data pages), making it the
dominant paradigm for multitasking over the last few decades.
-Beginning with v5.6.0, Perl attempts to flush all files opened for
+Perl attempts to flush all files opened for
output before forking the child process, but this may not be supported
on some platforms (see L<perlport>). To be safe, you may need to set
C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
@@ -2070,9 +2372,20 @@
backgrounded job launched from a remote shell) won't think you're done.
You should reopen those to F</dev/null> if it's any issue.
+On some platforms such as Windows, where the fork() system call is not available,
+Perl can be built to emulate fork() in the Perl interpreter.
+The emulation is designed, at the level of the Perl program,
+to be as compatible as possible with the "Unix" fork().
+However it has limitations that have to be considered in code intended to be portable.
+See L<perlfork> for more details.
+
+Portability issues: L<perlport/fork>.
+
=item format
X<format>
+=for Pod::Functions declare a picture format with use by the write() function
+
Declare a picture format for use by the C<write> function. For
example:
@@ -2091,6 +2404,8 @@
=item formline PICTURE,LIST
X<formline>
+=for Pod::Functions internal function used for formats
+
This is an internal function used by C<format>s, though you may call it,
too. It formats (see L<perlform>) a list of values according to the
contents of PICTURE, placing the output into the format output
@@ -2117,6 +2432,8 @@
=item getc
+=for Pod::Functions get the next character from the filehandle
+
Returns the next character from the input file attached to FILEHANDLE,
or the undefined value at end of file or if there was an error (in
the latter case C<$!> is set). If FILEHANDLE is omitted, reads from
@@ -2152,6 +2469,8 @@
=item getlogin
X<getlogin> X<login>
+=for Pod::Functions return who logged in at this tty
+
This implements the C library function of the same name, which on most
systems returns the current login from F</etc/utmp>, if any. If it
returns the empty string, use C<getpwuid>.
@@ -2161,9 +2480,13 @@
Do not consider C<getlogin> for authentication: it is not as
secure as C<getpwuid>.
+Portability issues: L<perlport/getlogin>.
+
=item getpeername SOCKET
X<getpeername> X<peer>
+=for Pod::Functions find the other end of a socket connection
+
Returns the packed sockaddr address of the other end of the SOCKET
connection.
@@ -2176,6 +2499,8 @@
=item getpgrp PID
X<getpgrp> X<group>
+=for Pod::Functions get process group
+
Returns the current process group for the specified PID. Use
a PID of C<0> to get the current process group for the
current process. Will raise an exception if used on a machine that
@@ -2183,25 +2508,34 @@
group of the current process. Note that the POSIX version of C<getpgrp>
does not accept a PID argument, so only C<PID==0> is truly portable.
+Portability issues: L<perlport/getpgrp>.
+
=item getppid
X<getppid> X<parent> X<pid>
+=for Pod::Functions get parent process ID
+
Returns the process id of the parent process.
-Note for Linux users: on Linux, the C functions C<getpid()> and
-C<getppid()> return different values from different threads. In order to
-be portable, this behavior is not reflected by the Perl-level function
-C<getppid()>, that returns a consistent value across threads. If you want
-to call the underlying C<getppid()>, you may use the CPAN module
-C<Linux::Pid>.
+Note for Linux users: Between v5.8.1 and v5.16.0 Perl would work
+around non-POSIX thread semantics the minority of Linux systems (and
+Debian GNU/kFreeBSD systems) that used LinuxThreads, this emulation
+has since been removed. See the documentation for L<$$|perlvar/$$> for
+details.
+Portability issues: L<perlport/getppid>.
+
=item getpriority WHICH,WHO
X<getpriority> X<priority> X<nice>
+=for Pod::Functions get current nice value
+
Returns the current priority for a process, a process group, or a user.
-(See C<getpriority(2)>.) Will raise a fatal exception if used on a
+(See L<getpriority(2)>.) Will raise a fatal exception if used on a
machine that doesn't implement getpriority(2).
+Portability issues: L<perlport/getpriority>.
+
=item getpwnam NAME
X<getpwnam> X<getgrnam> X<gethostbyname> X<getnetbyname> X<getprotobyname>
X<getpwuid> X<getgrgid> X<getservbyname> X<gethostbyaddr> X<getnetbyaddr>
@@ -2210,64 +2544,124 @@
X<setnetent> X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
X<endnetent> X<endprotoent> X<endservent>
+=for Pod::Functions get passwd record given user login name
+
=item getgrnam NAME
+=for Pod::Functions get group record given group name
+
=item gethostbyname NAME
+=for Pod::Functions get host record given name
+
=item getnetbyname NAME
+=for Pod::Functions get networks record given name
+
=item getprotobyname NAME
+=for Pod::Functions get protocol record given name
+
=item getpwuid UID
+=for Pod::Functions get passwd record given user ID
+
=item getgrgid GID
+=for Pod::Functions get group record given group user ID
+
=item getservbyname NAME,PROTO
+=for Pod::Functions get services record given its name
+
=item gethostbyaddr ADDR,ADDRTYPE
+=for Pod::Functions get host record given its address
+
=item getnetbyaddr ADDR,ADDRTYPE
+=for Pod::Functions get network record given its address
+
=item getprotobynumber NUMBER
+=for Pod::Functions get protocol record numeric protocol
+
=item getservbyport PORT,PROTO
+=for Pod::Functions get services record given numeric port
+
=item getpwent
+=for Pod::Functions get next passwd record
+
=item getgrent
+=for Pod::Functions get next group record
+
=item gethostent
+=for Pod::Functions get next hosts record
+
=item getnetent
+=for Pod::Functions get next networks record
+
=item getprotoent
+=for Pod::Functions get next protocols record
+
=item getservent
+=for Pod::Functions get next services record
+
=item setpwent
+=for Pod::Functions prepare passwd file for use
+
=item setgrent
+=for Pod::Functions prepare group file for use
+
=item sethostent STAYOPEN
+=for Pod::Functions prepare hosts file for use
+
=item setnetent STAYOPEN
+=for Pod::Functions prepare networks file for use
+
=item setprotoent STAYOPEN
+=for Pod::Functions prepare protocols file for use
+
=item setservent STAYOPEN
+=for Pod::Functions prepare services file for use
+
=item endpwent
+=for Pod::Functions be done using passwd file
+
=item endgrent
+=for Pod::Functions be done using group file
+
=item endhostent
+=for Pod::Functions be done using hosts file
+
=item endnetent
+=for Pod::Functions be done using networks file
+
=item endprotoent
+=for Pod::Functions be done using protocols file
+
=item endservent
+=for Pod::Functions be done using services file
+
These routines are the same as their counterparts in the
system C library. In list context, the return values from the
various get routines are as follows:
@@ -2354,9 +2748,16 @@
$ip_address = inet_ntoa($packed_ip);
}
-Make sure <gethostbyname()> is called in SCALAR context and that
+Make sure C<gethostbyname()> is called in SCALAR context and that
its return value is checked for definedness.
+The C<getprotobynumber> function, even though it only takes one argument,
+has the precedence of a list operator, so beware:
+
+ getprotobynumber $number eq 'icmp' # WRONG
+ getprotobynumber($number eq 'icmp') # actually means this
+ getprotobynumber($number) eq 'icmp' # better this way
+
If you get tired of remembering which element of the return list
contains which return value, by-name interfaces are provided
in standard modules: C<File::stat>, C<Net::hostent>, C<Net::netent>,
@@ -2373,9 +2774,13 @@
they aren't, because a C<File::stat> object is different from
a C<User::pwent> object.
+Portability issues: L<perlport/getpwnam> to L<perlport/endservent>.
+
=item getsockname SOCKET
X<getsockname>
+=for Pod::Functions retrieve the sockaddr for a given socket
+
Returns the packed sockaddr address of this end of the SOCKET connection,
in case you don't know the address because you have several different
IPs that the connection might have come in on.
@@ -2390,18 +2795,20 @@
=item getsockopt SOCKET,LEVEL,OPTNAME
X<getsockopt>
+=for Pod::Functions get socket options on a given socket
+
Queries the option named OPTNAME associated with SOCKET at a given LEVEL.
Options may exist at multiple protocol levels depending on the socket
type, but at least the uppermost socket level SOL_SOCKET (defined in the
-C<Socket> module) will exist. To query options at another level the
+C<Socket> module) will exist. To query options at another level the
protocol number of the appropriate protocol controlling the option
-should be supplied. For example, to indicate that an option is to be
+should be supplied. For example, to indicate that an option is to be
interpreted by the TCP protocol, LEVEL should be set to the protocol
number of TCP, which you can get using C<getprotobyname>.
The function returns a packed string representing the requested socket
option, or C<undef> on error, with the reason for the error placed in
-C<$!>. Just what is in the packed string depends on LEVEL and OPTNAME;
+C<$!>. Just what is in the packed string depends on LEVEL and OPTNAME;
consult getsockopt(2) for details. A common case is that the option is an
integer, in which case the result is a packed integer, which you can decode
using C<unpack> with the C<i> (or C<I>) format.
@@ -2416,43 +2823,23 @@
my $packed = getsockopt($socket, $tcp, TCP_NODELAY)
or die "getsockopt TCP_NODELAY: $!";
my $nodelay = unpack("I", $packed);
- print "Nagle's algorithm is turned ", $nodelay ? "off\n" : "on\n";
+ print "Nagle's algorithm is turned ",
+ $nodelay ? "off\n" : "on\n";
+Portability issues: L<perlport/getsockopt>.
-=item given EXPR BLOCK
-X<given>
-
-=item given BLOCK
-
-C<given> is analogous to the C<switch> keyword in other languages. C<given>
-and C<when> are used in Perl to implement C<switch>/C<case> like statements.
-Only available after Perl 5.10. For example:
-
- use v5.10;
- given ($fruit) {
- when (/apples?/) {
- print "I like apples."
- }
- when (/oranges?/) {
- print "I don't like oranges."
- }
- default {
- print "I don't like anything"
- }
- }
-
-See L<perlsyn/"Switch statements"> for detailed information.
-
=item glob EXPR
X<glob> X<wildcard> X<filename, expansion> X<expand>
=item glob
+=for Pod::Functions expand filenames using wildcards
+
In list context, returns a (possibly empty) list of filename expansions on
-the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
+the value of EXPR such as the standard Unix shell F</bin/csh> would do. In
scalar context, glob iterates through such filename expansions, returning
-undef when the list is exhausted. This is the internal function
-implementing the C<< <*.c> >> operator, but you can use it directly. If
+undef when the list is exhausted. This is the internal function
+implementing the C<< <*.c> >> operator, but you can use it directly. If
EXPR is omitted, C<$_> is used. The C<< <*.c> >> operator is discussed in
more detail in L<perlop/"I/O Operators">.
@@ -2460,7 +2847,20 @@
each segment as separate pattern. As such, C<glob("*.c *.h")>
matches all files with a F<.c> or F<.h> extension. The expression
C<glob(".* *")> matches all files in the current working directory.
+If you want to glob filenames that might contain whitespace, you'll
+have to use extra quotes around the spacey filename to protect it.
+For example, to glob filenames that have an C<e> followed by a space
+followed by an C<f>, use either of:
+ @spacies = <"*e f*">;
+ @spacies = glob '"*e f*"';
+ @spacies = glob q("*e f*");
+
+If you had to get a variable through, you could do this:
+
+ @spacies = glob "'*${var}e f*'";
+ @spacies = glob qq("*${var}e f*");
+
If non-empty braces are the only wildcard characters used in the
C<glob>, no filenames are matched, but potentially many strings
are returned. For example, this produces nine strings, one for
@@ -2468,16 +2868,20 @@
@many = glob "{apple,tomato,cherry}={green,yellow,red}";
-Beginning with v5.6.0, this operator is implemented using the standard
+This operator is implemented using the standard
C<File::Glob> extension. See L<File::Glob> for details, including
C<bsd_glob> which does not treat whitespace as a pattern separator.
+Portability issues: L<perlport/glob>.
+
=item gmtime EXPR
X<gmtime> X<UTC> X<Greenwich>
=item gmtime
-Works just like L<localtime> but the returned values are
+=for Pod::Functions convert UNIX time into record or string using Greenwich time
+
+Works just like L</localtime> but the returned values are
localized for the standard Greenwich time zone.
Note: When called in list context, $isdst, the last value
@@ -2484,7 +2888,7 @@
returned by gmtime, is always C<0>. There is no
Daylight Saving Time in GMT.
-See L<perlport/gmtime> for portability concerns.
+Portability issues: L<perlport/gmtime>.
=item goto LABEL
X<goto> X<jump> X<jmp>
@@ -2493,8 +2897,10 @@
=item goto &NAME
+=for Pod::Functions create spaghetti code
+
The C<goto-LABEL> form finds the statement labeled with LABEL and
-resumes execution there. It can't be used to get out of a block or
+resumes execution there. It can't be used to get out of a block or
subroutine given to C<sort>. It can be used to go almost anywhere
else within the dynamic scope, including out of subroutines, but it's
usually better to use some other construct such as C<last> or C<die>.
@@ -2510,8 +2916,10 @@
goto ("FOO", "BAR", "GLARCH")[$i];
As shown in this example, C<goto-EXPR> is exempt from the "looks like a
-function" rule. A pair of parentheses following it does not (necessarily)
-delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
+function" rule. A pair of parentheses following it does not (necessarily)
+delimit its argument. C<goto("NE")."XT"> is equivalent to C<goto NEXT>.
+Also, unlike most named operators, this has the same precedence as
+assignment.
Use of C<goto-LABEL> or C<goto-EXPR> to jump into a construct is
deprecated and will issue a warning. Even then, it may not be used to
@@ -2540,6 +2948,8 @@
=item grep EXPR,LIST
+=for Pod::Functions locate elements in a list test true against a given criterion
+
This is similar in spirit to, but not the same as, grep(1) and its
relatives. In particular, it is not limited to using regular expressions.
@@ -2564,7 +2974,8 @@
This is usually something to be avoided when writing clear code.
If C<$_> is lexical in the scope where the C<grep> appears (because it has
-been declared with C<my $_>) then, in addition to being locally aliased to
+been declared with the deprecated C<my $_> construct)
+then, in addition to being locally aliased to
the list elements, C<$_> keeps being lexical inside the block; i.e., it
can't be seen from the outside, avoiding any potential side-effects.
@@ -2575,6 +2986,8 @@
=item hex
+=for Pod::Functions convert a string to a hexadecimal number
+
Interprets EXPR as a hex string and returns the corresponding value.
(To convert strings that might start with either C<0>, C<0x>, or C<0b>, see
L</oct>.) If EXPR is omitted, uses C<$_>.
@@ -2584,12 +2997,14 @@
Hex strings may only represent integers. Strings that would cause
integer overflow trigger a warning. Leading whitespace is not stripped,
-unlike oct(). To present something as hex, look into L</printf>,
+unlike oct(). To present something as hex, look into L</printf>,
L</sprintf>, and L</unpack>.
=item import LIST
X<import>
+=for Pod::Functions patch a module's namespace into your own
+
There is no builtin C<import> function. It is just an ordinary
method (subroutine) defined (or inherited) by modules that wish to export
names to another module. The C<use> function calls the C<import> method
@@ -2600,6 +3015,8 @@
=item index STR,SUBSTR
+=for Pod::Functions find a substring within a string
+
The index function searches for one string within another, but without
the wildcard-like behavior of a full regular-expression pattern match.
It returns the position of the first occurrence of SUBSTR in STR at
@@ -2606,9 +3023,8 @@
or after POSITION. If POSITION is omitted, starts searching from the
beginning of the string. POSITION before the beginning of the string
or after its end is treated as if it were the beginning or the end,
-respectively. POSITION and the return value are based at C<0> (or whatever
-you've set the C<$[> variable to--but don't do that). If the substring
-is not found, C<index> returns one less than the base, ordinarily C<-1>.
+respectively. POSITION and the return value are based at zero.
+If the substring is not found, C<index> returns -1.
=item int EXPR
X<int> X<integer> X<truncate> X<trunc> X<floor>
@@ -2615,6 +3031,8 @@
=item int
+=for Pod::Functions get the integer portion of a number
+
Returns the integer portion of EXPR. If EXPR is omitted, uses C<$_>.
You should not use this function for rounding: one because it truncates
towards C<0>, and two because machine representations of floating-point
@@ -2627,9 +3045,12 @@
=item ioctl FILEHANDLE,FUNCTION,SCALAR
X<ioctl>
+=for Pod::Functions system-dependent device control system call
+
Implements the ioctl(2) function. You'll probably first have to say
- require "sys/ioctl.ph"; # probably in $Config{archlib}/sys/ioctl.ph
+ require "sys/ioctl.ph"; # probably in
+ # $Config{archlib}/sys/ioctl.ph
to get the correct function definitions. If F<sys/ioctl.ph> doesn't
exist or doesn't have the correct definitions you'll have to roll your
@@ -2661,9 +3082,13 @@
The special string C<"0 but true"> is exempt from B<-w> complaints
about improper numeric conversions.
+Portability issues: L<perlport/ioctl>.
+
=item join EXPR,LIST
X<join>
+=for Pod::Functions join a list into a string using a separator
+
Joins the separate strings of LIST into a single string with fields
separated by the value of EXPR, and returns that new string. Example:
@@ -2679,19 +3104,27 @@
=item keys EXPR
-Returns a list consisting of all the keys of the named hash, or the indices
-of an array. (In scalar context, returns the number of keys or indices.)
+=for Pod::Functions retrieve list of indices from a hash
-The keys of a hash are returned in an apparently random order. The actual
-random order is subject to change in future versions of Perl, but it
-is guaranteed to be the same order as either the C<values> or C<each>
-function produces (given that the hash has not been modified). Since
-Perl 5.8.1 the ordering can be different even between different runs of
-Perl for security reasons (see L<perlsec/"Algorithmic Complexity
-Attacks">).
+Called in list context, returns a list consisting of all the keys of the
+named hash, or in Perl 5.12 or later only, the indices of an array. Perl
+releases prior to 5.12 will produce a syntax error if you try to use an
+array argument. In scalar context, returns the number of keys or indices.
-As a side effect, calling keys() resets the internal interator of the HASH or ARRAY
-(see L</each>). In particular, calling keys() in void context resets
+Hash entries are returned in an apparently random order. The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
+
+As a side effect, calling keys() resets the internal iterator of the HASH or
+ARRAY (see L</each>). In particular, calling keys() in void context resets
the iterator with no other overhead.
Here is yet another way to print your environment:
@@ -2731,7 +3164,7 @@
%hash> if you want to free the storage while C<%hash> is still in scope.
You can't shrink the number of buckets allocated for the hash using
C<keys> in this way (but you needn't worry about doing this by accident,
-as trying has no effect). C<keys @array> in an lvalue context is a syntax
+as trying has no effect). C<keys @array> in an lvalue context is a syntax
error.
Starting with Perl 5.14, C<keys> can take a scalar EXPR, which must contain
@@ -2742,43 +3175,92 @@
for (keys $hashref) { ... }
for (keys $obj->get_arrayref) { ... }
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.012; # so keys/values/each work on arrays
+ use 5.014; # so keys/values/each work on scalars (experimental)
+
See also C<each>, C<values>, and C<sort>.
=item kill SIGNAL, LIST
+
+=item kill SIGNAL
X<kill> X<signal>
+=for Pod::Functions send a signal to a process or process group
+
Sends a signal to a list of processes. Returns the number of
processes successfully signaled (which is not necessarily the
same as the number actually killed).
- $cnt = kill 1, $child1, $child2;
- kill 9, @goners;
+ $cnt = kill 'HUP', $child1, $child2;
+ kill 'KILL', @goners;
-If SIGNAL is zero, no signal is sent to the process, but C<kill>
-checks whether it's I<possible> to send a signal to it (that
-means, to be brief, that the process is owned by the same user, or we are
+SIGNAL may be either a signal name (a string) or a signal number. A signal
+name may start with a C<SIG> prefix, thus C<FOO> and C<SIGFOO> refer to the
+same signal. The string form of SIGNAL is recommended for portability because
+the same signal may have different numbers in different operating systems.
+
+A list of signal names supported by the current platform can be found in
+C<$Config{sig_name}>, which is provided by the C<Config> module. See L<Config>
+for more details.
+
+A negative signal name is the same as a negative signal number, killing process
+groups instead of processes. For example, C<kill '-KILL', $pgrp> and
+C<kill -9, $pgrp> will send C<SIGKILL> to the entire process group specified. That
+means you usually want to use positive not negative signals.
+
+If SIGNAL is either the number 0 or the string C<ZERO> (or C<SIGZZERO>),
+no signal is sent to
+the process, but C<kill> checks whether it's I<possible> to send a signal to it
+(that means, to be brief, that the process is owned by the same user, or we are
the super-user). This is useful to check that a child process is still
alive (even if only as a zombie) and hasn't changed its UID. See
L<perlport> for notes on the portability of this construct.
-Unlike in the shell, if SIGNAL is negative, it kills process groups instead
-of processes. That means you usually want to use positive not negative signals.
-You may also use a signal name in quotes.
-
The behavior of kill when a I<PROCESS> number is zero or negative depends on
the operating system. For example, on POSIX-conforming systems, zero will
-signal the current process group and -1 will signal all processes.
+signal the current process group, -1 will signal all processes, and any
+other negative PROCESS number will act as a negative signal number and
+kill the entire process group specified.
+If both the SIGNAL and the PROCESS are negative, the results are undefined.
+A warning may be produced in a future version.
+
See L<perlipc/"Signals"> for more details.
+On some platforms such as Windows where the fork() system call is not available.
+Perl can be built to emulate fork() at the interpreter level.
+This emulation has limitations related to kill that have to be considered,
+for code running on Windows and in code intended to be portable.
+
+See L<perlfork> for more details.
+
+If there is no I<LIST> of processes, no signal is sent, and the return
+value is 0. This form is sometimes used, however, because it causes
+tainting checks to be run. But see
+L<perlsec/Laundering and Detecting Tainted Data>.
+
+Portability issues: L<perlport/kill>.
+
=item last LABEL
X<last> X<break>
+=item last EXPR
+
=item last
+=for Pod::Functions exit a block prematurely
+
The C<last> command is like the C<break> statement in C (as used in
loops); it immediately exits the loop in question. If the LABEL is
-omitted, the command refers to the innermost enclosing loop. The
+omitted, the command refers to the innermost enclosing
+loop. The C<last EXPR> form, available starting in Perl
+5.18.0, allows a label name to be computed at run time,
+and is otherwise identical to C<last LABEL>. The
C<continue> block, if any, is not executed:
LINE: while (<STDIN>) {
@@ -2797,11 +3279,18 @@
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+C<last ("foo")."bar"> will cause "bar" to be part of the argument to
+C<last>.
+
=item lc EXPR
X<lc> X<lowercase>
=item lc
+=for Pod::Functions return lower-case version of a string
+
Returns a lowercased version of EXPR. This is the internal function
implementing the C<\L> escape in double-quoted strings.
@@ -2813,57 +3302,47 @@
=item If C<use bytes> is in effect:
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
-
-=item On ASCII platforms
-
The results follow ASCII semantics. Only characters C<A-Z> change, to C<a-z>
respectively.
-=back
+=item Otherwise, if C<use locale> (but not C<use locale ':not_characters'>) is in effect:
-=item Otherwise, If EXPR has the UTF8 flag set
+Respects current LC_CTYPE locale for code points < 256; and uses Unicode
+semantics for the remaining code points (this last can only happen if
+the UTF8 flag is also set). See L<perllocale>.
-If the current package has a subroutine named C<ToLower>, it will be used to
-change the case
-(See L<perlunicode/"User-Defined Case Mappings (for serious hackers only)">.)
-Otherwise Unicode semantics are used for the case change.
+A deficiency in this is that case changes that cross the 255/256
+boundary are not well-defined. For example, the lower case of LATIN CAPITAL
+LETTER SHARP S (U+1E9E) in Unicode semantics is U+00DF (on ASCII
+platforms). But under C<use locale>, the lower case of U+1E9E is
+itself, because 0xDF may not be LATIN SMALL LETTER SHARP S in the
+current locale, and Perl has no way of knowing if that character even
+exists in the locale, much less what code point it is. Perl returns
+the input character unchanged, for all instances (and there aren't
+many) where the 255/256 boundary would otherwise be crossed.
-=item Otherwise, if C<use locale> is in effect
+=item Otherwise, If EXPR has the UTF8 flag set:
-Respects current LC_CTYPE locale. See L<perllocale>.
+Unicode semantics are used for the case change.
-=item Otherwise, if C<use feature 'unicode_strings'> is in effect:
+=item Otherwise, if C<use feature 'unicode_strings'> or C<use locale ':not_characters'> is in effect:
-Unicode semantics are used for the case change. Any subroutine named
-C<ToLower> will be ignored.
+Unicode semantics are used for the case change.
=item Otherwise:
-=over
-
-=item On EBCDIC platforms
-
-The results are what the C language system call C<tolower()> returns.
-
-=item On ASCII platforms
-
ASCII semantics are used for the case change. The lowercase of any character
outside the ASCII range is the character itself.
=back
-=back
-
=item lcfirst EXPR
X<lcfirst> X<lowercase>
=item lcfirst
+=for Pod::Functions return a string with just the next letter in lower case
+
Returns the value of EXPR with the first character lowercased. This
is the internal function implementing the C<\l> escape in
double-quoted strings.
@@ -2878,6 +3357,8 @@
=item length
+=for Pod::Functions return the number of characters in a string
+
Returns the length in I<characters> of the value of EXPR. If EXPR is
omitted, returns the length of C<$_>. If EXPR is undefined, returns
C<undef>.
@@ -2891,15 +3372,28 @@
UTF-8 would take up, use C<length(Encode::encode_utf8(EXPR))> (you'll have
to C<use Encode> first). See L<Encode> and L<perlunicode>.
+=item __LINE__
+X<__LINE__>
+
+=for Pod::Functions the current source line number
+
+A special token that compiles to the current line number.
+
=item link OLDFILE,NEWFILE
X<link>
+=for Pod::Functions create a hard link in the filesystem
+
Creates a new filename linked to the old filename. Returns true for
success, false otherwise.
+Portability issues: L<perlport/link>.
+
=item listen SOCKET,QUEUESIZE
X<listen>
+=for Pod::Functions register your socket as a server
+
Does the same thing that the listen(2) system call does. Returns true if
it succeeded, false otherwise. See the example in
L<perlipc/"Sockets: Client/Server Communication">.
@@ -2907,6 +3401,8 @@
=item local EXPR
X<local>
+=for Pod::Functions create a temporary value for a global variable (dynamic scoping)
+
You really probably want to be using C<my> instead, because C<local> isn't
what most people think of as "local". See
L<perlsub/"Private Variables via my()"> for details.
@@ -2925,6 +3421,8 @@
=item localtime
+=for Pod::Functions convert UNIX time into record or string using local time
+
Converts a time as returned by the time function to a 9-element list
with the time analyzed for the local time zone. Typically used as
follows:
@@ -2941,19 +3439,15 @@
the range C<0..11>, with 0 indicating January and 11 indicating December.
This makes it easy to get a month name from a list:
- my @abbr = qw( Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec );
+ my @abbr = qw(Jan Feb Mar Apr May Jun Jul Aug Sep Oct Nov Dec);
print "$abbr[$mon] $mday";
# $mon=9, $mday=18 gives "Oct 18"
-C<$year> is the number of years since 1900, B<not> just the last two digits
-of the year. That is, C<$year> is C<123> in year 2023. The proper way
-to get a 4-digit year is simply:
+C<$year> contains the number of years since 1900. To get a 4-digit
+year write:
$year += 1900;
-Otherwise you create non-Y2K-compliant programs--and you wouldn't want
-to do that, would you?
-
To get the last two digits of the year (e.g., "01" in 2001) do:
$year = sprintf("%02d", $year % 100);
@@ -2972,8 +3466,9 @@
$now_string = localtime; # e.g., "Thu Oct 13 04:54:34 1994"
-This scalar value is B<not> locale-dependent but is a Perl builtin. For GMT
-instead of local time use the L</gmtime> builtin. See also the
+The format of this scalar value is B<not> locale-dependent
+but built into Perl. For GMT instead of local
+time use the L</gmtime> builtin. See also the
C<Time::Local> module (for converting seconds, minutes, hours, and such back to
the integer value returned by time()), and the L<POSIX> module's strftime(3)
and mktime(3) functions.
@@ -2990,8 +3485,6 @@
Note that the C<%a> and C<%b>, the short forms of the day of the week
and the month of the year, may not necessarily be three characters wide.
-See L<perlport/localtime> for portability concerns.
-
The L<Time::gmtime> and L<Time::localtime> modules provide a convenient,
by-name access mechanism to the gmtime() and localtime() functions,
respectively.
@@ -2999,12 +3492,19 @@
For a comprehensive date and time representation look at the
L<DateTime> module on CPAN.
+Portability issues: L<perlport/localtime>.
+
=item lock THING
X<lock>
+=for Pod::Functions +5.005 get a thread lock on a variable, subroutine, or method
+
This function places an advisory lock on a shared variable or referenced
object contained in I<THING> until the lock goes out of scope.
+The value returned is the scalar itself, if the argument is a scalar, or a
+reference, if the argument is a hash, array or subroutine.
+
lock() is a "weak keyword" : this means that if you've defined a function
by this name (before any calls to it), that function will be called
instead. If you are not under C<use threads::shared> this does nothing.
@@ -3015,6 +3515,8 @@
=item log
+=for Pod::Functions retrieve the natural logarithm for a number
+
Returns the natural logarithm (base I<e>) of EXPR. If EXPR is omitted,
returns the log of C<$_>. To get the
log of another base, use basic algebra:
@@ -3028,11 +3530,17 @@
See also L</exp> for the inverse operation.
-=item lstat EXPR
+=item lstat FILEHANDLE
X<lstat>
+=item lstat EXPR
+
+=item lstat DIRHANDLE
+
=item lstat
+=for Pod::Functions stat a symbolic link
+
Does the same thing as the C<stat> function (including setting the
special C<_> filehandle) but stats a symbolic link instead of the file
the symbolic link points to. If symbolic links are unimplemented on
@@ -3041,8 +3549,12 @@
If EXPR is omitted, stats C<$_>.
+Portability issues: L<perlport/lstat>.
+
=item m//
+=for Pod::Functions match a string with a regular expression pattern
+
The match operator. See L<perlop/"Regexp Quote-Like Operators">.
=item map BLOCK LIST
@@ -3050,6 +3562,8 @@
=item map EXPR,LIST
+=for Pod::Functions apply a change to a list to get back a new list with the changes
+
Evaluates the BLOCK or EXPR for each element of LIST (locally setting
C<$_> to each element) and returns the list value composed of the
results of each such evaluation. In scalar context, returns the
@@ -3068,7 +3582,7 @@
my @squares = map { $_ > 5 ? ($_ * $_) : () } @numbers;
shows that number of returned elements can differ from the number of
-input elements. To omit an element, return an empty list ().
+input elements. To omit an element, return an empty list ().
This could also be achieved by writing
my @squares = map { $_ * $_ } grep { $_ > 5 } @numbers;
@@ -3077,7 +3591,7 @@
Map always returns a list, which can be
assigned to a hash such that the elements
-become key/value pairs. See L<perldata> for more details.
+become key/value pairs. See L<perldata> for more details.
%hash = map { get_a_key_for($_) => $_ } @array;
@@ -3096,30 +3610,33 @@
the original list for which the BLOCK or EXPR evaluates to true.
If C<$_> is lexical in the scope where the C<map> appears (because it has
-been declared with C<my $_>), then, in addition to being locally aliased to
+been declared with the deprecated C<my $_> construct),
+then, in addition to being locally aliased to
the list elements, C<$_> keeps being lexical inside the block; that is, it
can't be seen from the outside, avoiding any potential side-effects.
C<{> starts both hash references and blocks, so C<map { ...> could be either
-the start of map BLOCK LIST or map EXPR, LIST. Because Perl doesn't look
+the start of map BLOCK LIST or map EXPR, LIST. Because Perl doesn't look
ahead for the closing C<}> it has to take a guess at which it's dealing with
-based on what it finds just after the C<{>. Usually it gets it right, but if it
+based on what it finds just after the
+C<{>. Usually it gets it right, but if it
doesn't it won't realize something is wrong until it gets to the C<}> and
-encounters the missing (or unexpected) comma. The syntax error will be
+encounters the missing (or unexpected) comma. The syntax error will be
reported close to the C<}>, but you'll need to change something near the C<{>
such as using a unary C<+> to give Perl some help:
- %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
- %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
- %hash = map { ("\L$_" => 1) } @array # this also works
- %hash = map { lc($_) => 1 } @array # as does this.
- %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
+ %hash = map { "\L$_" => 1 } @array # perl guesses EXPR. wrong
+ %hash = map { +"\L$_" => 1 } @array # perl guesses BLOCK. right
+ %hash = map { ("\L$_" => 1) } @array # this also works
+ %hash = map { lc($_) => 1 } @array # as does this.
+ %hash = map +( lc($_) => 1 ), @array # this is EXPR and works!
- %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
+ %hash = map ( lc($_), 1 ), @array # evaluates to (1, @array)
or to force an anon hash constructor use C<+{>:
- @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs comma at end
+ @hashes = map +{ lc($_) => 1 }, @array # EXPR, so needs
+ # comma at end
to get a list of anonymous hashes each with only one entry apiece.
@@ -3130,6 +3647,8 @@
=item mkdir
+=for Pod::Functions create a directory
+
Creates the directory specified by FILENAME, with permissions
specified by MASK (as modified by C<umask>). If it succeeds it
returns true; otherwise it returns false and sets C<$!> (errno).
@@ -3154,6 +3673,8 @@
=item msgctl ID,CMD,ARG
X<msgctl>
+=for Pod::Functions SysV IPC message control operations
+
Calls the System V IPC function msgctl(2). You'll probably have to say
use IPC::SysV;
@@ -3165,17 +3686,25 @@
L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
C<IPC::Semaphore>.
+Portability issues: L<perlport/msgctl>.
+
=item msgget KEY,FLAGS
X<msgget>
+=for Pod::Functions get SysV IPC message queue
+
Calls the System V IPC function msgget(2). Returns the message queue
id, or C<undef> on error. See also
L<perlipc/"SysV IPC"> and the documentation for C<IPC::SysV> and
C<IPC::Msg>.
+Portability issues: L<perlport/msgget>.
+
=item msgrcv ID,VAR,SIZE,TYPE,FLAGS
X<msgrcv>
+=for Pod::Functions receive a SysV IPC message from a message queue
+
Calls the System V IPC function msgrcv to receive a message from
message queue ID into variable VAR with a maximum message size of
SIZE. Note that when a message is received, the message type as a
@@ -3185,9 +3714,13 @@
on error. See also L<perlipc/"SysV IPC"> and the documentation for
C<IPC::SysV> and C<IPC::SysV::Msg>.
+Portability issues: L<perlport/msgrcv>.
+
=item msgsnd ID,MSG,FLAGS
X<msgsnd>
+=for Pod::Functions send a SysV IPC message to a message queue
+
Calls the System V IPC function msgsnd to send the message MSG to the
message queue ID. MSG must begin with the native long integer message
type, be followed by the length of the actual message, and then finally
@@ -3196,6 +3729,8 @@
false on error. See also the C<IPC::SysV>
and C<IPC::SysV::Msg> documentation.
+Portability issues: L<perlport/msgsnd>.
+
=item my EXPR
X<my>
@@ -3205,6 +3740,8 @@
=item my TYPE EXPR : ATTRS
+=for Pod::Functions declare and assign a local variable (lexical scoping)
+
A C<my> declares the listed variables to be local (lexically) to the
enclosing block, file, or C<eval>. If more than one value is listed,
the list must be placed in parentheses.
@@ -3219,8 +3756,12 @@
=item next LABEL
X<next> X<continue>
+=item next EXPR
+
=item next
+=for Pod::Functions iterate a block prematurely
+
The C<next> command is like the C<continue> statement in C; it starts
the next iteration of the loop:
@@ -3231,7 +3772,9 @@
Note that if there were a C<continue> block on the above, it would get
executed even on discarded lines. If LABEL is omitted, the command
-refers to the innermost enclosing loop.
+refers to the innermost enclosing loop. The C<next EXPR> form, available
+as of Perl 5.18.0, allows a label name to be computed at run time, being
+otherwise identical to C<next LABEL>.
C<next> cannot be used to exit a block which returns a value such as
C<eval {}>, C<sub {}>, or C<do {}>, and should not be used to exit
@@ -3243,6 +3786,11 @@
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+C<next ("foo")."bar"> will cause "bar" to be part of the argument to
+C<next>.
+
=item no MODULE VERSION LIST
X<no declarations>
X<unimporting>
@@ -3255,6 +3803,8 @@
=item no VERSION
+=for Pod::Functions unimport some module symbols or semantics at compile time
+
See the C<use> function, of which C<no> is the opposite.
=item oct EXPR
@@ -3262,6 +3812,8 @@
=item oct
+=for Pod::Functions convert a string to an octal number
+
Interprets EXPR as an octal string and returns the corresponding
value. (If EXPR happens to start off with C<0x>, interprets it as a
hex string. If EXPR starts off with C<0b>, it is interpreted as a
@@ -3297,6 +3849,8 @@
=item open FILEHANDLE
+=for Pod::Functions open a file, pipe, or descriptor
+
Opens the file whose filename is given by EXPR, and associates it with
FILEHANDLE.
@@ -3337,7 +3891,7 @@
You can put a C<+> in front of the C<< > >> or C<< < >> to
indicate that you want both read and write access to the file; thus
C<< +< >> is almost always preferred for read/write updates--the
-C<< +> >> mode would clobber the file first. You cant usually use
+C<< +> >> mode would clobber the file first. You can't usually use
either read-write mode for updating textfiles, since they have
variable-length records. See the B<-i> switch in L<perlrun> for a
better approach. The file is created with permissions of C<0666>
@@ -3376,15 +3930,18 @@
You may (and usually should) use the three-argument form of open to specify
I/O layers (sometimes referred to as "disciplines") to apply to the handle
that affect how the input and output are processed (see L<open> and
-L<PerlIO> for more details). For example:
+L<PerlIO> for more details). For example:
open(my $fh, "<:encoding(UTF-8)", "filename")
|| die "can't open UTF-8 encoded filename: $!";
opens the UTF8-encoded file containing Unicode characters;
-see L<perluniintro>. Note that if layers are specified in the
+see L<perluniintro>. Note that if layers are specified in the
three-argument form, then default layers stored in ${^OPEN} (see L<perlvar>;
usually set by the B<open> pragma or the switch B<-CioD>) are ignored.
+Those layers will also be ignored if you specifying a colon with no name
+following it. In that case the default layer for the operating system
+(:raw on Unix, :crlf on Windows) is used.
Open returns nonzero on success, the undefined value otherwise. If
the C<open> involved a pipe, the return value happens to be the pid of
@@ -3415,7 +3972,7 @@
to the temporary file first. You will need to seek() to do the
reading.
-Since v5.8.0, Perl has built using PerlIO by default. Unless you've
+Perl is built using PerlIO by default; Unless you've
changed this (such as building Perl with C<Configure -Uuseperlio>), you can
open filehandles directly to Perl scalars via:
@@ -3454,7 +4011,7 @@
# in-memory files
open(MEMORY, ">", \$var)
or die "Can't open memory file: $!";
- print MEMORY "foo!\n"; # output will appear in $var
+ print MEMORY "foo!\n"; # output will appear in $var
# process argument list of files along with any includes
@@ -3489,7 +4046,8 @@
C<<< >> >>>, C<< < >>, C<< +> >>, C<<< +>> >>>, and C<< +< >>.
The mode you specify should match the mode of the original filehandle.
(Duping a filehandle does not take into account any existing contents
-of IO buffers.) If you use the three-argument form, then you can pass either a
+of IO buffers.) If you use the three-argument
+form, then you can pass either a
number, the name of a filehandle, or the normal "reference to a glob".
Here is a script that saves, redirects, and restores C<STDOUT> and
@@ -3561,9 +4119,10 @@
For example, use either
- $child_pid = open(FROM_KID, "|-") // die "can't fork: $!";
+ $child_pid = open(FROM_KID, "-|") // die "can't fork: $!";
or
+
$child_pid = open(TO_KID, "|-") // die "can't fork: $!";
followed by
@@ -3572,7 +4131,7 @@
# am the parent:
# either write TO_KID or else read FROM_KID
...
- wait $child_pid;
+ waitpid $child_pid, 0;
} else {
# am the child; use STDIN/STDOUT normally
...
@@ -3613,7 +4172,7 @@
See L<perlipc/"Safe Pipe Opens"> for more examples of this.
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
+Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
supported on some platforms (see L<perlport>). To be safe, you may need
to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
@@ -3661,7 +4220,7 @@
will have exactly the opposite restrictions.
-If you want a "real" C C<open> (see C<open(2)> on your system), then you
+If you want a "real" C C<open> (see L<open(2)> on your system), then you
should use the C<sysopen> function, which involves no such magic (but may
use subtly different filemodes than Perl open(), which is mapped to C
fopen()). This is another way to protect your filenames from
@@ -3696,7 +4255,7 @@
}
B<WARNING:> The previous example has a bug because the automatic
-close that happens when the refcount on C<handle> does not
+close that happens when the refcount on C<handle> reaches zero does not
properly detect and report failures. I<Always> close the handle
yourself and inspect the return value.
@@ -3705,9 +4264,13 @@
See L</seek> for some details about mixing reading and writing.
+Portability issues: L<perlport/open>.
+
=item opendir DIRHANDLE,EXPR
X<opendir>
+=for Pod::Functions open a directory
+
Opens a directory named EXPR for processing by C<readdir>, C<telldir>,
C<seekdir>, C<rewinddir>, and C<closedir>. Returns true if successful.
DIRHANDLE may be an expression whose value can be used as an indirect
@@ -3723,8 +4286,9 @@
=item ord
-Returns the numeric (the native 8-bit encoding, like ASCII or EBCDIC,
-or Unicode) value of the first character of EXPR.
+=for Pod::Functions find a character's numeric representation
+
+Returns the numeric value of the first character of EXPR.
If EXPR is an empty string, returns 0. If EXPR is omitted, uses C<$_>.
(Note I<character>, not byte.)
@@ -3740,19 +4304,21 @@
=item our TYPE EXPR : ATTRS
-C<our> associates a simple name with a package variable in the current
-package for use within the current scope. When C<use strict 'vars'> is in
-effect, C<our> lets you use declared global variables without qualifying
-them with package names, within the lexical scope of the C<our> declaration.
-In this way C<our> differs from C<use vars>, which is package-scoped.
+=for Pod::Functions +5.6.0 declare and assign a package variable (lexical scoping)
-Unlike C<my> or C<state>, which allocates storage for a variable and
-associates a simple name with that storage for use within the current
-scope, C<our> associates a simple name with a package (read: global)
-variable in the current package, for use within the current lexical scope.
-In other words, C<our> has the same scoping rules as C<my> or C<state>, but
-does not necessarily create a variable.
+C<our> makes a lexical alias to a package variable of the same name in the current
+package for use within the current lexical scope.
+C<our> has the same scoping rules as C<my> or C<state>, but C<our> only
+declares an alias, whereas C<my> or C<state> both declare a variable name and
+allocate storage for that name within the current scope.
+
+This means that when C<use strict 'vars'> is in effect, C<our> lets you use
+a package variable without qualifying it with the package name, but only within
+the lexical scope of the C<our> declaration. In this way, C<our> differs from
+C<use vars>, which allows use of an unqualified name I<only> within the
+affected package, but across scopes.
+
If more than one value is listed, the list must be placed
in parentheses.
@@ -3759,7 +4325,7 @@
our $foo;
our($bar, $baz);
-An C<our> declaration declares a global variable that will be visible
+An C<our> declaration declares an alias for a package variable that will be visible
across its entire lexical scope, even across package boundaries. The
package in which the variable is entered is determined at the point
of the declaration, not at the point of use. This means the following
@@ -3796,9 +4362,9 @@
with it.
The exact semantics and interface of TYPE and ATTRS are still
-evolving. TYPE is currently bound to the use of C<fields> pragma,
-and attributes are handled using the C<attributes> pragma, or starting
-from Perl 5.8.0 also via the C<Attribute::Handlers> module. See
+evolving. TYPE is currently bound to the use of the C<fields> pragma,
+and attributes are handled using the C<attributes> pragma, or, starting
+from Perl 5.8.0, also via the C<Attribute::Handlers> module. See
L<perlsub/"Private Variables via my()"> for details, and L<fields>,
L<attributes>, and L<Attribute::Handlers>.
@@ -3805,6 +4371,8 @@
=item pack TEMPLATE,LIST
X<pack>
+=for Pod::Functions convert a list into a binary representation
+
Takes a LIST of values and converts it into a string using the rules
given by the TEMPLATE. The resulting string is the concatenation of
the converted values. Typically, each converted value looks
@@ -3821,7 +4389,8 @@
A A text (ASCII) string, will be space padded.
Z A null-terminated (ASCIZ) string, will be null padded.
- b A bit string (ascending bit order inside each byte, like vec()).
+ b A bit string (ascending bit order inside each byte,
+ like vec()).
B A bit string (descending bit order inside each byte).
h A hex string (low nybble first).
H A hex string (high nybble first).
@@ -3838,14 +4407,14 @@
q A signed quad (64-bit) value.
Q An unsigned quad value.
- (Quads are available only if your system supports 64-bit
- integer values _and_ if Perl has been compiled to support those.
- Raises an exception otherwise.)
+ (Quads are available only if your system supports 64-bit
+ integer values _and_ if Perl has been compiled to support
+ those. Raises an exception otherwise.)
i A signed integer value.
I A unsigned integer value.
- (This 'integer' is _at_least_ 32 bits wide. Its exact
- size depends on what a local C compiler calls 'int'.)
+ (This 'integer' is _at_least_ 32 bits wide. Its exact
+ size depends on what a local C compiler calls 'int'.)
n An unsigned short (16-bit) in "network" (big-endian) order.
N An unsigned long (32-bit) in "network" (big-endian) order.
@@ -3852,8 +4421,8 @@
v An unsigned short (16-bit) in "VAX" (little-endian) order.
V An unsigned long (32-bit) in "VAX" (little-endian) order.
- j A Perl internal signed integer value (IV).
- J A Perl internal unsigned integer value (UV).
+ j A Perl internal signed integer value (IV).
+ J A Perl internal unsigned integer value (UV).
f A single-precision float in native format.
d A double-precision float in native format.
@@ -3860,27 +4429,30 @@
F A Perl internal floating-point value (NV) in native format
D A float of long-double precision in native format.
- (Long doubles are available only if your system supports long
- double values _and_ if Perl has been compiled to support those.
- Raises an exception otherwise.)
+ (Long doubles are available only if your system supports
+ long double values _and_ if Perl has been compiled to
+ support those. Raises an exception otherwise.)
p A pointer to a null-terminated string.
P A pointer to a structure (fixed-length string).
u A uuencoded string.
- U A Unicode character number. Encodes to a character in character mode
- and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in byte mode.
+ U A Unicode character number. Encodes to a character in char-
+ acter mode and UTF-8 (or UTF-EBCDIC in EBCDIC platforms) in
+ byte mode.
- w A BER compressed integer (not an ASN.1 BER, see perlpacktut for
- details). Its bytes represent an unsigned integer in base 128,
- most significant digit first, with as few digits as possible. Bit
- eight (the high bit) is set on each byte except the last.
+ w A BER compressed integer (not an ASN.1 BER, see perlpacktut
+ for details). Its bytes represent an unsigned integer in
+ base 128, most significant digit first, with as few digits
+ as possible. Bit eight (the high bit) is set on each byte
+ except the last.
x A null byte (a.k.a ASCII NUL, "\000", chr(0))
X Back up a byte.
@ Null-fill or truncate to absolute position, counted from the
start of the innermost ()-group.
- . Null-fill or truncate to absolute position specified by the value.
+ . Null-fill or truncate to absolute position specified by
+ the value.
( Start of a ()-group.
One or more modifiers below may optionally follow certain letters in the
@@ -3894,8 +4466,8 @@
nNvV Treat integers as signed instead of unsigned.
@. Specify position as byte offset in the internal
- representation of the packed string. Efficient but
- dangerous.
+ representation of the packed string. Efficient
+ but dangerous.
> sSiIlLqQ Force big-endian byte-order on the type.
jJfFdDpP (The "big end" touches the construct.)
@@ -3907,6 +4479,28 @@
to force a particular byte-order on all components in that group,
including all its subgroups.
+=begin comment
+
+Larry recalls that the hex and bit string formats (H, h, B, b) were added to
+pack for processing data from NASA's Magellan probe. Magellan was in an
+elliptical orbit, using the antenna for the radar mapping when close to
+Venus and for communicating data back to Earth for the rest of the orbit.
+There were two transmission units, but one of these failed, and then the
+other developed a fault whereby it would randomly flip the sense of all the
+bits. It was easy to automatically detect complete records with the correct
+sense, and complete records with all the bits flipped. However, this didn't
+recover the records where the sense flipped midway. A colleague of Larry's
+was able to pretty much eyeball where the records flipped, so they wrote an
+editor named kybble (a pun on the dog food Kibbles 'n Bits) to enable him to
+manually correct the records and recover the data. For this purpose pack
+gained the hex and bit string format specifiers.
+
+git shows that they were added to perl 3.0 in patch #44 (Jan 1991, commit
+27e2fb84680b9cc1), but the patch description makes no mention of their
+addition, let alone the story behind them.
+
+=end comment
+
The following rules apply:
=over
@@ -3918,7 +4512,7 @@
in C<pack("C[80]", @arr)>. The repeat count gobbles that many values from
the LIST when used with all format types other than C<a>, C<A>, C<Z>, C<b>,
C<B>, C<h>, C<H>, C<@>, C<.>, C<x>, C<X>, and C<P>, where it means
-something else, dscribed below. Supplying a C<*> for the repeat count
+something else, described below. Supplying a C<*> for the repeat count
instead of a number means to use however many items are left, except for:
=over
@@ -3977,7 +4571,7 @@
=back
The repeat count for C<u> is interpreted as the maximal number of bytes
-to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat
+to encode per line of output, with 0, 1 and 2 replaced by 45. The repeat
count should not be more than 65.
=item *
@@ -4070,18 +4664,18 @@
within the structure itself as separate fields.
For C<pack>, you write I<length-item>C</>I<sequence-item>, and the
-I<length-item> describes how the length value is packed. Formats likely
+I<length-item> describes how the length value is packed. Formats likely
to be of most use are integer-packing ones like C<n> for Java strings,
C<w> for ASN.1 or SNMP, and C<N> for Sun XDR.
For C<pack>, I<sequence-item> may have a repeat count, in which case
the minimum of that and the number of available items is used as the argument
-for I<length-item>. If it has no repeat count or uses a '*', the number
+for I<length-item>. If it has no repeat count or uses a '*', the number
of available items is used.
For C<unpack>, an internal stack of integer arguments unpacked so far is
-used. You write C</>I<sequence-item> and the repeat count is obtained by
-popping off the last element from the stack. The I<sequence-item> must not
+used. You write C</>I<sequence-item> and the repeat count is obtained by
+popping off the last element from the stack. The I<sequence-item> must not
have a repeat count.
If I<sequence-item> refers to a string type (C<"A">, C<"a">, or C<"Z">),
@@ -4089,13 +4683,15 @@
an explicit repeat count for pack, the packed string is adjusted to that
length. For example:
- unpack("W/a", "\004Gurusamy") gives ("Guru")
- unpack("a3/A A*", "007 Bond J ") gives (" Bond", "J")
- unpack("a3 x2 /A A*", "007: Bond, J.") gives ("Bond, J", ".")
+ This code: gives this result:
- pack("n/a* w/a","hello,","world") gives "\000\006hello,\005world"
- pack("a/W2", ord("a") .. ord("z")) gives "2ab"
+ unpack("W/a", "\004Gurusamy") ("Guru")
+ unpack("a3/A A*", "007 Bond J ") (" Bond", "J")
+ unpack("a3 x2 /A A*", "007: Bond, J.") ("Bond, J", ".")
+ pack("n/a* w/a","hello,","world") "\000\006hello,\005world"
+ pack("a/W2", ord("a") .. ord("z")) "2ab"
+
The I<length-item> is not returned explicitly from C<unpack>.
Supplying a count to the I<length-item> format letter is only useful with
@@ -4193,7 +4789,7 @@
=item *
-Starting with Perl 5.9.2, integer and floating-point formats, along with
+Starting with Perl 5.10.0, integer and floating-point formats, along with
the C<p> and C<P> formats and C<()> groups, may all be followed by the
C<< > >> or C<< < >> endianness modifiers to respectively enforce big-
or little-endian byte-order. These modifiers are especially useful
@@ -4259,8 +4855,9 @@
Pack and unpack can operate in two modes: character mode (C<C0> mode) where
the packed string is processed per character, and UTF-8 mode (C<U0> mode)
where the packed string is processed in its UTF-8-encoded Unicode form on
-a byte-by-byte basis. Character mode is the default unless the format string
-starts with C<U>. You can always switch mode mid-format with an explicit
+a byte-by-byte basis. Character mode is the default
+unless the format string starts with C<U>. You
+can always switch mode mid-format with an explicit
C<C0> or C<U0> in the format. This mode remains in effect until the next
mode change, or until the end of the C<()> group it (directly) applies to.
@@ -4296,7 +4893,7 @@
A C<()> group is a sub-TEMPLATE enclosed in parentheses. A group may
take a repeat count either as postfix, or for unpack(), also via the C</>
template character. Within each repetition of a group, positioning with
-C<@> starts over at 0. Therefore, the result of
+C<@> starts over at 0. Therefore, the result of
pack("@1A((@2A)@3A)", qw[X Y Z])
@@ -4306,7 +4903,7 @@
C<x> and C<X> accept the C<!> modifier to act as alignment commands: they
jump forward or back to the closest position aligned at a multiple of C<count>
-characters. For example, to pack() or unpack() a C structure like
+characters. For example, to pack() or unpack() a C structure like
struct {
char c; /* one signed, 8-bit character */
@@ -4354,12 +4951,14 @@
$foo = pack("W4",0x24b6,0x24b7,0x24b8,0x24b9);
# same thing with Unicode circled letters.
$foo = pack("U4",0x24b6,0x24b7,0x24b8,0x24b9);
- # same thing with Unicode circled letters. You don't get the UTF-8
- # bytes because the U at the start of the format caused a switch to
- # U0-mode, so the UTF-8 bytes get joined into characters
+ # same thing with Unicode circled letters. You don't get the
+ # UTF-8 bytes because the U at the start of the format caused
+ # a switch to U0-mode, so the UTF-8 bytes get joined into
+ # characters
$foo = pack("C0U4",0x24b6,0x24b7,0x24b8,0x24b9);
# foo eq "\xe2\x92\xb6\xe2\x92\xb7\xe2\x92\xb8\xe2\x92\xb9"
- # This is the UTF-8 encoding of the string in the previous example
+ # This is the UTF-8 encoding of the string in the
+ # previous example
$foo = pack("ccxxcc",65,66,67,68);
# foo eq "AB\0\0CD"
@@ -4425,6 +5024,8 @@
=item package NAMESPACE VERSION BLOCK
X<package> X<module> X<namespace> X<version>
+=for Pod::Functions declare a separate global namespace
+
Declares the BLOCK or the rest of the compilation unit as being in the
given namespace. The scope of the package declaration is either the
supplied code BLOCK or, in the absence of a BLOCK, from the declaration
@@ -4437,7 +5038,7 @@
like C<STDOUT>, C<ARGV>, C<ENV>, and the punctuation variables.
A package statement affects dynamic variables only, including those
-you've used C<local> on, but I<not> lexical variables, which are created
+you've used C<local> on, but I<not> lexically-scoped variables, which are created
with C<my>, C<state>, or C<our>. Typically it would be the first
declaration in a file included by C<require> or C<use>. You can switch into a
package in more than one place, since this only determines which default
@@ -4459,9 +5060,18 @@
See L<perlmod/"Packages"> for more information about packages, modules,
and classes. See L<perlsub> for other scoping issues.
+=item __PACKAGE__
+X<__PACKAGE__>
+
+=for Pod::Functions +5.004 the current package
+
+A special token that returns the name of the package in which it occurs.
+
=item pipe READHANDLE,WRITEHANDLE
X<pipe>
+=for Pod::Functions open a pair of connected filehandles
+
Opens a pair of connected pipes like the corresponding system call.
Note that if you set up a loop of piped processes, deadlock can occur
unless you are very careful. In addition, note that Perl's pipes use
@@ -4468,6 +5078,8 @@
IO buffering, so you may need to set C<$|> to flush your WRITEHANDLE
after each command, depending on the application.
+Returns true on success.
+
See L<IPC::Open2>, L<IPC::Open3>, and
L<perlipc/"Bidirectional Communication with Another Process">
for examples of such things.
@@ -4483,6 +5095,8 @@
=item pop
+=for Pod::Functions remove the last element from an array and return it
+
Pops and returns the last value of the array, shortening the array by
one element.
@@ -4495,14 +5109,23 @@
automatically. This aspect of C<pop> is considered highly experimental.
The exact behaviour may change in a future version of Perl.
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.014; # so push/pop/etc work on scalars (experimental)
+
=item pos SCALAR
X<pos> X<match, position>
=item pos
+=for Pod::Functions find or set the offset for the last/next m//g search
+
Returns the offset of where the last C<m//g> search left off for the
variable in question (C<$_> is used when the variable is not
-specified). Note that 0 is a valid match offset. C<undef> indicates
+specified). Note that 0 is a valid match offset. C<undef> indicates
that the search position is reset (usually due to match failure, but
can also be because no match has yet been run on the scalar).
@@ -4509,7 +5132,7 @@
C<pos> directly accesses the location used by the regexp engine to
store the offset, so assigning to C<pos> will change that offset, and
so will also influence the C<\G> zero-width assertion in regular
-expressions. Both of these effects take place for the next match, so
+expressions. Both of these effects take place for the next match, so
you can't affect the position with C<pos> during the current match,
such as in C<(?{pos() = 5})> or C<s//pos() = 5/e>.
@@ -4529,12 +5152,14 @@
=item print
+=for Pod::Functions output a list to a filehandle
+
Prints a string or a list of strings. Returns true if successful.
FILEHANDLE may be a scalar variable containing the name of or a reference
to the filehandle, thus introducing one level of indirection. (NOTE: If
FILEHANDLE is a variable and the next token is a term, it may be
misinterpreted as an operator unless you interpose a C<+> or put
-parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
+parentheses around the arguments.) If FILEHANDLE is omitted, prints to the
last selected (see L</select>) output handle. If LIST is omitted, prints
C<$_> to the currently selected output handle. To use FILEHANDLE alone to
print the content of C<$_> to it, you must use a real filehandle like
@@ -4571,16 +5196,27 @@
=item printf
+=for Pod::Functions output a formatted list to a filehandle
+
Equivalent to C<print FILEHANDLE sprintf(FORMAT, LIST)>, except that C<$\>
-(the output record separator) is not appended. The first argument of the
-list will be interpreted as the C<printf> format. See C<sprintf> for an
-explanation of the format argument. If you omit the LIST, C<$_> is used;
-to use FILEHANDLE without a LIST, you must use a real filehandle like
-C<FH>, not an indirect one like C<$fh>. If C<use locale> is in effect and
+(the output record separator) is not appended. The FORMAT and the
+LIST are actually parsed as a single list. The first argument
+of the list will be interpreted as the C<printf> format. This
+means that C<printf(@_)> will use C<$_[0]> as the format. See
+L<sprintf|/sprintf FORMAT, LIST> for an
+explanation of the format argument. If C<use locale> (including
+C<use locale ':not_characters'>) is in effect and
POSIX::setlocale() has been called, the character used for the decimal
separator in formatted floating-point numbers is affected by the LC_NUMERIC
locale setting. See L<perllocale> and L<POSIX>.
+For historical reasons, if you omit the list, C<$_> is used as the format;
+to use FILEHANDLE without a list, you must use a real filehandle like
+C<FH>, not an indirect one like C<$fh>. However, this will rarely do what
+you want; if $_ contains formatting codes, they will be replaced with the
+empty string and a warning will be emitted if warnings are enabled. Just
+use C<print> if you want to print the contents of $_.
+
Don't fall into the trap of using a C<printf> when a simple
C<print> would do. The C<print> is more efficient and less
error prone.
@@ -4588,13 +5224,15 @@
=item prototype FUNCTION
X<prototype>
+=for Pod::Functions +5.002 get the prototype (if any) of a subroutine
+
Returns the prototype of a function as a string (or C<undef> if the
function has no prototype). FUNCTION is a reference to, or the name of,
the function whose prototype you want to retrieve.
If FUNCTION is a string starting with C<CORE::>, the rest is taken as a
-name for a Perl builtin. If the builtin is not I<overridable> (such as
-C<qw//>) or if its arguments cannot be adequately expressed by a prototype
+name for a Perl builtin. If the builtin's arguments
+cannot be adequately expressed by a prototype
(such as C<system>), prototype() returns C<undef>, because the builtin
does not really behave like a Perl function. Otherwise, the string
describing the equivalent prototype is returned.
@@ -4604,6 +5242,8 @@
=item push EXPR,LIST
+=for Pod::Functions append one or more elements to an array
+
Treats ARRAY as a stack by appending the values of LIST to the end of
ARRAY. The length of ARRAY increases by the length of LIST. Has the same
effect as
@@ -4620,18 +5260,35 @@
automatically. This aspect of C<push> is considered highly experimental.
The exact behaviour may change in a future version of Perl.
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.014; # so push/pop/etc work on scalars (experimental)
+
=item q/STRING/
+=for Pod::Functions singly quote a string
+
=item qq/STRING/
-=item qx/STRING/
+=for Pod::Functions doubly quote a string
=item qw/STRING/
+=for Pod::Functions quote a list of words
+
+=item qx/STRING/
+
+=for Pod::Functions backquote quote a string
+
Generalized quotes. See L<perlop/"Quote-Like Operators">.
=item qr/STRING/
+=for Pod::Functions +5.005 compile pattern
+
Regexp-like quote. See L<perlop/"Regexp Quote-Like Operators">.
=item quotemeta EXPR
@@ -4639,18 +5296,21 @@
=item quotemeta
-Returns the value of EXPR with all non-"word"
-characters backslashed. (That is, all characters not matching
+=for Pod::Functions quote regular expression magic characters
+
+Returns the value of EXPR with all the ASCII non-"word"
+characters backslashed. (That is, all ASCII characters not matching
C</[A-Za-z_0-9]/> will be preceded by a backslash in the
returned string, regardless of any locale settings.)
This is the internal function implementing
the C<\Q> escape in double-quoted strings.
+(See below for the behavior on non-ASCII code points.)
If EXPR is omitted, uses C<$_>.
quotemeta (and C<\Q> ... C<\E>) are useful when interpolating strings into
regular expressions, because by default an interpolated variable will be
-considered a mini-regular expression. For example:
+considered a mini-regular expression. For example:
my $sentence = 'The quick brown fox jumped over the lazy dog';
my $substring = 'quick.*?fox';
@@ -4671,19 +5331,72 @@
my $quoted_substring = quotemeta($substring);
$sentence =~ s{$quoted_substring}{big bad wolf};
-Will both leave the sentence as is. Normally, when accepting literal string
+Will both leave the sentence as is.
+Normally, when accepting literal string
input from the user, quotemeta() or C<\Q> must be used.
-In Perl 5.14, all characters whose code points are above 127 are not
-quoted in UTF8-encoded strings, but all are quoted in UTF-8 strings.
-It is planned to change this behavior in 5.16, but the exact rules
-haven't been determined yet.
+In Perl v5.14, all non-ASCII characters are quoted in non-UTF-8-encoded
+strings, but not quoted in UTF-8 strings.
+Starting in Perl v5.16, Perl adopted a Unicode-defined strategy for
+quoting non-ASCII characters; the quoting of ASCII characters is
+unchanged.
+
+Also unchanged is the quoting of non-UTF-8 strings when outside the
+scope of a C<use feature 'unicode_strings'>, which is to quote all
+characters in the upper Latin1 range. This provides complete backwards
+compatibility for old programs which do not use Unicode. (Note that
+C<unicode_strings> is automatically enabled within the scope of a
+S<C<use v5.12>> or greater.)
+
+Within the scope of C<use locale>, all non-ASCII Latin1 code points
+are quoted whether the string is encoded as UTF-8 or not. As mentioned
+above, locale does not affect the quoting of ASCII-range characters.
+This protects against those locales where characters such as C<"|"> are
+considered to be word characters.
+
+Otherwise, Perl quotes non-ASCII characters using an adaptation from
+Unicode (see L<http://www.unicode.org/reports/tr31/>).
+The only code points that are quoted are those that have any of the
+Unicode properties: Pattern_Syntax, Pattern_White_Space, White_Space,
+Default_Ignorable_Code_Point, or General_Category=Control.
+
+Of these properties, the two important ones are Pattern_Syntax and
+Pattern_White_Space. They have been set up by Unicode for exactly this
+purpose of deciding which characters in a regular expression pattern
+should be quoted. No character that can be in an identifier has these
+properties.
+
+Perl promises, that if we ever add regular expression pattern
+metacharacters to the dozen already defined
+(C<\ E<verbar> ( ) [ { ^ $ * + ? .>), that we will only use ones that have the
+Pattern_Syntax property. Perl also promises, that if we ever add
+characters that are considered to be white space in regular expressions
+(currently mostly affected by C</x>), they will all have the
+Pattern_White_Space property.
+
+Unicode promises that the set of code points that have these two
+properties will never change, so something that is not quoted in v5.16
+will never need to be quoted in any future Perl release. (Not all the
+code points that match Pattern_Syntax have actually had characters
+assigned to them; so there is room to grow, but they are quoted
+whether assigned or not. Perl, of course, would never use an
+unassigned code point as an actual metacharacter.)
+
+Quoting characters that have the other 3 properties is done to enhance
+the readability of the regular expression and not because they actually
+need to be quoted for regular expression purposes (characters with the
+White_Space property are likely to be indistinguishable on the page or
+screen from those with the Pattern_White_Space property; and the other
+two properties contain non-printing characters).
+
=item rand EXPR
X<rand> X<random>
=item rand
+=for Pod::Functions retrieve the next pseudorandom number
+
Returns a random fractional number greater than or equal to C<0> and less
than the value of EXPR. (EXPR should be positive.) If EXPR is
omitted, the value C<1> is used. Currently EXPR with the value C<0> is
@@ -4706,8 +5419,8 @@
on it in security-sensitive situations.> As of this writing, a
number of third-party CPAN modules offer random number generators
intended by their authors to be cryptographically secure,
-including: L<Math::Random::Secure>, L<Math::Random::MT::Perl>, and
-L<Math::TrulyRandom>.
+including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
+and L<Math::TrulyRandom>.
=item read FILEHANDLE,SCALAR,LENGTH,OFFSET
X<read> X<file, read>
@@ -4714,6 +5427,8 @@
=item read FILEHANDLE,SCALAR,LENGTH
+=for Pod::Functions fixed-length buffered input from a filehandle
+
Attempts to read LENGTH I<characters> of data into variable SCALAR
from the specified FILEHANDLE. Returns the number of characters
actually read, C<0> at end of file, or undef if there was an error (in
@@ -4729,7 +5444,8 @@
bytes before the result of the read is appended.
The call is implemented in terms of either Perl's or your system's native
-fread(3) library function. To get a true read(2) system call, see C<sysread>.
+fread(3) library function. To get a true read(2) system call, see
+L<sysread|/sysread FILEHANDLE,SCALAR,LENGTH,OFFSET>.
Note the I<characters>: depending on the status of the filehandle,
either (8-bit) bytes or characters are read. By default, all
@@ -4742,6 +5458,8 @@
=item readdir DIRHANDLE
X<readdir>
+=for Pod::Functions get a directory from a directory handle
+
Returns the next directory entry for a directory opened by C<opendir>.
If used in list context, returns all the rest of the entries in the
directory. If there are no more entries, returns the undefined value in
@@ -4755,7 +5473,7 @@
@dots = grep { /^\./ && -f "$some_dir/$_" } readdir($dh);
closedir $dh;
-As of Perl 5.11.2 you can use a bare C<readdir> in a C<while> loop,
+As of Perl 5.12 you can use a bare C<readdir> in a C<while> loop,
which will set C<$_> on every iteration.
opendir(my $dh, $some_dir) || die;
@@ -4764,11 +5482,20 @@
}
closedir $dh;
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious failures, put this sort of thing at the
+top of your file to signal that your code will work I<only> on Perls of a
+recent vintage:
+
+ use 5.012; # so readdir assigns to $_ in a lone while test
+
=item readline EXPR
=item readline
X<readline> X<gets> X<fgets>
+=for Pod::Functions fetch a record from a file
+
Reads from the filehandle whose typeglob is contained in EXPR (or from
C<*ARGV> if EXPR is not provided). In scalar context, each call reads and
returns the next line until end-of-file is reached, whereupon the
@@ -4800,7 +5527,7 @@
}
Note that you have can't handle C<readline> errors that way with the
-C<ARGV> filehandle. In that case, you have to open each element of
+C<ARGV> filehandle. In that case, you have to open each element of
C<@ARGV> yourself since C<eof> handles C<ARGV> differently.
foreach my $arg (@ARGV) {
@@ -4818,16 +5545,22 @@
=item readlink
+=for Pod::Functions determine where a symbolic link is pointing
+
Returns the value of a symbolic link, if symbolic links are
implemented. If not, raises an exception. If there is a system
error, returns the undefined value and sets C<$!> (errno). If EXPR is
omitted, uses C<$_>.
+Portability issues: L<perlport/readlink>.
+
=item readpipe EXPR
=item readpipe
X<readpipe>
+=for Pod::Functions execute a system command and collect standard output
+
EXPR is executed as a system command.
The collected standard output of the command is returned.
In scalar context, it comes back as a single (potentially
@@ -4841,6 +5574,8 @@
=item recv SOCKET,SCALAR,LENGTH,FLAGS
X<recv>
+=for Pod::Functions receive a message over a Socket
+
Receives a message on a socket. Attempts to receive LENGTH characters
of data into variable SCALAR from the specified SOCKET filehandle.
SCALAR will be grown or shrunk to the length actually read. Takes the
@@ -4861,12 +5596,18 @@
=item redo LABEL
X<redo>
+=item redo EXPR
+
=item redo
+=for Pod::Functions start this loop iteration over again
+
The C<redo> command restarts the loop block without evaluating the
conditional again. The C<continue> block, if any, is not executed. If
the LABEL is omitted, the command refers to the innermost enclosing
-loop. Programs that want to lie to themselves about what was just input
+loop. The C<redo EXPR> form, available starting in Perl 5.18.0, allows a
+label name to be computed at run time, and is otherwise identical to C<redo
+LABEL>. Programs that want to lie to themselves about what was just input
normally use this command:
# a simpleminded Pascal comment stripper
@@ -4897,13 +5638,20 @@
See also L</continue> for an illustration of how C<last>, C<next>, and
C<redo> work.
+Unlike most named operators, this has the same precedence as assignment.
+It is also exempt from the looks-like-a-function rule, so
+C<redo ("foo")."bar"> will cause "bar" to be part of the argument to
+C<redo>.
+
=item ref EXPR
X<ref> X<reference>
=item ref
+=for Pod::Functions find out the type of thing being referenced
+
Returns a non-empty string if EXPR is a reference, the empty
-string otherwise. If EXPR
+string otherwise. If EXPR
is not specified, C<$_> will be used. The value returned depends on the
type of thing the reference is a reference to.
Builtin types include:
@@ -4931,8 +5679,8 @@
}
The return value C<LVALUE> indicates a reference to an lvalue that is not
-a variable. You get this from taking the reference of function calls like
-C<pos()> or C<substr()>. C<VSTRING> is returned if the reference points
+a variable. You get this from taking the reference of function calls like
+C<pos()> or C<substr()>. C<VSTRING> is returned if the reference points
to a L<version string|perldata/"Version Strings">.
The result C<Regexp> indicates that the argument is a regular expression
@@ -4943,6 +5691,8 @@
=item rename OLDNAME,NEWNAME
X<rename> X<move> X<mv> X<ren>
+=for Pod::Functions change a filename
+
Changes the name of a file; an existing file NEWNAME will be
clobbered. Returns true for success, false otherwise.
@@ -4956,6 +5706,8 @@
For a platform independent C<move> function look at the L<File::Copy>
module.
+Portability issues: L<perlport/rename>.
+
=item require VERSION
X<require>
@@ -4963,6 +5715,8 @@
=item require
+=for Pod::Functions load in external functions from a library at runtime
+
Demands a version of Perl specified by VERSION, or demands some semantics
specified by EXPR or by C<$_> if EXPR is not supplied.
@@ -4979,7 +5733,8 @@
require v5.6.1; # run time version check
require 5.6.1; # ditto
- require 5.006_001; # ditto; preferred for backwards compatibility
+ require 5.006_001; # ditto; preferred for backwards
+ compatibility
Otherwise, C<require> demands that a library file be included if it
hasn't already been included. The file is included via the do-FILE
@@ -5052,7 +5807,7 @@
Now that you understand how C<require> looks for files with a
bareword argument, there is a little extra functionality going on behind
the scenes. Before C<require> looks for a "F<.pm>" extension, it will
-first look for a similar filename with a "F<.pmc>" extension. If this file
+first look for a similar filename with a "F<.pmc>" extension. If this file
is found, it will be loaded in place of any file ending in a "F<.pm>"
extension.
@@ -5075,7 +5830,7 @@
=item 2
-A reference to a subroutine. If there is no filehandle (previous item),
+A reference to a subroutine. If there is no filehandle (previous item),
then this subroutine is expected to generate one line of source code per
call, writing the line into C<$_> and returning 1, then finally at end of
file returning 0. If there is a filehandle, then the subroutine will be
@@ -5085,7 +5840,7 @@
=item 3
-Optional state for the subroutine. The state is passed in as C<$_[1]>. A
+Optional state for the subroutine. The state is passed in as C<$_[1]>. A
reference to the subroutine itself is passed in as C<$_[0]>.
=back
@@ -5136,7 +5891,7 @@
push @INC, Foo->new(...);
These hooks are also permitted to set the %INC entry
-corresponding to the files they have loaded. See L<perlvar/%INC>.
+corresponding to the files they have loaded. See L<perlvar/%INC>.
For a yet-more-powerful import facility, see L</use> and L<perlmod>.
@@ -5145,6 +5900,8 @@
=item reset
+=for Pod::Functions clear all variables of a given name
+
Generally used in a C<continue> block at the end of a loop to clear
variables and reset C<??> searches so that they work again. The
expression is interpreted as a list of single characters (hyphens
@@ -5169,10 +5926,12 @@
=item return
+=for Pod::Functions get out of a function early
+
Returns from a subroutine, C<eval>, or C<do FILE> with the value
given in EXPR. Evaluation of EXPR may be in list, scalar, or void
context, depending on how the return value will be used, and the context
-may vary from one execution to the next (see C<wantarray>). If no EXPR
+may vary from one execution to the next (see L</wantarray>). If no EXPR
is given, returns an empty list in list context, the undefined value in
scalar context, and (of course) nothing at all in void context.
@@ -5180,9 +5939,15 @@
or do FILE automatically returns the value of the last expression
evaluated.)
+Unlike most named operators, this is also exempt from the
+looks-like-a-function rule, so C<return ("foo")."bar"> will
+cause "bar" to be part of the argument to C<return>.
+
=item reverse LIST
X<reverse> X<rev> X<invert>
+=for Pod::Functions flip a string or a list
+
In list context, returns a list value consisting of the elements
of LIST in the opposite order. In scalar context, concatenates the
elements of LIST and returns a string value with all characters
@@ -5195,12 +5960,12 @@
Used without arguments in scalar context, reverse() reverses C<$_>.
$_ = "dlrow ,olleH";
- print reverse; # No output, list context
- print scalar reverse; # Hello, world
+ print reverse; # No output, list context
+ print scalar reverse; # Hello, world
Note that reversing an array to itself (as in C<@a = reverse @a>) will
-preserve non-existent elements whenever possible, i.e., for non magical
-arrays or tied arrays with C<EXISTS> and C<DELETE> methods.
+preserve non-existent elements whenever possible; i.e., for non-magical
+arrays or for tied arrays with C<EXISTS> and C<DELETE> methods.
This operator is also handy for inverting a hash, although there are some
caveats. If a value is duplicated in the original hash, only one of those
@@ -5213,14 +5978,20 @@
=item rewinddir DIRHANDLE
X<rewinddir>
+=for Pod::Functions reset directory handle
+
Sets the current position to the beginning of the directory for the
C<readdir> routine on DIRHANDLE.
+Portability issues: L<perlport/rewinddir>.
+
=item rindex STR,SUBSTR,POSITION
X<rindex>
=item rindex STR,SUBSTR
+=for Pod::Functions right-to-left substring search
+
Works just like index() except that it returns the position of the I<last>
occurrence of SUBSTR in STR. If POSITION is specified, returns the
last occurrence beginning at or before that position.
@@ -5230,6 +6001,8 @@
=item rmdir
+=for Pod::Functions remove a directory
+
Deletes the directory specified by FILENAME if that directory is
empty. If it succeeds it returns true; otherwise it returns false and
sets C<$!> (errno). If FILENAME is omitted, uses C<$_>.
@@ -5239,6 +6012,8 @@
=item s///
+=for Pod::Functions replace a pattern with a string
+
The substitution operator. See L<perlop/"Regexp Quote-Like Operators">.
=item say FILEHANDLE LIST
@@ -5250,12 +6025,15 @@
=item say
+=for Pod::Functions +say output a list to a filehandle, appending a newline
+
Just like C<print>, but implicitly appends a newline. C<say LIST> is
simply an abbreviation for C<{ local $\ = "\n"; print LIST }>. To use
FILEHANDLE without a LIST to print the contents of C<$_> to it, you must
use a real filehandle like C<FH>, not an indirect one like C<$fh>.
-This keyword is available only when the C<"say"> feature is enabled; see
+This keyword is available only when the C<"say"> feature
+is enabled, or when prefixed with C<CORE::>; see
L<feature>. Alternately, include a C<use v5.10> or later to the current
scope.
@@ -5262,6 +6040,8 @@
=item scalar EXPR
X<scalar> X<context>
+=for Pod::Functions force a scalar context
+
Forces EXPR to be interpreted in scalar context and returns the value
of EXPR.
@@ -5292,6 +6072,8 @@
=item seek FILEHANDLE,POSITION,WHENCE
X<seek> X<fseek> X<filehandle, position>
+=for Pod::Functions reposition file pointer for random-access I/O
+
Sets FILEHANDLE's position, just like the C<fseek> call of C<stdio>.
FILEHANDLE may be an expression whose value gives the name of the
filehandle. The values for WHENCE are C<0> to set the new position
@@ -5339,6 +6121,8 @@
=item seekdir DIRHANDLE,POS
X<seekdir>
+=for Pod::Functions reposition directory pointer
+
Sets the current position for the C<readdir> routine on DIRHANDLE. POS
must be a value returned by C<telldir>. C<seekdir> also has the same caveats
about possible directory compaction as the corresponding system library
@@ -5349,6 +6133,8 @@
=item select
+=for Pod::Functions reset default output or do I/O multiplexing
+
Returns the currently selected filehandle. If FILEHANDLE is supplied,
sets the new current default filehandle for output. This has two
effects: first, a C<write> or a C<print> without a filehandle
@@ -5374,6 +6160,8 @@
use IO::Handle;
STDERR->autoflush(1);
+Portability issues: L<perlport/select>.
+
=item select RBITS,WBITS,EBITS,TIMEOUT
X<select>
@@ -5381,8 +6169,8 @@
can be constructed using C<fileno> and C<vec>, along these lines:
$rin = $win = $ein = '';
- vec($rin,fileno(STDIN),1) = 1;
- vec($win,fileno(STDOUT),1) = 1;
+ vec($rin, fileno(STDIN), 1) = 1;
+ vec($win, fileno(STDOUT), 1) = 1;
$ein = $rin | $win;
If you want to select on many filehandles, you may wish to write a
@@ -5389,14 +6177,14 @@
subroutine like this:
sub fhbits {
- my(@fhlist) = split(' ',$_[0]);
- my($bits);
- for (@fhlist) {
- vec($bits,fileno($_),1) = 1;
+ my @fhlist = @_;
+ my $bits = "";
+ for my $fh (@fhlist) {
+ vec($bits, fileno($fh), 1) = 1;
}
- $bits;
+ return $bits;
}
- $rin = fhbits('STDIN TTY SOCK');
+ $rin = fhbits(*STDIN, *TTY, *MYSOCK);
The usual idiom is:
@@ -5423,21 +6211,28 @@
is implementation-dependent. See also L<perlport> for notes on the
portability of C<select>.
-On error, C<select> behaves like select(2): it returns
+On error, C<select> behaves just like select(2): it returns
-1 and sets C<$!>.
On some Unixes, select(2) may report a socket file descriptor as "ready for
reading" even when no data is available, and thus any subsequent C<read>
-would block. This can be avoided if you always use O_NONBLOCK on the
-socket. See select(2) and fcntl(2) for further details.
+would block. This can be avoided if you always use O_NONBLOCK on the
+socket. See select(2) and fcntl(2) for further details.
+The standard C<IO::Select> module provides a user-friendlier interface
+to C<select>, mostly because it does all the bit-mask work for you.
+
B<WARNING>: One should not attempt to mix buffered I/O (like C<read>
or <FH>) with C<select>, except as permitted by POSIX, and even
then only on POSIX systems. You have to use C<sysread> instead.
+Portability issues: L<perlport/select>.
+
=item semctl ID,SEMNUM,CMD,ARG
X<semctl>
+=for Pod::Functions SysV semaphore control operations
+
Calls the System V IPC function semctl(2). You'll probably have to say
use IPC::SysV;
@@ -5451,17 +6246,25 @@
See also L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::Semaphore>
documentation.
+Portability issues: L<perlport/semctl>.
+
=item semget KEY,NSEMS,FLAGS
X<semget>
+=for Pod::Functions get set of SysV semaphores
+
Calls the System V IPC function semget(2). Returns the semaphore id, or
the undefined value on error. See also
L<perlipc/"SysV IPC">, C<IPC::SysV>, C<IPC::SysV::Semaphore>
documentation.
+Portability issues: L<perlport/semget>.
+
=item semop KEY,OPSTRING
X<semop>
+=for Pod::Functions SysV semaphore operations
+
Calls the System V IPC function semop(2) for semaphore operations
such as signalling and waiting. OPSTRING must be a packed array of
semop structures. Each semop structure can be generated with
@@ -5477,11 +6280,15 @@
L<perlipc/"SysV IPC">, C<IPC::SysV>, and C<IPC::SysV::Semaphore>
documentation.
+Portability issues: L<perlport/semop>.
+
=item send SOCKET,MSG,FLAGS,TO
X<send>
=item send SOCKET,MSG,FLAGS
+=for Pod::Functions send a message over a socket
+
Sends a message on a socket. Attempts to send the scalar MSG to the SOCKET
filehandle. Takes the same flags as the system call of the same name. On
unconnected sockets, you must specify a destination to I<send to>, in which
@@ -5500,6 +6307,8 @@
=item setpgrp PID,PGRP
X<setpgrp> X<group>
+=for Pod::Functions set the process group of a process
+
Sets the current process group for the specified PID, C<0> for the current
process. Raises an exception when used on a machine that doesn't
implement POSIX setpgid(2) or BSD setpgrp(2). If the arguments are omitted,
@@ -5507,16 +6316,24 @@
accept any arguments, so only C<setpgrp(0,0)> is portable. See also
C<POSIX::setsid()>.
+Portability issues: L<perlport/setpgrp>.
+
=item setpriority WHICH,WHO,PRIORITY
X<setpriority> X<priority> X<nice> X<renice>
+=for Pod::Functions set a process's nice value
+
Sets the current priority for a process, a process group, or a user.
(See setpriority(2).) Raises an exception when used on a machine
that doesn't implement setpriority(2).
+Portability issues: L<perlport/setpriority>.
+
=item setsockopt SOCKET,LEVEL,OPTNAME,OPTVAL
X<setsockopt>
+=for Pod::Functions set some socket options
+
Sets the socket option requested. Returns C<undef> on error.
Use integer constants provided by the C<Socket> module for
LEVEL and OPNAME. Values for LEVEL can also be obtained from
@@ -5528,6 +6345,8 @@
use Socket qw(IPPROTO_TCP TCP_NODELAY);
setsockopt($socket, IPPROTO_TCP, TCP_NODELAY, 1);
+Portability issues: L<perlport/setsockopt>.
+
=item shift ARRAY
X<shift>
@@ -5535,6 +6354,8 @@
=item shift
+=for Pod::Functions remove the first element of an array, and return it
+
Shifts the first value of the array off and returns it, shortening the
array by 1 and moving everything down. If there are no elements in the
array, returns the undefined value. If ARRAY is omitted, shifts the
@@ -5548,6 +6369,13 @@
automatically. This aspect of C<shift> is considered highly experimental.
The exact behaviour may change in a future version of Perl.
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.014; # so push/pop/etc work on scalars (experimental)
+
See also C<unshift>, C<push>, and C<pop>. C<shift> and C<unshift> do the
same thing to the left end of an array that C<pop> and C<push> do to the
right end.
@@ -5555,6 +6383,8 @@
=item shmctl ID,CMD,ARG
X<shmctl>
+=for Pod::Functions SysV shared memory operations
+
Calls the System V IPC function shmctl. You'll probably have to say
use IPC::SysV;
@@ -5565,19 +6395,29 @@
true" for zero; and the actual return value otherwise.
See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
+Portability issues: L<perlport/shmctl>.
+
=item shmget KEY,SIZE,FLAGS
X<shmget>
+=for Pod::Functions get SysV shared memory segment identifier
+
Calls the System V IPC function shmget. Returns the shared memory
segment id, or C<undef> on error.
See also L<perlipc/"SysV IPC"> and C<IPC::SysV> documentation.
+Portability issues: L<perlport/shmget>.
+
=item shmread ID,VAR,POS,SIZE
X<shmread>
X<shmwrite>
+=for Pod::Functions read SysV shared memory
+
=item shmwrite ID,STRING,POS,SIZE
+=for Pod::Functions write SysV shared memory
+
Reads or writes the System V shared memory segment ID starting at
position POS for size SIZE by attaching to it, copying in/out, and
detaching from it. When reading, VAR must be a variable that will
@@ -5584,12 +6424,16 @@
hold the data read. When writing, if STRING is too long, only SIZE
bytes are used; if STRING is too short, nulls are written to fill out
SIZE bytes. Return true if successful, false on error.
-shmread() taints the variable. See also L<perlipc/"SysV IPC">,
+shmread() taints the variable. See also L<perlipc/"SysV IPC">,
C<IPC::SysV>, and the C<IPC::Shareable> module from CPAN.
+Portability issues: L<perlport/shmread> and L<perlport/shmwrite>.
+
=item shutdown SOCKET,HOW
X<shutdown>
+=for Pod::Functions close down just half of a socket connection
+
Shuts down a socket connection in the manner indicated by HOW, which
has the same interpretation as in the syscall of the same name.
@@ -5612,6 +6456,8 @@
=item sin
+=for Pod::Functions return the sine of a number
+
Returns the sine of EXPR (expressed in radians). If EXPR is omitted,
returns sine of C<$_>.
@@ -5625,6 +6471,8 @@
=item sleep
+=for Pod::Functions block for some number of seconds
+
Causes the script to sleep for (integer) EXPR seconds, or forever if no
argument is given. Returns the integer number of seconds actually slept.
@@ -5650,7 +6498,7 @@
distribution) provides usleep(). You may also use Perl's four-argument
version of select() leaving the first three arguments undefined, or you
might be able to use the C<syscall> interface to access setitimer(2) if
-your system supports it. See L<perlfaq8> for details.
+your system supports it. See L<perlfaq8> for details.
See also the POSIX module's C<pause> function.
@@ -5657,6 +6505,8 @@
=item socket SOCKET,DOMAIN,TYPE,PROTOCOL
X<socket>
+=for Pod::Functions create a socket
+
Opens a socket of the specified kind and attaches it to filehandle
SOCKET. DOMAIN, TYPE, and PROTOCOL are specified the same as for
the syscall of the same name. You should C<use Socket> first
@@ -5670,6 +6520,8 @@
=item socketpair SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL
X<socketpair>
+=for Pod::Functions create a pair of sockets
+
Creates an unnamed pair of sockets in the specified domain, of the
specified type. DOMAIN, TYPE, and PROTOCOL are specified the same as
for the syscall of the same name. If unimplemented, raises an exception.
@@ -5691,6 +6543,8 @@
emulate socketpair using IP sockets to localhost if your system implements
sockets but not socketpair.
+Portability issues: L<perlport/socketpair>.
+
=item sort SUBNAME LIST
X<sort> X<qsort> X<quicksort> X<mergesort>
@@ -5698,6 +6552,8 @@
=item sort LIST
+=for Pod::Functions sort a list of values
+
In list context, this sorts the LIST and returns the sorted list value.
In scalar context, the behaviour of C<sort()> is undefined.
@@ -5718,6 +6574,10 @@
below). Note that in the latter case, it is usually highly counter-productive
to declare $a and $b as lexicals.
+If the subroutine is an XSUB, the elements to be compared are pushed on to
+the stack, the way arguments are usually passed to XSUBs. $a and $b are
+not set.
+
The values to be compared are always passed by reference and should not
be modified.
@@ -5724,7 +6584,8 @@
You also cannot exit out of the sort block or subroutine using any of the
loop control operators described in L<perlsyn> or with C<goto>.
-When C<use locale> is in effect, C<sort LIST> sorts LIST according to the
+When C<use locale> (but not C<use locale 'not_characters'>) is in
+effect, C<sort LIST> sorts LIST according to the
current collation locale. See L<perllocale>.
sort() returns aliases into the original list, much as a for loop's index
@@ -5751,32 +6612,32 @@
# sort lexically
@articles = sort @files;
-
+
# same thing, but with explicit sort routine
@articles = sort {$a cmp $b} @files;
-
+
# now case-insensitively
- @articles = sort {uc($a) cmp uc($b)} @files;
-
+ @articles = sort {fc($a) cmp fc($b)} @files;
+
# same thing in reversed order
@articles = sort {$b cmp $a} @files;
-
+
# sort numerically ascending
@articles = sort {$a <=> $b} @files;
-
+
# sort numerically descending
@articles = sort {$b <=> $a} @files;
-
+
# this sorts the %age hash by value instead of key
# using an in-line function
@eldest = sort { $age{$b} <=> $age{$a} } keys %age;
-
+
# sort using explicit subroutine name
sub byage {
- $age{$a} <=> $age{$b}; # presuming numeric
+ $age{$a} <=> $age{$b}; # presuming numeric
}
@sortedclass = sort byage @class;
-
+
sub backwards { $b cmp $a }
@harry = qw(dog cat x Cain Abel);
@george = qw(gone chased yz Punished Axed);
@@ -5793,8 +6654,8 @@
my @new = sort {
($b =~ /=(\d+)/)[0] <=> ($a =~ /=(\d+)/)[0]
- ||
- uc($a) cmp uc($b)
+ ||
+ fc($a) cmp fc($b)
} @old;
# same thing, but much more efficiently;
@@ -5803,41 +6664,41 @@
my @nums = @caps = ();
for (@old) {
push @nums, ( /=(\d+)/ ? $1 : undef );
- push @caps, uc($_);
+ push @caps, fc($_);
}
my @new = @old[ sort {
- $nums[$b] <=> $nums[$a]
- ||
- $caps[$a] cmp $caps[$b]
- } 0..$#old
- ];
+ $nums[$b] <=> $nums[$a]
+ ||
+ $caps[$a] cmp $caps[$b]
+ } 0..$#old
+ ];
# same thing, but without any temps
@new = map { $_->[0] }
sort { $b->[1] <=> $a->[1]
- ||
- $a->[2] cmp $b->[2]
- } map { [$_, /=(\d+)/, uc($_)] } @old;
+ ||
+ $a->[2] cmp $b->[2]
+ } map { [$_, /=(\d+)/, fc($_)] } @old;
# using a prototype allows you to use any comparison subroutine
# as a sort subroutine (including other package's subroutines)
package other;
- sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are not set here
-
+ sub backwards ($$) { $_[1] cmp $_[0]; } # $a and $b are
+ # not set here
package main;
@new = sort other::backwards @old;
-
+
# guarantee stability, regardless of algorithm
use sort 'stable';
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
-
+
# force use of mergesort (not portable outside Perl 5.8)
use sort '_mergesort'; # note discouraging _
@new = sort { substr($a, 3, 5) cmp substr($b, 3, 5) } @old;
Warning: syntactical care is required when sorting the list returned from
-a function. If you want to sort the list returned by the function call
+a function. If you want to sort the list returned by the function call
C<find_records(@key)>, you can use:
@contact = sort { $a cmp $b } find_records @key;
@@ -5870,8 +6731,7 @@
well-defined.
Because C<< <=> >> returns C<undef> when either operand is C<NaN>
-(not-a-number), and laso because C<sort> raises an exception unless the
-result of a comparison is defined, be careful when sorting with a
+(not-a-number), be careful when sorting with a
comparison function like C<< $a <=> $b >> any lists that might contain a
C<NaN>. The following example takes advantage that C<NaN != NaN> to
eliminate any C<NaN>s from the input list.
@@ -5887,6 +6747,8 @@
=item splice ARRAY or EXPR
+=for Pod::Functions add or remove elements anywhere in an array
+
Removes the elements designated by OFFSET and LENGTH from an array, and
replaces them with the elements of LIST, if any. In list context,
returns the elements removed from the array. In scalar context,
@@ -5896,11 +6758,11 @@
If LENGTH is omitted, removes everything from OFFSET onward.
If LENGTH is negative, removes the elements from OFFSET onward
except for -LENGTH elements at the end of the array.
-If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
+If both OFFSET and LENGTH are omitted, removes everything. If OFFSET is
past the end of the array, Perl issues a warning, and splices at the
end of the array.
-The following equivalences hold (assuming C<< $[ == 0 and $#a >= $i >> )
+The following equivalences hold (assuming C<< $#a >= $i >> )
push(@a,$x,$y) splice(@a, at a,0,$x,$y)
pop(@a) splice(@a,-1)
@@ -5926,6 +6788,13 @@
automatically. This aspect of C<splice> is considered highly experimental.
The exact behaviour may change in a future version of Perl.
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.014; # so push/pop/etc work on scalars (experimental)
+
=item split /PATTERN/,EXPR,LIMIT
X<split>
@@ -5935,124 +6804,165 @@
=item split
-Splits the string EXPR into a list of strings and returns that list. By
-default, empty leading fields are preserved, and empty trailing ones are
-deleted. (If all fields are empty, they are considered to be trailing.)
+=for Pod::Functions split up a string using a regexp delimiter
-In scalar context, returns the number of fields found.
+Splits the string EXPR into a list of strings and returns the
+list in list context, or the size of the list in scalar context.
-If EXPR is omitted, splits the C<$_> string. If PATTERN is also omitted,
-splits on whitespace (after skipping any leading whitespace). Anything
-matching PATTERN is taken to be a delimiter separating the fields. (Note
-that the delimiter may be longer than one character.)
+If only PATTERN is given, EXPR defaults to C<$_>.
+Anything in EXPR that matches PATTERN is taken to be a separator
+that separates the EXPR into substrings (called "I<fields>") that
+do B<not> include the separator. Note that a separator may be
+longer than one character or even have no characters at all (the
+empty string, which is a zero-width match).
+
+The PATTERN need not be constant; an expression may be used
+to specify a pattern that varies at runtime.
+
+If PATTERN matches the empty string, the EXPR is split at the match
+position (between characters). As an example, the following:
+
+ print join(':', split('b', 'abc')), "\n";
+
+uses the 'b' in 'abc' as a separator to produce the output 'a:c'.
+However, this:
+
+ print join(':', split('', 'abc')), "\n";
+
+uses empty string matches as separators to produce the output
+'a:b:c'; thus, the empty string may be used to split EXPR into a
+list of its component characters.
+
+As a special case for C<split>, the empty pattern given in
+L<match operator|perlop/"m/PATTERN/msixpodualgc"> syntax (C<//>) specifically matches the empty string, which is contrary to its usual
+interpretation as the last successful match.
+
+If PATTERN is C</^/>, then it is treated as if it used the
+L<multiline modifier|perlreref/OPERATORS> (C</^/m>), since it
+isn't much use otherwise.
+
+As another special case, C<split> emulates the default behavior of the
+command line tool B<awk> when the PATTERN is either omitted or a I<literal
+string> composed of a single space character (such as S<C<' '>> or
+S<C<"\x20">>, but not e.g. S<C</ />>). In this case, any leading
+whitespace in EXPR is removed before splitting occurs, and the PATTERN is
+instead treated as if it were C</\s+/>; in particular, this means that
+I<any> contiguous whitespace (not just a single space character) is used as
+a separator. However, this special treatment can be avoided by specifying
+the pattern S<C</ />> instead of the string S<C<" ">>, thereby allowing
+only a single space character to be a separator. In earlier Perl's this
+special case was restricted to the use of a plain S<C<" ">> as the
+pattern argument to split, in Perl 5.18.0 and later this special case is
+triggered by any expression which evaluates as the simple string S<C<" ">>.
+
+If omitted, PATTERN defaults to a single space, S<C<" ">>, triggering
+the previously described I<awk> emulation.
+
If LIMIT is specified and positive, it represents the maximum number
-of fields the EXPR will be split into, though the actual number of
-fields returned depends on the number of times PATTERN matches within
-EXPR. If LIMIT is unspecified or zero, trailing null fields are
-stripped (which potential users of C<pop> would do well to remember).
-If LIMIT is negative, it is treated as if an arbitrarily large LIMIT
-had been specified. Note that splitting an EXPR that evaluates to the
-empty string always returns the empty list, regardless of the LIMIT
-specified.
+of fields into which the EXPR may be split; in other words, LIMIT is
+one greater than the maximum number of times EXPR may be split. Thus,
+the LIMIT value C<1> means that EXPR may be split a maximum of zero
+times, producing a maximum of one field (namely, the entire value of
+EXPR). For instance:
-A pattern matching the empty string (not to be confused with
-an empty pattern C<//>, which is just one member of the set of patterns
-matching the epmty string), splits EXPR into individual
-characters. For example:
+ print join(':', split(//, 'abc', 1)), "\n";
- print join(':', split(/ */, 'hi there')), "\n";
+produces the output 'abc', and this:
-produces the output 'h:i:t:h:e:r:e'.
+ print join(':', split(//, 'abc', 2)), "\n";
-As a special case for C<split>, the empty pattern C<//> specifically
-matches the empty string; this is not be confused with the normal use
-of an empty pattern to mean the last successful match. So to split
-a string into individual characters, the following:
+produces the output 'a:bc', and each of these:
- print join(':', split(//, 'hi there')), "\n";
+ print join(':', split(//, 'abc', 3)), "\n";
+ print join(':', split(//, 'abc', 4)), "\n";
-produces the output 'h:i: :t:h:e:r:e'.
+produces the output 'a:b:c'.
-Empty leading fields are produced when there are positive-width matches at
-the beginning of the string; a zero-width match at the beginning of
-the string does not produce an empty field. For example:
+If LIMIT is negative, it is treated as if it were instead arbitrarily
+large; as many fields as possible are produced.
- print join(':', split(/(?=\w)/, 'hi there!'));
+If LIMIT is omitted (or, equivalently, zero), then it is usually
+treated as if it were instead negative but with the exception that
+trailing empty fields are stripped (empty leading fields are always
+preserved); if all fields are empty, then all fields are considered to
+be trailing (and are thus stripped in this case). Thus, the following:
-produces the output 'h:i :t:h:e:r:e!'. Empty trailing fields, on the other
-hand, are produced when there is a match at the end of the string (and
-when LIMIT is given and is not 0), regardless of the length of the match.
-For example:
+ print join(':', split(',', 'a,b,c,,,')), "\n";
- print join(':', split(//, 'hi there!', -1)), "\n";
- print join(':', split(/\W/, 'hi there!', -1)), "\n";
+produces the output 'a:b:c', but the following:
-produce the output 'h:i: :t:h:e:r:e:!:' and 'hi:there:', respectively,
-both with an empty trailing field.
+ print join(':', split(',', 'a,b,c,,,', -1)), "\n";
-The LIMIT parameter can be used to split a line partially
+produces the output 'a:b:c:::'.
- ($login, $passwd, $remainder) = split(/:/, $_, 3);
+In time-critical applications, it is worthwhile to avoid splitting
+into more fields than necessary. Thus, when assigning to a list,
+if LIMIT is omitted (or zero), then LIMIT is treated as though it
+were one larger than the number of variables in the list; for the
+following, LIMIT is implicitly 3:
-When assigning to a list, if LIMIT is omitted, or zero, Perl supplies
-a LIMIT one larger than the number of variables in the list, to avoid
-unnecessary work. For the list above LIMIT would have been 4 by
-default. In time critical applications it behooves you not to split
-into more fields than you really need.
+ ($login, $passwd) = split(/:/);
-If the PATTERN contains parentheses, additional list elements are
-created from each matching substring in the delimiter.
+Note that splitting an EXPR that evaluates to the empty string always
+produces zero fields, regardless of the LIMIT specified.
- split(/([,-])/, "1-10,20", 3);
+An empty leading field is produced when there is a positive-width
+match at the beginning of EXPR. For instance:
-produces the list value
+ print join(':', split(/ /, ' abc')), "\n";
- (1, '-', 10, ',', 20)
+produces the output ':abc'. However, a zero-width match at the
+beginning of EXPR never produces an empty field, so that:
-If you had the entire header of a normal Unix email message in $header,
-you could split it up into fields and their values this way:
+ print join(':', split(//, ' abc'));
- $header =~ s/\n(?=\s)//g; # fix continuation lines
- %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header);
+produces the output S<' :a:b:c'> (rather than S<': :a:b:c'>).
-The pattern C</PATTERN/> may be replaced with an expression to specify
-patterns that vary at runtime. (To do runtime compilation only once,
-use C</$variable/o>.)
+An empty trailing field, on the other hand, is produced when there is a
+match at the end of EXPR, regardless of the length of the match
+(of course, unless a non-zero LIMIT is given explicitly, such fields are
+removed, as in the last example). Thus:
-As a special case, specifying a PATTERN of space (S<C<' '>>) will split on
-white space just as C<split> with no arguments does. Thus, S<C<split(' ')>> can
-be used to emulate B<awk>'s default behavior, whereas S<C<split(/ /)>>
-will give you as many initial null fields (empty string) as there are leading spaces.
-A C<split> on C</\s+/> is like a S<C<split(' ')>> except that any leading
-whitespace produces a null first field. A C<split> with no arguments
-really does a S<C<split(' ', $_)>> internally.
+ print join(':', split(//, ' abc', -1)), "\n";
-A PATTERN of C</^/> is treated as if it were C</^/m>, since it isn't
-much use otherwise.
+produces the output S<' :a:b:c:'>.
-Example:
+If the PATTERN contains
+L<capturing groups|perlretut/Grouping things and hierarchical matching>,
+then for each separator, an additional field is produced for each substring
+captured by a group (in the order in which the groups are specified,
+as per L<backreferences|perlretut/Backreferences>); if any group does not
+match, then it captures the C<undef> value instead of a substring. Also,
+note that any such additional field is produced whenever there is a
+separator (that is, whenever a split occurs), and such an additional field
+does B<not> count towards the LIMIT. Consider the following expressions
+evaluated in list context (each returned list is provided in the associated
+comment):
- open(PASSWD, '/etc/passwd');
- while (<PASSWD>) {
- chomp;
- ($login, $passwd, $uid, $gid,
- $gcos, $home, $shell) = split(/:/);
- #...
- }
+ split(/-|,/, "1-10,20", 3)
+ # ('1', '10', '20')
-As with regular pattern matching, any capturing parentheses that are not
-matched in a C<split()> will be set to C<undef> when returned:
+ split(/(-|,)/, "1-10,20", 3)
+ # ('1', '-', '10', ',', '20')
- @fields = split /(A)|B/, "1A2B3";
- # @fields is (1, 'A', 2, undef, 3)
+ split(/-|(,)/, "1-10,20", 3)
+ # ('1', undef, '10', ',', '20')
+ split(/(-)|,/, "1-10,20", 3)
+ # ('1', '-', '10', undef, '20')
+
+ split(/(-)|(,)/, "1-10,20", 3)
+ # ('1', '-', undef, '10', undef, ',', '20')
+
=item sprintf FORMAT, LIST
X<sprintf>
+=for Pod::Functions formatted print into a string
+
Returns a string formatted by the usual C<printf> conventions of the C
library function C<sprintf>. See below for more details
-and see C<sprintf(3)> or C<printf(3)> on your system for an explanation of
+and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of
the general principles.
For example:
@@ -6070,7 +6980,8 @@
therefore unavailable from Perl.
Unlike C<printf>, C<sprintf> does not do what you probably mean when you
-pass it an array as your first argument. The array is given scalar context,
+pass it an array as your first argument.
+The array is given scalar context,
and instead of using the 0th element of the array as the format, Perl will
use the count of elements in the array as the format, which is almost never
useful.
@@ -6097,7 +7008,7 @@
%B like %b, but using an upper-case "B" with the # flag
%p a pointer (outputs the Perl value's address in hexadecimal)
%n special: *stores* the number of characters output so far
- into the next variable in the parameter list
+ into the next argument in the parameter list
Finally, for backward (and we do mean "backward") compatibility, Perl
permits these unnecessary but widely-supported conversions:
@@ -6122,7 +7033,7 @@
=item format parameter index
-An explicit format parameter index, such as C<2$>. By default sprintf
+An explicit format parameter index, such as C<2$>. By default sprintf
will format the next unused argument in the list, but this allows you
to take the arguments out of order:
@@ -6170,9 +7081,9 @@
=item vector flag
This flag tells Perl to interpret the supplied string as a vector of
-integers, one for each character in the string. Perl applies the format to
+integers, one for each character in the string. Perl applies the format to
each integer in turn, then joins the resulting strings with a separator (a
-dot C<.> by default). This can be useful for displaying ordinal values of
+dot C<.> by default). This can be useful for displaying ordinal values of
characters in arbitrary strings:
printf "%vd", "AB\x{100}"; # prints "65.66.256"
@@ -6187,20 +7098,21 @@
You can also explicitly specify the argument number to use for
the join string using something like C<*2$v>; for example:
- printf '%*4$vX %*4$vX %*4$vX', @addr[1..3], ":"; # 3 IPv6 addresses
+ printf '%*4$vX %*4$vX %*4$vX', # 3 IPv6 addresses
+ @addr[1..3], ":";
=item (minimum) width
Arguments are usually formatted to be only as wide as required to
-display the given value. You can override the width by putting
+display the given value. You can override the width by putting
a number here, or get the width from the next argument (with C<*>)
or from a specified argument (e.g., with C<*2$>):
- printf "<%s>", "a"; # prints "<a>"
- printf "<%6s>", "a"; # prints "< a>"
- printf "<%*s>", 6, "a"; # prints "< a>"
- printf "<%*2$s>", "a", 6; # prints "< a>"
- printf "<%2s>", "long"; # prints "<long>" (does not truncate)
+ printf "<%s>", "a"; # prints "<a>"
+ printf "<%6s>", "a"; # prints "< a>"
+ printf "<%*s>", 6, "a"; # prints "< a>"
+ printf '<%*2$s>', "a", 6; # prints "< a>"
+ printf "<%2s>", "long"; # prints "<long>" (does not truncate)
If a field width obtained through C<*> is negative, it has the same
effect as the C<-> flag: left-justification.
@@ -6222,7 +7134,7 @@
printf '<%.1e>', 10; # prints "<1.0e+01>"
For "g" and "G", this specifies the maximum number of digits to show,
-including thoe prior to the decimal point and those after it; for
+including those prior to the decimal point and those after it; for
example:
# These examples are subject to system-specific variation.
@@ -6279,27 +7191,34 @@
but it is intended that this will be possible in the future, for
example using C<.*2$>:
- printf "<%.*2$x>", 1, 6; # INVALID, but in future will print "<000001>"
+ printf '<%.*2$x>', 1, 6; # INVALID, but in future will print
+ # "<000001>"
=item size
For numeric conversions, you can specify the size to interpret the
-number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
+number as using C<l>, C<h>, C<V>, C<q>, C<L>, or C<ll>. For integer
conversions (C<d u o x X b i D U O>), numbers are usually assumed to be
whatever the default integer size is on your platform (usually 32 or 64
bits), but you can override this to use instead one of the standard C types,
as supported by the compiler used to build Perl:
- hh interpret integer as C type "char" or "unsigned char"
- on Perl 5.14 or later
- h interpret integer as C type "short" or "unsigned short"
- j intepret integer as C type "intmax_t" on Perl 5.14
- or later, and only with a C99 compiler (unportable)
- l interpret integer as C type "long" or "unsigned long"
- q, L, or ll interpret integer as C type "long long", "unsigned long long",
- or "quad" (typically 64-bit integers)
- t intepret integer as C type "ptrdiff_t" on Perl 5.14 or later
- z intepret integer as C type "size_t" on Perl 5.14 or later
+ hh interpret integer as C type "char" or "unsigned
+ char" on Perl 5.14 or later
+ h interpret integer as C type "short" or
+ "unsigned short"
+ j interpret integer as C type "intmax_t" on Perl
+ 5.14 or later, and only with a C99 compiler
+ (unportable)
+ l interpret integer as C type "long" or
+ "unsigned long"
+ q, L, or ll interpret integer as C type "long long",
+ "unsigned long long", or "quad" (typically
+ 64-bit integers)
+ t interpret integer as C type "ptrdiff_t" on Perl
+ 5.14 or later
+ z interpret integer as C type "size_t" on Perl 5.14
+ or later
As of 5.14, none of these raises an exception if they are not supported on
your platform. However, if warnings are enabled, a warning of the
@@ -6316,7 +7235,8 @@
You can find out whether your Perl supports quads via L<Config>:
use Config;
- if ($Config{use64bitint} eq "define" || $Config{longsize} >= 8) {
+ if ($Config{use64bitint} eq "define"
+ || $Config{longsize} >= 8) {
print "Nice quads!\n";
}
@@ -6323,7 +7243,7 @@
For floating-point conversions (C<e f g E F G>), numbers are usually assumed
to be the default floating-point size on your platform (double or long double),
but you can force "long double" with C<q>, C<L>, or C<ll> if your
-platform supports them. You can find out whether your Perl supports long
+platform supports them. You can find out whether your Perl supports long
doubles via L<Config>:
use Config;
@@ -6334,7 +7254,7 @@
use Config;
if ($Config{uselongdouble} eq "define") {
- print "long doubles by default\n";
+ print "long doubles by default\n";
}
It can also be that long doubles and doubles are the same thing:
@@ -6350,7 +7270,7 @@
=item order of arguments
Normally, sprintf() takes the next unused argument as the value to
-format for each format specification. If the format specification
+format for each format specification. If the format specification
uses C<*> to require additional arguments, these are consumed from
the argument list in the order they appear in the format
specification I<before> the value to format. Where an argument is
@@ -6365,7 +7285,7 @@
uses C<$a> for the width, C<$b> for the precision, and C<$c>
as the value to format; while:
- printf "<%*1$.*s>", $a, $b;
+ printf '<%*1$.*s>', $a, $b;
would use C<$a> for the width and precision, and C<$b> as the
value to format.
@@ -6373,14 +7293,15 @@
Here are some more examples; be aware that when using an explicit
index, the C<$> may need escaping:
- printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
- printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
- printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
- printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
+ printf "%2\$d %d\n", 12, 34; # will print "34 12\n"
+ printf "%2\$d %d %d\n", 12, 34; # will print "34 12 34\n"
+ printf "%3\$d %d %d\n", 12, 34, 56; # will print "56 12 34\n"
+ printf "%2\$*3\$d %d\n", 12, 34, 3; # will print " 34 12\n"
=back
-If C<use locale> is in effect and POSIX::setlocale() has been called,
+If C<use locale> (including C<use locale 'not_characters'>) is in effect
+and POSIX::setlocale() has been called,
the character used for the decimal separator in formatted floating-point
numbers is affected by the LC_NUMERIC locale. See L<perllocale>
and L<POSIX>.
@@ -6390,6 +7311,8 @@
=item sqrt
+=for Pod::Functions square root function
+
Return the positive square root of EXPR. If EXPR is omitted, uses
C<$_>. Works only for non-negative operands unless you've
loaded the C<Math::Complex> module.
@@ -6402,27 +7325,25 @@
=item srand
+=for Pod::Functions seed the random number generator
+
Sets and returns the random number seed for the C<rand> operator.
-The point of the function is to "seed" the C<rand> function so that
-C<rand> can produce a different sequence each time you run your
-program. When called with a parameter, C<srand> uses that for the seed;
-otherwise it (semi-)randomly chooses a seed. In either case, starting with
-Perl 5.14, it returns the seed.
+The point of the function is to "seed" the C<rand> function so that C<rand>
+can produce a different sequence each time you run your program. When
+called with a parameter, C<srand> uses that for the seed; otherwise it
+(semi-)randomly chooses a seed. In either case, starting with Perl 5.14,
+it returns the seed. To signal that your code will work I<only> on Perls
+of a recent vintage:
+ use 5.014; # so srand returns the seed
+
If C<srand()> is not called explicitly, it is called implicitly without a
-parameter at the first use of the C<rand> operator. However, this was not true
-of versions of Perl before 5.004, so if your script will run under older
-Perl versions, it should call C<srand>; otherwise most programs won't call
-C<srand()> at all.
-
-But there are a few situations in recent Perls where programs are likely to
-want to call C<srand>. One is for generating predictable results generally for
+parameter at the first use of the C<rand> operator.
+However, there are a few situations where programs are likely to
+want to call C<srand>. One is for generating predictable results, generally for
testing or debugging. There, you use C<srand($seed)>, with the same C<$seed>
-each time. Another other case is where you need a cryptographically-strong
-starting point rather than the generally acceptable default, which is based on
-time of day, process ID, and memory allocation, or the F</dev/urandom> device
-if available. And still another case is that you may want to call C<srand()>
+each time. Another case is that you may want to call C<srand()>
after a C<fork()> to avoid child processes sharing the same seed value as the
parent (and consequently each other).
@@ -6436,36 +7357,18 @@
produce the same results as C<srand(42.1)>. To be safe, always pass
C<srand> an integer.
-In versions of Perl prior to 5.004 the default seed was just the
-current C<time>. This isn't a particularly good seed, so many old
-programs supply their own seed value (often C<time ^ $$> or C<time ^
-($$ + ($$ << 15))>), but that isn't necessary any more.
-
-For cryptographic purposes, however, you need something much more random
-than the default seed. Checksumming the compressed output of one or more
-rapidly changing operating system status programs is the usual method. For
-example:
-
- srand (time ^ $$ ^ unpack "%L*", `ps axww | gzip -f`);
-
-If you're particularly concerned with this, search the CPAN for
-random number generator modules instead of rolling out your own.
-
-Frequently called programs (like CGI scripts) that simply use
-
- time ^ $$
-
-for a seed can fall prey to the mathematical property that
-
- a^b == (a+1)^(b+1)
-
-one-third of the time. So don't do that.
-
A typical use of the returned seed is for a test program which has too many
combinations to test comprehensively in the time available to it each run. It
can test a random subset each time, and should there be a failure, log the seed
used for that run so that it can later be used to reproduce the same results.
+B<C<rand()> is not cryptographically secure. You should not rely
+on it in security-sensitive situations.> As of this writing, a
+number of third-party CPAN modules offer random number generators
+intended by their authors to be cryptographically secure,
+including: L<Data::Entropy>, L<Crypt::Random>, L<Math::Random::Secure>,
+and L<Math::TrulyRandom>.
+
=item stat FILEHANDLE
X<stat> X<file, status> X<ctime>
@@ -6475,6 +7378,8 @@
=item stat
+=for Pod::Functions get a file's status information
+
Returns a 13-element list giving the status info for a file, either
the file opened via FILEHANDLE or DIRHANDLE, or named by EXPR. If EXPR is
omitted, it stats C<$_> (not C<_>!). Returns the empty list if C<stat> fails. Typically
@@ -6498,12 +7403,14 @@
8 atime last access time in seconds since the epoch
9 mtime last modify time in seconds since the epoch
10 ctime inode change time in seconds since the epoch (*)
- 11 blksize preferred block size for file system I/O
- 12 blocks actual number of blocks allocated
+ 11 blksize preferred I/O size in bytes for interacting with the
+ file (may vary from file to file)
+ 12 blocks actual number of system-specific blocks allocated
+ on disk (often, but not always, 512 bytes each)
(The epoch was at 00:00 January 1, 1970 GMT.)
-(*) Not all fields are supported on all filesystem types. Notably, the
+(*) Not all fields are supported on all filesystem types. Notably, the
ctime field is non-portable. In particular, you cannot expect it to be a
"creation time"; see L<perlport/"Files and Filesystems"> for details.
@@ -6563,26 +7470,29 @@
S_IRWXO S_IROTH S_IWOTH S_IXOTH
# Setuid/Setgid/Stickiness/SaveText.
- # Note that the exact meaning of these is system dependent.
+ # Note that the exact meaning of these is system-dependent.
S_ISUID S_ISGID S_ISVTX S_ISTXT
- # File types. Not necessarily all are available on your system.
+ # File types. Not all are necessarily available on
+ # your system.
- S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
+ S_IFREG S_IFDIR S_IFLNK S_IFBLK S_IFCHR
+ S_IFIFO S_IFSOCK S_IFWHT S_ENFMT
- # The following are compatibility aliases for S_IRUSR, S_IWUSR, S_IXUSR.
+ # The following are compatibility aliases for S_IRUSR,
+ # S_IWUSR, and S_IXUSR.
S_IREAD S_IWRITE S_IEXEC
and the C<S_IF*> functions are
- S_IMODE($mode) the part of $mode containing the permission bits
- and the setuid/setgid/sticky bits
+ S_IMODE($mode) the part of $mode containing the permission
+ bits and the setuid/setgid/sticky bits
- S_IFMT($mode) the part of $mode containing the file type
- which can be bit-anded with (for example) S_IFREG
- or with the following functions
+ S_IFMT($mode) the part of $mode containing the file type
+ which can be bit-anded with (for example)
+ S_IFREG or with the following functions
# The operators -f, -d, -l, -b, -c, -p, and -S.
@@ -6599,6 +7509,8 @@
about the C<S_*> constants. To get status info for a symbolic link
instead of the target file behind the link, use the C<lstat> function.
+Portability issues: L<perlport/stat>.
+
=item state EXPR
X<state>
@@ -6608,13 +7520,17 @@
=item state TYPE EXPR : ATTRS
-C<state> declares a lexically scoped variable, just like C<my> does.
+=for Pod::Functions +state declare and assign a persistent lexical variable
+
+C<state> declares a lexically scoped variable, just like C<my>.
However, those variables will never be reinitialized, contrary to
lexical variables that are reinitialized each time their enclosing block
is entered.
+See L<perlsub/"Persistent Private Variables"> for details.
C<state> variables are enabled only when the C<use feature "state"> pragma
-is in effect. See L<feature>.
+is in effect, unless the keyword is written as C<CORE::state>.
+See also L<feature>.
=item study SCALAR
X<study>
@@ -6621,6 +7537,8 @@
=item study
+=for Pod::Functions optimize input data for repeated searches
+
Takes extra time to study SCALAR (C<$_> if unspecified) in anticipation of
doing many pattern matches on the string before it is next modified.
This may or may not save time, depending on the nature and number of
@@ -6628,9 +7546,8 @@
frequencies in the string to be searched; you probably want to compare
run times with and without it to see which is faster. Those loops
that scan for many short constant strings (including the constant
-parts of more complex patterns) will benefit most. You may have only
-one C<study> active at a time: if you study a different scalar the first
-is "unstudied". (The way C<study> works is this: a linked list of every
+parts of more complex patterns) will benefit most.
+(The way C<study> works is this: a linked list of every
character in the string to be searched is made, so we know, for
example, where all the C<'k'> characters are. From each search string,
the rarest character is selected, based on some static frequency tables
@@ -6685,6 +7602,8 @@
=item sub NAME (PROTO) : ATTRS BLOCK
+=for Pod::Functions declare a subroutine, possibly anonymously
+
This is subroutine definition, not a real function I<per se>. Without a
BLOCK it's just a forward declaration. Without a NAME, it's an anonymous
function declaration, so does return a value: the CODE ref of the closure
@@ -6694,6 +7613,20 @@
references; see L<attributes> and L<Attribute::Handlers> for more
information about attributes.
+=item __SUB__
+X<__SUB__>
+
+=for Pod::Functions +current_sub the current subroutine, or C<undef> if not in a subroutine
+
+A special token that returns a reference to the current subroutine, or
+C<undef> outside of a subroutine.
+
+The behaviour of C<__SUB__> within a regex code block (such as C</(?{...})/>)
+is subject to change.
+
+This token is only available under C<use v5.16> or the "current_sub"
+feature. See L<feature>.
+
=item substr EXPR,OFFSET,LENGTH,REPLACEMENT
X<substr> X<substring> X<mid> X<left> X<right>
@@ -6701,9 +7634,10 @@
=item substr EXPR,OFFSET
+=for Pod::Functions get or alter a portion of a string
+
Extracts a substring out of EXPR and returns it. First character is at
-offset C<0> (or whatever you've set C<$[> to (but B<<don't do that>)).
-If OFFSET is negative (or more precisely, less than C<$[>), starts
+offset zero. If OFFSET is negative, starts
that far back from the end of the string. If LENGTH is omitted, returns
everything through the end of the string. If LENGTH is negative, leaves that
many characters off the end of the string.
@@ -6755,12 +7689,25 @@
$_ = 'pq'; print $x,"\n"; # prints 5pq9
}
-Prior to Perl version 5.9.1, the result of using an lvalue multiple times was
+With negative offsets, it remembers its position from the end of the string
+when the target string is modified:
+
+ $x = '1234';
+ for (substr($x, -3, 2)) {
+ $_ = 'a'; print $x,"\n"; # prints 1a4, as above
+ $x = 'abcdefg';
+ print $_,"\n"; # prints f
+ }
+
+Prior to Perl version 5.10, the result of using an lvalue multiple times was
+unspecified. Prior to 5.16, the result with negative offsets was
unspecified.
=item symlink OLDFILE,NEWFILE
X<symlink> X<link> X<symbolic link> X<link, symbolic>
+=for Pod::Functions create a symbolic link to a file
+
Creates a new filename symbolically linked to the old filename.
Returns C<1> for success, C<0> otherwise. On systems that don't support
symbolic links, raises an exception. To check for that,
@@ -6768,9 +7715,13 @@
$symlink_exists = eval { symlink("",""); 1 };
+Portability issues: L<perlport/symlink>.
+
=item syscall NUMBER, LIST
X<syscall> X<system call>
+=for Pod::Functions execute an arbitrary system call
+
Calls the system call specified as the first element of the list,
passing the remaining elements as arguments to the system call. If
unimplemented, raises an exception. The arguments are interpreted
@@ -6803,14 +7754,18 @@
to retrieve the file number of the other end. You can avoid this
problem by using C<pipe> instead.
+Portability issues: L<perlport/syscall>.
+
=item sysopen FILEHANDLE,FILENAME,MODE
X<sysopen>
=item sysopen FILEHANDLE,FILENAME,MODE,PERMS
+=for Pod::Functions +5.002 open a file, pipe, or descriptor
+
Opens the file whose filename is given by FILENAME, and associates it with
FILEHANDLE. If FILEHANDLE is an expression, its value is used as the real
-filehandle wanted; an undefined scalar will be suitably autovivified. This
+filehandle wanted; an undefined scalar will be suitably autovivified. This
function calls the underlying operating system's I<open>(2) function with the
parameters FILENAME, MODE, and PERMS.
@@ -6828,7 +7783,7 @@
For historical reasons, some values work on almost every system
supported by Perl: 0 means read-only, 1 means write-only, and 2
means read/write. We know that these values do I<not> work under
-OS/390 & VM/ESA Unix and on the Macintosh; you probably don't want to
+OS/390 and on the Macintosh; you probably don't want to
use them in new code.
If the file named by FILENAME does not exist and the C<open> call creates
@@ -6860,17 +7815,21 @@
Note that C<sysopen> depends on the fdopen() C library function.
On many Unix systems, fdopen() is known to fail when file descriptors
-exceed a certain value, typically 255. If you need more file
+exceed a certain value, typically 255. If you need more file
descriptors than that, consider rebuilding Perl to use the C<sfio>
library, or perhaps using the POSIX::open() function.
See L<perlopentut> for a kinder, gentler explanation of opening files.
+Portability issues: L<perlport/sysopen>.
+
=item sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
X<sysread>
=item sysread FILEHANDLE,SCALAR,LENGTH
+=for Pod::Functions fixed-length unbuffered input from a filehandle
+
Attempts to read LENGTH bytes of data into variable SCALAR from the
specified FILEHANDLE, using the read(2). It bypasses
buffered IO, so mixing this with other kinds of reads, C<print>,
@@ -6901,6 +7860,8 @@
=item sysseek FILEHANDLE,POSITION,WHENCE
X<sysseek> X<lseek>
+=for Pod::Functions +5.004 position I/O pointer on handle used with sysread and syswrite
+
Sets FILEHANDLE's system position in bytes using lseek(2). FILEHANDLE may
be an expression whose value gives the name of the filehandle. The values
for WHENCE are C<0> to set the new position to POSITION; C<1> to set the it
@@ -6934,6 +7895,8 @@
=item system PROGRAM LIST
+=for Pod::Functions run a separate program
+
Does exactly the same thing as C<exec LIST>, except that a fork is
done first and the parent process waits for the child process to
exit. Note that argument processing varies depending on the
@@ -6948,7 +7911,7 @@
it is split into words and passed directly to C<execvp>, which is
more efficient.
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
+Perl will attempt to flush all files opened for
output before any operation that may do a fork, but this may not be
supported on some platforms (see L<perlport>). To be safe, you may need
to set C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method
@@ -6956,7 +7919,7 @@
The return value is the exit status of the program as returned by the
C<wait> call. To get the actual exit value, shift right by eight (see
-below). See also L</exec>. This is I<not> what you want to use to capture
+below). See also L</exec>. This is I<not> what you want to use to capture
the output from a command; for that you should use merely backticks or
C<qx//>, as described in L<perlop/"`STRING`">. Return value of -1
indicates a failure to start the program or an error of the wait(2) system
@@ -6999,8 +7962,10 @@
See L<perlop/"`STRING`"> and L</exec> for details.
Since C<system> does a C<fork> and C<wait> it may affect a C<SIGCHLD>
-handler. See L<perlipc> for details.
+handler. See L<perlipc> for details.
+Portability issues: L<perlport/system>.
+
=item syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
X<syswrite>
@@ -7008,6 +7973,8 @@
=item syswrite FILEHANDLE,SCALAR
+=for Pod::Functions fixed-length unbuffered output to a filehandle
+
Attempts to write LENGTH bytes of data from variable SCALAR to the
specified FILEHANDLE, using write(2). If LENGTH is
not specified, writes whole SCALAR. It bypasses buffered IO, so
@@ -7037,6 +8004,8 @@
=item tell
+=for Pod::Functions get current seekpointer on a filehandle
+
Returns the current position I<in bytes> for FILEHANDLE, or -1 on
error. FILEHANDLE may be an expression whose value gives the name of
the actual filehandle. If FILEHANDLE is omitted, assumes the file
@@ -7060,6 +8029,8 @@
=item telldir DIRHANDLE
X<telldir>
+=for Pod::Functions get current seekpointer on a directory handle
+
Returns the current position of the C<readdir> routines on DIRHANDLE.
Value may be given to C<seekdir> to access a particular location in a
directory. C<telldir> has the same caveats about possible directory
@@ -7068,14 +8039,17 @@
=item tie VARIABLE,CLASSNAME,LIST
X<tie>
+=for Pod::Functions +5.002 bind a variable to an object class
+
This function binds a variable to a package class that will provide the
implementation for the variable. VARIABLE is the name of the variable
to be enchanted. CLASSNAME is the name of a class implementing objects
-of correct type. Any additional arguments are passed to the C<new>
+of correct type. Any additional arguments are passed to the
+appropriate constructor
method of the class (meaning C<TIESCALAR>, C<TIEHANDLE>, C<TIEARRAY>,
or C<TIEHASH>). Typically these are arguments such as might be passed
-to the C<dbm_open()> function of C. The object returned by the C<new>
-method is also returned by the C<tie> function, which would be useful
+to the C<dbm_open()> function of C. The object returned by the
+constructor is also returned by the C<tie> function, which would be useful
if you want to access other methods in CLASSNAME.
Note that functions such as C<keys> and C<values> may return huge lists
@@ -7118,6 +8092,8 @@
UNSHIFT this, LIST
SPLICE this, offset, length, LIST
EXTEND this, count
+ DELETE this, key
+ EXISTS this, key
DESTROY this
UNTIE this
@@ -7160,6 +8136,8 @@
=item tied VARIABLE
X<tied>
+=for Pod::Functions get a reference to the object underlying a tied variable
+
Returns a reference to the object underlying VARIABLE (the same value
that was originally returned by the C<tie> call that bound the variable
to a package.) Returns the undefined value if VARIABLE isn't tied to a
@@ -7168,9 +8146,11 @@
=item time
X<time> X<epoch>
+=for Pod::Functions return number of seconds since 1970
+
Returns the number of non-leap seconds since whatever time the system
considers to be the epoch, suitable for feeding to C<gmtime> and
-C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;
+C<localtime>. On most systems the epoch is 00:00:00 UTC, January 1, 1970;
a prominent exception being Mac OS Classic which uses 00:00:00, January 1,
1904 in the current local time zone for its epoch.
@@ -7186,6 +8166,8 @@
=item times
X<times>
+=for Pod::Functions return elapsed time for self and child processes
+
Returns a four-element list giving the user and system times in
seconds for this process and any exited children of this process.
@@ -7195,8 +8177,12 @@
Children's times are only included for terminated children.
+Portability issues: L<perlport/times>.
+
=item tr///
+=for Pod::Functions transliterate a string
+
The transliteration operator. Same as C<y///>. See
L<perlop/"Quote and Quote-like Operators">.
@@ -7205,6 +8191,8 @@
=item truncate EXPR,LENGTH
+=for Pod::Functions shorten a file
+
Truncates the file opened on FILEHANDLE, or named by EXPR, to the
specified length. Raises an exception if truncate isn't implemented
on your system. Returns true if successful, C<undef> on error.
@@ -7215,11 +8203,15 @@
The position in the file of FILEHANDLE is left unchanged. You may want to
call L<seek|/"seek FILEHANDLE,POSITION,WHENCE"> before writing to the file.
+Portability issues: L<perlport/truncate>.
+
=item uc EXPR
X<uc> X<uppercase> X<toupper>
=item uc
+=for Pod::Functions return upper-case version of a string
+
Returns an uppercased version of EXPR. This is the internal function
implementing the C<\U> escape in double-quoted strings.
It does not attempt to do titlecase mapping on initial letters. See
@@ -7235,6 +8227,8 @@
=item ucfirst
+=for Pod::Functions return a string with just the next letter in upper case
+
Returns the value of EXPR with the first character in uppercase
(titlecase in Unicode). This is the internal function implementing
the C<\u> escape in double-quoted strings.
@@ -7249,6 +8243,8 @@
=item umask
+=for Pod::Functions set file creation mode mask
+
Sets the umask for the process to EXPR and returns the previous value.
If EXPR is omitted, merely returns the current umask.
@@ -7282,16 +8278,20 @@
Remember that a umask is a number, usually given in octal; it is I<not> a
string of octal digits. See also L</oct>, if all you have is a string.
+Portability issues: L<perlport/umask>.
+
=item undef EXPR
X<undef> X<undefine>
=item undef
+=for Pod::Functions remove a variable or function definition
+
Undefines the value of EXPR, which must be an lvalue. Use only on a
scalar value, an array (using C<@>), a hash (using C<%>), a subroutine
(using C<&>), or a typeglob (using C<*>). Saying C<undef $hash{$key}>
will probably not do what you expect on most predefined variables or
-DBM list values, so don't do that; see L<delete>. Always returns the
+DBM list values, so don't do that; see L</delete>. Always returns the
undefined value. You can omit the EXPR, in which case nothing is
undefined, but you still get an undefined value that you could, for
instance, return from a subroutine, assign to a variable, or pass as a
@@ -7314,8 +8314,10 @@
=item unlink
-Deletes a list of files. On success, it returns the number of files
-it successfully deleted. On failure, it returns false and sets C<$!>
+=for Pod::Functions remove one link to a file
+
+Deletes a list of files. On success, it returns the number of files
+it successfully deleted. On failure, it returns false and sets C<$!>
(errno):
my $unlinked = unlink 'a', 'b', 'c';
@@ -7331,7 +8333,7 @@
}
Note: C<unlink> will not attempt to delete directories unless you are
-superuser and the B<-U> flag is supplied to Perl. Even if these
+superuser and the B<-U> flag is supplied to Perl. Even if these
conditions are met, be warned that unlinking a directory can inflict
damage on your filesystem. Finally, using C<unlink> on directories is
not supported on many operating systems. Use C<rmdir> instead.
@@ -7343,6 +8345,8 @@
=item unpack TEMPLATE
+=for Pod::Functions convert binary structure into normal perl variables
+
C<unpack> does the reverse of C<pack>: it takes a string
and expands it out into a list of values.
(In scalar context, it returns merely the first value produced.)
@@ -7400,17 +8404,13 @@
See L</pack> for more examples and notes.
-=item untie VARIABLE
-X<untie>
-
-Breaks the binding between a variable and a package. (See C<tie>.)
-Has no effect if the variable is not tied.
-
=item unshift ARRAY,LIST
X<unshift>
=item unshift EXPR,LIST
+=for Pod::Functions prepend more elements to the beginning of a list
+
Does the opposite of a C<shift>. Or the opposite of a C<push>,
depending on how you look at it. Prepends list to the front of the
array and returns the new number of elements in the array.
@@ -7426,6 +8426,22 @@
automatically. This aspect of C<unshift> is considered highly
experimental. The exact behaviour may change in a future version of Perl.
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.014; # so push/pop/etc work on scalars (experimental)
+
+=item untie VARIABLE
+X<untie>
+
+=for Pod::Functions break a tie binding to a variable
+
+Breaks the binding between a variable and a package.
+(See L<tie|/tie VARIABLE,CLASSNAME,LIST>.)
+Has no effect if the variable is not tied.
+
=item use Module VERSION LIST
X<use> X<module> X<import>
@@ -7437,6 +8453,8 @@
=item use VERSION
+=for Pod::Functions load in a module at compile time and import its namespace
+
Imports some semantics into the current package from the named module,
generally by aliasing certain subroutine or variable names into your
package. It is exactly equivalent to
@@ -7444,7 +8462,7 @@
BEGIN { require Module; Module->import( LIST ); }
except that Module I<must> be a bareword.
-The importation can be made conditional; see L<if>.
+The importation can be made conditional by using the L<if> module.
In the peculiar C<use VERSION> form, VERSION may be either a positive
decimal fraction such as 5.006, which will be compared to C<$]>, or a v-string
@@ -7468,12 +8486,15 @@
C<use>ing library modules that won't work with older versions of Perl.
(We try not to do this more than we have to.)
-Also, if the specified Perl version is greater than or equal to 5.9.5,
-C<use VERSION> will also load the C<feature> pragma and enable all
-features available in the requested version. See L<feature>.
+C<use VERSION> also enables all features available in the requested
+version as defined by the C<feature> pragma, disabling any features
+not in the requested version's feature bundle. See L<feature>.
Similarly, if the specified Perl version is greater than or equal to
-5.11.0, strictures are enabled lexically as with C<use strict> (except
-that the F<strict.pm> file is not actually loaded).
+5.12.0, strictures are enabled lexically as
+with C<use strict>. Any explicit use of
+C<use strict> or C<no strict> overrides C<use VERSION>, even if it comes
+before it. In both cases, the F<feature.pm> and F<strict.pm> files are
+not actually loaded.
The C<BEGIN> forces the C<require> and C<import> to happen at compile time. The
C<require> makes sure the module is loaded into memory if it hasn't been
@@ -7552,6 +8573,8 @@
=item utime LIST
X<utime>
+=for Pod::Functions set a file's last access and modify times
+
Changes the access and modification times on each file of a list of
files. The first two elements of the list must be the NUMERIC access
and modification times, in that order. Returns the number of files
@@ -7564,9 +8587,9 @@
$atime = $mtime = time;
utime $atime, $mtime, @ARGV;
-Since Perl 5.7.2, if the first two elements of the list are C<undef>,
+Since Perl 5.8.0, if the first two elements of the list are C<undef>,
the utime(2) syscall from your C library is called with a null second
-argument. On most systems, this will set the file's access and
+argument. On most systems, this will set the file's access and
modification times to the current time (i.e., equivalent to the example
above) and will work even on files you don't own provided you have write
permission:
@@ -7592,6 +8615,8 @@
an exception. Filehandles must be passed as globs or glob references to be
recognized; barewords are considered filenames.
+Portability issues: L<perlport/utime>.
+
=item values HASH
X<values>
@@ -7599,30 +8624,38 @@
=item values EXPR
-Returns a list consisting of all the values of the named hash, or the values
-of an array. (In scalar context, returns the number of values.)
+=for Pod::Functions return a list of the values in a hash
-The values are returned in an apparently random order. The actual
-random order is subject to change in future versions of Perl, but it
-is guaranteed to be the same order as either the C<keys> or C<each>
-function would produce on the same (unmodified) hash. Since Perl
-5.8.1 the ordering is different even between different runs of Perl
-for security reasons (see L<perlsec/"Algorithmic Complexity Attacks">).
+In list context, returns a list consisting of all the values of the named
+hash. In Perl 5.12 or later only, will also return a list of the values of
+an array; prior to that release, attempting to use an array argument will
+produce a syntax error. In scalar context, returns the number of values.
+Hash entries are returned in an apparently random order. The actual random
+order is specific to a given hash; the exact same series of operations
+on two hashes may result in a different order for each hash. Any insertion
+into the hash may change the order, as will any deletion, with the exception
+that the most recent key returned by C<each> or C<keys> may be deleted
+without changing the order. So long as a given hash is unmodified you may
+rely on C<keys>, C<values> and C<each> to repeatedly return the same order
+as each other. See L<perlsec/"Algorithmic Complexity Attacks"> for
+details on why hash order is randomized. Aside from the guarantees
+provided here the exact details of Perl's hash algorithm and the hash
+traversal order are subject to change in any release of Perl.
+
As a side effect, calling values() resets the HASH or ARRAY's internal
-iterator;
-see L</each>. (In particular, calling values() in void context resets
-the iterator with no other overhead. Apart from resetting the iterator,
-C<values @array> in list context is the same as plain C<@array>.
-We recommend that you use void context C<keys @array> for this, but reasoned
-that it taking C<values @array> out would require more documentation than
-leaving it in.)
+iterator, see L</each>. (In particular, calling values() in void context
+resets the iterator with no other overhead. Apart from resetting the
+iterator, C<values @array> in list context is the same as plain C<@array>.
+(We recommend that you use void context C<keys @array> for this, but
+reasoned that taking C<values @array> out would require more
+documentation than leaving it in.)
Note that the values are not copied, which means modifying them will
modify the contents of the hash:
- for (values %hash) { s/foo/bar/g } # modifies %hash values
- for (@hash{keys %hash}) { s/foo/bar/g } # same
+ for (values %hash) { s/foo/bar/g } # modifies %hash values
+ for (@hash{keys %hash}) { s/foo/bar/g } # same
Starting with Perl 5.14, C<values> can take a scalar EXPR, which must hold
a reference to an unblessed hash or array. The argument will be
@@ -7632,11 +8665,21 @@
for (values $hashref) { ... }
for (values $obj->get_arrayref) { ... }
+To avoid confusing would-be users of your code who are running earlier
+versions of Perl with mysterious syntax errors, put this sort of thing at
+the top of your file to signal that your code will work I<only> on Perls of
+a recent vintage:
+
+ use 5.012; # so keys/values/each work on arrays
+ use 5.014; # so keys/values/each work on scalars (experimental)
+
See also C<keys>, C<each>, and C<sort>.
=item vec EXPR,OFFSET,BITS
X<vec> X<bit> X<bit vector>
+=for Pod::Functions test or set particular bits in a string
+
Treats the string in EXPR as a bit vector made up of elements of
width BITS and returns the value of the element specified by OFFSET
as an unsigned integer. BITS therefore specifies the number of bits
@@ -7709,172 +8752,174 @@
Here is an example to illustrate how the bits actually fall in place:
- #!/usr/bin/perl -wl
+ #!/usr/bin/perl -wl
- print <<'EOT';
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- EOT
+ print <<'EOT';
+ 0 1 2 3
+ unpack("V",$_) 01234567890123456789012345678901
+ ------------------------------------------------------------------
+ EOT
- for $w (0..3) {
- $width = 2**$w;
- for ($shift=0; $shift < $width; ++$shift) {
- for ($off=0; $off < 32/$width; ++$off) {
- $str = pack("B*", "0"x32);
- $bits = (1<<$shift);
- vec($str, $off, $width) = $bits;
- $res = unpack("b*",$str);
- $val = unpack("V", $str);
- write;
- }
- }
- }
+ for $w (0..3) {
+ $width = 2**$w;
+ for ($shift=0; $shift < $width; ++$shift) {
+ for ($off=0; $off < 32/$width; ++$off) {
+ $str = pack("B*", "0"x32);
+ $bits = (1<<$shift);
+ vec($str, $off, $width) = $bits;
+ $res = unpack("b*",$str);
+ $val = unpack("V", $str);
+ write;
+ }
+ }
+ }
- format STDOUT =
- vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
- $off, $width, $bits, $val, $res
- .
- __END__
+ format STDOUT =
+ vec($_,@#,@#) = @<< == @######### @>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>>
+ $off, $width, $bits, $val, $res
+ .
+ __END__
Regardless of the machine architecture on which it runs, the
example above should print the following table:
- 0 1 2 3
- unpack("V",$_) 01234567890123456789012345678901
- ------------------------------------------------------------------
- vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
- vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
- vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
- vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
- vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
- vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
- vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
- vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
- vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
- vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
- vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
- vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
- vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
- vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
- vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
- vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
- vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
- vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
- vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
- vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
- vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
- vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
- vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
- vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
- vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
- vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
- vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
- vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
- vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
- vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
- vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
- vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
- vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
- vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
- vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
- vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
- vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
- vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
- vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
- vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
- vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
- vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
- vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
- vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
- vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
- vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
- vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
- vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
- vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
- vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
- vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
- vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
- vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
- vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
- vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
- vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
- vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
- vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
- vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
- vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
- vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
- vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
- vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
- vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
- vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
- vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
- vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
- vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
- vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
- vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
- vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
- vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
- vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
- vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
- vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
- vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
- vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
- vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
- vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
- vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
- vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
- vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
- vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
- vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
- vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
- vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
- vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
- vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
- vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
- vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
- vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
- vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
- vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
- vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
- vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
- vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
- vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
- vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
- vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
- vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
- vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
- vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
- vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
- vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
- vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
- vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
- vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
- vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
- vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
- vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
- vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
- vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
- vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
+ 0 1 2 3
+ unpack("V",$_) 01234567890123456789012345678901
+ ------------------------------------------------------------------
+ vec($_, 0, 1) = 1 == 1 10000000000000000000000000000000
+ vec($_, 1, 1) = 1 == 2 01000000000000000000000000000000
+ vec($_, 2, 1) = 1 == 4 00100000000000000000000000000000
+ vec($_, 3, 1) = 1 == 8 00010000000000000000000000000000
+ vec($_, 4, 1) = 1 == 16 00001000000000000000000000000000
+ vec($_, 5, 1) = 1 == 32 00000100000000000000000000000000
+ vec($_, 6, 1) = 1 == 64 00000010000000000000000000000000
+ vec($_, 7, 1) = 1 == 128 00000001000000000000000000000000
+ vec($_, 8, 1) = 1 == 256 00000000100000000000000000000000
+ vec($_, 9, 1) = 1 == 512 00000000010000000000000000000000
+ vec($_,10, 1) = 1 == 1024 00000000001000000000000000000000
+ vec($_,11, 1) = 1 == 2048 00000000000100000000000000000000
+ vec($_,12, 1) = 1 == 4096 00000000000010000000000000000000
+ vec($_,13, 1) = 1 == 8192 00000000000001000000000000000000
+ vec($_,14, 1) = 1 == 16384 00000000000000100000000000000000
+ vec($_,15, 1) = 1 == 32768 00000000000000010000000000000000
+ vec($_,16, 1) = 1 == 65536 00000000000000001000000000000000
+ vec($_,17, 1) = 1 == 131072 00000000000000000100000000000000
+ vec($_,18, 1) = 1 == 262144 00000000000000000010000000000000
+ vec($_,19, 1) = 1 == 524288 00000000000000000001000000000000
+ vec($_,20, 1) = 1 == 1048576 00000000000000000000100000000000
+ vec($_,21, 1) = 1 == 2097152 00000000000000000000010000000000
+ vec($_,22, 1) = 1 == 4194304 00000000000000000000001000000000
+ vec($_,23, 1) = 1 == 8388608 00000000000000000000000100000000
+ vec($_,24, 1) = 1 == 16777216 00000000000000000000000010000000
+ vec($_,25, 1) = 1 == 33554432 00000000000000000000000001000000
+ vec($_,26, 1) = 1 == 67108864 00000000000000000000000000100000
+ vec($_,27, 1) = 1 == 134217728 00000000000000000000000000010000
+ vec($_,28, 1) = 1 == 268435456 00000000000000000000000000001000
+ vec($_,29, 1) = 1 == 536870912 00000000000000000000000000000100
+ vec($_,30, 1) = 1 == 1073741824 00000000000000000000000000000010
+ vec($_,31, 1) = 1 == 2147483648 00000000000000000000000000000001
+ vec($_, 0, 2) = 1 == 1 10000000000000000000000000000000
+ vec($_, 1, 2) = 1 == 4 00100000000000000000000000000000
+ vec($_, 2, 2) = 1 == 16 00001000000000000000000000000000
+ vec($_, 3, 2) = 1 == 64 00000010000000000000000000000000
+ vec($_, 4, 2) = 1 == 256 00000000100000000000000000000000
+ vec($_, 5, 2) = 1 == 1024 00000000001000000000000000000000
+ vec($_, 6, 2) = 1 == 4096 00000000000010000000000000000000
+ vec($_, 7, 2) = 1 == 16384 00000000000000100000000000000000
+ vec($_, 8, 2) = 1 == 65536 00000000000000001000000000000000
+ vec($_, 9, 2) = 1 == 262144 00000000000000000010000000000000
+ vec($_,10, 2) = 1 == 1048576 00000000000000000000100000000000
+ vec($_,11, 2) = 1 == 4194304 00000000000000000000001000000000
+ vec($_,12, 2) = 1 == 16777216 00000000000000000000000010000000
+ vec($_,13, 2) = 1 == 67108864 00000000000000000000000000100000
+ vec($_,14, 2) = 1 == 268435456 00000000000000000000000000001000
+ vec($_,15, 2) = 1 == 1073741824 00000000000000000000000000000010
+ vec($_, 0, 2) = 2 == 2 01000000000000000000000000000000
+ vec($_, 1, 2) = 2 == 8 00010000000000000000000000000000
+ vec($_, 2, 2) = 2 == 32 00000100000000000000000000000000
+ vec($_, 3, 2) = 2 == 128 00000001000000000000000000000000
+ vec($_, 4, 2) = 2 == 512 00000000010000000000000000000000
+ vec($_, 5, 2) = 2 == 2048 00000000000100000000000000000000
+ vec($_, 6, 2) = 2 == 8192 00000000000001000000000000000000
+ vec($_, 7, 2) = 2 == 32768 00000000000000010000000000000000
+ vec($_, 8, 2) = 2 == 131072 00000000000000000100000000000000
+ vec($_, 9, 2) = 2 == 524288 00000000000000000001000000000000
+ vec($_,10, 2) = 2 == 2097152 00000000000000000000010000000000
+ vec($_,11, 2) = 2 == 8388608 00000000000000000000000100000000
+ vec($_,12, 2) = 2 == 33554432 00000000000000000000000001000000
+ vec($_,13, 2) = 2 == 134217728 00000000000000000000000000010000
+ vec($_,14, 2) = 2 == 536870912 00000000000000000000000000000100
+ vec($_,15, 2) = 2 == 2147483648 00000000000000000000000000000001
+ vec($_, 0, 4) = 1 == 1 10000000000000000000000000000000
+ vec($_, 1, 4) = 1 == 16 00001000000000000000000000000000
+ vec($_, 2, 4) = 1 == 256 00000000100000000000000000000000
+ vec($_, 3, 4) = 1 == 4096 00000000000010000000000000000000
+ vec($_, 4, 4) = 1 == 65536 00000000000000001000000000000000
+ vec($_, 5, 4) = 1 == 1048576 00000000000000000000100000000000
+ vec($_, 6, 4) = 1 == 16777216 00000000000000000000000010000000
+ vec($_, 7, 4) = 1 == 268435456 00000000000000000000000000001000
+ vec($_, 0, 4) = 2 == 2 01000000000000000000000000000000
+ vec($_, 1, 4) = 2 == 32 00000100000000000000000000000000
+ vec($_, 2, 4) = 2 == 512 00000000010000000000000000000000
+ vec($_, 3, 4) = 2 == 8192 00000000000001000000000000000000
+ vec($_, 4, 4) = 2 == 131072 00000000000000000100000000000000
+ vec($_, 5, 4) = 2 == 2097152 00000000000000000000010000000000
+ vec($_, 6, 4) = 2 == 33554432 00000000000000000000000001000000
+ vec($_, 7, 4) = 2 == 536870912 00000000000000000000000000000100
+ vec($_, 0, 4) = 4 == 4 00100000000000000000000000000000
+ vec($_, 1, 4) = 4 == 64 00000010000000000000000000000000
+ vec($_, 2, 4) = 4 == 1024 00000000001000000000000000000000
+ vec($_, 3, 4) = 4 == 16384 00000000000000100000000000000000
+ vec($_, 4, 4) = 4 == 262144 00000000000000000010000000000000
+ vec($_, 5, 4) = 4 == 4194304 00000000000000000000001000000000
+ vec($_, 6, 4) = 4 == 67108864 00000000000000000000000000100000
+ vec($_, 7, 4) = 4 == 1073741824 00000000000000000000000000000010
+ vec($_, 0, 4) = 8 == 8 00010000000000000000000000000000
+ vec($_, 1, 4) = 8 == 128 00000001000000000000000000000000
+ vec($_, 2, 4) = 8 == 2048 00000000000100000000000000000000
+ vec($_, 3, 4) = 8 == 32768 00000000000000010000000000000000
+ vec($_, 4, 4) = 8 == 524288 00000000000000000001000000000000
+ vec($_, 5, 4) = 8 == 8388608 00000000000000000000000100000000
+ vec($_, 6, 4) = 8 == 134217728 00000000000000000000000000010000
+ vec($_, 7, 4) = 8 == 2147483648 00000000000000000000000000000001
+ vec($_, 0, 8) = 1 == 1 10000000000000000000000000000000
+ vec($_, 1, 8) = 1 == 256 00000000100000000000000000000000
+ vec($_, 2, 8) = 1 == 65536 00000000000000001000000000000000
+ vec($_, 3, 8) = 1 == 16777216 00000000000000000000000010000000
+ vec($_, 0, 8) = 2 == 2 01000000000000000000000000000000
+ vec($_, 1, 8) = 2 == 512 00000000010000000000000000000000
+ vec($_, 2, 8) = 2 == 131072 00000000000000000100000000000000
+ vec($_, 3, 8) = 2 == 33554432 00000000000000000000000001000000
+ vec($_, 0, 8) = 4 == 4 00100000000000000000000000000000
+ vec($_, 1, 8) = 4 == 1024 00000000001000000000000000000000
+ vec($_, 2, 8) = 4 == 262144 00000000000000000010000000000000
+ vec($_, 3, 8) = 4 == 67108864 00000000000000000000000000100000
+ vec($_, 0, 8) = 8 == 8 00010000000000000000000000000000
+ vec($_, 1, 8) = 8 == 2048 00000000000100000000000000000000
+ vec($_, 2, 8) = 8 == 524288 00000000000000000001000000000000
+ vec($_, 3, 8) = 8 == 134217728 00000000000000000000000000010000
+ vec($_, 0, 8) = 16 == 16 00001000000000000000000000000000
+ vec($_, 1, 8) = 16 == 4096 00000000000010000000000000000000
+ vec($_, 2, 8) = 16 == 1048576 00000000000000000000100000000000
+ vec($_, 3, 8) = 16 == 268435456 00000000000000000000000000001000
+ vec($_, 0, 8) = 32 == 32 00000100000000000000000000000000
+ vec($_, 1, 8) = 32 == 8192 00000000000001000000000000000000
+ vec($_, 2, 8) = 32 == 2097152 00000000000000000000010000000000
+ vec($_, 3, 8) = 32 == 536870912 00000000000000000000000000000100
+ vec($_, 0, 8) = 64 == 64 00000010000000000000000000000000
+ vec($_, 1, 8) = 64 == 16384 00000000000000100000000000000000
+ vec($_, 2, 8) = 64 == 4194304 00000000000000000000001000000000
+ vec($_, 3, 8) = 64 == 1073741824 00000000000000000000000000000010
+ vec($_, 0, 8) = 128 == 128 00000001000000000000000000000000
+ vec($_, 1, 8) = 128 == 32768 00000000000000010000000000000000
+ vec($_, 2, 8) = 128 == 8388608 00000000000000000000000100000000
+ vec($_, 3, 8) = 128 == 2147483648 00000000000000000000000000000001
=item wait
X<wait>
+=for Pod::Functions wait for any child process to die
+
Behaves like wait(2) on your system: it waits for a child
process to terminate and returns the pid of the deceased process, or
C<-1> if there are no child processes. The status is returned in C<$?>
@@ -7883,11 +8928,15 @@
being automatically reaped, as described in L<perlipc>.
If you use wait in your handler for $SIG{CHLD} it may accidentally for the
-child created by qx() or system(). See L<perlipc> for details.
+child created by qx() or system(). See L<perlipc> for details.
+Portability issues: L<perlport/wait>.
+
=item waitpid PID,FLAGS
X<waitpid>
+=for Pod::Functions wait for a particular child process to die
+
Waits for a particular child process to terminate and returns the pid of
the deceased process, or C<-1> if there is no such child process. On some
systems, a value of 0 indicates that there are processes still running.
@@ -7910,9 +8959,13 @@
processes are being automatically reaped. See L<perlipc> for details,
and for other examples.
+Portability issues: L<perlport/waitpid>.
+
=item wantarray
X<wantarray> X<context>
+=for Pod::Functions get void vs scalar vs list context of current subroutine call
+
Returns true if the context of the currently executing subroutine or
C<eval> is looking for a list value. Returns false if the context is
looking for a scalar. Returns the undefined value if the context is
@@ -7931,6 +8984,8 @@
=item warn LIST
X<warn> X<warning> X<STDERR>
+=for Pod::Functions print debugging info
+
Prints the value of LIST to STDERR. If the last element of LIST does
not end in a newline, it appends the same file/line number text as C<die>
does.
@@ -7973,53 +9028,6 @@
examples. See the Carp module for other kinds of warnings using its
carp() and cluck() functions.
-=item when EXPR BLOCK
-X<when>
-
-=item when BLOCK
-
-C<when> is analogous to the C<case> keyword in other languages. Used with a
-C<foreach> loop or the experimental C<given> block, C<when> can be used in
-Perl to implement C<switch>/C<case> like statements. Available as a
-statement after Perl 5.10 and as a statement modifier after 5.14.
-Here are three examples:
-
- use v5.10;
- foreach (@fruits) {
- when (/apples?/) {
- say "I like apples."
- }
- when (/oranges?/) {
- say "I don't like oranges."
- }
- default {
- say "I don't like anything"
- }
- }
-
- # require 5.14 for when as statement modifier
- use v5.14;
- foreach (@fruits) {
- say "I like apples." when /apples?/;
- say "I don't like oranges." when /oranges?;
- default { say "I don't like anything" }
- }
-
- use v5.10;
- given ($fruit) {
- when (/apples?/) {
- say "I like apples."
- }
- when (/oranges?/) {
- say "I don't like oranges."
- }
- default {
- say "I don't like anything"
- }
- }
-
-See L<perlsyn/"Switch statements"> for detailed information.
-
=item write FILEHANDLE
X<write>
@@ -8027,6 +9035,8 @@
=item write
+=for Pod::Functions print a picture record
+
Writes a formatted record (possibly multi-line) to the specified FILEHANDLE,
using the format associated with that file. By default the format for
a file is the one having the same name as the filehandle, but the
@@ -8037,7 +9047,7 @@
room on the current page for the formatted record, the page is advanced by
writing a form feed, a special top-of-page format is used to format the new
page header before the record is written. By default, the top-of-page
-format is the name of the filehandle with "_TOP" appended. This would be a
+format is the name of the filehandle with "_TOP" appended. This would be a
problem with autovivified filehandles, but it may be dynamically set to the
format of your choice by assigning the name to the C<$^> variable while
that filehandle is selected. The number of lines remaining on the current
@@ -8053,9 +9063,134 @@
=item y///
+=for Pod::Functions transliterate a string
+
The transliteration operator. Same as C<tr///>. See
L<perlop/"Quote and Quote-like Operators">.
=back
+=head2 Non-function Keywords by Cross-reference
+
+=head3 perldata
+
+=over
+
+=item __DATA__
+
+=item __END__
+
+These keywords are documented in L<perldata/"Special Literals">.
+
+=back
+
+=head3 perlmod
+
+=over
+
+=item BEGIN
+
+=item CHECK
+
+=item END
+
+=item INIT
+
+=item UNITCHECK
+
+These compile phase keywords are documented in L<perlmod/"BEGIN, UNITCHECK, CHECK, INIT and END">.
+
+=back
+
+=head3 perlobj
+
+=over
+
+=item DESTROY
+
+This method keyword is documented in L<perlobj/"Destructors">.
+
+=back
+
+=head3 perlop
+
+=over
+
+=item and
+
+=item cmp
+
+=item eq
+
+=item ge
+
+=item gt
+
+=item if
+
+=item le
+
+=item lt
+
+=item ne
+
+=item not
+
+=item or
+
+=item x
+
+=item xor
+
+These operators are documented in L<perlop>.
+
+=back
+
+=head3 perlsub
+
+=over
+
+=item AUTOLOAD
+
+This keyword is documented in L<perlsub/"Autoloading">.
+
+=back
+
+=head3 perlsyn
+
+=over
+
+=item else
+
+=item elseif
+
+=item elsif
+
+=item for
+
+=item foreach
+
+=item unless
+
+=item until
+
+=item while
+
+These flow-control keywords are documented in L<perlsyn/"Compound Statements">.
+
+=back
+
+=over
+
+=item default
+
+=item given
+
+=item when
+
+These flow-control keywords related to the experimental switch feature are
+documented in L<perlsyn/"Switch Statements"> .
+
+=back
+
=cut
Property changes on: trunk/contrib/perl/pod/perlfunc.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlgit.pod
===================================================================
--- trunk/contrib/perl/pod/perlgit.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlgit.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -51,7 +51,7 @@
The branches that begin with "origin" correspond to the "git remote"
that you cloned from (which is named "origin"). Each branch on the
-remote will be exactly tracked by theses branches. You should NEVER do
+remote will be exactly tracked by these branches. You should NEVER do
work on these remote tracking branches. You only ever do work in a
local branch. Local branches can be configured to automerge (on pull)
from a designated remote tracking branch. This is the case with the
@@ -258,7 +258,7 @@
% git format-patch -M origin..
0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
-You should now send an email to to
+You should now send an email to
L<perlbug at perl.org|mailto:perlbug at perl.org> with a description of your
changes, and include this patch file as an attachment. In addition to
being tracked by RT, mail to perlbug will automatically be forwarded to
@@ -385,46 +385,60 @@
=head2 Bisecting
-C<git> provides a built-in way to determine, with a binary search in
-the history, which commit should be blamed for introducing a given bug.
+C<git> provides a built-in way to determine which commit should be blamed
+for introducing a given bug. C<git bisect> performs a binary search of
+history to locate the first failing commit. It is fast, powerful and
+flexible, but requires some setup and to automate the process an auxiliary
+shell script is needed.
-Suppose that we have a script F<~/testcase.pl> that exits with C<0>
-when some behaviour is correct, and with C<1> when it's faulty. You
-need an helper script that automates building C<perl> and running the
-testcase:
+The core provides a wrapper program, F<Porting/bisect.pl>, which attempts to
+simplify as much as possible, making bisecting as simple as running a Perl
+one-liner. For example, if you want to know when this became an error:
- % cat ~/run
- #!/bin/sh
- git clean -dxf
+ perl -e 'my $a := 2'
- # If you get './makedepend: 1: Syntax error: Unterminated quoted
- # string' when bisecting versions of perl older than 5.9.5 this hack
- # will work around the bug in makedepend.SH which was fixed in
- # version 96a8704c. Make sure to comment out `git checkout makedepend.SH'
- # below too.
- git show blead:makedepend.SH > makedepend.SH
+you simply run this:
- # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
- # if Encode is not needed for the test, you can speed up the bisect by
- # excluding it from the runs with -Dnoextensions=Encode
- sh Configure -des -Dusedevel -Doptimize="-g"
- test -f config.sh || exit 125
- # Correct makefile for newer GNU gcc
- perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
- # if you just need miniperl, replace test_prep with miniperl
- make test_prep
- [ -x ./perl ] || exit 125
- ./perl -Ilib ~/testcase.pl
- ret=$?
- [ $ret -gt 127 ] && ret=127
- # git checkout makedepend.SH
- git clean -dxf
- exit $ret
+ .../Porting/bisect.pl -e 'my $a := 2;'
-This script may return C<125> to indicate that the corresponding commit
-should be skipped. Otherwise, it returns the status of
-F<~/testcase.pl>.
+Using C<bisect.pl>, with one command (and no other files) it's easy to find
+out
+=over 4
+
+=item *
+
+Which commit caused this example code to break?
+
+=item *
+
+Which commit caused this example code to start working?
+
+=item *
+
+Which commit added the first file to match this regex?
+
+=item *
+
+Which commit removed the last file to match this regex?
+
+=back
+
+usually without needing to know which versions of perl to use as start and
+end revisions, as F<bisect.pl> automatically searches to find the earliest
+stable version for which the test case passes. Run
+C<Porting/bisect.pl --help> for the full documentation, including how to
+set the C<Configure> and build time options.
+
+If you require more flexibility than F<Porting/bisect.pl> has to offer, you'll
+need to run C<git bisect> yourself. It's most useful to use C<git bisect run>
+to automate the building and testing of perl revisions. For this you'll need
+a shell script for C<git> to call to test a particular revision. An example
+script is F<Porting/bisect-example.sh>, which you should copy B<outside> of
+the repository, as the bisect process will reset the state to a clean checkout
+as it runs. The instructions below assume that you copied it as F<~/run> and
+then edited it as appropriate.
+
You first enter in bisect mode with:
% git bisect start
@@ -466,8 +480,9 @@
C<git help bisect> has much more information on how you can tweak your
binary searches.
-=head1 Topic branches and rewriting history
+=head2 Topic branches and rewriting history
+
Individual committers should create topic branches under
B<yourname>/B<some_descriptive_name>. Other committers should check
with a topic branch's creator before making any change to it.
@@ -543,7 +558,7 @@
a local tag to perl.git before doing so. (Pushing unannotated tags is
not allowed.)
-=head3 Grafts
+=head2 Grafts
The perl history contains one mistake which was not caught in the
conversion: a merge was recorded in the history between blead and
@@ -557,83 +572,6 @@
It is particularly important to have this graft line if any bisecting
is done in the area of the "merge" in question.
-=head2 Topic branches and rewriting history
-
-Individual committers should create topic branches under
-B<yourname>/B<some_descriptive_name>. Other committers should check
-with a topic branch's creator before making any change to it.
-
-The simplest way to create a remote topic branch that works on all
-versions of git is to push the current head as a new branch on the
-remote, then check it out locally:
-
- $ branch="$yourname/$some_descriptive_name"
- $ git push origin HEAD:$branch
- $ git checkout -b $branch origin/$branch
-
-Users of git 1.7 or newer can do it in a more obvious manner:
-
- $ branch="$yourname/$some_descriptive_name"
- $ git checkout -b $branch
- $ git push origin -u $branch
-
-If you are not the creator of B<yourname>/B<some_descriptive_name>, you
-might sometimes find that the original author has edited the branch's
-history. There are lots of good reasons for this. Sometimes, an author
-might simply be rebasing the branch onto a newer source point.
-Sometimes, an author might have found an error in an early commit which
-they wanted to fix before merging the branch to blead.
-
-Currently the master repository is configured to forbid
-non-fast-forward merges. This means that the branches within can not be
-rebased and pushed as a single step.
-
-The only way you will ever be allowed to rebase or modify the history
-of a pushed branch is to delete it and push it as a new branch under
-the same name. Please think carefully about doing this. It may be
-better to sequentially rename your branches so that it is easier for
-others working with you to cherry-pick their local changes onto the new
-version. (XXX: needs explanation).
-
-If you want to rebase a personal topic branch, you will have to delete
-your existing topic branch and push as a new version of it. You can do
-this via the following formula (see the explanation about C<refspec>'s
-in the git push documentation for details) after you have rebased your
-branch:
-
- # first rebase
- $ git checkout $user/$topic
- $ git fetch
- $ git rebase origin/blead
-
- # then "delete-and-push"
- $ git push origin :$user/$topic
- $ git push origin $user/$topic
-
-B<NOTE:> it is forbidden at the repository level to delete any of the
-"primary" branches. That is any branch matching
-C<m!^(blead|maint|perl)!>. Any attempt to do so will result in git
-producing an error like this:
-
- $ git push origin :blead
- *** It is forbidden to delete blead/maint branches in this repository
- error: hooks/update exited with error code 1
- error: hook declined to update refs/heads/blead
- To ssh://perl5.git.perl.org/perl
- ! [remote rejected] blead (hook declined)
- error: failed to push some refs to 'ssh://perl5.git.perl.org/perl'
-
-As a matter of policy we do B<not> edit the history of the blead and
-maint-* branches. If a typo (or worse) sneaks into a commit to blead or
-maint-*, we'll fix it in another commit. The only types of updates
-allowed on these branches are "fast-forward's", where all history is
-preserved.
-
-Annotated tags in the canonical perl.git repository will never be
-deleted or modified. Think long and hard about whether you want to push
-a local tag to perl.git before doing so. (Pushing unannotated tags is
-not allowed.)
-
=head1 WRITE ACCESS TO THE GIT REPOSITORY
Once you have write access, you will need to modify the URL for the
@@ -648,7 +586,7 @@
% git config --global user.name "Ævar Arnfjörð Bjarmason"
% git config --global user.email avarab at gmail.com
-However if you'd like to override that just for perl then execute then
+However, if you'd like to override that just for perl,
execute something like the following in F<perl>:
% git config user.email avar at cpan.org
@@ -667,8 +605,9 @@
The C<fetch> command just updates the C<camel> refs, as the objects
themselves should have been fetched when pulling from C<origin>.
-=head1 Accepting a patch
+=head2 Accepting a patch
+
If you have received a patch file generated using the above section,
you should try out the patch.
@@ -717,7 +656,7 @@
% git checkout blead
% git merge experimental
- % git push
+ % git push origin blead
If you want to delete your temporary branch, you may do so with:
@@ -763,12 +702,79 @@
=item *
If you make any changes that affect miniperl or core routines that have
-different code paths for miniperl, be sure to run C<make minitest>.
+different code paths for miniperl, be sure to run C<make minitest>.
This will catch problems that even the full test suite will not catch
because it runs a subset of tests under miniperl rather than perl.
=back
+=head2 On merging and rebasing
+
+Simple, one-off commits pushed to the 'blead' branch should be simple
+commits that apply cleanly. In other words, you should make sure your
+work is committed against the current position of blead, so that you can
+push back to the master repository without merging.
+
+Sometimes, blead will move while you're building or testing your
+changes. When this happens, your push will be rejected with a message
+like this:
+
+ To ssh://perl5.git.perl.org/perl.git
+ ! [rejected] blead -> blead (non-fast-forward)
+ error: failed to push some refs to 'ssh://perl5.git.perl.org/perl.git'
+ To prevent you from losing history, non-fast-forward updates were rejected
+ Merge the remote changes (e.g. 'git pull') before pushing again. See the
+ 'Note about fast-forwards' section of 'git push --help' for details.
+
+When this happens, you can just I<rebase> your work against the new
+position of blead, like this (assuming your remote for the master
+repository is "p5p"):
+
+ $ git fetch p5p
+ $ git rebase p5p/blead
+
+You will see your commits being re-applied, and you will then be able to
+push safely. More information about rebasing can be found in the
+documentation for the git-rebase(1) command.
+
+For larger sets of commits that only make sense together, or that would
+benefit from a summary of the set's purpose, you should use a merge
+commit. You should perform your work on a L<topic branch|/Topic
+branches and rewriting history>, which you should regularly rebase
+against blead to ensure that your code is not broken by blead moving.
+When you have finished your work, please perform a final rebase and
+test. Linear history is something that gets lost with every
+commit on blead, but a final rebase makes the history linear
+again, making it easier for future maintainers to see what has
+happened. Rebase as follows (assuming your work was on the
+branch C<< committer/somework >>):
+
+ $ git checkout committer/somework
+ $ git rebase blead
+
+Then you can merge it into master like this:
+
+ $ git checkout blead
+ $ git merge --no-ff --no-commit committer/somework
+ $ git commit -a
+
+The switches above deserve explanation. C<--no-ff> indicates that even
+if all your work can be applied linearly against blead, a merge commit
+should still be prepared. This ensures that all your work will be shown
+as a side branch, with all its commits merged into the mainstream blead
+by the merge commit.
+
+C<--no-commit> means that the merge commit will be I<prepared> but not
+I<committed>. The commit is then actually performed when you run the
+next command, which will bring up your editor to describe the commit.
+Without C<--no-commit>, the commit would be made with nearly no useful
+message, which would greatly diminish the value of the merge commit as a
+placeholder for the work's description.
+
+When describing the merge commit, explain the purpose of the branch, and
+keep in mind that this description will probably be used by the
+eventual release engineer when reviewing the next perldelta document.
+
=head2 Committing to maintenance versions
Maintenance versions should only be altered to add critical bug fixes,
@@ -791,20 +797,6 @@
Before pushing any change to a maint version, make sure you've
satisfied the steps in L</Committing to blead> above.
-=head2 Grafts
-
-The perl history contains one mistake which was not caught in the
-conversion: a merge was recorded in the history between blead and
-maint-5.10 where no merge actually occurred. Due to the nature of git,
-this is now impossible to fix in the public repository. You can remove
-this mis-merge locally by adding the following line to your
-C<.git/info/grafts> file:
-
- 296f12bbbbaa06de9be9d09d3dcf8f4528898a49 434946e0cb7a32589ed92d18008aaa1d88515930
-
-It is particularly important to have this graft line if any bisecting
-is done in the area of the "merge" in question.
-
=head2 Merging from a branch via GitHub
While we don't encourage the submission of patches via GitHub, that
@@ -832,8 +824,78 @@
And then push back to the repository:
- % git push
+ % git push origin blead
+=head2 Using a smoke-me branch to test changes
+
+Sometimes a change affects code paths which you cannot test on the OSes
+which are directly available to you and it would be wise to have users
+on other OSes test the change before you commit it to blead.
+
+Fortunately, there is a way to get your change smoke-tested on various
+OSes: push it to a "smoke-me" branch and wait for certain automated
+smoke-testers to report the results from their OSes.
+
+The procedure for doing this is roughly as follows (using the example of
+of tonyc's smoke-me branch called win32stat):
+
+First, make a local branch and switch to it:
+
+ % git checkout -b win32stat
+
+Make some changes, build perl and test your changes, then commit them to
+your local branch. Then push your local branch to a remote smoke-me
+branch:
+
+ % git push origin win32stat:smoke-me/tonyc/win32stat
+
+Now you can switch back to blead locally:
+
+ % git checkout blead
+
+and continue working on other things while you wait a day or two,
+keeping an eye on the results reported for your smoke-me branch at
+L<http://perl.develop-help.com/?b=smoke-me/tonyc/win32state>.
+
+If all is well then update your blead branch:
+
+ % git pull
+
+then checkout your smoke-me branch once more and rebase it on blead:
+
+ % git rebase blead win32stat
+
+Now switch back to blead and merge your smoke-me branch into it:
+
+ % git checkout blead
+ % git merge win32stat
+
+As described earlier, if there are many changes on your smoke-me branch
+then you should prepare a merge commit in which to give an overview of
+those changes by using the following command instead of the last
+command above:
+
+ % git merge win32stat --no-ff --no-commit
+
+You should now build perl and test your (merged) changes one last time
+(ideally run the whole test suite, but failing that at least run the
+F<t/porting/*.t> tests) before pushing your changes as usual:
+
+ % git push origin blead
+
+Finally, you should then delete the remote smoke-me branch:
+
+ % git push origin :smoke-me/tonyc/win32stat
+
+(which is likely to produce a warning like this, which can be ignored:
+
+ remote: fatal: ambiguous argument 'refs/heads/smoke-me/tonyc/win32stat': unknown revision or path not in the working tree.
+ remote: Use '--' to separate paths from revisions
+
+) and then delete your local branch:
+
+ % git branch -d win32stat
+
=head2 A note on camel and dromedary
The committers have SSH access to the two servers that serve
Property changes on: trunk/contrib/perl/pod/perlgit.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlglossary.pod
===================================================================
--- trunk/contrib/perl/pod/perlglossary.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlglossary.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlglossary.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlgpl.pod
===================================================================
--- trunk/contrib/perl/pod/perlgpl.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlgpl.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -35,14 +35,15 @@
GNU GENERAL PUBLIC LICENSE
Version 1, February 1989
-
+
Copyright (C) 1989 Free Software Foundation, Inc.
- 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA
+ 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
+
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
-
+
Preamble
-
+
The license agreements of most software companies try to keep users
at the mercy of those companies. By contrast, our General Public
License is intended to guarantee your freedom to share and change free
@@ -50,7 +51,7 @@
General Public License applies to the Free Software Foundation's
software and to any other program whose authors commit to using it.
You can use it for your programs, too.
-
+
When we speak of free software, we are referring to freedom, not
price. Specifically, the General Public License is designed to make
sure that you have the freedom to give away or sell copies of free
@@ -57,21 +58,21 @@
software, that you receive source code or can get it if you want it,
that you can change the software or use pieces of it in new free
programs; and that you know you can do these things.
-
+
To protect your rights, we need to make restrictions that forbid
anyone to deny you these rights or to ask you to surrender the rights.
These restrictions translate to certain responsibilities for you if you
distribute copies of the software, or if you modify it.
-
+
For example, if you distribute copies of a such a program, whether
gratis or for a fee, you must give the recipients all the rights that
you have. You must make sure that they, too, receive or can get the
source code. And you must tell them their rights.
-
+
We protect your rights with two steps: (1) copyright the software, and
(2) offer you this license which gives you legal permission to copy,
distribute and/or modify the software.
-
+
Also, for each author's protection and ours, we want to make certain
that everyone understands that there is no warranty for this free
software. If the software is modified by someone else and passed on, we
@@ -78,13 +79,13 @@
want its recipients to know that what they have is not the original, so
that any problems introduced by others will not reflect on the original
authors' reputations.
-
+
The precise terms and conditions for copying, distribution and
modification follow.
-
+
GNU GENERAL PUBLIC LICENSE
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
-
+
0. This License Agreement applies to any program or other work which
contains a notice placed by the copyright holder saying it may be
distributed under the terms of this General Public License. The
@@ -92,7 +93,7 @@
on the Program" means either the Program or any work containing the
Program or a portion of it, either verbatim or with modifications. Each
licensee is addressed as "you".
-
+
1. You may copy and distribute verbatim copies of the Program's source
code as you receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice and
@@ -101,14 +102,14 @@
other recipients of the Program a copy of this General Public License
along with the Program. You may charge a fee for the physical act of
transferring a copy.
-
+
2. You may modify your copy or copies of the Program or any portion of
it, and copy and distribute such modifications under the terms of Paragraph
1 above, provided that you also do the following:
-
+
a) cause the modified files to carry prominent notices stating that
you changed the files and the date of any change; and
-
+
b) cause the whole of any work that you distribute or publish, that
in whole or in part contains the Program or any part thereof, either
with or without modifications, to be licensed at no charge to all
@@ -115,7 +116,7 @@
third parties under the terms of this General Public License (except
that you may choose to grant warranty protection to some or all
third parties, at your option).
-
+
c) If the modified program normally reads commands interactively when
run, you must cause it, when started running for such interactive use
in the simplest and most usual way, to print or display an
@@ -124,34 +125,34 @@
warranty) and that users may redistribute the program under these
conditions, and telling the user how to view a copy of this General
Public License.
-
+
d) You may charge a fee for the physical act of transferring a
copy, and you may at your option offer warranty protection in
exchange for a fee.
-
+
Mere aggregation of another independent work with the Program (or its
derivative) on a volume of a storage or distribution medium does not bring
the other work under the scope of these terms.
-
+
3. You may copy and distribute the Program (or a portion or derivative of
it, under Paragraph 2) in object code or executable form under the terms of
Paragraphs 1 and 2 above provided that you also do one of the following:
-
+
a) accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,
-
+
b) accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal charge
for the cost of distribution) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,
-
+
c) accompany it with the information you received as to where the
corresponding source code may be obtained. (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
-
+
Source code for a work means the preferred form of the work for making
modifications to it. For an executable file, complete source code means
all the source code for all modules it contains; but, as a special
@@ -159,7 +160,7 @@
libraries that accompany the operating system on which the executable
file runs, or for standard header files or definitions files that
accompany that operating system.
-
+
4. You may not copy, modify, sublicense, distribute or transfer the
Program except as expressly provided under this General Public License.
Any attempt otherwise to copy, modify, sublicense, distribute or transfer
@@ -168,22 +169,22 @@
copies, or rights to use copies, from you under this General Public
License will not have their licenses terminated so long as such parties
remain in full compliance.
-
+
5. By copying, distributing or modifying the Program (or any work based
on the Program) you indicate your acceptance of this license to do so,
and all its terms and conditions.
-
+
6. Each time you redistribute the Program (or any work based on the
Program), the recipient automatically receives a license from the original
licensor to copy, distribute or modify the Program subject to these
terms and conditions. You may not impose any further restrictions on the
recipients' exercise of the rights granted herein.
-
+
7. The Free Software Foundation may publish revised and/or new versions
of the General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
-
+
Each version is given a distinguishing version number. If the Program
specifies a version number of the license which applies to it and "any
later version", you have the option of following the terms and conditions
@@ -191,7 +192,7 @@
Software Foundation. If the Program does not specify a version number of
the license, you may choose any version ever published by the Free Software
Foundation.
-
+
8. If you wish to incorporate parts of the Program into other free
programs whose distribution conditions are different, write to the author
to ask for permission. For software which is copyrighted by the Free
@@ -199,9 +200,9 @@
make exceptions for this. Our decision will be guided by the two goals
of preserving the free status of all derivatives of our free software and
of promoting the sharing and reuse of software generally.
-
+
NO WARRANTY
-
+
9. BECAUSE THE PROGRAM IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
FOR THE PROGRAM, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
@@ -211,7 +212,7 @@
TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS WITH YOU. SHOULD THE
PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING,
REPAIR OR CORRECTION.
-
+
10. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
REDISTRIBUTE THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES,
@@ -221,67 +222,67 @@
YOU OR THIRD PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER
PROGRAMS), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE
POSSIBILITY OF SUCH DAMAGES.
-
+
END OF TERMS AND CONDITIONS
-
+
Appendix: How to Apply These Terms to Your New Programs
-
+
If you develop a new program, and you want it to be of the greatest
possible use to humanity, the best way to achieve this is to make it
free software which everyone can redistribute and change under these
terms.
-
+
To do so, attach the following notices to the program. It is safest to
attach them to the start of each source file to most effectively convey
the exclusion of warranty; and each file should have at least the
"copyright" line and a pointer to where the full notice is found.
-
+
<one line to give the program's name and a brief idea of what it does.>
Copyright (C) 19yy <name of author>
-
+
This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 1, or (at your option)
any later version.
-
+
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
-
+
You should have received a copy of the GNU General Public License
- along with this program; if not, write to the Free Software Foundation,
- Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
-
+ along with this program; if not, write to the Free Software
+ Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA
+ 02110-1301 USA
+
+
Also add information on how to contact you by electronic and paper mail.
-
+
If the program is interactive, make it output a short notice like this
when it starts in an interactive mode:
-
+
Gnomovision version 69, Copyright (C) 19xx name of author
- Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
+ Gnomovision comes with ABSOLUTELY NO WARRANTY; for details type 'show w'.
This is free software, and you are welcome to redistribute it
- under certain conditions; type `show c' for details.
-
- The hypothetical commands `show w' and `show c' should show the
+ under certain conditions; type 'show c' for details.
+
+ The hypothetical commands 'show w' and 'show c' should show the
appropriate parts of the General Public License. Of course, the
- commands you use may be called something other than `show w' and `show
+ commands you use may be called something other than 'show w' and 'show
c'; they could even be mouse-clicks or menu items--whatever suits your
program.
-
+
You should also get your employer (if you work as a programmer) or your
school, if any, to sign a "copyright disclaimer" for the program, if
necessary. Here a sample; alter the names:
-
+
Yoyodyne, Inc., hereby disclaims all copyright interest in the
- program `Gnomovision' (a program to direct compilers to make passes
+ program 'Gnomovision' (a program to direct compilers to make passes
at assemblers) written by James Hacker.
-
+
<signature of Ty Coon>, 1 April 1989
Ty Coon, President of Vice
-
+
That's all there is to it!
=cut
-
-
Property changes on: trunk/contrib/perl/pod/perlgpl.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlguts.pod
===================================================================
--- trunk/contrib/perl/pod/perlguts.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlguts.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -37,6 +37,15 @@
An SV can be created and loaded with one command. There are five types of
values that can be loaded: an integer value (IV), an unsigned integer
value (UV), a double (NV), a string (PV), and another scalar (SV).
+("PV" stands for "Pointer Value". You might think that it is misnamed
+because it is described as pointing only to strings. However, it is
+possible to have it point to other things. For example, inversion
+lists, used in regular expression data structures, are scalars, each
+consisting of an array of UVs which are accessed through PVs. But,
+using it for non-strings requires care, as the underlying assumption of
+much of the internals is that PVs are just for strings. Often, for
+example, a trailing NUL is tacked on automatically. The non-string use
+is documented only in this paragraph.)
The seven routines are:
@@ -56,10 +65,11 @@
can create an empty SV with newSV(len). If C<len> is 0 an empty SV of
type NULL is returned, else an SV of type PV is returned with len + 1 (for
the NUL) bytes of storage allocated, accessible via SvPVX. In both cases
-the SV has value undef.
+the SV has the undef value.
SV *sv = newSV(0); /* no storage allocated */
- SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage allocated */
+ SV *sv = newSV(10); /* 10 (+1) bytes of uninitialised storage
+ * allocated */
To change the value of an I<already-existing> SV, there are eight routines:
@@ -69,7 +79,8 @@
void sv_setpv(SV*, const char*);
void sv_setpvn(SV*, const char*, STRLEN)
void sv_setpvf(SV*, const char*, ...);
- void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool *);
+ void sv_vsetpvfn(SV*, const char*, STRLEN, va_list *,
+ SV **, I32, bool *);
void sv_setsv(SV*, SV*);
Notice that you can choose to specify the length of the string to be
@@ -77,7 +88,8 @@
allow Perl to calculate the length by using C<sv_setpv> or by specifying
0 as the second argument to C<newSVpv>. Be warned, though, that Perl will
determine the string's length by using C<strlen>, which depends on the
-string terminating with a NUL character.
+string terminating with a NUL character, and not otherwise containing
+NULs.
The arguments of C<sv_setpvf> are processed like C<sprintf>, and the
formatted output becomes the value.
@@ -128,7 +140,7 @@
SV *s;
STRLEN len;
- char * ptr;
+ char *ptr;
ptr = SvPV(s, len);
foo(ptr, len);
@@ -144,7 +156,7 @@
which will determine if more memory needs to be allocated. If so, it will
call the function C<sv_grow>. Note that C<SvGROW> can only increase, not
decrease, the allocated memory of an SV and that it does not automatically
-add a byte for the a trailing NUL (perl's own string functions typically do
+add space for the trailing NUL byte (perl's own string functions typically do
C<SvGROW(sv, len + 1)>).
If you have an SV and want to know what kind of data Perl thinks is stored
@@ -173,7 +185,8 @@
void sv_catpv(SV*, const char*);
void sv_catpvn(SV*, const char*, STRLEN);
void sv_catpvf(SV*, const char*, ...);
- void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **, I32, bool);
+ void sv_vcatpvfn(SV*, const char*, STRLEN, va_list *, SV **,
+ I32, bool);
void sv_catsv(SV*, SV*);
The first function calculates the length of the string to be appended by
@@ -300,7 +313,7 @@
These will tell you if you truly have an integer, double, or string pointer
stored in your SV. The "p" stands for private.
-The are various ways in which the private and public flags may differ.
+There are various ways in which the private and public flags may differ.
For example, a tied SV may have a valid underlying value in the IV slot
(so SvIOKp is true), but the data should be accessed via the FETCH
routine rather than directly, so SvIOK is false. Another is when
@@ -324,7 +337,7 @@
The second argument points to an array containing C<num> C<SV*>'s. Once the
AV has been created, the SVs can be destroyed, if so desired.
-Once the AV has been created, the following operations are possible on AVs:
+Once the AV has been created, the following operations are possible on it:
void av_push(AV*, SV*);
SV* av_pop(AV*);
@@ -338,11 +351,11 @@
Here are some other functions:
- I32 av_len(AV*);
+ I32 av_top_index(AV*);
SV** av_fetch(AV*, I32 key, I32 lval);
SV** av_store(AV*, I32 key, SV* val);
-The C<av_len> function returns the highest index value in array (just
+The C<av_top_index> function returns the highest index value in an array (just
like $#array in Perl). If the array is empty, -1 is returned. The
C<av_fetch> function returns the value at index C<key>, but if C<lval>
is non-zero, then C<av_fetch> will store an undef value at that index.
@@ -353,6 +366,8 @@
C<av_fetch> and C<av_store> both return C<SV**>'s, not C<SV*>'s as their
return value.
+A few more:
+
void av_clear(AV*);
void av_undef(AV*);
void av_extend(AV*, I32 key);
@@ -380,7 +395,7 @@
HV* newHV();
-Once the HV has been created, the following operations are possible on HVs:
+Once the HV has been created, the following operations are possible on it:
SV** hv_store(HV*, const char* key, U32 klen, SV* val, U32 hash);
SV** hv_fetch(HV*, const char* key, U32 klen, I32 lval);
@@ -399,7 +414,8 @@
value. However, you should check to make sure that the return value is
not NULL before dereferencing it.
-These two functions check if a hash table entry exists, and deletes it.
+The first of these two functions checks if a hash table entry exists, and the
+second deletes it.
bool hv_exists(HV*, const char* key, U32 klen);
SV* hv_delete(HV*, const char* key, U32 klen, I32 flags);
@@ -416,7 +432,7 @@
table but does not actually delete the hash table. The C<hv_undef> deletes
both the entries and the hash table itself.
-Perl keeps the actual data in linked list of structures with a typedef of HE.
+Perl keeps the actual data in a linked list of structures with a typedef of HE.
These contain the actual key and value pointers (plus extra administrative
overhead). The key is a string pointer; the value is an C<SV*>. However,
once you have an C<HE*>, to get the actual key and value, use the routines
@@ -446,15 +462,13 @@
This returns NULL if the variable does not exist.
-The hash algorithm is defined in the C<PERL_HASH(hash, key, klen)> macro:
+The hash algorithm is defined in the C<PERL_HASH> macro:
- hash = 0;
- while (klen--)
- hash = (hash * 33) + *key++;
- hash = hash + (hash >> 5); /* after 5.6 */
+ PERL_HASH(hash, key, klen)
-The last step was added in version 5.6 to improve distribution of
-lower bits in the resulting hash value.
+The exact implementation of this macro varies by architecture and version
+of perl, and the return value may change per invocation, so the value
+is only valid for the duration of a single perl process.
See L<Understanding the Magic of Tied Hashes and Arrays> for more
information on how to use the hash access functions on tied hashes.
@@ -559,7 +573,7 @@
=head2 References
References are a special type of scalar that point to other data types
-(including references).
+(including other references).
To create a reference, use either of the following functions:
@@ -590,17 +604,13 @@
The most useful types that will be returned are:
- SVt_IV Scalar
- SVt_NV Scalar
- SVt_PV Scalar
- SVt_RV Scalar
- SVt_PVAV Array
- SVt_PVHV Hash
- SVt_PVCV Code
- SVt_PVGV Glob (possible a file handle)
- SVt_PVMG Blessed or Magical Scalar
+ < SVt_PVAV Scalar
+ SVt_PVAV Array
+ SVt_PVHV Hash
+ SVt_PVCV Code
+ SVt_PVGV Glob (possibly a file handle)
-See the F<sv.h> header file for more details.
+See L<perlapi/svtype> for more details.
=head2 Blessed References and Class Objects
@@ -619,41 +629,46 @@
/* Still under construction */
-Upgrades rv to reference if not already one. Creates new SV for rv to
-point to. If C<classname> is non-null, the SV is blessed into the specified
-class. SV is returned.
+The following function upgrades rv to reference if not already one.
+Creates a new SV for rv to point to. If C<classname> is non-null, the SV
+is blessed into the specified class. SV is returned.
SV* newSVrv(SV* rv, const char* classname);
-Copies integer, unsigned integer or double into an SV whose reference is C<rv>. SV is blessed
-if C<classname> is non-null.
+The following three functions copy integer, unsigned integer or double
+into an SV whose reference is C<rv>. SV is blessed if C<classname> is
+non-null.
SV* sv_setref_iv(SV* rv, const char* classname, IV iv);
SV* sv_setref_uv(SV* rv, const char* classname, UV uv);
SV* sv_setref_nv(SV* rv, const char* classname, NV iv);
-Copies the pointer value (I<the address, not the string!>) into an SV whose
-reference is rv. SV is blessed if C<classname> is non-null.
+The following function copies the pointer value (I<the address, not the
+string!>) into an SV whose reference is rv. SV is blessed if C<classname>
+is non-null.
- SV* sv_setref_pv(SV* rv, const char* classname, PV iv);
+ SV* sv_setref_pv(SV* rv, const char* classname, void* pv);
-Copies string into an SV whose reference is C<rv>. Set length to 0 to let
-Perl calculate the string length. SV is blessed if C<classname> is non-null.
+The following function copies a string into an SV whose reference is C<rv>.
+Set length to 0 to let Perl calculate the string length. SV is blessed if
+C<classname> is non-null.
- SV* sv_setref_pvn(SV* rv, const char* classname, PV iv, STRLEN length);
+ SV* sv_setref_pvn(SV* rv, const char* classname, char* pv,
+ STRLEN length);
-Tests whether the SV is blessed into the specified class. It does not
-check inheritance relationships.
+The following function tests whether the SV is blessed into the specified
+class. It does not check inheritance relationships.
int sv_isa(SV* sv, const char* name);
-Tests whether the SV is a reference to a blessed object.
+The following function tests whether the SV is a reference to a blessed object.
int sv_isobject(SV* sv);
-Tests whether the SV is derived from the specified class. SV can be either
-a reference to a blessed object or a string containing a class name. This
-is the function implementing the C<UNIVERSAL::isa> functionality.
+The following function tests whether the SV is derived from the specified
+class. SV can be either a reference to a blessed object or a string
+containing a class name. This is the function implementing the
+C<UNIVERSAL::isa> functionality.
bool sv_derived_from(SV* sv, const char* name);
@@ -766,7 +781,7 @@
The first call creates a mortal SV (with no value), the second converts an existing
SV to a mortal SV (and thus defers a call to C<SvREFCNT_dec>), and the
third creates a mortal copy of an existing SV.
-Because C<sv_newmortal> gives the new SV no value,it must normally be given one
+Because C<sv_newmortal> gives the new SV no value, it must normally be given one
via C<sv_setpv>, C<sv_setiv>, etc. :
SV *tmp = sv_newmortal();
@@ -781,7 +796,7 @@
can happen if you make the same value mortal within multiple contexts,
or if you make a variable mortal multiple times. Thinking of "Mortalization"
as deferred C<SvREFCNT_dec> should help to minimize such problems.
-For example if you are passing an SV which you I<know> has high enough REFCNT
+For example if you are passing an SV which you I<know> has a high enough REFCNT
to survive its use on the stack you need not do any mortalization.
If you are not sure then doing an C<SvREFCNT_inc> and C<sv_2mortal>, or
making a C<sv_mortalcopy> is safer.
@@ -912,7 +927,7 @@
Perl adds magic to an SV using the sv_magic function:
- void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
+ void sv_magic(SV* sv, SV* obj, int how, const char* name, I32 namlen);
The C<sv> argument is a pointer to the SV that is to acquire a new magical
feature.
@@ -985,7 +1000,8 @@
int (*svt_clear)(SV* sv, MAGIC* mg);
int (*svt_free)(SV* sv, MAGIC* mg);
- int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv, const char *name, I32 namlen);
+ int (*svt_copy)(SV *sv, MAGIC* mg, SV *nsv,
+ const char *name, I32 namlen);
int (*svt_dup)(MAGIC *mg, CLONE_PARAMS *param);
int (*svt_local)(SV *nsv, MAGIC *mg);
@@ -995,17 +1011,18 @@
routines that perform additional actions depending on which function is
being called.
- Function pointer Action taken
- ---------------- ------------
- svt_get Do something before the value of the SV is retrieved.
- svt_set Do something after the SV is assigned a value.
- svt_len Report on the SV's length.
- svt_clear Clear something the SV represents.
- svt_free Free any extra storage associated with the SV.
+ Function pointer Action taken
+ ---------------- ------------
+ svt_get Do something before the value of the SV is
+ retrieved.
+ svt_set Do something after the SV is assigned a value.
+ svt_len Report on the SV's length.
+ svt_clear Clear something the SV represents.
+ svt_free Free any extra storage associated with the SV.
- svt_copy copy tied variable magic to a tied element
- svt_dup duplicate a magic structure during thread cloning
- svt_local copy magic to local value during 'local'
+ svt_copy copy tied variable magic to a tied element
+ svt_dup duplicate a magic structure during thread cloning
+ svt_local copy magic to local value during 'local'
For instance, the MGVTBL structure called C<vtbl_sv> (which corresponds
to an C<mg_type> of C<PERL_MAGIC_sv>) contains:
@@ -1027,55 +1044,74 @@
The current kinds of Magic Virtual Tables are:
- mg_type
- (old-style char and macro) MGVTBL Type of magic
- -------------------------- ------ -------------
- \0 PERL_MAGIC_sv vtbl_sv Special scalar variable
- A PERL_MAGIC_overload vtbl_amagic %OVERLOAD hash
- a PERL_MAGIC_overload_elem vtbl_amagicelem %OVERLOAD hash element
- c PERL_MAGIC_overload_table (none) Holds overload table (AMT)
- on stash
- B PERL_MAGIC_bm vtbl_bm Boyer-Moore (fast string search)
- D PERL_MAGIC_regdata vtbl_regdata Regex match position data
- (@+ and @- vars)
- d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data
- element
- E PERL_MAGIC_env vtbl_env %ENV hash
- e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
- f PERL_MAGIC_fm vtbl_fm Formline ('compiled' format)
- g PERL_MAGIC_regex_global vtbl_mglob m//g target / study()ed string
- H PERL_MAGIC_hints vtbl_hints %^H hash
- h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element
- I PERL_MAGIC_isa vtbl_isa @ISA array
- i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
- k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue
- L PERL_MAGIC_dbfile (none) Debugger %_<filename
- l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename element
- o PERL_MAGIC_collxfrm vtbl_collxfrm Locale collate transformation
- P PERL_MAGIC_tied vtbl_pack Tied array or hash
- p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
- q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
- r PERL_MAGIC_qr vtbl_qr precompiled qr// regex
- S PERL_MAGIC_sig vtbl_sig %SIG hash
- s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element
- t PERL_MAGIC_taint vtbl_taint Taintedness
- U PERL_MAGIC_uvar vtbl_uvar Available for use by extensions
- v PERL_MAGIC_vec vtbl_vec vec() lvalue
- V PERL_MAGIC_vstring (none) v-string scalars
- w PERL_MAGIC_utf8 vtbl_utf8 UTF-8 length+offset cache
- x PERL_MAGIC_substr vtbl_substr substr() lvalue
- y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
- variable / smart parameter
- vivification
- # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
- . PERL_MAGIC_pos vtbl_pos pos() lvalue
- < PERL_MAGIC_backref vtbl_backref back pointer to a weak ref
- ~ PERL_MAGIC_ext (none) Available for use by extensions
- : PERL_MAGIC_symtab (none) hash used as symbol table
- % PERL_MAGIC_rhash (none) hash used as restricted hash
- @ PERL_MAGIC_arylen_p vtbl_arylen_p pointer to $#a from @a
+=for comment
+This table is generated by regen/mg_vtable.pl. Any changes made here
+will be lost.
+=for mg_vtable.pl begin
+ mg_type
+ (old-style char and macro) MGVTBL Type of magic
+ -------------------------- ------ -------------
+ \0 PERL_MAGIC_sv vtbl_sv Special scalar variable
+ # PERL_MAGIC_arylen vtbl_arylen Array length ($#ary)
+ % PERL_MAGIC_rhash (none) extra data for restricted
+ hashes
+ & PERL_MAGIC_proto (none) my sub prototype CV
+ . PERL_MAGIC_pos vtbl_pos pos() lvalue
+ : PERL_MAGIC_symtab (none) extra data for symbol
+ tables
+ < PERL_MAGIC_backref vtbl_backref for weak ref data
+ @ PERL_MAGIC_arylen_p (none) to move arylen out of XPVAV
+ B PERL_MAGIC_bm vtbl_regexp Boyer-Moore
+ (fast string search)
+ c PERL_MAGIC_overload_table vtbl_ovrld Holds overload table
+ (AMT) on stash
+ D PERL_MAGIC_regdata vtbl_regdata Regex match position data
+ (@+ and @- vars)
+ d PERL_MAGIC_regdatum vtbl_regdatum Regex match position data
+ element
+ E PERL_MAGIC_env vtbl_env %ENV hash
+ e PERL_MAGIC_envelem vtbl_envelem %ENV hash element
+ f PERL_MAGIC_fm vtbl_regexp Formline
+ ('compiled' format)
+ g PERL_MAGIC_regex_global vtbl_mglob m//g target
+ H PERL_MAGIC_hints vtbl_hints %^H hash
+ h PERL_MAGIC_hintselem vtbl_hintselem %^H hash element
+ I PERL_MAGIC_isa vtbl_isa @ISA array
+ i PERL_MAGIC_isaelem vtbl_isaelem @ISA array element
+ k PERL_MAGIC_nkeys vtbl_nkeys scalar(keys()) lvalue
+ L PERL_MAGIC_dbfile (none) Debugger %_<filename
+ l PERL_MAGIC_dbline vtbl_dbline Debugger %_<filename
+ element
+ N PERL_MAGIC_shared (none) Shared between threads
+ n PERL_MAGIC_shared_scalar (none) Shared between threads
+ o PERL_MAGIC_collxfrm vtbl_collxfrm Locale transformation
+ P PERL_MAGIC_tied vtbl_pack Tied array or hash
+ p PERL_MAGIC_tiedelem vtbl_packelem Tied array or hash element
+ q PERL_MAGIC_tiedscalar vtbl_packelem Tied scalar or handle
+ r PERL_MAGIC_qr vtbl_regexp precompiled qr// regex
+ S PERL_MAGIC_sig (none) %SIG hash
+ s PERL_MAGIC_sigelem vtbl_sigelem %SIG hash element
+ t PERL_MAGIC_taint vtbl_taint Taintedness
+ U PERL_MAGIC_uvar vtbl_uvar Available for use by
+ extensions
+ u PERL_MAGIC_uvar_elem (none) Reserved for use by
+ extensions
+ V PERL_MAGIC_vstring (none) SV was vstring literal
+ v PERL_MAGIC_vec vtbl_vec vec() lvalue
+ w PERL_MAGIC_utf8 vtbl_utf8 Cached UTF-8 information
+ x PERL_MAGIC_substr vtbl_substr substr() lvalue
+ y PERL_MAGIC_defelem vtbl_defelem Shadow "foreach" iterator
+ variable / smart parameter
+ vivification
+ ] PERL_MAGIC_checkcall vtbl_checkcall inlining/mutation of call
+ to this CV
+ ~ PERL_MAGIC_ext (none) Available for use by
+ extensions
+
+=for mg_vtable.pl end
+
When an uppercase and lowercase letter both exist in the table, then the
uppercase letter is typically used to represent some kind of composite type
(a list or a hash), and the lowercase letter is used to represent an element
@@ -1125,7 +1161,7 @@
an C<SV> through the functions C<hv_store_ent>, C<hv_fetch_ent>,
C<hv_delete_ent>, and C<hv_exists_ent>. Accessing the key as a string
through the functions without the C<..._ent> suffix circumvents the
-hook. See L<Hash::Util::Fieldhash/Guts> for a detailed description.
+hook. See L<Hash::Util::FieldHash/GUTS> for a detailed description.
Note that because multiple extensions may be using C<PERL_MAGIC_ext>
or C<PERL_MAGIC_uvar> magic, it is important for extensions to take
@@ -1160,13 +1196,14 @@
=head2 Finding Magic
- MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that type */
+ MAGIC *mg_find(SV *sv, int type); /* Finds the magic pointer of that
+ * type */
This routine returns a pointer to a C<MAGIC> structure stored in the SV.
If the SV does not have that magical feature, C<NULL> is returned. If the
SV has multiple instances of that magical feature, the first one will be
returned. C<mg_findext> can be used to find a C<MAGIC> structure of an SV
-based on both it's magic type and it's magic virtual table:
+based on both its magic type and its magic virtual table:
MAGIC *mg_findext(SV *sv, int type, MGVTBL *vtbl);
@@ -1463,7 +1500,8 @@
PUSHs(sv_2mortal(newSVuv(an_unsigned_integer)))
PUSHs(sv_2mortal(newSVnv(a_double)))
PUSHs(sv_2mortal(newSVpv("Some String",0)))
- /* Although the last example is better written as the more efficient: */
+ /* Although the last example is better written as the more
+ * efficient: */
PUSHs(newSVpvs_flags("Some String", SVs_TEMP))
And now the Perl program calling C<tzname>, the two values will be assigned
@@ -1476,7 +1514,7 @@
XPUSHs(SV*)
-This macro automatically adjust the stack for you, if needed. Thus, you
+This macro automatically adjusts the stack for you, if needed. Thus, you
do not need to call C<EXTEND> to extend the stack.
Despite their suggestions in earlier versions of this document the macros
@@ -1486,6 +1524,28 @@
For more information, consult L<perlxs> and L<perlxstut>.
+=head2 Autoloading with XSUBs
+
+If an AUTOLOAD routine is an XSUB, as with Perl subroutines, Perl puts the
+fully-qualified name of the autoloaded subroutine in the $AUTOLOAD variable
+of the XSUB's package.
+
+But it also puts the same information in certain fields of the XSUB itself:
+
+ HV *stash = CvSTASH(cv);
+ const char *subname = SvPVX(cv);
+ STRLEN name_length = SvCUR(cv); /* in bytes */
+ U32 is_utf8 = SvUTF8(cv);
+
+C<SvPVX(cv)> contains just the sub name itself, not including the package.
+For an AUTOLOAD routine in UNIVERSAL or one of its superclasses,
+C<CvSTASH(cv)> returns NULL during a method call on a nonexistent package.
+
+B<Note>: Setting $AUTOLOAD stopped working in 5.6.1, which did not support
+XS AUTOLOAD subs at all. Perl 5.8.0 introduced the use of fields in the
+XSUB itself. Perl 5.16.0 restored the setting of $AUTOLOAD. If you need
+to support 5.8-5.14, use the XSUB's fields.
+
=head2 Calling Perl Routines from within C Programs
There are four routines that can be used to call a Perl subroutine from
@@ -1494,7 +1554,7 @@
I32 call_sv(SV*, I32);
I32 call_pv(const char*, I32);
I32 call_method(const char*, I32);
- I32 call_argv(const char*, I32, register char**);
+ I32 call_argv(const char*, I32, char**);
The routine most often used is C<call_sv>. The C<SV*> argument
contains either the name of the Perl subroutine to be called, or a
@@ -1586,7 +1646,7 @@
=head2 PerlIO
-The most recent development releases of Perl has been experimenting with
+The most recent development releases of Perl have been experimenting with
removing Perl's dependency on the "normal" standard I/O suite and allowing
other stdio implementations to be used. This involves creating a new
abstraction layer that then calls whichever implementation of stdio Perl
@@ -1864,7 +1924,7 @@
static void my_peep(pTHX_ OP *o)
{
/* custom per-subroutine optimisation goes here */
- prev_peepp(o);
+ prev_peepp(aTHX_ o);
/* custom per-subroutine optimisation may also go here */
}
BOOT:
@@ -1878,7 +1938,7 @@
for(; o; o = o->op_next) {
/* custom per-op optimisation goes here */
}
- prev_rpeepp(orig_o);
+ prev_rpeepp(aTHX_ orig_o);
}
BOOT:
prev_rpeepp = PL_rpeepp;
@@ -2079,7 +2139,7 @@
S_incline(pTHX_ char *s)
STATIC becomes "static" in C, and may be #define'd to nothing in some
-configurations in future.
+configurations in the future.
A public function (i.e. part of the internal API, but not necessarily
sanctioned for use in extensions) begins like this:
@@ -2171,7 +2231,7 @@
Perl_sv_setiv(sv, num);
-You have to do nothing new in your extension to get this; since
+You don't have to do anything new in your extension to get this; since
the Perl library provides Perl_get_context(), it will all just
work.
@@ -2359,9 +2419,9 @@
=item n
-This does not need a interpreter context, so the definition has no
+This does not need an interpreter context, so the definition has no
C<pTHX>, and it follows that callers don't use C<aTHX>. (See
-L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.)
+L</Background and PERL_IMPLICIT_CONTEXT>.)
=item r
@@ -2577,7 +2637,8 @@
In general, you either have to know what you're dealing with, or you
have to guess. The API function C<is_utf8_string> can help; it'll tell
you if a string contains only valid UTF-8 characters. However, it can't
-do the work for you. On a character-by-character basis, C<is_utf8_char>
+do the work for you. On a character-by-character basis,
+C<is_utf8_char_buf>
will tell you whether the current character in a string is valid UTF-8.
=head2 How does UTF-8 represent Unicode characters?
@@ -2610,22 +2671,24 @@
whether the byte can be encoded as a single byte even in UTF-8):
U8 *utf;
+ U8 *utf_end; /* 1 beyond buffer pointed to by utf */
UV uv; /* Note: a UV, not a U8, not a char */
+ STRLEN len; /* length of character in bytes */
if (!UTF8_IS_INVARIANT(*utf))
/* Must treat this as UTF-8 */
- uv = utf8_to_uv(utf);
+ uv = utf8_to_uvchr_buf(utf, utf_end, &len);
else
/* OK to treat this character as a byte */
uv = *utf;
-You can also see in that example that we use C<utf8_to_uv> to get the
-value of the character; the inverse function C<uv_to_utf8> is available
+You can also see in that example that we use C<utf8_to_uvchr_buf> to get the
+value of the character; the inverse function C<uvchr_to_utf8> is available
for putting a UV into UTF-8:
if (!UTF8_IS_INVARIANT(uv))
/* Must treat this as UTF8 */
- utf8 = uv_to_utf8(utf8, uv);
+ utf8 = uvchr_to_utf8(utf8, uv);
else
/* OK to treat this character as a byte */
*utf8++ = uv;
@@ -2725,19 +2788,19 @@
=item *
There's no way to tell if a string is UTF-8 or not. You can tell if an SV
-is UTF-8 by looking at is C<SvUTF8> flag. Don't forget to set the flag if
+is UTF-8 by looking at its C<SvUTF8> flag. Don't forget to set the flag if
something should be UTF-8. Treat the flag as part of the PV, even though
it's not - if you pass on the PV to somewhere, pass on the flag too.
=item *
-If a string is UTF-8, B<always> use C<utf8_to_uv> to get at the value,
+If a string is UTF-8, B<always> use C<utf8_to_uvchr_buf> to get at the value,
unless C<UTF8_IS_INVARIANT(*s)> in which case you can use C<*s>.
=item *
When writing a character C<uv> to a UTF-8 string, B<always> use
-C<uv_to_utf8>, unless C<UTF8_IS_INVARIANT(uv))> in which case
+C<uvchr_to_utf8>, unless C<UTF8_IS_INVARIANT(uv))> in which case
you can use C<*s = uv>.
=item *
@@ -2749,7 +2812,7 @@
=head1 Custom Operators
-Custom operator support is a new experimental feature that allows you to
+Custom operator support is an experimental feature that allows you to
define your own ops. This is primarily to allow the building of
interpreters for other languages in the Perl core, but it also allows
optimizations through the creation of "macro-ops" (ops which perform the
@@ -2771,7 +2834,7 @@
a custom peephole optimizer with the C<optimize> module.
When you do this, you replace ordinary Perl ops with custom ops by
-creating ops with the type C<OP_CUSTOM> and the C<pp_addr> of your own
+creating ops with the type C<OP_CUSTOM> and the C<op_ppaddr> of your own
PP function. This should be defined in XS code, and should look like
the PP ops in C<pp_*.c>. You are responsible for ensuring that your op
takes the appropriate number of values from the stack, and you are
Property changes on: trunk/contrib/perl/pod/perlguts.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlhack.pod
===================================================================
--- trunk/contrib/perl/pod/perlhack.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlhack.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -56,15 +56,16 @@
The next step is to submit your patch to the Perl core ticket system
via email.
-Assuming your patch consists of a single git commit, you can send it to
-perlbug with this command line:
+Assuming your patch consists of a single git commit, the following
+writes the file as a MIME attachment, and sends it with a meaningful
+subject:
- % git format-patch HEAD^1..HEAD
- % perlbug -s '[PATCH] `git log --pretty=format:%s HEAD^1..HEAD`' -f 0001-*.patch
+ % git format-patch -1 --attach
+ % perlbug -s "[PATCH] $(git log -1 --oneline HEAD)" -f 0001-*.patch
The perlbug program will ask you a few questions about your email
-address and the patch you're submitting. Once you've answered them you
-can submit your patch.
+address and the patch you're submitting. Once you've answered them it
+will submit your patch via email.
=item * Thank you
@@ -75,9 +76,9 @@
=head1 BUG REPORTING
-If you want to report a bug in Perl, you must use the F<perlbug> command
-line tool. This tool will ensure that your bug report includes all the
-relevant system and configuration information.
+If you want to report a bug in Perl, you must use the F<perlbug>
+command line tool. This tool will ensure that your bug report includes
+all the relevant system and configuration information.
To browse existing Perl bugs and patches, you can use the web interface
at L<http://rt.perl.org/>.
@@ -94,7 +95,8 @@
The perl5-porters (p5p) mailing list is where the Perl standard
distribution is maintained and developed. The people who maintain Perl
-are also referred to as the "Perl 5 Porters", or just the "porters".
+are also referred to as the "Perl 5 Porters", "p5p" or just the
+"porters".
A searchable archive of the list is available at
L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>. There is
@@ -108,6 +110,12 @@
repository. See L<http://lists.perl.org/list/perl5-changes.html> for
subscription and archive information.
+=head2 #p5p on IRC
+
+Many porters are also active on the L<irc://irc.perl.org/#p5p> channel.
+Feel free to join the channel and ask questions about hacking on the
+Perl core.
+
=head1 GETTING THE PERL SOURCE
All of Perl's source code is kept centrally in a Git repository at
@@ -215,7 +223,7 @@
made. If you prefer to send a single patch for all commits, you can use
C<git diff>.
- % git co blead
+ % git checkout blead
% git pull
% git diff blead my-branch-name
@@ -373,6 +381,21 @@
"if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
+=item *
+
+Do not declare variables using "register". It may be counterproductive
+with modern compilers, and is deprecated in C++, under which the Perl
+source is regularly compiled.
+
+=item *
+
+In-line functions that are in headers that are accessible to XS code
+need to be able to compile without warnings with commonly used extra
+compilation flags, such as gcc's C<-Wswitch-default> which warns
+whenever a switch statement does not have a "default" case. The use of
+these extra flags is to catch potential problems in legal C code, and is
+often used by Perl aggregators, such as Linux distributors.
+
=back
=head3 Test suite
@@ -464,15 +487,20 @@
This works just like patching anything else, with one extra
consideration.
-Some core modules also live on CPAN and are maintained outside of the
-Perl core. When the author updates the module, the updates are simply
-copied into the core.
-
Modules in the F<cpan/> directory of the source tree are maintained
-outside of the Perl core. See that module's listing on documentation or
-its listing on L<http://search.cpan.org/> for more information on
-reporting bugs and submitting patches.
+outside of the Perl core. When the author updates the module, the
+updates are simply copied into the core. See that module's
+documentation or its listing on L<http://search.cpan.org/> for more
+information on reporting bugs and submitting patches.
+In most cases, patches to modules in F<cpan/> should be sent upstream
+and should not be applied to the Perl core individually. If a patch to
+a file in F<cpan/> absolutely cannot wait for the fix to be made
+upstream, released to CPAN and copied to blead, you must add (or
+update) a C<CUSTOMIZED> entry in the F<"Porting/Maintainers.pl"> file
+to flag that a local modification has been made. See
+F<"Porting/Maintainers.pl"> for more details.
+
In contrast, modules in the F<dist/> directory are maintained in the
core.
@@ -684,15 +712,18 @@
L<Test::More>, but avoids loading most modules and uses as few core
features as possible.
-If you write your own test, use the L<Test Anything Protocol|TAP>.
+If you write your own test, use the L<Test Anything
+Protocol|http://testanything.org>.
=over 4
-=item * F<t/base> and F<t/comp>
+=item * F<t/base>, F<t/comp> and F<t/opbasic>
Since we don't know if require works, or even subroutines, use ad hoc
-tests for these two. Step carefully to avoid using the feature being
-tested.
+tests for these three. Step carefully to avoid using the feature being
+tested. Tests in F<t/opbasic>, for instance, have been placed there rather
+than in F<t/op> because they test functionality which F<t/test.pl> presumes
+has already been demonstrated to work.
=item * F<t/cmd>, F<t/run>, F<t/io> and F<t/op>
@@ -766,8 +797,8 @@
=item * test.torture torturetest
-Run all the usual tests and some extra tests. As of Perl 5.8.0, the only
-extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
+Run all the usual tests and some extra tests. As of Perl 5.8.0, the
+only extra tests are Abigail's JAPHs, F<t/japh/abigail.t>.
You can also run the torture test with F<t/harness> by giving
C<-torture> argument to F<t/harness>.
@@ -827,14 +858,14 @@
non-conflicting test scripts itself, and there is no standard interface
to C<make> utilities to interact with their job schedulers.
-Note that currently some test scripts may fail when run in parallel (most
-notably C<ext/IO/t/io_dir.t>). If necessary, run just the failing scripts
-again sequentially and see if the failures go away.
+Note that currently some test scripts may fail when run in parallel
+(most notably F<ext/IO/t/io_dir.t>). If necessary, run just the failing
+scripts again sequentially and see if the failures go away.
=head2 Running tests by hand
-You can run part of the test suite by hand by using one of the following
-commands from the F<t/> directory:
+You can run part of the test suite by hand by using one of the
+following commands from the F<t/> directory:
./perl -I../lib TEST list-of-.t-files
@@ -846,9 +877,9 @@
=head2 Using F<t/harness> for testing
-If you use C<harness> for testing, you have several command line options
-available to you. The arguments are as follows, and are in the order
-that they must appear if used together.
+If you use C<harness> for testing, you have several command line
+options available to you. The arguments are as follows, and are in the
+order that they must appear if used together.
harness -v -torture -re=pattern LIST OF FILES TO TEST
harness -v -torture -re LIST OF PATTERNS TO MATCH
@@ -934,6 +965,13 @@
This sets a variable in op/numconvert.t.
+=item * PERL_TEST_MEMORY
+
+Setting this variable includes the tests in F<t/bigmem/>. This should
+be set to the number of gigabytes of memory available for testing,
+eg. C<PERL_TEST_MEMORY=4> indicates that tests that require 4GiB of
+available memory can be run safely.
+
=back
See also the documentation for the Test and Test::Harness modules, for
@@ -1001,13 +1039,6 @@
is only useful to the pumpkin holder, but most of it applies to anyone
wanting to go about Perl development.
-=item * The perl5-porters FAQ
-
-This should be available from
-http://dev.perl.org/perl5/docs/p5p-faq.html . It contains hints on
-reading perl5-porters, information on how perl5-porters works and how
-Perl development in general works.
-
=back
=head1 CPAN TESTERS AND PERL SMOKERS
@@ -1074,9 +1105,9 @@
to that file's purpose.
Like chapters in many books, all top-level Perl source files (along
-with a few others here and there) begin with an epigramic inscription
-that alludes, indirectly and metaphorically, to the material you're
-about to read.
+with a few others here and there) begin with an epigrammatic
+inscription that alludes, indirectly and metaphorically, to the
+material you're about to read.
Quotations are taken from writings of J.R.R. Tolkien pertaining to his
Legendarium, almost always from I<The Lord of the Rings>. Chapters and
Property changes on: trunk/contrib/perl/pod/perlhack.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlhacktips.pod
===================================================================
--- trunk/contrib/perl/pod/perlhacktips.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlhacktips.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,3 +1,4 @@
+
=encoding utf8
=for comment
@@ -203,7 +204,7 @@
long pony = *p; /* BAD */
Many platforms, quite rightly so, will give you a core dump instead of
-a pony if the p happens not be correctly aligned.
+a pony if the p happens not to be correctly aligned.
=item *
@@ -276,11 +277,9 @@
differ, you shouldn't use numeric (decimal, octal, nor hex) constants
to refer to characters. You can safely say 'A', but not 0x41. You can
safely say '\n', but not \012. If a character doesn't have a trivial
-input form, you can create a #define for it in both C<utfebcdic.h> and
-C<utf8.h>, so that it resolves to different values depending on the
-character set being used. (There are three different EBCDIC character
-sets defined in C<utfebcdic.h>, so it might be best to insert the
-#define three times in that file.)
+input form, you should add it to the list in
+F<regen/unicode_constants.pl>, and have Perl create #defines for you,
+based on the current platform.
Also, the range 'A' - 'Z' in ASCII is an unbroken sequence of 26 upper
case alphabetic characters. That is not true in EBCDIC. Nor for 'a' to
@@ -885,7 +884,8 @@
Download the pmd-bin-X.Y.zip () from the SourceForge site, extract the
pmd-X.Y.jar from it, and then run that on source code thusly:
- java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD --minimum-tokens 100 --files /some/where/src --language c > cpd.txt
+ java -cp pmd-X.Y.jar net.sourceforge.pmd.cpd.CPD \
+ --minimum-tokens 100 --files /some/where/src --language c > cpd.txt
You may run into memory limits, in which case you should use the -Xmx
option:
@@ -966,14 +966,16 @@
=head1 MEMORY DEBUGGERS
-B<NOTE 1>: Running under memory debuggers such as Purify, valgrind, or
-Third Degree greatly slows down the execution: seconds become minutes,
-minutes become hours. For example as of Perl 5.8.1, the
+B<NOTE 1>: Running under older memory debuggers such as Purify,
+valgrind or Third Degree greatly slows down the execution: seconds
+become minutes, minutes become hours. For example as of Perl 5.8.1, the
ext/Encode/t/Unicode.t takes extraordinarily long to complete under
e.g. Purify, Third Degree, and valgrind. Under valgrind it takes more
than six hours, even on a snappy computer. The said test must be doing
something that is quite unfriendly for memory debuggers. If you don't
feel like waiting, that you can simply kill away the perl process.
+Roughly valgrind slows down execution by factor 10, AddressSanitizer by
+factor 2.
B<NOTE 2>: To minimize the number of memory leak false alarms (see
L</PERL_DESTRUCT_LEVEL> for more information), you have to set the
@@ -1136,11 +1138,12 @@
=head2 valgrind
-The excellent valgrind tool can be used to find out both memory leaks
-and illegal memory accesses. As of version 3.3.0, Valgrind only
-supports Linux on x86, x86-64 and PowerPC. The special "test.valgrind"
-target can be used to run the tests under valgrind. Found errors and
-memory leaks are logged in files named F<testfile.valgrind>.
+The valgrind tool can be used to find out both memory leaks and illegal
+heap memory accesses. As of version 3.3.0, Valgrind only supports Linux
+on x86, x86-64 and PowerPC and Darwin (OS X) on x86 and x86-64). The
+special "test.valgrind" target can be used to run the tests under
+valgrind. Found errors and memory leaks are logged in files named
+F<testfile.valgrind>.
Valgrind also provides a cachegrind tool, invoked on perl as:
@@ -1153,8 +1156,54 @@
To get valgrind and for more information see
- http://developer.kde.org/~sewardj/
+ http://valgrind.org/
+=head2 AddressSanitizer
+
+AddressSanitizer is a clang extension, included in clang since v3.1. It
+checks illegal heap pointers, global pointers, stack pointers and use
+after free errors, and is fast enough that you can easily compile your
+debugging or optimized perl with it. It does not check memory leaks
+though. AddressSanitizer is available for linux, Mac OS X and soon on
+Windows.
+
+To build perl with AddressSanitizer, your Configure invocation should
+look like:
+
+ sh Configure -des -Dcc=clang \
+ -Accflags=-faddress-sanitizer -Aldflags=-faddress-sanitizer \
+ -Alddlflags=-shared\ -faddress-sanitizer
+
+where these arguments mean:
+
+=over 4
+
+=item * -Dcc=clang
+
+This should be replaced by the full path to your clang executable if it
+is not in your path.
+
+=item * -Accflags=-faddress-sanitizer
+
+Compile perl and extensions sources with AddressSanitizer.
+
+=item * -Aldflags=-faddress-sanitizer
+
+Link the perl executable with AddressSanitizer.
+
+=item * -Alddlflags=-shared\ -faddress-sanitizer
+
+Link dynamic extensions with AddressSanitizer. You must manually
+specify C<-shared> because using C<-Alddlflags=-shared> will prevent
+Configure from setting a default value for C<lddlflags>, which usually
+contains C<-shared> (at least on linux).
+
+=back
+
+See also
+L<http://code.google.com/p/address-sanitizer/wiki/AddressSanitizer>.
+
+
=head1 PROFILING
Depending on your platform there are various ways of profiling Perl.
@@ -1409,42 +1458,18 @@
Under ithreads the optree is read only. If you want to enforce this, to
check for write accesses from buggy code, compile with
-C<-DPL_OP_SLAB_ALLOC> to enable the OP slab allocator and
C<-DPERL_DEBUG_READONLY_OPS> to enable code that allocates op memory
-via C<mmap>, and sets it read-only at run time. Any write access to an
-op results in a C<SIGBUS> and abort.
+via C<mmap>, and sets it read-only when it is attached to a subroutine. Any
+write access to an op results in a C<SIGBUS> and abort.
This code is intended for development only, and may not be portable
even to all Unix variants. Also, it is an 80% solution, in that it
-isn't able to make all ops read only. Specifically it
+isn't able to make all ops read only. Specifically it does not apply to op
+slabs belonging to C<BEGIN> blocks.
-=over
+However, as an 80% solution it is still effective, as it has caught bugs in
+the past.
-=item * 1
-
-Only sets read-only on all slabs of ops at C<CHECK> time, hence ops
-allocated later via C<require> or C<eval> will be re-write
-
-=item * 2
-
-Turns an entire slab of ops read-write if the refcount of any op in the
-slab needs to be decreased.
-
-=item * 3
-
-Turns an entire slab of ops read-write if any op from the slab is
-freed.
-
-=back
-
-It's not possible to turn the slabs to read-only after an action
-requiring read-write access, as either can happen during op tree
-building time, so there may still be legitimate write access.
-
-However, as an 80% solution it is still effective, as currently it
-catches a write access during the generation of F<Config.pm>, which
-means that we can't yet build F<perl> with this enabled.
-
=head2 The .i Targets
You can expand the macros in a F<foo.c> file by saying
@@ -1451,7 +1476,8 @@
make foo.i
-which will expand the macros using cpp. Don't be scared by the results.
+which will expand the macros using cpp. Don't be scared by the
+results.
=head1 AUTHOR
Property changes on: trunk/contrib/perl/pod/perlhacktips.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlhacktut.pod
===================================================================
--- trunk/contrib/perl/pod/perlhacktut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlhacktut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -53,9 +53,9 @@
C<pat> is set up:
STRLEN fromlen;
- register char *pat = SvPVx(*++MARK, fromlen);
- register char *patend = pat + fromlen;
- register I32 len;
+ char *pat = SvPVx(*++MARK, fromlen);
+ char *patend = pat + fromlen;
+ I32 len;
I32 datumtype;
SV *fromstr;
@@ -62,10 +62,10 @@
We'll have another string pointer in there:
STRLEN fromlen;
- register char *pat = SvPVx(*++MARK, fromlen);
- register char *patend = pat + fromlen;
+ char *pat = SvPVx(*++MARK, fromlen);
+ char *patend = pat + fromlen;
+ char *patcopy;
- register I32 len;
+ I32 len;
I32 datumtype;
SV *fromstr;
Property changes on: trunk/contrib/perl/pod/perlhacktut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlhist.pod
===================================================================
--- trunk/contrib/perl/pod/perlhist.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlhist.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -12,15 +12,15 @@
Perl history in brief, by Larry Wall:
- Perl 0 introduced Perl to my officemates.
- Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
- /(...|...)/. \(Dan Faigin still hasn't forgiven me. :-\)
- Perl 2 introduced Henry Spencer's regular expression package.
- Perl 3 introduced the ability to handle binary data (embedded nulls).
- Perl 4 introduced the first Camel book. Really. We mostly just
- switched version numbers so the book could refer to 4.000.
- Perl 5 introduced everything else, including the ability to
- introduce everything else.
+ Perl 0 introduced Perl to my officemates.
+ Perl 1 introduced Perl to the world, and changed /\(...\|...\)/ to
+ /(...|...)/. \(Dan Faigin still hasn't forgiven me. :-\)
+ Perl 2 introduced Henry Spencer's regular expression package.
+ Perl 3 introduced the ability to handle binary data (embedded nulls).
+ Perl 4 introduced the first Camel book. Really. We mostly just
+ switched version numbers so the book could refer to 4.000.
+ Perl 5 introduced everything else, including the ability to
+ introduce everything else.
=head1 THE KEEPERS OF THE PUMPKIN
@@ -30,12 +30,16 @@
Michael Schwern, Rafael Garcia-Suarez, Nicholas Clark, Richard Clamp,
Leon Brocard, Dave Mitchell, Jesse Vincent, Ricardo Signes, Steve Hay,
Matt S Trout, David Golden, Florian Ragwitz, Tatsuhiko Miyagawa,
-Chris C<BinGOs> Williams, Zefram and Ævar Arnfjörð Bjarmason.
+Chris C<BinGOs> Williams, Zefram, Ævar Arnfjörð Bjarmason, Stevan
+Little, Dave Rolsky, Max Maischein, Abigail, Jesse Luehrs, Tony Cook,
+Dominic Hargreaves, Aaron Crane and Aristotle Pagaltzis.
=head2 PUMPKIN?
[from Porting/pumpkin.pod in the Perl source code distribution]
+=for disclaimer orking cows is hazardous, and not legal in all jurisdictions
+
Chip Salzenberg gets credit for that, with a nod to his cow orker,
David Croy. We had passed around various names (baton, token, hot
potato) but none caught on. Then, Chip asked:
@@ -44,7 +48,7 @@
Who has the patch pumpkin?
-To explain: David Croy once told me once that at a previous job,
+To explain: David Croy once told me that at a previous job,
there was one tape drive and multiple systems that used it for backups.
But instead of some high-tech exclusion software, they used a low-tech
method to prevent multiple simultaneous backups: a stuffed pumpkin.
@@ -431,7 +435,7 @@
Jesse 5.12.1-RC2 2010-May-13 The 5.12 maintenance track
5.12.1-RC1 2010-May-09
- 5.12.1 2010-May-16
+ 5.12.1 2010-May-16
5.12.2-RC2 2010-Aug-31
5.12.2 2010-Sep-06
Ricardo 5.12.3-RC1 2011-Jan-09
@@ -438,6 +442,9 @@
Ricardo 5.12.3-RC2 2011-Jan-14
Ricardo 5.12.3-RC3 2011-Jan-17
Ricardo 5.12.3 2011-Jan-21
+ Leon 5.12.4-RC1 2011-Jun-08
+ Leon 5.12.4 2011-Jun-20
+ Dominic 5.12.5 2012-Nov-10
Leon 5.13.0 2010-Apr-20 The 5.13 development track
Ricardo 5.13.1 2010-May-20
@@ -459,8 +466,57 @@
Jesse 5.14.1 2011-Jun-16
Florian 5.14.2-RC1 2011-Sep-19
5.14.2 2011-Sep-26
+ Dominic 5.14.3 2012-Oct-12
+ David M 5.14.4-RC1 2013-Mar-05
+ David M 5.14.4-RC2 2013-Mar-07
+ David M 5.14.4 2013-Mar-10
+ David G 5.15.0 2011-Jun-20 The 5.15 development track
+ Zefram 5.15.1 2011-Jul-20
+ Ricardo 5.15.2 2011-Aug-20
+ Stevan 5.15.3 2011-Sep-20
+ Florian 5.15.4 2011-Oct-20
+ Steve 5.15.5 2011-Nov-20
+ Dave R 5.15.6 2011-Dec-20
+ BinGOs 5.15.7 2012-Jan-20
+ Max M 5.15.8 2012-Feb-20
+ Abigail 5.15.9 2012-Mar-20
+ Ricardo 5.16.0-RC0 2012-May-10
+ Ricardo 5.16.0-RC1 2012-May-14
+ Ricardo 5.16.0-RC2 2012-May-15
+ Ricardo 5.16.0 2012-May-20 The 5.16 maintenance track
+ Ricardo 5.16.1 2012-Aug-08
+ Ricardo 5.16.2 2012-Nov-01
+ Ricardo 5.16.3-RC1 2013-Mar-06
+ Ricardo 5.16.3 2013-Mar-11
+
+ Zefram 5.17.0 2012-May-26 The 5.17 development track
+ Jesse L 5.17.1 2012-Jun-20
+ TonyC 5.17.2 2012-Jul-20
+ Steve 5.17.3 2012-Aug-20
+ Florian 5.17.4 2012-Sep-20
+ Florian 5.17.5 2012-Oct-20
+ Ricardo 5.17.6 2012-Nov-20
+ Dave R 5.17.7 2012-Dec-18
+ Aaron 5.17.8 2013-Jan-20
+ BinGOs 5.17.9 2013-Feb-20
+ Max M 5.17.10 2013-Mar-21
+
+ Ricardo 5.18.0-RC1 2013-May-11 The 5.18 maintenance track
+ Ricardo 5.18.0-RC2 2013-May-12
+ Ricardo 5.18.0-RC3 2013-May-13
+ Ricardo 5.18.0-RC4 2013-May-15
+ Ricardo 5.18.0 2013-May-18
+ Ricardo 5.18.1-RC1 2013-Aug-01
+ Ricardo 5.18.1-RC2 2013-Aug-03
+ Ricardo 5.18.1-RC3 2013-Aug-08
+ Ricardo 5.18.1 2013-Aug-12
+
+ Ricardo 5.19.0 2013-May-20 The 5.19 development track
+ David G 5.19.1 2013-Jun-21
+ Aristotle 5.19.2 2013-Jul-22
+
=head2 SELECTED RELEASE SIZES
For example the notation "core: 212 29" in the release 1.000 means that
@@ -537,6 +593,9 @@
5.12.1 5000 100 1146 121 15283 2178 6407 1846 5354 169
5.12.2 5003 100 1146 121 15404 2178 6413 1846 5376 170
5.12.3 5004 100 1146 121 15529 2180 6417 1848 5391 171
+ 5.14.0 5328 104 1100 114 17779 2479 7697 2130 5871 188
+ 5.16.0 5562 109 1077 80 20504 2702 8750 2375 4815 152
+ 5.18.0 5892 113 1088 79 20077 2760 9365 2439 4943 154
The "core"..."doc" mean the following files from the Perl source code
distribution. The glob notation ** means recursively, (.) means
@@ -647,7 +706,7 @@
apollo - - - - - - - - 0 1
beos 1 1 1 1 1 1 1 1 1 1
Configure 256 1 256 1 264 1 264 1 270 1
- cygwin32 24 5 24 5 24 5 24 5 24 5
+ cygwin32 24 5 24 5 24 5 24 5 24 5
djgpp 14 5 14 5 14 5 14 5 15 5
eg 86 65 86 65 86 65 86 65 86 65
emacs 262 2 262 2 262 2 262 2 274 2
@@ -812,32 +871,32 @@
======================================================================
- 5.12.2 5.12.3
+ 5.12.2 5.12.3 5.14.0 5.16.0 5.18.0
- apollo 0 3 0 3
- beos 4 4 4 4
- Configure 536 1 536 1
- Cross 118 15 118 15
- djgpp 17 7 17 7
- emacs 402 4 402 4
- epoc 31 8 31 8
- h2pl 12 15 12 15
- hints 368 97 368 97
- mad 174 8 174 8
- mpeix 45 6 45 6
- NetWare 466 61 466 61
- os2 507 70 507 70
- plan9 316 17 316 17
- Porting 750 54 750 54
- qnx 1 4 1 4
- symbian 288 54 288 54
- utils 269 27 269 27
- uts 8 3 8 3
- vmesa 21 4 21 4
- vms 646 18 644 18
- vos 16 8 16 8
- win32 1841 73 1841 73
- x2p 345 19 345 19
+ apollo 0 3 0 3 - - - - - -
+ beos 4 4 4 4 5 4 5 4 - -
+ Configure 536 1 536 1 539 1 547 1 550 1
+ Cross 118 15 118 15 118 15 118 15 118 15
+ djgpp 17 7 17 7 18 7 18 7 18 7
+ emacs 402 4 402 4 - - - - - -
+ epoc 31 8 31 8 32 8 30 8 - -
+ h2pl 12 15 12 15 15 15 15 15 13 15
+ hints 368 97 368 97 370 96 371 96 354 91
+ mad 174 8 174 8 176 8 176 8 174 8
+ mpeix 45 6 45 6 46 6 46 6 - -
+ NetWare 466 61 466 61 473 61 472 61 469 61
+ os2 507 70 507 70 518 70 519 70 510 70
+ plan9 316 17 316 17 319 17 319 17 318 17
+ Porting 750 54 750 54 855 60 1093 69 1149 70
+ qnx 1 4 1 4 2 4 2 4 1 4
+ symbian 288 54 288 54 292 54 292 54 290 54
+ utils 269 27 269 27 249 29 245 30 246 31
+ uts 8 3 8 3 9 3 9 3 - -
+ vmesa 21 4 21 4 22 4 22 4 - -
+ vms 646 18 644 18 639 17 571 15 564 15
+ vos 16 8 16 8 17 8 9 7 8 7
+ win32 1841 73 1841 73 1833 72 1655 67 1157 62
+ x2p 345 19 345 19 346 19 345 19 344 20
=head2 SELECTED PATCH SIZES
@@ -910,7 +969,7 @@
In more modern times, named releases don't come as often, and as progress
can be followed (nearly) instantly (with rsync, and since late 2008, git)
patches between versions are no longer provided. However, that doesn't
-keep us from calculating how large a patch could have been. Which is
+keep us from calculating how large a patch could have been. Which is
shown in the table below. Unless noted otherwise, the size mentioned is
the patch to bring version x.y.z to x.y.z+1.
@@ -944,7 +1003,7 @@
Jarkko Hietaniemi <F<jhi at iki.fi>>.
Thanks to the collective memory of the Perlfolk. In addition to the
-Keepers of the Pumpkin also Alan Champion, Mark Dominus,
+Keepers of the Pumpkin also Alan Champion, Mark Dominus,
Andreas KE<0xf6>nig, John Macdonald, Matthias Neeracher, Jeff Okamoto,
Michael Peppler, Randal Schwartz, and Paul D. Smith sent corrections
and additions. Abigail added file and patch size data for the 5.6.0 - 5.10
Property changes on: trunk/contrib/perl/pod/perlhist.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlintern.pod (from rev 6437, vendor/perl/5.18.1/pod/perlintern.pod)
===================================================================
--- trunk/contrib/perl/pod/perlintern.pod (rev 0)
+++ trunk/contrib/perl/pod/perlintern.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,1111 @@
+-*- buffer-read-only: t -*-
+
+!!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+This file is built by autodoc.pl extracting documentation from the C source
+files.
+
+=head1 NAME
+
+perlintern - autogenerated documentation of purely B<internal>
+ Perl functions
+
+=head1 DESCRIPTION
+X<internal Perl functions> X<interpreter functions>
+
+This file is the autogenerated documentation of functions in the
+Perl interpreter that are documented using Perl's internal documentation
+format but are not marked as part of the Perl API. In other words,
+B<they are not for use in extensions>!
+
+
+=head1 CV reference counts and CvOUTSIDE
+
+=over 8
+
+=item CvWEAKOUTSIDE
+X<CvWEAKOUTSIDE>
+
+Each CV has a pointer, C<CvOUTSIDE()>, to its lexically enclosing
+CV (if any). Because pointers to anonymous sub prototypes are
+stored in C<&> pad slots, it is a possible to get a circular reference,
+with the parent pointing to the child and vice-versa. To avoid the
+ensuing memory leak, we do not increment the reference count of the CV
+pointed to by C<CvOUTSIDE> in the I<one specific instance> that the parent
+has a C<&> pad slot pointing back to us. In this case, we set the
+C<CvWEAKOUTSIDE> flag in the child. This allows us to determine under what
+circumstances we should decrement the refcount of the parent when freeing
+the child.
+
+There is a further complication with non-closure anonymous subs (i.e. those
+that do not refer to any lexicals outside that sub). In this case, the
+anonymous prototype is shared rather than being cloned. This has the
+consequence that the parent may be freed while there are still active
+children, eg
+
+ BEGIN { $a = sub { eval '$x' } }
+
+In this case, the BEGIN is freed immediately after execution since there
+are no active references to it: the anon sub prototype has
+C<CvWEAKOUTSIDE> set since it's not a closure, and $a points to the same
+CV, so it doesn't contribute to BEGIN's refcount either. When $a is
+executed, the C<eval '$x'> causes the chain of C<CvOUTSIDE>s to be followed,
+and the freed BEGIN is accessed.
+
+To avoid this, whenever a CV and its associated pad is freed, any
+C<&> entries in the pad are explicitly removed from the pad, and if the
+refcount of the pointed-to anon sub is still positive, then that
+child's C<CvOUTSIDE> is set to point to its grandparent. This will only
+occur in the single specific case of a non-closure anon prototype
+having one or more active references (such as C<$a> above).
+
+One other thing to consider is that a CV may be merely undefined
+rather than freed, eg C<undef &foo>. In this case, its refcount may
+not have reached zero, but we still delete its pad and its C<CvROOT> etc.
+Since various children may still have their C<CvOUTSIDE> pointing at this
+undefined CV, we keep its own C<CvOUTSIDE> for the time being, so that
+the chain of lexical scopes is unbroken. For example, the following
+should print 123:
+
+ my $x = 123;
+ sub tmp { sub { eval '$x' } }
+ my $a = tmp();
+ undef &tmp;
+ print $a->();
+
+ bool CvWEAKOUTSIDE(CV *cv)
+
+=for hackers
+Found in file cv.h
+
+
+=back
+
+=head1 Functions in file pad.h
+
+
+=over 8
+
+=item CX_CURPAD_SAVE
+X<CX_CURPAD_SAVE>
+
+Save the current pad in the given context block structure.
+
+ void CX_CURPAD_SAVE(struct context)
+
+=for hackers
+Found in file pad.h
+
+=item CX_CURPAD_SV
+X<CX_CURPAD_SV>
+
+Access the SV at offset po in the saved current pad in the given
+context block structure (can be used as an lvalue).
+
+ SV * CX_CURPAD_SV(struct context, PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_BASE_SV
+X<PAD_BASE_SV>
+
+Get the value from slot C<po> in the base (DEPTH=1) pad of a padlist
+
+ SV * PAD_BASE_SV(PADLIST padlist, PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_CLONE_VARS
+X<PAD_CLONE_VARS>
+
+|CLONE_PARAMS* param
+Clone the state variables associated with running and compiling pads.
+
+ void PAD_CLONE_VARS(PerlInterpreter *proto_perl \)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_FLAGS
+X<PAD_COMPNAME_FLAGS>
+
+Return the flags for the current compiling pad name
+at offset C<po>. Assumes a valid slot entry.
+
+ U32 PAD_COMPNAME_FLAGS(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_GEN
+X<PAD_COMPNAME_GEN>
+
+The generation number of the name at offset C<po> in the current
+compiling pad (lvalue). Note that C<SvUVX> is hijacked for this purpose.
+
+ STRLEN PAD_COMPNAME_GEN(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_GEN_set
+X<PAD_COMPNAME_GEN_set>
+
+Sets the generation number of the name at offset C<po> in the current
+ling pad (lvalue) to C<gen>. Note that C<SvUV_set> is hijacked for this purpose.
+
+ STRLEN PAD_COMPNAME_GEN_set(PADOFFSET po, int gen)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_OURSTASH
+X<PAD_COMPNAME_OURSTASH>
+
+Return the stash associated with an C<our> variable.
+Assumes the slot entry is a valid C<our> lexical.
+
+ HV * PAD_COMPNAME_OURSTASH(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_PV
+X<PAD_COMPNAME_PV>
+
+Return the name of the current compiling pad name
+at offset C<po>. Assumes a valid slot entry.
+
+ char * PAD_COMPNAME_PV(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_COMPNAME_TYPE
+X<PAD_COMPNAME_TYPE>
+
+Return the type (stash) of the current compiling pad name at offset
+C<po>. Must be a valid name. Returns null if not typed.
+
+ HV * PAD_COMPNAME_TYPE(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_DUP
+X<PAD_DUP>
+
+Clone a padlist.
+
+ void PAD_DUP(PADLIST dstpad, PADLIST srcpad, CLONE_PARAMS* param)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_RESTORE_LOCAL
+X<PAD_RESTORE_LOCAL>
+
+Restore the old pad saved into the local variable opad by PAD_SAVE_LOCAL()
+
+ void PAD_RESTORE_LOCAL(PAD *opad)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SAVE_LOCAL
+X<PAD_SAVE_LOCAL>
+
+Save the current pad to the local variable opad, then make the
+current pad equal to npad
+
+ void PAD_SAVE_LOCAL(PAD *opad, PAD *npad)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SAVE_SETNULLPAD
+X<PAD_SAVE_SETNULLPAD>
+
+Save the current pad then set it to null.
+
+ void PAD_SAVE_SETNULLPAD()
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SETSV
+X<PAD_SETSV>
+
+Set the slot at offset C<po> in the current pad to C<sv>
+
+ SV * PAD_SETSV(PADOFFSET po, SV* sv)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SET_CUR
+X<PAD_SET_CUR>
+
+Set the current pad to be pad C<n> in the padlist, saving
+the previous current pad. NB currently this macro expands to a string too
+long for some compilers, so it's best to replace it with
+
+ SAVECOMPPAD();
+ PAD_SET_CUR_NOSAVE(padlist,n);
+
+
+ void PAD_SET_CUR(PADLIST padlist, I32 n)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SET_CUR_NOSAVE
+X<PAD_SET_CUR_NOSAVE>
+
+like PAD_SET_CUR, but without the save
+
+ void PAD_SET_CUR_NOSAVE(PADLIST padlist, I32 n)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SV
+X<PAD_SV>
+
+Get the value at offset C<po> in the current pad
+
+ void PAD_SV(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item PAD_SVl
+X<PAD_SVl>
+
+Lightweight and lvalue version of C<PAD_SV>.
+Get or set the value at offset C<po> in the current pad.
+Unlike C<PAD_SV>, does not print diagnostics with -DX.
+For internal use only.
+
+ SV * PAD_SVl(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+=item SAVECLEARSV
+X<SAVECLEARSV>
+
+Clear the pointed to pad value on scope exit. (i.e. the runtime action of 'my')
+
+ void SAVECLEARSV(SV **svp)
+
+=for hackers
+Found in file pad.h
+
+=item SAVECOMPPAD
+X<SAVECOMPPAD>
+
+save PL_comppad and PL_curpad
+
+
+
+
+
+ void SAVECOMPPAD()
+
+=for hackers
+Found in file pad.h
+
+=item SAVEPADSV
+X<SAVEPADSV>
+
+Save a pad slot (used to restore after an iteration)
+
+XXX DAPM it would make more sense to make the arg a PADOFFSET
+ void SAVEPADSV(PADOFFSET po)
+
+=for hackers
+Found in file pad.h
+
+
+=back
+
+=head1 GV Functions
+
+=over 8
+
+=item is_gv_magical
+X<is_gv_magical>
+
+Returns C<TRUE> if given the name of a magical GV.
+
+Currently only useful internally when determining if a GV should be
+created even in rvalue contexts.
+
+C<flags> is not used at present but available for future extension to
+allow selecting particular classes of magical variable.
+
+Currently assumes that C<name> is NUL terminated (as well as len being valid).
+This assumption is met by all callers within the perl core, which all pass
+pointers returned by SvPV.
+
+ bool is_gv_magical(const char *name, STRLEN len, U32 flags)
+
+=for hackers
+Found in file gv.c
+
+=item is_gv_magical_sv
+X<is_gv_magical_sv>
+
+Returns C<TRUE> if given the name of a magical GV. Calls is_gv_magical.
+
+ bool is_gv_magical_sv(SV *name, U32 flags)
+
+=for hackers
+Found in file gv.c
+
+
+=back
+
+=head1 Hash Manipulation Functions
+
+=over 8
+
+=item refcounted_he_chain_2hv
+X<refcounted_he_chain_2hv>
+
+Generates and returns a C<HV *> by walking up the tree starting at the passed
+in C<struct refcounted_he *>.
+
+ HV * refcounted_he_chain_2hv(const struct refcounted_he *c)
+
+=for hackers
+Found in file hv.c
+
+=item refcounted_he_free
+X<refcounted_he_free>
+
+Decrements the reference count of the passed in C<struct refcounted_he *>
+by one. If the reference count reaches zero the structure's memory is freed,
+and C<refcounted_he_free> iterates onto the parent node.
+
+ void refcounted_he_free(struct refcounted_he *he)
+
+=for hackers
+Found in file hv.c
+
+=item refcounted_he_new
+X<refcounted_he_new>
+
+Creates a new C<struct refcounted_he>. As S<key> is copied, and value is
+stored in a compact form, all references remain the property of the caller.
+The C<struct refcounted_he> is returned with a reference count of 1.
+
+ struct refcounted_he * refcounted_he_new(struct refcounted_he *const parent, SV *const key, SV *const value)
+
+=for hackers
+Found in file hv.c
+
+
+=back
+
+=head1 IO Functions
+
+=over 8
+
+=item start_glob
+X<start_glob>
+
+Function called by C<do_readline> to spawn a glob (or do the glob inside
+perl on VMS). This code used to be inline, but now perl uses C<File::Glob>
+this glob starter is only used by miniperl during the build process.
+Moving it away shrinks pp_hot.c; shrinking pp_hot.c helps speed perl up.
+
+ PerlIO* start_glob(SV* pattern, IO *io)
+
+=for hackers
+Found in file doio.c
+
+
+=back
+
+=head1 Magical Functions
+
+=over 8
+
+=item magic_sethint
+X<magic_sethint>
+
+Triggered by a delete from %^H, records the key to
+C<PL_compiling.cop_hints_hash>.
+
+ int magic_sethint(SV* sv, MAGIC* mg)
+
+=for hackers
+Found in file mg.c
+
+=item mg_localize
+X<mg_localize>
+
+Copy some of the magic from an existing SV to new localized version of
+that SV. Container magic (eg %ENV, $1, tie) gets copied, value magic
+doesn't (eg taint, pos).
+
+ void mg_localize(SV* sv, SV* nsv)
+
+=for hackers
+Found in file mg.c
+
+
+=back
+
+=head1 MRO Functions
+
+=over 8
+
+=item mro_get_linear_isa_c3
+X<mro_get_linear_isa_c3>
+
+Returns the C3 linearization of @ISA
+the given stash. The return value is a read-only AV*.
+C<level> should be 0 (it is used internally in this
+function's recursion).
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+ AV* mro_get_linear_isa_c3(HV* stash, I32 level)
+
+=for hackers
+Found in file mro.c
+
+=item mro_get_linear_isa_dfs
+X<mro_get_linear_isa_dfs>
+
+Returns the Depth-First Search linearization of @ISA
+the given stash. The return value is a read-only AV*.
+C<level> should be 0 (it is used internally in this
+function's recursion).
+
+You are responsible for C<SvREFCNT_inc()> on the
+return value if you plan to store it anywhere
+semi-permanently (otherwise it might be deleted
+out from under you the next time the cache is
+invalidated).
+
+ AV* mro_get_linear_isa_dfs(HV* stash, I32 level)
+
+=for hackers
+Found in file mro.c
+
+=item mro_isa_changed_in
+X<mro_isa_changed_in>
+
+Takes the necessary steps (cache invalidations, mostly)
+when the @ISA of the given package has changed. Invoked
+by the C<setisa> magic, should not need to invoke directly.
+
+ void mro_isa_changed_in(HV* stash)
+
+=for hackers
+Found in file mro.c
+
+
+=back
+
+=head1 Pad Data Structures
+
+=over 8
+
+=item CvPADLIST
+X<CvPADLIST>
+
+CV's can have CvPADLIST(cv) set to point to an AV.
+
+For these purposes "forms" are a kind-of CV, eval""s are too (except they're
+not callable at will and are always thrown away after the eval"" is done
+executing). Require'd files are simply evals without any outer lexical
+scope.
+
+XSUBs don't have CvPADLIST set - dXSTARG fetches values from PL_curpad,
+but that is really the callers pad (a slot of which is allocated by
+every entersub).
+
+The CvPADLIST AV has does not have AvREAL set, so REFCNT of component items
+is managed "manual" (mostly in pad.c) rather than normal av.c rules.
+The items in the AV are not SVs as for a normal AV, but other AVs:
+
+0'th Entry of the CvPADLIST is an AV which represents the "names" or rather
+the "static type information" for lexicals.
+
+The CvDEPTH'th entry of CvPADLIST AV is an AV which is the stack frame at that
+depth of recursion into the CV.
+The 0'th slot of a frame AV is an AV which is @_.
+other entries are storage for variables and op targets.
+
+During compilation:
+C<PL_comppad_name> is set to the names AV.
+C<PL_comppad> is set to the frame AV for the frame CvDEPTH == 1.
+C<PL_curpad> is set to the body of the frame AV (i.e. AvARRAY(PL_comppad)).
+
+During execution, C<PL_comppad> and C<PL_curpad> refer to the live
+frame of the currently executing sub.
+
+Iterating over the names AV iterates over all possible pad
+items. Pad slots that are SVs_PADTMP (targets/GVs/constants) end up having
+&PL_sv_undef "names" (see pad_alloc()).
+
+Only my/our variable (SVs_PADMY/SVs_PADOUR) slots get valid names.
+The rest are op targets/GVs/constants which are statically allocated
+or resolved at compile time. These don't have names by which they
+can be looked up from Perl code at run time through eval"" like
+my/our variables can be. Since they can't be looked up by "name"
+but only by their index allocated at compile time (which is usually
+in PL_op->op_targ), wasting a name SV for them doesn't make sense.
+
+The SVs in the names AV have their PV being the name of the variable.
+xlow+1..xhigh inclusive in the NV union is a range of cop_seq numbers for
+which the name is valid. For typed lexicals name SV is SVt_PVMG and SvSTASH
+points at the type. For C<our> lexicals, the type is also SVt_PVMG, with the
+SvOURSTASH slot pointing at the stash of the associated global (so that
+duplicate C<our> declarations in the same package can be detected). SvUVX is
+sometimes hijacked to store the generation number during compilation.
+
+If SvFAKE is set on the name SV, then that slot in the frame AV is
+a REFCNT'ed reference to a lexical from "outside". In this case,
+the name SV does not use xlow and xhigh to store a cop_seq range, since it is
+in scope throughout. Instead xhigh stores some flags containing info about
+the real lexical (is it declared in an anon, and is it capable of being
+instantiated multiple times?), and for fake ANONs, xlow contains the index
+within the parent's pad where the lexical's value is stored, to make
+cloning quicker.
+
+If the 'name' is '&' the corresponding entry in frame AV
+is a CV representing a possible closure.
+(SvFAKE and name of '&' is not a meaningful combination currently but could
+become so if C<my sub foo {}> is implemented.)
+
+Note that formats are treated as anon subs, and are cloned each time
+write is called (if necessary).
+
+The flag SVf_PADSTALE is cleared on lexicals each time the my() is executed,
+and set on scope exit. This allows the 'Variable $x is not available' warning
+to be generated in evals, such as
+
+ { my $x = 1; sub f { eval '$x'} } f();
+
+ AV * CvPADLIST(CV *cv)
+
+=for hackers
+Found in file pad.c
+
+=item cv_clone
+X<cv_clone>
+
+Clone a CV: make a new CV which points to the same code etc, but which
+has a newly-created pad built by copying the prototype pad and capturing
+any outer lexicals.
+
+ CV* cv_clone(CV* proto)
+
+=for hackers
+Found in file pad.c
+
+=item cv_dump
+X<cv_dump>
+
+dump the contents of a CV
+
+ void cv_dump(const CV *cv, const char *title)
+
+=for hackers
+Found in file pad.c
+
+=item do_dump_pad
+X<do_dump_pad>
+
+Dump the contents of a padlist
+
+ void do_dump_pad(I32 level, PerlIO *file, PADLIST *padlist, int full)
+
+=for hackers
+Found in file pad.c
+
+=item intro_my
+X<intro_my>
+
+"Introduce" my variables to visible status.
+
+ U32 intro_my()
+
+=for hackers
+Found in file pad.c
+
+=item pad_add_anon
+X<pad_add_anon>
+
+Add an anon code entry to the current compiling pad
+
+ PADOFFSET pad_add_anon(SV* sv, OPCODE op_type)
+
+=for hackers
+Found in file pad.c
+
+=item pad_add_name
+X<pad_add_name>
+
+Create a new name and associated PADMY SV in the current pad; return the
+offset.
+If C<typestash> is valid, the name is for a typed lexical; set the
+name's stash to that value.
+If C<ourstash> is valid, it's an our lexical, set the name's
+SvOURSTASH to that value
+
+If fake, it means we're cloning an existing entry
+
+ PADOFFSET pad_add_name(const char *name, HV* typestash, HV* ourstash, bool clone, bool state)
+
+=for hackers
+Found in file pad.c
+
+=item pad_alloc
+X<pad_alloc>
+
+Allocate a new my or tmp pad entry. For a my, simply push a null SV onto
+the end of PL_comppad, but for a tmp, scan the pad from PL_padix upwards
+for a slot which has no name and no active value.
+
+ PADOFFSET pad_alloc(I32 optype, U32 tmptype)
+
+=for hackers
+Found in file pad.c
+
+=item pad_block_start
+X<pad_block_start>
+
+Update the pad compilation state variables on entry to a new block
+
+ void pad_block_start(int full)
+
+=for hackers
+Found in file pad.c
+
+=item pad_check_dup
+X<pad_check_dup>
+
+Check for duplicate declarations: report any of:
+ * a my in the current scope with the same name;
+ * an our (anywhere in the pad) with the same name and the same stash
+ as C<ourstash>
+C<is_our> indicates that the name to check is an 'our' declaration
+
+ void pad_check_dup(const char* name, bool is_our, const HV* ourstash)
+
+=for hackers
+Found in file pad.c
+
+=item pad_findlex
+X<pad_findlex>
+
+Find a named lexical anywhere in a chain of nested pads. Add fake entries
+in the inner pads if it's found in an outer one.
+
+Returns the offset in the bottom pad of the lex or the fake lex.
+cv is the CV in which to start the search, and seq is the current cop_seq
+to match against. If warn is true, print appropriate warnings. The out_*
+vars return values, and so are pointers to where the returned values
+should be stored. out_capture, if non-null, requests that the innermost
+instance of the lexical is captured; out_name_sv is set to the innermost
+matched namesv or fake namesv; out_flags returns the flags normally
+associated with the IVX field of a fake namesv.
+
+Note that pad_findlex() is recursive; it recurses up the chain of CVs,
+then comes back down, adding fake entries as it goes. It has to be this way
+because fake namesvs in anon protoypes have to store in xlow the index into
+the parent pad.
+
+ PADOFFSET pad_findlex(const char *name, const CV* cv, U32 seq, int warn, SV** out_capture, SV** out_name_sv, int *out_flags)
+
+=for hackers
+Found in file pad.c
+
+=item pad_findmy
+X<pad_findmy>
+
+Given a lexical name, try to find its offset, first in the current pad,
+or failing that, in the pads of any lexically enclosing subs (including
+the complications introduced by eval). If the name is found in an outer pad,
+then a fake entry is added to the current pad.
+Returns the offset in the current pad, or NOT_IN_PAD on failure.
+
+ PADOFFSET pad_findmy(const char* name)
+
+=for hackers
+Found in file pad.c
+
+=item pad_fixup_inner_anons
+X<pad_fixup_inner_anons>
+
+For any anon CVs in the pad, change CvOUTSIDE of that CV from
+old_cv to new_cv if necessary. Needed when a newly-compiled CV has to be
+moved to a pre-existing CV struct.
+
+ void pad_fixup_inner_anons(PADLIST *padlist, CV *old_cv, CV *new_cv)
+
+=for hackers
+Found in file pad.c
+
+=item pad_free
+X<pad_free>
+
+Free the SV at offset po in the current pad.
+
+ void pad_free(PADOFFSET po)
+
+=for hackers
+Found in file pad.c
+
+=item pad_leavemy
+X<pad_leavemy>
+
+Cleanup at end of scope during compilation: set the max seq number for
+lexicals in this scope and warn of any lexicals that never got introduced.
+
+ void pad_leavemy()
+
+=for hackers
+Found in file pad.c
+
+=item pad_new
+X<pad_new>
+
+Create a new compiling padlist, saving and updating the various global
+vars at the same time as creating the pad itself. The following flags
+can be OR'ed together:
+
+ padnew_CLONE this pad is for a cloned CV
+ padnew_SAVE save old globals
+ padnew_SAVESUB also save extra stuff for start of sub
+
+ PADLIST* pad_new(int flags)
+
+=for hackers
+Found in file pad.c
+
+=item pad_push
+X<pad_push>
+
+Push a new pad frame onto the padlist, unless there's already a pad at
+this depth, in which case don't bother creating a new one. Then give
+the new pad an @_ in slot zero.
+
+ void pad_push(PADLIST *padlist, int depth)
+
+=for hackers
+Found in file pad.c
+
+=item pad_reset
+X<pad_reset>
+
+Mark all the current temporaries for reuse
+
+ void pad_reset()
+
+=for hackers
+Found in file pad.c
+
+=item pad_setsv
+X<pad_setsv>
+
+Set the entry at offset po in the current pad to sv.
+Use the macro PAD_SETSV() rather than calling this function directly.
+
+ void pad_setsv(PADOFFSET po, SV* sv)
+
+=for hackers
+Found in file pad.c
+
+=item pad_swipe
+X<pad_swipe>
+
+Abandon the tmp in the current pad at offset po and replace with a
+new one.
+
+ void pad_swipe(PADOFFSET po, bool refadjust)
+
+=for hackers
+Found in file pad.c
+
+=item pad_tidy
+X<pad_tidy>
+
+Tidy up a pad after we've finished compiling it:
+ * remove most stuff from the pads of anonsub prototypes;
+ * give it a @_;
+ * mark tmps as such.
+
+ void pad_tidy(padtidy_type type)
+
+=for hackers
+Found in file pad.c
+
+=item pad_undef
+X<pad_undef>
+
+Free the padlist associated with a CV.
+If parts of it happen to be current, we null the relevant
+PL_*pad* global vars so that we don't have any dangling references left.
+We also repoint the CvOUTSIDE of any about-to-be-orphaned
+inner subs to the outer of this cv.
+
+(This function should really be called pad_free, but the name was already
+taken)
+
+ void pad_undef(CV* cv)
+
+=for hackers
+Found in file pad.c
+
+
+=back
+
+=head1 Per-Interpreter Variables
+
+=over 8
+
+=item PL_DBsingle
+X<PL_DBsingle>
+
+When Perl is run in debugging mode, with the B<-d> switch, this SV is a
+boolean which indicates whether subs are being single-stepped.
+Single-stepping is automatically turned on after every step. This is the C
+variable which corresponds to Perl's $DB::single variable. See
+C<PL_DBsub>.
+
+ SV * PL_DBsingle
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_DBsub
+X<PL_DBsub>
+
+When Perl is run in debugging mode, with the B<-d> switch, this GV contains
+the SV which holds the name of the sub being debugged. This is the C
+variable which corresponds to Perl's $DB::sub variable. See
+C<PL_DBsingle>.
+
+ GV * PL_DBsub
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_DBtrace
+X<PL_DBtrace>
+
+Trace variable used when Perl is run in debugging mode, with the B<-d>
+switch. This is the C variable which corresponds to Perl's $DB::trace
+variable. See C<PL_DBsingle>.
+
+ SV * PL_DBtrace
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_dowarn
+X<PL_dowarn>
+
+The C variable which corresponds to Perl's $^W warning variable.
+
+ bool PL_dowarn
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_last_in_gv
+X<PL_last_in_gv>
+
+The GV which was last used for a filehandle input operation. (C<< <FH> >>)
+
+ GV* PL_last_in_gv
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_ofs_sv
+X<PL_ofs_sv>
+
+The output field separator - C<$,> in Perl space.
+
+ SV* PL_ofs_sv
+
+=for hackers
+Found in file intrpvar.h
+
+=item PL_rs
+X<PL_rs>
+
+The input record separator - C<$/> in Perl space.
+
+ SV* PL_rs
+
+=for hackers
+Found in file intrpvar.h
+
+
+=back
+
+=head1 Stack Manipulation Macros
+
+=over 8
+
+=item djSP
+X<djSP>
+
+Declare Just C<SP>. This is actually identical to C<dSP>, and declares
+a local copy of perl's stack pointer, available via the C<SP> macro.
+See C<SP>. (Available for backward source code compatibility with the
+old (Perl 5.005) thread model.)
+
+ djSP;
+
+=for hackers
+Found in file pp.h
+
+=item LVRET
+X<LVRET>
+
+True if this op will be the return value of an lvalue subroutine
+
+=for hackers
+Found in file pp.h
+
+
+=back
+
+=head1 SV Manipulation Functions
+
+=over 8
+
+=item sv_add_arena
+X<sv_add_arena>
+
+Given a chunk of memory, link it to the head of the list of arenas,
+and split it into a list of free SVs.
+
+ void sv_add_arena(char* ptr, U32 size, U32 flags)
+
+=for hackers
+Found in file sv.c
+
+=item sv_clean_all
+X<sv_clean_all>
+
+Decrement the refcnt of each remaining SV, possibly triggering a
+cleanup. This function may have to be called multiple times to free
+SVs which are in complex self-referential hierarchies.
+
+ I32 sv_clean_all()
+
+=for hackers
+Found in file sv.c
+
+=item sv_clean_objs
+X<sv_clean_objs>
+
+Attempt to destroy all objects not yet freed
+
+ void sv_clean_objs()
+
+=for hackers
+Found in file sv.c
+
+=item sv_free_arenas
+X<sv_free_arenas>
+
+Deallocate the memory used by all arenas. Note that all the individual SV
+heads and bodies within the arenas must already have been freed.
+
+ void sv_free_arenas()
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 SV-Body Allocation
+
+=over 8
+
+=item sv_2num
+X<sv_2num>
+
+Return an SV with the numeric value of the source SV, doing any necessary
+reference or overload conversion. You must use the C<SvNUM(sv)> macro to
+access this function.
+
+ SV* sv_2num(SV* sv)
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 Unicode Support
+
+=over 8
+
+=item find_uninit_var
+X<find_uninit_var>
+
+Find the name of the undefined variable (if any) that caused the operator o
+to issue a "Use of uninitialized value" warning.
+If match is true, only return a name if it's value matches uninit_sv.
+So roughly speaking, if a unary operator (such as OP_COS) generates a
+warning, then following the direct child of the op may yield an
+OP_PADSV or OP_GV that gives the name of the undefined variable. On the
+other hand, with OP_ADD there are two branches to follow, so we only print
+the variable name if we get an exact match.
+
+The name is returned as a mortal SV.
+
+Assumes that PL_op is the op that originally triggered the error, and that
+PL_comppad/PL_curpad points to the currently executing pad.
+
+ SV* find_uninit_var(OP* obase, SV* uninit_sv, bool top)
+
+=for hackers
+Found in file sv.c
+
+=item report_uninit
+X<report_uninit>
+
+Print appropriate "Use of uninitialized variable" warning
+
+ void report_uninit(SV* uninit_sv)
+
+=for hackers
+Found in file sv.c
+
+
+=back
+
+=head1 AUTHORS
+
+The autodocumentation system was originally added to the Perl core by
+Benjamin Stuhl. Documentation is by whoever was kind enough to
+document their functions.
+
+=head1 SEE ALSO
+
+perlguts(1), perlapi(1)
+
+=cut
+
+ ex: set ro:
Modified: trunk/contrib/perl/pod/perlinterp.pod
===================================================================
--- trunk/contrib/perl/pod/perlinterp.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlinterp.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -363,7 +363,7 @@
F<sv.c>
1 void
- 2 Perl_sv_catpvn(pTHX_ register SV *sv, register const char *ptr, register STRLEN len)
+ 2 Perl_sv_catpvn(pTHX_ SV *sv, const char *ptr, STRLEN len)
3 {
4 STRLEN tlen;
5 char *junk;
@@ -696,7 +696,7 @@
...
}
-See L<perlguts/"Localizing Changes"> for how to use the save stack.
+See L<perlguts/"Localizing changes"> for how to use the save stack.
=head1 MILLIONS OF MACROS
Property changes on: trunk/contrib/perl/pod/perlinterp.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlintro.pod
===================================================================
--- trunk/contrib/perl/pod/perlintro.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlintro.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -35,10 +35,10 @@
to make the example easier to read.
Do note that the examples have been written by many different authors over
-a period of several decades. Styles and techniques will therefore differ,
+a period of several decades. Styles and techniques will therefore differ,
although some effort has been made to not vary styles too widely in the
-same sections. Do not consider one style to be better than others - "There
-Is More Than One Way Of Doing It" is one Perl's mottos. After all, in your
+same sections. Do not consider one style to be better than others - "There's
+More Than One Way To Do It" is one of Perl's mottos. After all, in your
journey as a programmer, you are likely to encounter different styles.
=head2 What is Perl?
@@ -64,16 +64,16 @@
To run a Perl program from the Unix command line:
- perl progname.pl
+ perl progname.pl
Alternatively, put this as the first line of your script:
- #!/usr/bin/env perl
+ #!/usr/bin/env perl
-... and run the script as C</path/to/script.pl>. Of course, it'll need
+... and run the script as F</path/to/script.pl>. Of course, it'll need
to be executable first, so C<chmod 755 script.pl> (under Unix).
-(This start line assumes you have the B<env> program. You can also put
+(This start line assumes you have the B<env> program. You can also put
directly the path to your perl executable, like in C<#!/usr/bin/perl>).
For more information, including instructions for other platforms such as
@@ -81,15 +81,15 @@
=head2 Safety net
-Perl by default is very forgiving. In order to make it more robust
+Perl by default is very forgiving. In order to make it more robust
it is recommended to start every program with the following lines:
- #!/usr/bin/perl
- use strict;
- use warnings;
+ #!/usr/bin/perl
+ use strict;
+ use warnings;
The two additional lines request from perl to catch various common
-problems in your code. They check different things so you need both. A
+problems in your code. They check different things so you need both. A
potential problem caught by C<use strict;> will cause your code to stop
immediately when it is encountered, while C<use warnings;> will merely
give a warning (like the command-line switch B<-w>) and let your code run.
@@ -105,45 +105,45 @@
Perl statements end in a semi-colon:
- print "Hello, world";
+ print "Hello, world";
Comments start with a hash symbol and run to the end of the line
- # This is a comment
+ # This is a comment
Whitespace is irrelevant:
- print
- "Hello, world"
- ;
+ print
+ "Hello, world"
+ ;
... except inside quoted strings:
- # this would print with a linebreak in the middle
- print "Hello
- world";
+ # this would print with a linebreak in the middle
+ print "Hello
+ world";
Double quotes or single quotes may be used around literal strings:
- print "Hello, world";
- print 'Hello, world';
+ print "Hello, world";
+ print 'Hello, world';
However, only double quotes "interpolate" variables and special
characters such as newlines (C<\n>):
- print "Hello, $name\n"; # works fine
- print 'Hello, $name\n'; # prints $name\n literally
+ print "Hello, $name\n"; # works fine
+ print 'Hello, $name\n'; # prints $name\n literally
Numbers don't need quotes around them:
- print 42;
+ print 42;
You can use parentheses for functions' arguments or omit them
according to your personal taste. They are only required
occasionally to clarify issues of precedence.
- print("Hello, world\n");
- print "Hello, world\n";
+ print("Hello, world\n");
+ print "Hello, world\n";
More detailed information about Perl syntax can be found in L<perlsyn>.
@@ -157,20 +157,20 @@
A scalar represents a single value:
- my $animal = "camel";
- my $answer = 42;
+ my $animal = "camel";
+ my $answer = 42;
Scalar values can be strings, integers or floating point numbers, and Perl
will automatically convert between them as required. There is no need
to pre-declare your variable types, but you have to declare them using
-the C<my> keyword the first time you use them. (This is one of the
+the C<my> keyword the first time you use them. (This is one of the
requirements of C<use strict;>.)
Scalar values can be used in various ways:
- print $animal;
- print "The animal is $animal\n";
- print "The square of $answer is ", $answer * $answer, "\n";
+ print $animal;
+ print "The animal is $animal\n";
+ print "The square of $answer is ", $answer * $answer, "\n";
There are a number of "magic" scalars with names that look like
punctuation or line noise. These special variables are used for all
@@ -179,25 +179,25 @@
It's used as the default argument to a number of functions in Perl, and
it's set implicitly by certain looping constructs.
- print; # prints contents of $_ by default
+ print; # prints contents of $_ by default
=item Arrays
An array represents a list of values:
- my @animals = ("camel", "llama", "owl");
- my @numbers = (23, 42, 69);
- my @mixed = ("camel", 42, 1.23);
+ my @animals = ("camel", "llama", "owl");
+ my @numbers = (23, 42, 69);
+ my @mixed = ("camel", 42, 1.23);
Arrays are zero-indexed. Here's how you get at elements in an array:
- print $animals[0]; # prints "camel"
- print $animals[1]; # prints "llama"
+ print $animals[0]; # prints "camel"
+ print $animals[1]; # prints "llama"
The special variable C<$#array> tells you the index of the last element
of an array:
- print $mixed[$#mixed]; # last element, prints 1.23
+ print $mixed[$#mixed]; # last element, prints 1.23
You might be tempted to use C<$#array + 1> to tell you how many items there
are in an array. Don't bother. As it happens, using C<@array> where Perl
@@ -204,7 +204,7 @@
expects to find a scalar value ("in scalar context") will give you the number
of elements in the array:
- if (@animals < 5) { ... }
+ if (@animals < 5) { ... }
The elements we're getting from the array start with a C<$> because
we're getting just a single value out of the array; you ask for a scalar,
@@ -212,16 +212,16 @@
To get multiple values from an array:
- @animals[0,1]; # gives ("camel", "llama");
- @animals[0..2]; # gives ("camel", "llama", "owl");
- @animals[1..$#animals]; # gives all except the first element
+ @animals[0,1]; # gives ("camel", "llama");
+ @animals[0..2]; # gives ("camel", "llama", "owl");
+ @animals[1..$#animals]; # gives all except the first element
This is called an "array slice".
You can do various useful things to lists:
- my @sorted = sort @animals;
- my @backwards = reverse @numbers;
+ my @sorted = sort @animals;
+ my @backwards = reverse @numbers;
There are a couple of special arrays too, such as C<@ARGV> (the command
line arguments to your script) and C<@_> (the arguments passed to a
@@ -231,25 +231,25 @@
A hash represents a set of key/value pairs:
- my %fruit_color = ("apple", "red", "banana", "yellow");
+ my %fruit_color = ("apple", "red", "banana", "yellow");
You can use whitespace and the C<< => >> operator to lay them out more
nicely:
- my %fruit_color = (
- apple => "red",
- banana => "yellow",
- );
+ my %fruit_color = (
+ apple => "red",
+ banana => "yellow",
+ );
To get at hash elements:
- $fruit_color{"apple"}; # gives "red"
+ $fruit_color{"apple"}; # gives "red"
You can get at lists of keys and values with C<keys()> and
C<values()>.
- my @fruits = keys %fruit_colors;
- my @colors = values %fruit_colors;
+ my @fruits = keys %fruit_colors;
+ my @colors = values %fruit_colors;
Hashes have no particular internal order, though you can sort the keys
and loop through them.
@@ -267,27 +267,27 @@
you to build lists and hashes within lists and hashes.
A reference is a scalar value and can refer to any other Perl data
-type. So by storing a reference as the value of an array or hash
+type. So by storing a reference as the value of an array or hash
element, you can easily create lists and hashes within lists and
-hashes. The following example shows a 2 level hash of hash
+hashes. The following example shows a 2 level hash of hash
structure using anonymous hash references.
- my $variables = {
- scalar => {
- description => "single item",
- sigil => '$',
- },
- array => {
- description => "ordered list of items",
- sigil => '@',
- },
- hash => {
- description => "key/value pairs",
- sigil => '%',
- },
- };
+ my $variables = {
+ scalar => {
+ description => "single item",
+ sigil => '$',
+ },
+ array => {
+ description => "ordered list of items",
+ sigil => '@',
+ },
+ hash => {
+ description => "key/value pairs",
+ sigil => '%',
+ },
+ };
- print "Scalars begin with a $variables->{'scalar'}->{'sigil'}\n";
+ print "Scalars begin with a $variables->{'scalar'}->{'sigil'}\n";
Exhaustive information on the topic of references can be found in
L<perlreftut>, L<perllol>, L<perlref> and L<perldsc>.
@@ -296,11 +296,11 @@
Throughout the previous section all the examples have used the syntax:
- my $var = "value";
+ my $var = "value";
The C<my> is actually not required; you could just use:
- $var = "value";
+ $var = "value";
However, the above usage will create global variables throughout your
program, which is bad programming practice. C<my> creates lexically
@@ -308,15 +308,15 @@
(i.e. a bunch of statements surrounded by curly-braces) in which they
are defined.
- my $x = "foo";
- my $some_condition = 1;
- if ($some_condition) {
- my $y = "bar";
- print $x; # prints "foo"
- print $y; # prints "bar"
- }
- print $x; # prints "foo"
- print $y; # prints nothing; $y has fallen out of scope
+ my $x = "foo";
+ my $some_condition = 1;
+ if ($some_condition) {
+ my $y = "bar";
+ print $x; # prints "foo"
+ print $y; # prints "bar"
+ }
+ print $x; # prints "foo"
+ print $y; # prints nothing; $y has fallen out of scope
Using C<my> in combination with a C<use strict;> at the top of
your Perl scripts means that the interpreter will pick up certain common
@@ -328,7 +328,7 @@
Perl has most of the usual conditional and looping constructs. As of Perl
5.10, it even has a case/switch statement (spelled C<given>/C<when>). See
-L<perlsyn/"Switch statements"> for more details.
+L<perlsyn/"Switch Statements"> for more details.
The conditions can be any Perl expression. See the list of operators in
the next section for information on comparison and boolean logic operators,
@@ -338,19 +338,19 @@
=item if
- if ( condition ) {
- ...
- } elsif ( other condition ) {
- ...
- } else {
- ...
- }
+ if ( condition ) {
+ ...
+ } elsif ( other condition ) {
+ ...
+ } else {
+ ...
+ }
There's also a negated version of it:
- unless ( condition ) {
- ...
- }
+ unless ( condition ) {
+ ...
+ }
This is provided as a more readable version of C<if (!I<condition>)>.
@@ -358,38 +358,38 @@
line in the block. However, there is a clever way of making your one-line
conditional blocks more English like:
- # the traditional way
- if ($zippy) {
- print "Yow!";
- }
+ # the traditional way
+ if ($zippy) {
+ print "Yow!";
+ }
- # the Perlish post-condition way
- print "Yow!" if $zippy;
- print "We have no bananas" unless $bananas;
+ # the Perlish post-condition way
+ print "Yow!" if $zippy;
+ print "We have no bananas" unless $bananas;
=item while
- while ( condition ) {
- ...
- }
+ while ( condition ) {
+ ...
+ }
There's also a negated version, for the same reason we have C<unless>:
- until ( condition ) {
- ...
- }
+ until ( condition ) {
+ ...
+ }
You can also use C<while> in a post-condition:
- print "LA LA LA\n" while 1; # loops forever
+ print "LA LA LA\n" while 1; # loops forever
=item for
Exactly like C:
- for ($i = 0; $i <= $max; $i++) {
- ...
- }
+ for ($i = 0; $i <= $max; $i++) {
+ ...
+ }
The C style for loop is rarely needed in Perl since Perl provides
the more friendly list scanning C<foreach> loop.
@@ -396,17 +396,20 @@
=item foreach
- foreach (@array) {
- print "This element is $_\n";
- }
+ foreach (@array) {
+ print "This element is $_\n";
+ }
- print $list[$_] foreach 0 .. $max;
+ print $list[$_] foreach 0 .. $max;
- # you don't have to use the default $_ either...
- foreach my $key (keys %hash) {
- print "The value of $key is $hash{$key}\n";
- }
+ # you don't have to use the default $_ either...
+ foreach my $key (keys %hash) {
+ print "The value of $key is $hash{$key}\n";
+ }
+The C<foreach> keyword is actually a synonym for the C<for>
+keyword. See C<L<perlsyn/"Foreach Loops">>.
+
=back
For more detail on looping constructs (and some that weren't mentioned in
@@ -426,28 +429,28 @@
=item Arithmetic
- + addition
- - subtraction
- * multiplication
- / division
+ + addition
+ - subtraction
+ * multiplication
+ / division
=item Numeric comparison
- == equality
- != inequality
- < less than
- > greater than
- <= less than or equal
- >= greater than or equal
+ == equality
+ != inequality
+ < less than
+ > greater than
+ <= less than or equal
+ >= greater than or equal
=item String comparison
- eq equality
- ne inequality
- lt less than
- gt greater than
- le less than or equal
- ge greater than or equal
+ eq equality
+ ne inequality
+ lt less than
+ gt greater than
+ le less than or equal
+ ge greater than or equal
(Why do we have separate numeric and string comparisons? Because we don't
have special variable types, and Perl needs to know whether to sort
@@ -456,12 +459,12 @@
=item Boolean logic
- && and
- || or
- ! not
+ && and
+ || or
+ ! not
(C<and>, C<or> and C<not> aren't just in the above table as descriptions
-of the operators. They're also supported as operators in their own
+of the operators. They're also supported as operators in their own
right. They're more readable than the C-style operators, but have
different precedence to C<&&> and friends. Check L<perlop> for more
detail.)
@@ -468,18 +471,18 @@
=item Miscellaneous
- = assignment
- . string concatenation
- x string multiplication
- .. range operator (creates a list of numbers)
+ = assignment
+ . string concatenation
+ x string multiplication
+ .. range operator (creates a list of numbers)
=back
Many operators can be combined with a C<=> as follows:
- $a += 1; # same as $a = $a + 1
- $a -= 1; # same as $a = $a - 1
- $a .= "\n"; # same as $a = $a . "\n";
+ $a += 1; # same as $a = $a + 1
+ $a -= 1; # same as $a = $a - 1
+ $a .= "\n"; # same as $a = $a . "\n";
=head2 Files and I/O
@@ -487,9 +490,9 @@
It's documented in extravagant detail in L<perlfunc> and L<perlopentut>,
but in short:
- open(my $in, "<", "input.txt") or die "Can't open input.txt: $!";
- open(my $out, ">", "output.txt") or die "Can't open output.txt: $!";
- open(my $log, ">>", "my.log") or die "Can't open my.log: $!";
+ open(my $in, "<", "input.txt") or die "Can't open input.txt: $!";
+ open(my $out, ">", "output.txt") or die "Can't open output.txt: $!";
+ open(my $log, ">>", "my.log") or die "Can't open my.log: $!";
You can read from an open filehandle using the C<< <> >> operator. In
scalar context it reads a single line from the filehandle, and in list
@@ -496,31 +499,31 @@
context it reads the whole file in, assigning each line to an element of
the list:
- my $line = <$in>;
- my @lines = <$in>;
+ my $line = <$in>;
+ my @lines = <$in>;
-Reading in the whole file at one time is called slurping. It can
-be useful but it may be a memory hog. Most text file processing
+Reading in the whole file at one time is called slurping. It can
+be useful but it may be a memory hog. Most text file processing
can be done a line at a time with Perl's looping constructs.
The C<< <> >> operator is most often seen in a C<while> loop:
- while (<$in>) { # assigns each line in turn to $_
- print "Just read in this line: $_";
- }
+ while (<$in>) { # assigns each line in turn to $_
+ print "Just read in this line: $_";
+ }
We've already seen how to print to standard output using C<print()>.
However, C<print()> can also take an optional first argument specifying
which filehandle to print to:
- print STDERR "This is your final warning.\n";
- print $out $record;
- print $log $logmessage;
+ print STDERR "This is your final warning.\n";
+ print $out $record;
+ print $log $logmessage;
When you're done with your filehandles, you should C<close()> them
(though to be honest, Perl will clean up after you if you forget):
- close $in or die "$in: $!";
+ close $in or die "$in: $!";
=head2 Regular expressions
@@ -532,8 +535,8 @@
=item Simple matching
- if (/foo/) { ... } # true if $_ contains "foo"
- if ($a =~ /foo/) { ... } # true if $a contains "foo"
+ if (/foo/) { ... } # true if $_ contains "foo"
+ if ($a =~ /foo/) { ... } # true if $a contains "foo"
The C<//> matching operator is documented in L<perlop>. It operates on
C<$_> by default, or can be bound to another variable using the C<=~>
@@ -541,9 +544,10 @@
=item Simple substitution
- s/foo/bar/; # replaces foo with bar in $_
- $a =~ s/foo/bar/; # replaces foo with bar in $a
- $a =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar in $a
+ s/foo/bar/; # replaces foo with bar in $_
+ $a =~ s/foo/bar/; # replaces foo with bar in $a
+ $a =~ s/foo/bar/g; # replaces ALL INSTANCES of foo with bar
+ # in $a
The C<s///> substitution operator is documented in L<perlop>.
@@ -554,19 +558,21 @@
expressions. These are documented at great length in L<perlre>, but for
the meantime, here's a quick cheat sheet:
- . a single character
- \s a whitespace character (space, tab, newline, ...)
- \S non-whitespace character
- \d a digit (0-9)
- \D a non-digit
- \w a word character (a-z, A-Z, 0-9, _)
- \W a non-word character
- [aeiou] matches a single character in the given set
- [^aeiou] matches a single character outside the given set
- (foo|bar|baz) matches any of the alternatives specified
+ . a single character
+ \s a whitespace character (space, tab, newline,
+ ...)
+ \S non-whitespace character
+ \d a digit (0-9)
+ \D a non-digit
+ \w a word character (a-z, A-Z, 0-9, _)
+ \W a non-word character
+ [aeiou] matches a single character in the given set
+ [^aeiou] matches a single character outside the given
+ set
+ (foo|bar|baz) matches any of the alternatives specified
- ^ start of string
- $ end of string
+ ^ start of string
+ $ end of string
Quantifiers can be used to specify how many of the previous thing you
want to match on, where "thing" means either a literal character, one
@@ -573,27 +579,28 @@
of the metacharacters listed above, or a group of characters or
metacharacters in parentheses.
- * zero or more of the previous thing
- + one or more of the previous thing
- ? zero or one of the previous thing
- {3} matches exactly 3 of the previous thing
- {3,6} matches between 3 and 6 of the previous thing
- {3,} matches 3 or more of the previous thing
+ * zero or more of the previous thing
+ + one or more of the previous thing
+ ? zero or one of the previous thing
+ {3} matches exactly 3 of the previous thing
+ {3,6} matches between 3 and 6 of the previous thing
+ {3,} matches 3 or more of the previous thing
Some brief examples:
- /^\d+/ string starts with one or more digits
- /^$/ nothing in the string (start and end are adjacent)
- /(\d\s){3}/ a three digits, each followed by a whitespace
- character (eg "3 4 5 ")
- /(a.)+/ matches a string in which every odd-numbered letter
- is a (eg "abacadaf")
+ /^\d+/ string starts with one or more digits
+ /^$/ nothing in the string (start and end are
+ adjacent)
+ /(\d\s){3}/ three digits, each followed by a whitespace
+ character (eg "3 4 5 ")
+ /(a.)+/ matches a string in which every odd-numbered
+ letter is a (eg "abacadaf")
- # This loop reads from STDIN, and prints non-blank lines:
- while (<>) {
- next if /^$/;
- print;
- }
+ # This loop reads from STDIN, and prints non-blank lines:
+ while (<>) {
+ next if /^$/;
+ print;
+ }
=item Parentheses for capturing
@@ -601,12 +608,12 @@
used to capture the results of parts of the regexp match for later use.
The results end up in C<$1>, C<$2> and so on.
- # a cheap and nasty way to break an email address up into parts
+ # a cheap and nasty way to break an email address up into parts
- if ($email =~ /([^@]+)@(.+)/) {
- print "Username is $1\n";
- print "Hostname is $2\n";
- }
+ if ($email =~ /([^@]+)@(.+)/) {
+ print "Username is $1\n";
+ print "Hostname is $2\n";
+ }
=item Other regexp features
@@ -620,15 +627,15 @@
Writing subroutines is easy:
- sub logger {
- my $logmessage = shift;
- open my $logfile, ">>", "my.log" or die "Could not open my.log: $!";
- print $logfile $logmessage;
- }
+ sub logger {
+ my $logmessage = shift;
+ open my $logfile, ">>", "my.log" or die "Could not open my.log: $!";
+ print $logfile $logmessage;
+ }
Now we can use the subroutine just as any other built-in function:
- logger("We have a logger subroutine!");
+ logger("We have a logger subroutine!");
What's that C<shift>? Well, the arguments to a subroutine are available
to us as a special array called C<@_> (see L<perlvar> for more on that).
@@ -638,20 +645,20 @@
We can manipulate C<@_> in other ways too:
- my ($logmessage, $priority) = @_; # common
- my $logmessage = $_[0]; # uncommon, and ugly
+ my ($logmessage, $priority) = @_; # common
+ my $logmessage = $_[0]; # uncommon, and ugly
Subroutines can also return values:
- sub square {
- my $num = shift;
- my $result = $num * $num;
- return $result;
- }
+ sub square {
+ my $num = shift;
+ my $result = $num * $num;
+ return $result;
+ }
Then use it like:
- $sq = square(8);
+ $sq = square(8);
For more information on writing subroutines, see L<perlsub>.
@@ -660,7 +667,7 @@
OO Perl is relatively simple and is implemented using references which
know what sort of object they are based on Perl's concept of packages.
However, OO Perl is largely beyond the scope of this document.
-Read L<perlboot>, L<perltoot>, L<perltooc> and L<perlobj>.
+Read L<perlootut> and L<perlobj>.
As a beginning Perl programmer, your most common use of OO Perl will be
in using third-party modules, which are documented below.
Property changes on: trunk/contrib/perl/pod/perlintro.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perliol.pod
===================================================================
--- trunk/contrib/perl/pod/perliol.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perliol.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -685,7 +685,7 @@
Return error indicator. C<PerlIOBase_error()> is normally sufficient.
-Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set,
+Returns 1 if there is an error (usually when C<PERLIO_F_ERROR> is set),
0 otherwise.
=item Clearerr
@@ -923,7 +923,7 @@
=head2 Extension Layers
-Layers can made available by extension modules. When an unknown layer
+Layers can be made available by extension modules. When an unknown layer
is encountered the PerlIO code will perform the equivalent of :
use PerlIO 'layer';
Property changes on: trunk/contrib/perl/pod/perliol.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlipc.pod
===================================================================
--- trunk/contrib/perl/pod/perlipc.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlipc.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -31,7 +31,7 @@
$SIG{INT} = __PACKAGE__ . "::catch_zap";
$SIG{INT} = \&catch_zap; # best strategy
-Prior to Perl 5.7.3 it was necessary to do as little as you possibly
+Prior to Perl 5.8.0 it was necessary to do as little as you possibly
could in your handler; notice how all we do is set a global variable
and then raise an exception. That's because on most systems,
libraries are not re-entrant; particularly, memory allocation and I/O
@@ -40,25 +40,8 @@
dump - see L</Deferred Signals (Safe Signals)> below.
The names of the signals are the ones listed out by C<kill -l> on your
-system, or you can retrieve them from the Config module. Set up an
- at signame list indexed by number to get the name and a %signo hash table
-indexed by name to get the number:
+system, or you can retrieve them using the CPAN module L<IPC::Signal>.
- use Config;
- defined($Config{sig_name}) || die "No sigs?";
- foreach $name (split(" ", $Config{sig_name})) {
- $signo{$name} = $i;
- $signame[$i] = $name;
- $i++;
- }
-
-So to check whether signal 17 and SIGALRM were the same, do just this:
-
- print "signal #17 = $signame[17]\n";
- if ($signo{ALRM}) {
- print "SIGALRM is $signo{ALRM}\n";
- }
-
You may also choose to assign the strings C<"IGNORE"> or C<"DEFAULT"> as
the handler, in which case Perl will try to discard the signal or do the
default thing.
@@ -72,20 +55,10 @@
C<-1> on such platforms.
Some signals can be neither trapped nor ignored, such as the KILL and STOP
-(but not the TSTP) signals. One strategy for temporarily ignoring signals
-is to use a local() on that hash element, automatically restoring a
-previous value once your block is exited. Remember that values created by
-the dynamically-scoped local() are "inherited" by functions called from
-within their caller's scope.
+(but not the TSTP) signals. Note that ignoring signals makes them disappear.
+If you only want them blocked temporarily without them getting lost you'll
+have to use POSIX' sigprocmask.
- sub precious {
- local $SIG{INT} = "IGNORE";
- more_functions();
- }
- sub more_functions {
- # interrupts still ignored, for now...
- }
-
Sending a signal to a negative process ID means that you send the signal
to the entire Unix process group. This code sends a hang-up signal to all
processes in the current process group, and also sets $SIG{HUP} to C<"IGNORE">
@@ -100,16 +73,17 @@
Another interesting signal to send is signal number zero. This doesn't
actually affect a child process, but instead checks whether it's alive
-or has changed its UID.
+or has changed its UIDs.
unless (kill 0 => $kid_pid) {
warn "something wicked happened to $kid_pid";
}
-When directed at a process whose UID is not identical to that
-of the sending process, signal number zero may fail because
-you lack permission to send the signal, even though the process is alive.
-You may be able to determine the cause of failure using C<%!>.
+Signal number zero may fail because you lack permission to send the
+signal when directed at a process whose real or saved UID is not
+identical to the real or effective UID of the sending process, even
+though the process is alive. You may be able to determine the cause of
+failure using C<$!> or C<%!>.
unless (kill(0 => $pid) || $!{EPERM}) {
warn "$pid looks dead";
@@ -120,45 +94,25 @@
$SIG{INT} = sub { die "\nOutta here!\n" };
-But that will be problematic for the more complicated handlers that need
-to reinstall themselves. Because Perl's signal mechanism is currently
-based on the signal(3) function from the C library, you may sometimes be so
-unfortunate as to run on systems where that function is "broken"; that
-is, it behaves in the old unreliable SysV way rather than the newer, more
-reasonable BSD and POSIX fashion. So you'll see defensive people writing
-signal handlers like this:
+SIGCHLD handlers require some special care. If a second child dies
+while in the signal handler caused by the first death, we won't get
+another signal. So must loop here else we will leave the unreaped child
+as a zombie. And the next time two children die we get another zombie.
+And so on.
- sub REAPER {
- $waitedpid = wait;
- # loathe SysV: it makes us not only reinstate
- # the handler, but place it after the wait
- $SIG{CHLD} = \&REAPER;
- }
- $SIG{CHLD} = \&REAPER;
- # now do something that forks...
-
-or better still:
-
use POSIX ":sys_wait_h";
- sub REAPER {
- my $child;
- # If a second child dies while in the signal handler caused by the
- # first death, we won't get another signal. So must loop here else
- # we will leave the unreaped child as a zombie. And the next time
- # two children die we get another zombie. And so on.
- while (($child = waitpid(-1, WNOHANG)) > 0) {
+ $SIG{CHLD} = sub {
+ while ((my $child = waitpid(-1, WNOHANG)) > 0) {
$Kid_Status{$child} = $?;
}
- $SIG{CHLD} = \&REAPER; # still loathe SysV
- }
- $SIG{CHLD} = \&REAPER;
+ };
# do something that forks...
Be careful: qx(), system(), and some modules for calling external commands
do a fork(), then wait() for the result. Thus, your signal handler
-(C<&REAPER> in the example) will be called. Because wait() was already
-called by system() or qx(), the wait() in the signal handler will see no
-more zombies and will therefore block.
+will be called. Because wait() was already called by system() or qx(),
+the wait() in the signal handler will see no more zombies and will
+therefore block.
The best way to prevent this issue is to use waitpid(), as in the following
example:
@@ -196,8 +150,7 @@
alarm signals and then schedule to have one delivered to you in some
number of seconds. Then try your blocking operation, clearing the alarm
when it's done but not before you've exited your C<eval{}> block. If it
-goes off, you'll use die() to jump out of the block, much as you might
-using longjmp() or throw() in other languages.
+goes off, you'll use die() to jump out of the block.
Here's an example:
@@ -231,12 +184,6 @@
signal handler. When you want to tell the daemon to reread the file,
simply send it the C<SIGHUP> signal.
-Not all platforms automatically reinstall their (native) signal
-handlers after a signal delivery. This means that the handler works
-the first time the signal is sent, only. The solution to this problem
-is to use C<POSIX> signal handlers if available; their behavior
-is well-defined.
-
The following example implements a simple daemon, which restarts
itself every time the C<SIGHUP> signal is received. The actual code is
located in the subroutine C<code()>, which just prints some debugging
@@ -257,16 +204,10 @@
my $SELF = catfile($FindBin::Bin, $script);
# POSIX unmasks the sigprocmask properly
- my $sigset = POSIX::SigSet->new();
- my $action = POSIX::SigAction->new("sigHUP_handler",
- $sigset,
- &POSIX::SA_NODEFER);
- POSIX::sigaction(&POSIX::SIGHUP, $action);
-
- sub sigHUP_handler {
+ $SIG{HUP} = sub {
print "got SIGHUP\n";
exec($SELF, @ARGV) || die "$0: couldn't restart: $!";
- }
+ };
code();
@@ -283,7 +224,7 @@
=head2 Deferred Signals (Safe Signals)
-Before Perl 5.7.3, installing Perl code to deal with signals exposed you to
+Before Perl 5.8.0, installing Perl code to deal with signals exposed you to
danger from two things. First, few system library functions are
re-entrant. If the signal interrupts while Perl is executing one function
(like malloc(3) or printf(3)), and your signal handler then calls the same
@@ -303,7 +244,7 @@
convenience", and to do anything you wanted in your signal handler,
and be prepared to clean up core dumps now and again.
-Perl 5.7.3 and later avoid these problems by "deferring" signals. That is,
+Perl 5.8.0 and later avoid these problems by "deferring" signals. That is,
when the signal is delivered to the process by the system (to the C code
that implements Perl) a flag is set, and the handler returns immediately.
Then at strategic "safe" points in the Perl interpreter (e.g. when it is
@@ -310,7 +251,8 @@
about to execute a new opcode) the flags are checked and the Perl level
handler from %SIG is executed. The "deferred" scheme allows much more
flexibility in the coding of signal handlers as we know the Perl
-interpreter is in a safe state, and that we are not in a system library function when the handler is called. However the implementation does
+interpreter is in a safe state, and that we are not in a system library
+function when the handler is called. However the implementation does
differ from previous Perls in the following ways:
=over 4
@@ -351,7 +293,7 @@
checks the signal flags and calls %SIG handlers before resuming IO
operation.)
-The default in Perl 5.7.3 and later is to automatically use
+The default in Perl 5.8.0 and later is to automatically use
the C<:perlio> layer.
Note that it is not advisable to access a file handle within a signal
@@ -372,10 +314,9 @@
try something like the following:
- use POSIX qw(SIGALRM);
- POSIX::sigaction(SIGALRM,
- POSIX::SigAction->new(sub { die "alarm" }))
- || die "Error setting SIGALRM handler: $!\n";
+ use POSIX qw(SIGALRM);
+ POSIX::sigaction(SIGALRM, POSIX::SigAction->new(sub { die "alarm" }))
+ || die "Error setting SIGALRM handler: $!\n";
Another way to disable the safe signal behavior locally is to use
the C<Perl::Unsafe::Signals> module from CPAN, which affects
@@ -387,7 +328,7 @@
SA_RESTART flag when installing %SIG handlers. This meant that
restartable system calls would continue rather than returning when
a signal arrived. In order to deliver deferred signals promptly,
-Perl 5.7.3 and later do I<not> use SA_RESTART. Consequently,
+Perl 5.8.0 and later do I<not> use SA_RESTART. Consequently,
restartable system calls can fail (with $! set to C<EINTR>) in places
where they previously would have succeeded.
@@ -399,7 +340,7 @@
Certain signals like SEGV, ILL, and BUS are generated by virtual memory
addressing errors and similar "faults". These are normally fatal: there is
-little a Perl-level handler can do with them. So Perl now delivers them
+little a Perl-level handler can do with them. So Perl delivers them
immediately rather than attempting to defer them.
=item Signals triggered by operating system state
@@ -580,7 +521,7 @@
open(STDOUT, "> /dev/null") || die "can't write to /dev/null: $!";
defined(my $pid = fork()) || die "can't fork: $!";
exit if $pid; # non-zero now means I am the parent
- (setsid() != -1) || die "Can't start a new session: $!"
+ (setsid() != -1) || die "Can't start a new session: $!";
open(STDERR, ">&STDOUT") || die "can't dup stdout: $!";
}
@@ -885,7 +826,7 @@
close PARENT_WTR;
print CHILD_WTR "Parent Pid $$ is sending this\n";
chomp($line = <CHILD_RDR>);
- print "Parent Pid $$ just read this: `$line'\n";
+ print "Parent Pid $$ just read this: '$line'\n";
close CHILD_RDR; close CHILD_WTR;
waitpid($pid, 0);
} else {
@@ -893,7 +834,7 @@
close CHILD_RDR;
close CHILD_WTR;
chomp($line = <PARENT_RDR>);
- print "Child Pid $$ just read this: `$line'\n";
+ print "Child Pid $$ just read this: '$line'\n";
print PARENT_WTR "Child Pid $$ is sending this\n";
close PARENT_RDR;
close PARENT_WTR;
@@ -923,7 +864,7 @@
close PARENT;
print CHILD "Parent Pid $$ is sending this\n";
chomp($line = <CHILD>);
- print "Parent Pid $$ just read this: `$line'\n";
+ print "Parent Pid $$ just read this: '$line'\n";
close CHILD;
waitpid($pid, 0);
} else {
@@ -1155,7 +1096,7 @@
Within the while loop we call accept() and check to see if it returns
a false value. This would normally indicate a system error needs
to be reported. However, the introduction of safe signals (see
-L</Deferred Signals (Safe Signals)> above) in Perl 5.7.3 means that
+L</Deferred Signals (Safe Signals)> above) in Perl 5.8.0 means that
accept() might also be interrupted when the process receives a signal.
This typically happens when one of the forked subprocesses exits and
notifies the parent process with a CHLD signal.
@@ -1336,10 +1277,8 @@
=head1 TCP Clients with IO::Socket
For those preferring a higher-level interface to socket programming, the
-IO::Socket module provides an object-oriented approach. IO::Socket has
-been included in the standard Perl distribution ever since Perl 5.004. If
-you're running an earlier version of Perl (in which case, how are you
-reading this manpage?), just fetch IO::Socket from CPAN, where you'll also
+IO::Socket module provides an object-oriented approach. If for some reason
+you lack this module, you can just fetch IO::Socket from CPAN, where you'll also
find modules providing easy interfaces to the following systems: DNS, FTP,
Ident (RFC 931), NIS and NISPlus, NNTP, Ping, POP3, SMTP, SNMP, SSLeay,
Telnet, and Time--to name just a few.
@@ -1746,7 +1685,7 @@
print "read : '$buff'\n";
# the buffer of shmread is zero-character end-padded.
- substr($buff, index($buff, "\0")) = "":
+ substr($buff, index($buff, "\0")) = "";
print "un" unless $buff eq $message;
print "swell\n";
@@ -1759,8 +1698,8 @@
$IPC_KEY = 1234;
$id = semget($IPC_KEY, 10, 0666 | IPC_CREAT);
- defined($id) || die "shmget: $!";
- print "shm key $id\n";
+ defined($id) || die "semget: $!";
+ print "sem id $id\n";
Put this code in a separate file to be run in more than one process.
Call the file F<take>:
@@ -1769,7 +1708,7 @@
$IPC_KEY = 1234;
$id = semget($IPC_KEY, 0, 0);
- defined($id) || die "shmget: $!";
+ defined($id) || die "semget: $!";
$semnum = 0;
$semflag = 0;
@@ -1807,8 +1746,7 @@
semop($id, $opstring) || die "semop: $!";
The SysV IPC code above was written long ago, and it's definitely
-clunky looking. For a more modern look, see the IPC::SysV module
-which is included with Perl starting from Perl 5.005.
+clunky looking. For a more modern look, see the IPC::SysV module.
A small example demonstrating SysV message queues:
Property changes on: trunk/contrib/perl/pod/perlipc.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perllexwarn.pod
===================================================================
--- trunk/contrib/perl/pod/perllexwarn.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perllexwarn.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -158,7 +158,7 @@
=head2 Backward Compatibility
-If you are used with working with a version of Perl prior to the
+If you are used to working with a version of Perl prior to the
introduction of lexically scoped warnings, or have code that uses both
lexical warnings and C<$^W>, this section will describe how they interact.
@@ -169,7 +169,7 @@
=item 1.
If none of the three command line flags (B<-w>, B<-W> or B<-X>) that
-control warnings is used and neither C<$^W> or the C<warnings> pragma
+control warnings is used and neither C<$^W> nor the C<warnings> pragma
are used, then default warnings will be enabled and optional warnings
disabled.
This means that legacy code that doesn't attempt to control the warnings
@@ -212,107 +212,111 @@
The current hierarchy is:
- all -+
- |
- +- closure
- |
- +- deprecated
- |
- +- exiting
- |
- +- glob
- |
- +- io -----------+
- | |
- | +- closed
- | |
- | +- exec
- | |
- | +- layer
- | |
- | +- newline
- | |
- | +- pipe
- | |
- | +- unopened
- |
- +- imprecision
- |
- +- misc
- |
- +- numeric
- |
- +- once
- |
- +- overflow
- |
- +- pack
- |
- +- portable
- |
- +- recursion
- |
- +- redefine
- |
- +- regexp
- |
- +- severe -------+
- | |
- | +- debugging
- | |
- | +- inplace
- | |
- | +- internal
- | |
- | +- malloc
- |
- +- signal
- |
- +- substr
- |
- +- syntax -------+
- | |
- | +- ambiguous
- | |
- | +- bareword
- | |
- | +- digit
- | |
- | +- illegalproto
- | |
- | +- parenthesis
- | |
- | +- precedence
- | |
- | +- printf
- | |
- | +- prototype
- | |
- | +- qw
- | |
- | +- reserved
- | |
- | +- semicolon
- |
- +- taint
- |
- +- threads
- |
- +- uninitialized
- |
- +- unpack
- |
- +- untie
- |
- +- utf8----------+
- | |
- | +- surrogate
- | |
- | +- non_unicode
- | |
- | +- nonchar
- |
- +- void
+ all -+
+ |
+ +- closure
+ |
+ +- deprecated
+ |
+ +- exiting
+ |
+ +- experimental --+
+ | |
+ | +- experimental::lexical_subs
+ |
+ +- glob
+ |
+ +- imprecision
+ |
+ +- io ------------+
+ | |
+ | +- closed
+ | |
+ | +- exec
+ | |
+ | +- layer
+ | |
+ | +- newline
+ | |
+ | +- pipe
+ | |
+ | +- unopened
+ |
+ +- misc
+ |
+ +- numeric
+ |
+ +- once
+ |
+ +- overflow
+ |
+ +- pack
+ |
+ +- portable
+ |
+ +- recursion
+ |
+ +- redefine
+ |
+ +- regexp
+ |
+ +- severe --------+
+ | |
+ | +- debugging
+ | |
+ | +- inplace
+ | |
+ | +- internal
+ | |
+ | +- malloc
+ |
+ +- signal
+ |
+ +- substr
+ |
+ +- syntax --------+
+ | |
+ | +- ambiguous
+ | |
+ | +- bareword
+ | |
+ | +- digit
+ | |
+ | +- illegalproto
+ | |
+ | +- parenthesis
+ | |
+ | +- precedence
+ | |
+ | +- printf
+ | |
+ | +- prototype
+ | |
+ | +- qw
+ | |
+ | +- reserved
+ | |
+ | +- semicolon
+ |
+ +- taint
+ |
+ +- threads
+ |
+ +- uninitialized
+ |
+ +- unpack
+ |
+ +- untie
+ |
+ +- utf8 ----------+
+ | |
+ | +- non_unicode
+ | |
+ | +- nonchar
+ | |
+ | +- surrogate
+ |
+ +- void
Just like the "strict" pragma any of these categories can be combined
@@ -335,7 +339,6 @@
sub-category of the "syntax" category. It is now a top-level category
in its own right.
-
=head2 Fatal Warnings
X<warning, fatal>
Property changes on: trunk/contrib/perl/pod/perllexwarn.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perllocale.pod
===================================================================
--- trunk/contrib/perl/pod/perllocale.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perllocale.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,3 +1,5 @@
+=encoding utf8
+
=head1 NAME
perllocale - Perl locale handling (internationalization and localization)
@@ -4,37 +6,96 @@
=head1 DESCRIPTION
-Locales these days have been mostly been supplanted by Unicode, but Perl
-continues to support them. See L</Unicode and UTF-8> below.
+In the beginning there was ASCII, the "American Standard Code for
+Information Interchange", which works quite well for Americans with
+their English alphabet and dollar-denominated currency. But it doesn't
+work so well even for other English speakers, who may use different
+currencies, such as the pound sterling (as the symbol for that currency
+is not in ASCII); and it's hopelessly inadequate for many of the
+thousands of the world's other languages.
-Perl supports language-specific notions of data such as "is this
-a letter", "what is the uppercase equivalent of this letter", and
-"which of these letters comes first". These are important issues,
-especially for languages other than English--but also for English: it
-would be naE<iuml>ve to imagine that C<A-Za-z> defines all the "letters"
-needed to write correct English. Perl is also aware that some character other
-than "." may be preferred as a decimal point, and that output date
-representations may be language-specific. The process of making an
-application take account of its users' preferences in such matters is
-called B<internationalization> (often abbreviated as B<i18n>); telling
-such an application about a particular set of preferences is known as
-B<localization> (B<l10n>).
+To address these deficiencies, the concept of locales was invented
+(formally the ISO C, XPG4, POSIX 1.c "locale system"). And applications
+were and are being written that use the locale mechanism. The process of
+making such an application take account of its users' preferences in
+these kinds of matters is called B<internationalization> (often
+abbreviated as B<i18n>); telling such an application about a particular
+set of preferences is known as B<localization> (B<l10n>).
-Perl can understand language-specific data via the standardized (ISO C,
-XPG4, POSIX 1.c) method called "the locale system". The locale system is
-controlled per application using one pragma, one function call, and
-several environment variables.
+Perl was extended to support the locale system. This
+is controlled per application by using one pragma, one function call,
+and several environment variables.
-B<NOTE>: This feature is new in Perl 5.004, and does not apply unless an
-application specifically requests it--see L<Backward compatibility>.
-The one exception is that write() now B<always> uses the current locale
-- see L<"NOTES">.
+Unfortunately, there are quite a few deficiencies with the design (and
+often, the implementations) of locales, and their use for character sets
+has mostly been supplanted by Unicode (see L<perlunitut> for an
+introduction to that, and keep on reading here for how Unicode interacts
+with locales in Perl).
+Perl continues to support the old locale system, and starting in v5.16,
+provides a hybrid way to use the Unicode character set, along with the
+other portions of locales that may not be so problematic.
+(Unicode is also creating C<CLDR>, the "Common Locale Data Repository",
+L<http://cldr.unicode.org/> which includes more types of information than
+are available in the POSIX locale system. At the time of this writing,
+there was no CPAN module that provides access to this XML-encoded data.
+However, many of its locales have the POSIX-only data extracted, and are
+available at L<http://unicode.org/Public/cldr/latest/>.)
+
+=head1 WHAT IS A LOCALE
+
+A locale is a set of data that describes various aspects of how various
+communities in the world categorize their world. These categories are
+broken down into the following types (some of which include a brief
+note here):
+
+=over
+
+=item Category LC_NUMERIC: Numeric formatting
+
+This indicates how numbers should be formatted for human readability,
+for example the character used as the decimal point.
+
+=item Category LC_MONETARY: Formatting of monetary amounts
+
+=for comment
+The nbsp below makes this look better
+
+E<160>
+
+=item Category LC_TIME: Date/Time formatting
+
+=for comment
+The nbsp below makes this look better
+
+E<160>
+
+=item Category LC_MESSAGES: Error and other messages
+
+This for the most part is beyond the scope of Perl
+
+=item Category LC_COLLATE: Collation
+
+This indicates the ordering of letters for comparison and sorting.
+In Latin alphabets, for example, "b", generally follows "a".
+
+=item Category LC_CTYPE: Character Types
+
+This indicates, for example if a character is an uppercase letter.
+
+=back
+
+More details on the categories are given below in L</LOCALE CATEGORIES>.
+
+Together, these categories go a long way towards being able to customize
+a single program to run in many different locations. But there are
+deficiencies, so keep reading.
+
=head1 PREPARING TO USE LOCALES
-If Perl applications are to understand and present your data
-correctly according a locale of your choice, B<all> of the following
-must be true:
+Perl will not use locales unless specifically requested to (see L</NOTES> below
+for the partial exception of C<write()>). But even if there is such a
+request, B<all> of the following must be true for it to work properly:
=over 4
@@ -74,9 +135,9 @@
=item 1
-B<The locale-determining environment variables (see L<"ENVIRONMENT">)
+B<The locale-determining environment variables (see L</"ENVIRONMENT">)
must be correctly set up> at the time the application is started, either
-by yourself or by whoever set up your system account; or
+by yourself or by whomever set up your system account; or
=item 2
@@ -90,13 +151,25 @@
=head2 The use locale pragma
By default, Perl ignores the current locale. The S<C<use locale>>
-pragma and the C</l> regular expression modifier tell Perl to use the
-current locale for some operations (C</l> for just pattern matching).
+pragma tells Perl to use the current locale for some operations.
+Starting in v5.16, there is an optional parameter to this pragma:
+ use locale ':not_characters';
+
+This parameter allows better mixing of locales and Unicode, and is
+described fully in L</Unicode and UTF-8>, but briefly, it tells Perl to
+not use the character portions of the locale definition, that is
+the C<LC_CTYPE> and C<LC_COLLATE> categories. Instead it will use the
+native (extended by Unicode) character set. When using this parameter,
+you are responsible for getting the external character set translated
+into the native/Unicode one (which it already will be if it is one of
+the increasingly popular UTF-8 locales). There are convenient ways of
+doing this, as described in L</Unicode and UTF-8>.
+
The current locale is set at execution time by
L<setlocale()|/The setlocale function> described below. If that function
hasn't yet been called in the course of the program's execution, the
-current locale is that which was determined by the L<"ENVIRONMENT"> in
+current locale is that which was determined by the L</"ENVIRONMENT"> in
effect at the start of the program, except that
C<L<LC_NUMERIC|/Category LC_NUMERIC: Numeric Formatting>> is always
initialized to the C locale (mentioned under L<Finding locales>).
@@ -107,8 +180,33 @@
=over 4
+=item B<Under C<use locale ':not_characters';>>
+
+=over 4
+
=item *
+B<Format declarations> (format()) use C<LC_NUMERIC>
+
+=item *
+
+B<The POSIX date formatting function> (strftime()) uses C<LC_TIME>.
+
+=back
+
+=for comment
+The nbsp below makes this look better
+
+E<160>
+
+=item B<Under just plain C<use locale;>>
+
+The above operations are affected, as well as the following:
+
+=over 4
+
+=item *
+
B<The comparison operators> (C<lt>, C<le>, C<cmp>, C<ge>, and C<gt>) and
the POSIX string collation functions strcoll() and strxfrm() use
C<LC_COLLATE>. sort() is also affected if used without an
@@ -129,21 +227,15 @@
B<Regular expressions and case-modification functions> (uc(), lc(),
ucfirst(), and lcfirst()) use C<LC_CTYPE>
-=item *
+=back
-B<Format declarations> (format()) use C<LC_NUMERIC>
-
-=item *
-
-B<The POSIX date formatting function> (strftime()) uses C<LC_TIME>.
-
=back
-C<LC_COLLATE>, C<LC_CTYPE>, and so on, are discussed further in
-L<LOCALE CATEGORIES>.
-
The default behavior is restored with the S<C<no locale>> pragma, or
-upon reaching the end of block enclosing C<use locale>.
+upon reaching the end of the block enclosing C<use locale>.
+Note that C<use locale> and C<use locale ':not_characters'> may be
+nested, and that what is in effect within an inner scope will revert to
+the outer scope's rules at the end of the inner scope.
The string result of any operation that uses locale
information is tainted, as it is possible for a locale to be
@@ -154,9 +246,6 @@
You can switch locales as often as you wish at run time with the
POSIX::setlocale() function:
- # This functionality not usable prior to Perl 5.004
- require 5.004;
-
# Import locale-handling tool set from POSIX module.
# This example uses: setlocale -- the function call
# LC_CTYPE -- explained below
@@ -178,7 +267,7 @@
The first argument of setlocale() gives the B<category>, the second the
B<locale>. The category tells in what aspect of data processing you
want to apply locale-specific rules. Category names are discussed in
-L<LOCALE CATEGORIES> and L<"ENVIRONMENT">. The locale is the name of a
+L</LOCALE CATEGORIES> and L</"ENVIRONMENT">. The locale is the name of a
collection of customization information corresponding to a particular
combination of language, country or territory, and codeset. Read on for
hints on the naming of locales: not all systems name locales as in the
@@ -212,6 +301,9 @@
If the second argument does not correspond to a valid locale, the locale
for the category is not changed, and the function returns I<undef>.
+Note that Perl ignores the current C<LC_CTYPE> and C<LC_COLLATE> locales
+within the scope of a C<use locale ':not_characters'>.
+
For further information about the categories, consult setlocale(3).
=head2 Finding locales
@@ -308,7 +400,7 @@
these changes. If you make the new settings permanent (read on), all
programs you run see the changes. See L<"ENVIRONMENT"> for
the full list of relevant environment variables and L<USING LOCALES>
-for their effects in Perl. Effects in other programs are
+for their effects in Perl. Effects in other programs are
easily deducible. For example, the variable LC_COLLATE may well affect
your B<sort> program (or whatever the program that arranges "records"
alphabetically in your system is called).
@@ -369,7 +461,7 @@
the same. In this case, try running under a locale
that you can list and which somehow matches what you tried. The
rules for matching locale names are a bit vague because
-standardization is weak in this area. See again the
+standardization is weak in this area. See again the
L<Finding locales> about general rules.
=head2 Fixing system locale configuration
@@ -411,42 +503,40 @@
Here's a simple-minded example program that rewrites its command-line
parameters as integers correctly formatted in the current locale:
- # See comments in previous example
- require 5.004;
- use POSIX qw(locale_h);
+ use POSIX qw(locale_h);
- # Get some of locale's numeric formatting parameters
- my ($thousands_sep, $grouping) =
- @{localeconv()}{'thousands_sep', 'grouping'};
+ # Get some of locale's numeric formatting parameters
+ my ($thousands_sep, $grouping) =
+ @{localeconv()}{'thousands_sep', 'grouping'};
- # Apply defaults if values are missing
- $thousands_sep = ',' unless $thousands_sep;
+ # Apply defaults if values are missing
+ $thousands_sep = ',' unless $thousands_sep;
- # grouping and mon_grouping are packed lists
- # of small integers (characters) telling the
- # grouping (thousand_seps and mon_thousand_seps
- # being the group dividers) of numbers and
- # monetary quantities. The integers' meanings:
- # 255 means no more grouping, 0 means repeat
- # the previous grouping, 1-254 means use that
- # as the current grouping. Grouping goes from
- # right to left (low to high digits). In the
- # below we cheat slightly by never using anything
- # else than the first grouping (whatever that is).
- if ($grouping) {
- @grouping = unpack("C*", $grouping);
- } else {
- @grouping = (3);
- }
+ # grouping and mon_grouping are packed lists
+ # of small integers (characters) telling the
+ # grouping (thousand_seps and mon_thousand_seps
+ # being the group dividers) of numbers and
+ # monetary quantities. The integers' meanings:
+ # 255 means no more grouping, 0 means repeat
+ # the previous grouping, 1-254 means use that
+ # as the current grouping. Grouping goes from
+ # right to left (low to high digits). In the
+ # below we cheat slightly by never using anything
+ # else than the first grouping (whatever that is).
+ if ($grouping) {
+ @grouping = unpack("C*", $grouping);
+ } else {
+ @grouping = (3);
+ }
- # Format command line params for current locale
- for (@ARGV) {
- $_ = int; # Chop non-integer part
- 1 while
- s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
- print "$_";
- }
- print "\n";
+ # Format command line params for current locale
+ for (@ARGV) {
+ $_ = int; # Chop non-integer part
+ 1 while
+ s/(\d)(\d{$grouping[0]}($|$thousands_sep))/$1$thousands_sep$2/;
+ print "$_";
+ }
+ print "\n";
=head2 I18N::Langinfo
@@ -462,7 +552,8 @@
use I18N::Langinfo qw(langinfo ABDAY_1 YESSTR NOSTR);
- my ($abday_1, $yesstr, $nostr) = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
+ my ($abday_1, $yesstr, $nostr)
+ = map { langinfo } qw(ABDAY_1 YESSTR NOSTR);
print "$abday_1? [$yesstr/$nostr] ";
@@ -469,7 +560,7 @@
In other words, in the "C" (or English) locale the above will probably
print something like:
- Sun? [yes/no]
+ Sun? [yes/no]
See L<I18N::Langinfo> for more information.
@@ -481,11 +572,12 @@
=head2 Category LC_COLLATE: Collation
-In the scope of S<C<use locale>>, Perl looks to the C<LC_COLLATE>
+In the scope of S<C<use locale>> (but not a
+C<use locale ':not_characters'>), Perl looks to the C<LC_COLLATE>
environment variable to determine the application's notions on collation
(ordering) of characters. For example, "b" follows "a" in Latin
alphabets, but where do "E<aacute>" and "E<aring>" belong? And while
-"color" follows "chocolate" in English, what about in Spanish?
+"color" follows "chocolate" in English, what about in traditional Spanish?
The following collations all make sense and you may meet any of them
if you "use locale".
@@ -561,7 +653,8 @@
=head2 Category LC_CTYPE: Character Types
-In the scope of S<C<use locale>>, Perl obeys the C<LC_CTYPE> locale
+In the scope of S<C<use locale>> (but not a
+C<use locale ':not_characters'>), Perl obeys the C<LC_CTYPE> locale
setting. This controls the application's notion of which characters are
alphabetic. This affects Perl's C<\w> regular expression metanotation,
which stands for alphanumeric characters--that is, alphabetic,
@@ -582,7 +675,15 @@
functions--isalpha(), islower(), and so on. For example, if you move
from the "C" locale to a 7-bit Scandinavian one, you may find--possibly
to your surprise--that "|" moves from the ispunct() class to isalpha().
+Unfortunately, this creates big problems for regular expressions. "|" still
+means alternation even though it matches C<\w>.
+Note that there are quite a few things that are unaffected by the
+current locale. All the escape sequences for particular characters,
+C<\n> for example, always mean the platform's native one. This means,
+for example, that C<\N> in regular expressions (every character
+but new-line) work on the platform character set.
+
B<Note:> A broken or malicious C<LC_CTYPE> locale definition may result
in clearly ineligible characters being considered to be alphanumeric by
your application. For strict matching of (mundane) ASCII letters and
@@ -628,11 +729,11 @@
that is affected by its contents. (Those with experience of standards
committees will recognize that the working group decided to punt on the
issue.) Consequently, Perl takes no notice of it. If you really want
-to use C<LC_MONETARY>, you can query its contents--see
-L<The localeconv function>--and use the information that it returns in your
-application's own formatting of currency amounts. However, you may well
-find that the information, voluminous and complex though it may be, still
-does not quite meet your requirements: currency formatting is a hard nut
+to use C<LC_MONETARY>, you can query its contents--see
+L<The localeconv function>--and use the information that it returns in your
+application's own formatting of currency amounts. However, you may well
+find that the information, voluminous and complex though it may be, still
+does not quite meet your requirements: currency formatting is a hard nut
to crack.
See also L<I18N::Langinfo> and C<CRNCYSTR>.
@@ -742,7 +843,7 @@
B<Case-mapping interpolation> (with C<\l>, C<\L>, C<\u> or C<\U>)
Result string containing interpolated material is tainted if
-C<use locale> is in effect.
+C<use locale> (but not S<C<use locale ':not_characters'>>) is in effect.
=item *
@@ -751,7 +852,8 @@
Scalar true/false result never tainted.
Subpatterns, either delivered as a list-context result or as $1 etc.
-are tainted if C<use locale> is in effect, and the subpattern regular
+are tainted if C<use locale> (but not S<C<use locale ':not_characters'>>)
+is in effect, and the subpattern regular
expression contains C<\w> (to match an alphanumeric character), C<\W>
(non-alphanumeric character), C<\s> (whitespace character), or C<\S>
(non whitespace character). The matched-pattern variable, $&, $`
@@ -764,8 +866,9 @@
B<Substitution operator> (C<s///>):
Has the same behavior as the match operator. Also, the left
-operand of C<=~> becomes tainted when C<use locale> in effect
-if modified as a result of a substitution based on a regular
+operand of C<=~> becomes tainted when C<use locale>
+(but not S<C<use locale ':not_characters'>>) is in effect if modified as
+a result of a substitution based on a regular
expression match involving C<\w>, C<\W>, C<\s>, or C<\S>; or of
case-mapping with C<\l>, C<\L>,C<\u> or C<\U>.
@@ -781,7 +884,8 @@
B<Case-mapping functions> (lc(), lcfirst(), uc(), ucfirst()):
-Results are tainted if C<use locale> is in effect.
+Results are tainted if C<use locale> (but not
+S<C<use locale ':not_characters'>>) is in effect.
=item *
@@ -812,7 +916,7 @@
$tainted_output_file = shift;
open(F, ">$tainted_output_file")
- or warn "Open of $untainted_output_file failed: $!\n";
+ or warn "Open of $tainted_output_file failed: $!\n";
The program can be made to run by "laundering" the tainted value through
a regular expression: the second example--which still ignores locale
@@ -930,18 +1034,18 @@
The LC_NUMERIC controls the numeric output:
- use locale;
- use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
- setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
- printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
+ use locale;
+ use POSIX qw(locale_h); # Imports setlocale() and the LC_ constants.
+ setlocale(LC_NUMERIC, "fr_FR") or die "Pardon";
+ printf "%g\n", 1.23; # If the "fr_FR" succeeded, probably shows 1,23.
and also how strings are parsed by POSIX::strtod() as numbers:
- use locale;
- use POSIX qw(locale_h strtod);
- setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
- my $x = strtod("2,34") + 5;
- print $x, "\n"; # Probably shows 7,34.
+ use locale;
+ use POSIX qw(locale_h strtod);
+ setlocale(LC_NUMERIC, "de_DE") or die "Entschuldigung";
+ my $x = strtod("2,34") + 5;
+ print $x, "\n"; # Probably shows 7,34.
=head1 NOTES
@@ -953,7 +1057,8 @@
(see L<The setlocale function>). By default, Perl still behaves this
way for backward compatibility. If you want a Perl application to pay
attention to locale information, you B<must> use the S<C<use locale>>
-pragma (see L<The use locale pragma>) or for just pattern matching, the
+pragma (see L<The use locale pragma>) or, in the unlikely event
+that you want to do so for just pattern matching, the
C</l> regular expression modifier (see L<perlre/Character set
modifiers>) to instruct it to do so.
@@ -994,6 +1099,11 @@
=head2 Freely available locale definitions
+The Unicode CLDR project extracts the POSIX portion of many of its
+locales, available at
+
+ http://unicode.org/Public/cldr/latest/
+
There is a large collection of locale definitions at:
http://std.dkuug.dk/i18n/WG15-collection/locales/
@@ -1023,25 +1133,65 @@
=head1 Unicode and UTF-8
-The support of Unicode is new starting from Perl version 5.6, and more fully
-implemented in version 5.8 and later. See L<perluniintro>. Perl tries to
-work with both Unicode and locales--but of course, there are problems.
+The support of Unicode is new starting from Perl version v5.6, and more fully
+implemented in version v5.8 and later. See L<perluniintro>. It is
+strongly recommended that when combining Unicode and locale (starting in
+v5.16), you use
-Perl does not handle multi-byte locales, such as have been used for various
-Asian languages, such as Big5 or Shift JIS. However, the increasingly common
-multi-byte UTF-8 locales, if properly implemented, tend to work
-reasonably well in Perl, simply because both they and Perl store
-characters that take up multiple bytes the same way.
+ use locale ':not_characters';
+When this form of the pragma is used, only the non-character portions of
+locales are used by Perl, for example C<LC_NUMERIC>. Perl assumes that
+you have translated all the characters it is to operate on into Unicode
+(actually the platform's native character set (ASCII or EBCDIC) plus
+Unicode). For data in files, this can conveniently be done by also
+specifying
+
+ use open ':locale';
+
+This pragma arranges for all inputs from files to be translated into
+Unicode from the current locale as specified in the environment (see
+L</ENVIRONMENT>), and all outputs to files to be translated back
+into the locale. (See L<open>). On a per-filehandle basis, you can
+instead use the L<PerlIO::locale> module, or the L<Encode::Locale>
+module, both available from CPAN. The latter module also has methods to
+ease the handling of C<ARGV> and environment variables, and can be used
+on individual strings. Also, if you know that all your locales will be
+UTF-8, as many are these days, you can use the L<B<-C>|perlrun/-C>
+command line switch.
+
+This form of the pragma allows essentially seamless handling of locales
+with Unicode. The collation order will be Unicode's. It is strongly
+recommended that when you need to order and sort strings that you use
+the standard module L<Unicode::Collate> which gives much better results
+in many instances than you can get with the old-style locale handling.
+
+For pre-v5.16 Perls, or if you use the locale pragma without the
+C<:not_characters> parameter, Perl tries to work with both Unicode and
+locales--but there are problems.
+
+Perl does not handle multi-byte locales in this case, such as have been
+used for various
+Asian languages, such as Big5 or Shift JIS. However, the increasingly
+common multi-byte UTF-8 locales, if properly implemented, may work
+reasonably well (depending on your C library implementation) in this
+form of the locale pragma, simply because both
+they and Perl store characters that take up multiple bytes the same way.
+However, some, if not most, C library implementations may not process
+the characters in the upper half of the Latin-1 range (128 - 255)
+properly under LC_CTYPE. To see if a character is a particular type
+under a locale, Perl uses the functions like C<isalnum()>. Your C
+library may not work for UTF-8 locales with those functions, instead
+only working under the newer wide library functions like C<iswalnum()>.
+
Perl generally takes the tack to use locale rules on code points that can fit
-in a single byte, and Unicode rules for those that can't (though this wasn't
-uniformly applied prior to Perl 5.14). This prevents many problems in locales
-that aren't UTF-8. Suppose the locale is ISO8859-7, Greek. The character at
-0xD7 there is a capital Chi. But in the ISO8859-1 locale, Latin1, it is a
-multiplication sign. The POSIX regular expression character class
-C<[[:alpha:]]> will magically match 0xD7 in the Greek locale but not in the
-Latin one, even if the string is encoded in UTF-8, which would normally imply
-Unicode semantics. (The "U" in UTF-8 stands for Unicode.)
+in a single byte, and Unicode rules for those that can't (though this
+isn't uniformly applied, see the note at the end of this section). This
+prevents many problems in locales that aren't UTF-8. Suppose the locale
+is ISO8859-7, Greek. The character at 0xD7 there is a capital Chi. But
+in the ISO8859-1 locale, Latin1, it is a multiplication sign. The POSIX
+regular expression character class C<[[:alpha:]]> will magically match
+0xD7 in the Greek locale but not in the Latin one.
However, there are places where this breaks down. Certain constructs are
for Unicode only, such as C<\p{Alpha}>. They assume that 0xD7 always has its
@@ -1049,11 +1199,20 @@
subset of Unicode and 0xD7 is the multiplication sign in both Latin1 and
Unicode, C<\p{Alpha}> will never match it, regardless of locale. A similar
issue occurs with C<\N{...}>. It is therefore a bad idea to use C<\p{}> or
-C<\N{}> under C<use locale>--I<unless> you can guarantee that the locale will
-be a ISO8859-1 or UTF-8 one. Use POSIX character classes instead.
+C<\N{}> under plain C<use locale>--I<unless> you can guarantee that the
+locale will be a ISO8859-1. Use POSIX character classes instead.
+Another problem with this approach is that operations that cross the
+single byte/multiple byte boundary are not well-defined, and so are
+disallowed. (This boundary is between the codepoints at 255/256.).
+For example, lower casing LATIN CAPITAL LETTER Y WITH DIAERESIS (U+0178)
+should return LATIN SMALL LETTER Y WITH DIAERESIS (U+00FF). But in the
+Greek locale, for example, there is no character at 0xFF, and Perl
+has no way of knowing what the character at 0xFF is really supposed to
+represent. Thus it disallows the operation. In this mode, the
+lowercase of U+0178 is itself.
-The same problem ensues if you enable automatic UTF-8-ification of your
+The same problems ensue if you enable automatic UTF-8-ification of your
standard file handles, default C<open()> layer, and C<@ARGV> on non-ISO8859-1,
non-UTF-8 locales (by using either the B<-C> command line switch or the
C<PERL_UNICODE> environment variable; see L<perlrun>).
@@ -1061,20 +1220,38 @@
interpretation, but the presence of a locale causes them to be interpreted
in that locale instead. For example, a 0xD7 code point in the Unicode
input, which should mean the multiplication sign, won't be interpreted by
-Perl that way under the Greek locale. Again, this is not a problem
+Perl that way under the Greek locale. This is not a problem
I<provided> you make certain that all locales will always and only be either
-an ISO8859-1 or a UTF-8 locale.
+an ISO8859-1, or, if you don't have a deficient C library, a UTF-8 locale.
Vendor locales are notoriously buggy, and it is difficult for Perl to test
its locale-handling code because this interacts with code that Perl has no
control over; therefore the locale-handling code in Perl may be buggy as
-well. But if you I<do> have locales that work, using them may be
-worthwhile for certain specific purposes, as long as you keep in mind the
-gotchas already mentioned. For example, collation runs faster under
-locales than under L<Unicode::Collate> (albeit with less flexibility), and
-you gain access to such things as the local currency symbol and the names
-of the months and days of the week.
+well. (However, the Unicode-supplied locales should be better, and
+there is a feed back mechanism to correct any problems. See
+L</Freely available locale definitions>.)
+If you have Perl v5.16, the problems mentioned above go away if you use
+the C<:not_characters> parameter to the locale pragma (except for vendor
+bugs in the non-character portions). If you don't have v5.16, and you
+I<do> have locales that work, using them may be worthwhile for certain
+specific purposes, as long as you keep in mind the gotchas already
+mentioned. For example, if the collation for your locales works, it
+runs faster under locales than under L<Unicode::Collate>; and you gain
+access to such things as the local currency symbol and the names of the
+months and days of the week. (But to hammer home the point, in v5.16,
+you get this access without the downsides of locales by using the
+C<:not_characters> form of the pragma.)
+
+Note: The policy of using locale rules for code points that can fit in a
+byte, and Unicode rules for those that can't is not uniformly applied.
+Pre-v5.12, it was somewhat haphazard; in v5.12 it was applied fairly
+consistently to regular expression matching except for bracketed
+character classes; in v5.14 it was extended to all regex matches; and in
+v5.16 to the casing operations such as C<"\L"> and C<uc()>. For
+collation, in all releases, the system's C<strxfrm()> function is called,
+and whatever it does is what you get.
+
=head1 BUGS
=head2 Broken systems
Property changes on: trunk/contrib/perl/pod/perllocale.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perllol.pod
===================================================================
--- trunk/contrib/perl/pod/perllol.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perllol.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -174,7 +174,7 @@
push $AoA[0], "wilma", "betty"; # implicit deref
-How come? Because once upon a time, the argument to push() had to be be a
+How come? Because once upon a time, the argument to push() had to be a
real array, not just a reference to one. That's no longer true. In fact,
the line marked "implicit deref" above works just fine--in this
instance--to do what the one that says explicit deref did.
Property changes on: trunk/contrib/perl/pod/perllol.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlmod.pod
===================================================================
--- trunk/contrib/perl/pod/perlmod.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlmod.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -102,6 +102,10 @@
instance. The standard but antiquated F<dumpvar.pl> library and
the CPAN module Devel::Symdump make use of this.
+The results of creating new symbol table entries directly or modifying any
+entries that are not already typeglobs are undefined and subject to change
+between releases of perl.
+
Assignment to a typeglob performs an aliasing operation, i.e.,
*dick = *richard;
@@ -303,7 +307,7 @@
C<UNITCHECK> blocks are run just after the unit which defined them has
been compiled. The main program file and each module it loads are
-compilation units, as are string C<eval>s, code compiled using the
+compilation units, as are string C<eval>s, run-time code compiled using the
C<(?{ })> construct in a regex, calls to C<do FILE>, C<require FILE>,
and code after the C<-e> switch on the command line.
@@ -377,7 +381,7 @@
by listing the other package name(s) in its global @ISA array (which
must be a package global, not a lexical).
-For more on this, see L<perltoot> and L<perlobj>.
+For more on this, see L<perlootut> and L<perlobj>.
=head2 Perl Modules
X<module>
@@ -400,66 +404,51 @@
use warnings;
BEGIN {
- use Exporter ();
- our ($VERSION, @ISA, @EXPORT, @EXPORT_OK, %EXPORT_TAGS);
+ require Exporter;
# set the version for version checking
- $VERSION = 1.00;
- # if using RCS/CVS, this may be preferred
- $VERSION = sprintf "%d.%03d", q$Revision: 1.1.1.3 $ =~ /(\d+)/g;
+ our $VERSION = 1.00;
- @ISA = qw(Exporter);
- @EXPORT = qw(&func1 &func2 &func4);
- %EXPORT_TAGS = ( ); # eg: TAG => [ qw!name1 name2! ],
+ # Inherit from Exporter to export functions and variables
+ our @ISA = qw(Exporter);
- # your exported package globals go here,
- # as well as any optionally exported functions
- @EXPORT_OK = qw($Var1 %Hashit &func3);
+ # Functions and variables which are exported by default
+ our @EXPORT = qw(func1 func2);
+
+ # Functions and variables which can be optionally exported
+ our @EXPORT_OK = qw($Var1 %Hashit func3);
}
- our @EXPORT_OK;
# exported package globals go here
- our $Var1;
- our %Hashit;
+ our $Var1 = '';
+ our %Hashit = ();
# non-exported package globals go here
- our @more;
- our $stuff;
+ # (they are still accessible as $Some::Module::stuff)
+ our @more = ();
+ our $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
+ # file-private lexicals go here, before any functions which use them
my $priv_var = '';
my %secret_hash = ();
# here's a file-private function as a closure,
- # callable as &$priv_func; it cannot be prototyped.
+ # callable as $priv_func->();
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
+ sub func1 { ... }
+ sub func2 { ... }
- # this one isn't exported, but could be called!
- sub func4(\%) {} # proto'd to 1 hash ref
+ # this one isn't exported, but could be called directly
+ # as Some::Module::func3()
+ sub func3 { ... }
- END { } # module clean-up code here (global destructor)
+ END { ... } # module clean-up code here (global destructor)
- ## YOUR CODE GOES HERE
-
1; # don't forget to return a true value from the file
Then go on to declare and use your variables in functions without
@@ -476,11 +465,11 @@
This is exactly equivalent to
- BEGIN { require Module; import Module; }
+ BEGIN { require 'Module.pm'; 'Module'->import; }
or
- BEGIN { require Module; import Module LIST; }
+ BEGIN { require 'Module.pm'; 'Module'->import( LIST ); }
As a special case
@@ -488,7 +477,7 @@
is exactly equivalent to
- BEGIN { require Module; }
+ BEGIN { require 'Module.pm'; }
All Perl module files have the extension F<.pm>. The C<use> operator
assumes this so you don't have to spell out "F<Module.pm>" in quotes.
@@ -556,15 +545,14 @@
X<module, threadsafe> X<module, thread safe>
X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
-Since 5.6.0, Perl has had support for a new type of threads called
-interpreter threads (ithreads). These threads can be used explicitly
-and implicitly.
+Perl supports a type of threads called interpreter threads (ithreads).
+These threads can be used explicitly and implicitly.
Ithreads work by cloning the data tree so that no data is shared
between different threads. These threads can be used by using the C<threads>
module or by doing fork() on win32 (fake fork() support). When a
thread is cloned all Perl data is cloned, however non-Perl data cannot
-be cloned automatically. Perl after 5.7.2 has support for the C<CLONE>
+be cloned automatically. Perl after 5.8.0 has support for the C<CLONE>
special subroutine. In C<CLONE> you can do whatever
you need to do,
like for example handle the cloning of non-Perl data, if necessary.
@@ -571,7 +559,7 @@
C<CLONE> will be called once as a class method for every package that has it
defined (or inherits it). It will be called in the context of the new thread,
so all modifications are made in the new area. Currently CLONE is called with
-no parameters other than the invocand package name, but code should not assume
+no parameters other than the invocant package name, but code should not assume
that this will remain unchanged, as it is likely that in future extra parameters
will be passed in to give more information about the state of cloning.
@@ -593,7 +581,7 @@
needed.
Like C<CLONE>, C<CLONE_SKIP> is currently called with no parameters other
-than the invocand package name, although that may change. Similarly, to
+than the invocant package name, although that may change. Similarly, to
allow for future expansion, the return value should be a single C<0> or
C<1> value.
@@ -602,7 +590,7 @@
See L<perlmodlib> for general style issues related to building Perl
modules and classes, as well as descriptions of the standard library
and CPAN, L<Exporter> for how Perl's standard import/export mechanism
-works, L<perltoot> and L<perltooc> for an in-depth tutorial on
+works, L<perlootut> and L<perlobj> for in-depth information on
creating classes, L<perlobj> for a hard-core reference document on
objects, L<perlsub> for an explanation of functions and scoping,
and L<perlxstut> and L<perlguts> for more information on writing
Property changes on: trunk/contrib/perl/pod/perlmod.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlmodinstall.pod
===================================================================
--- trunk/contrib/perl/pod/perlmodinstall.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlmodinstall.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -19,7 +19,7 @@
First, are you sure that the module isn't already on your system? Try
C<perl -MFoo -e 1>. (Replace "Foo" with the name of the module; for
-instance, C<perl -MCGI::Carp -e 1>.
+instance, C<perl -MCGI::Carp -e 1>.)
If you don't see an error message, you have the module. (If you do
see an error message, it's still possible you have the module, but
@@ -53,7 +53,7 @@
install modules into any directory you wish. For instance, where I
say C<perl Makefile.PL>, you can substitute C<perl Makefile.PL
PREFIX=/my/perl_directory> to install the modules into
-C</my/perl_directory>. Then you can use the modules from your Perl
+F</my/perl_directory>. Then you can use the modules from your Perl
programs with C<use lib "/my/perl_directory/lib/site_perl";> or
sometimes just C<use "/my/perl_directory";>. If you're on a system
that requires superuser/root access to install modules into the
@@ -117,7 +117,7 @@
=item *
-B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris)>
+B<If you're running ActivePerl (Win95/98/2K/NT/XP, Linux, Solaris),>
First, type C<ppm> from a shell and see whether ActiveState's PPM
repository has your module. If so, you can install it with C<ppm> and
@@ -436,19 +436,4 @@
Copyright (C) 1998, 2002, 2003 Jon Orwant. All Rights Reserved.
-Permission is granted to make and distribute verbatim copies of this
-documentation provided the copyright notice and this permission notice are
-preserved on all copies.
-
-Permission is granted to copy and distribute modified versions of this
-documentation under the conditions for verbatim copying, provided also
-that they are marked clearly as modified versions, that the authors'
-names and title are unchanged (though subtitles and additional
-authors' names may be added), and that the entire resulting derived
-work is distributed under the terms of a permission notice identical
-to this one.
-
-Permission is granted to copy and distribute translations of this
-documentation into another language, under the above conditions for
-modified versions.
-
+This document may be distributed under the same terms as Perl itself.
Property changes on: trunk/contrib/perl/pod/perlmodinstall.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlmodlib.PL
===================================================================
--- trunk/contrib/perl/pod/perlmodlib.PL 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlmodlib.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -80,14 +80,16 @@
# Much easier to special case it like this than special case the depending on
# and parsing lib/Config.pod, or special case opening configpm and finding its
# =head1 (which is not found with the $/="" above)
-push @mod, <<'CONFIG';
-=item Config
+push @mod, "=item Config\n\nAccess Perl configuration information\n\n";
-Access Perl configuration information
-CONFIG
+# The intent of using =cut as the heredoc terminator is to make the whole file
+# parse as (reasonably) sane Pod as-is to anything that attempts to
+# brute-force treat it as such. The content is already useful - this just
+# makes it tidier, by stopping anything doing this mistaking the rest of the
+# Perl code for Pod. eg http://search.cpan.org/dist/perl/pod/perlmodlib.PL
-print OUT <<'EOF';
+print OUT <<'=cut';
=for maintainers
Generated by perlmodlib.PL -- DO NOT EDIT!
@@ -137,11 +139,12 @@
=over 12
-EOF
+=cut
print OUT $_ for (sort @pragma);
-print OUT <<EOF;
+print OUT <<'=cut';
+
=back
=head2 Standard Modules
@@ -156,11 +159,12 @@
=over 12
-EOF
+=cut
print OUT $_ for (sort @mod);
-print OUT <<'EOF';
+print OUT <<'=cut';
+
=back
To find out I<all> modules installed on your system, including
@@ -318,6 +322,9 @@
Registered CPAN sites
+=for maintainers
+Generated by Porting/make_modlib_cpan.pl
+
=head2 Africa
=over 4
@@ -324,11 +331,11 @@
=item South Africa
- http://cpan.mirror.ac.za/
- ftp://cpan.mirror.ac.za/
- http://mirror.is.co.za/pub/cpan/
- ftp://ftp.is.co.za/pub/cpan/
- ftp://ftp.saix.net/pub/CPAN/
+ http://cpan.mirror.ac.za/
+ ftp://cpan.mirror.ac.za/
+ http://mirror.is.co.za/pub/cpan/
+ ftp://ftp.is.co.za/pub/cpan/
+ ftp://ftp.saix.net/pub/CPAN/
=back
@@ -336,98 +343,93 @@
=over 4
+=item China
+
+ http://cpan.wenzk.com/
+
=item Hong Kong
- http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
- ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
- http://mirrors.geoexpat.com/cpan/
+ http://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
+ ftp://ftp.cuhk.edu.hk/pub/packages/perl/CPAN/
+ http://mirrors.geoexpat.com/cpan/
=item India
- http://perlmirror.indialinks.com/
+ http://perlmirror.indialinks.com/
=item Indonesia
- http://cpan.biz.net.id/
- http://komo.vlsm.org/CPAN/
- ftp://komo.vlsm.org/CPAN/
- http://cpan.pesat.net.id/
- http://mirror.unej.ac.id/cpan/
- ftp://mirror.unej.ac.id/cpan/
+ http://cpan.biz.net.id/
+ http://komo.vlsm.org/CPAN/
+ ftp://komo.vlsm.org/CPAN/
+ http://cpan.cermin.lipi.go.id/
+ ftp://cermin.lipi.go.id/pub/CPAN/
+ http://cpan.pesat.net.id/
=item Japan
- ftp://ftp.u-aizu.ac.jp/pub/CPAN
- ftp://ftp.kddilabs.jp/CPAN/
- http://ftp.nara.wide.ad.jp/pub/CPAN/
- ftp://ftp.nara.wide.ad.jp/pub/CPAN/
- http://ftp.jaist.ac.jp/pub/CPAN/
- ftp://ftp.jaist.ac.jp/pub/CPAN/
- ftp://ftp.dti.ad.jp/pub/lang/CPAN/
- ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
- http://ftp.riken.jp/lang/CPAN/
- ftp://ftp.riken.jp/lang/CPAN/
- http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
- ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
+ ftp://ftp.u-aizu.ac.jp/pub/CPAN
+ ftp://ftp.kddilabs.jp/CPAN/
+ http://ftp.nara.wide.ad.jp/pub/CPAN/
+ ftp://ftp.nara.wide.ad.jp/pub/CPAN/
+ http://ftp.jaist.ac.jp/pub/CPAN/
+ ftp://ftp.jaist.ac.jp/pub/CPAN/
+ ftp://ftp.dti.ad.jp/pub/lang/CPAN/
+ ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
+ http://ftp.riken.jp/lang/CPAN/
+ ftp://ftp.riken.jp/lang/CPAN/
+ http://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
+ ftp://ftp.yz.yamagata-u.ac.jp/pub/lang/cpan/
-=item Kazakhstan
-
- http://mirror.linuxiso.kz/CPAN/
-
=item Republic of Korea
- http://ftp.kaist.ac.kr/pub/CPAN
- ftp://ftp.kaist.ac.kr/pub/CPAN
- http://cpan.mirror.cdnetworks.com/
- ftp://cpan.mirror.cdnetworks.com/CPAN/
- http://cpan.sarang.net/
- ftp://cpan.sarang.net/CPAN/
+ http://ftp.kaist.ac.kr/pub/CPAN
+ ftp://ftp.kaist.ac.kr/pub/CPAN
+ http://cpan.mirror.cdnetworks.com/
+ ftp://cpan.mirror.cdnetworks.com/CPAN/
+ http://cpan.sarang.net/
+ ftp://cpan.sarang.net/CPAN/
=item Russia
- http://cpan.tomsk.ru/
- ftp://cpan.tomsk.ru/
+ http://cpan.tomsk.ru/
+ ftp://cpan.tomsk.ru/
=item Singapore
- http://mirror.averse.net/pub/CPAN
- ftp://mirror.averse.net/pub/CPAN
- http://cpan.mirror.choon.net/
- http://cpan.oss.eznetsols.org
- ftp://ftp.oss.eznetsols.org/cpan
+ http://mirror.averse.net/pub/CPAN
+ ftp://mirror.averse.net/pub/CPAN
+ http://cpan.mirror.choon.net/
+ http://cpan.oss.eznetsols.org
+ ftp://ftp.oss.eznetsols.org/cpan
=item Taiwan
- http://ftp.cse.yzu.edu.tw/pub/CPAN/
- ftp://ftp.cse.yzu.edu.tw/pub/CPAN/
- http://cpan.nctu.edu.tw/
- ftp://cpan.nctu.edu.tw/
- ftp://ftp.ncu.edu.tw/CPAN/
- http://cpan.cdpa.nsysu.edu.tw/
- ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
- http://cpan.stu.edu.tw
- ftp://ftp.stu.edu.tw/CPAN
- http://ftp.stu.edu.tw/CPAN
- ftp://ftp.stu.edu.tw/pub/CPAN
- http://cpan.cs.pu.edu.tw/
- ftp://cpan.cs.pu.edu.tw/pub/CPAN
+ http://ftp.cse.yzu.edu.tw/pub/CPAN/
+ ftp://ftp.cse.yzu.edu.tw/pub/CPAN/
+ http://cpan.nctu.edu.tw/
+ ftp://cpan.nctu.edu.tw/
+ ftp://ftp.ncu.edu.tw/CPAN/
+ http://cpan.cdpa.nsysu.edu.tw/
+ ftp://cpan.cdpa.nsysu.edu.tw/Unix/Lang/CPAN/
+ http://cpan.stu.edu.tw
+ ftp://ftp.stu.edu.tw/CPAN
+ http://ftp.stu.edu.tw/CPAN
+ ftp://ftp.stu.edu.tw/pub/CPAN
+ http://cpan.cs.pu.edu.tw/
+ ftp://cpan.cs.pu.edu.tw/pub/CPAN
=item Thailand
- http://mirrors.issp.co.th/cpan/
- ftp://mirrors.issp.co.th/cpan/
+ http://mirrors.issp.co.th/cpan/
+ ftp://mirrors.issp.co.th/cpan/
+ http://mirror.yourconnect.com/CPAN/
+ ftp://mirror.yourconnect.com/CPAN/
=item Turkey
- http://cpan.gazi.edu.tr/
- http://cpan.ulak.net.tr
- ftp://ftp.ulak.net.tr/pub/CPAN
+ http://cpan.gazi.edu.tr/
-=item Viet Nam
-
- http://mirror-fpt-telecom.fpt.net/cpan/
- ftp://mirror-fpt-telecom.fpt.net/cpan/
-
=back
=head2 Central America
@@ -436,8 +438,8 @@
=item Costa Rica
- http://mirrors.ucr.ac.cr/CPAN/
- ftp://mirrors.ucr.ac.cr/CPAN/
+ http://mirrors.ucr.ac.cr/CPAN/
+ ftp://mirrors.ucr.ac.cr/CPAN/
=back
@@ -447,284 +449,274 @@
=item Austria
- http://cpan.inode.at/
- ftp://cpan.inode.at
- http://gd.tuwien.ac.at/languages/perl/CPAN/
- ftp://gd.tuwien.ac.at/pub/CPAN/
+ http://cpan.inode.at/
+ ftp://cpan.inode.at
+ http://gd.tuwien.ac.at/languages/perl/CPAN/
+ ftp://gd.tuwien.ac.at/pub/CPAN/
=item Belgium
- http://ftp.belnet.be/mirror/ftp.cpan.org/
- ftp://ftp.belnet.be/mirror/ftp.cpan.org/
- http://ftp.easynet.be/pub/CPAN/
- http://cpan.weepee.org/
- http://cpan.fluoline.net/
+ http://ftp.belnet.be/mirror/ftp.cpan.org/
+ ftp://ftp.belnet.be/mirror/ftp.cpan.org/
+ http://ftp.easynet.be/pub/CPAN/
+ http://cpan.weepee.org/
=item Bosnia and Herzegovina
- http://cpan.blic.net/
+ http://cpan.blic.net/
=item Bulgaria
- http://cpan.cbox.biz/
- ftp://cpan.cbox.biz/cpan/
- http://cpan.digsys.bg/
- ftp://ftp.digsys.bg/pub/CPAN
+ http://cpan.cbox.biz/
+ ftp://cpan.cbox.biz/cpan/
+ http://cpan.digsys.bg/
+ ftp://ftp.digsys.bg/pub/CPAN
=item Croatia
- http://ftp.carnet.hr/pub/CPAN/
- ftp://ftp.carnet.hr/pub/CPAN/
+ http://ftp.carnet.hr/pub/CPAN/
+ ftp://ftp.carnet.hr/pub/CPAN/
=item Czech Republic
- ftp://ftp.fi.muni.cz/pub/CPAN/
- http://archive.cpan.cz/
+ ftp://ftp.fi.muni.cz/pub/CPAN/
+ http://archive.cpan.cz/
=item Denmark
- http://mirrors.dotsrc.org/cpan
- ftp://mirrors.dotsrc.org/cpan/
- http://www.cpan.dk/
- http://mirror.uni-c.dk/pub/CPAN/
+ http://mirrors.dotsrc.org/cpan
+ ftp://mirrors.dotsrc.org/cpan/
+ http://www.cpan.dk/
+ http://mirror.uni-c.dk/pub/CPAN/
=item Finland
- ftp://ftp.funet.fi/pub/languages/perl/CPAN/
- http://mirror.eunet.fi/CPAN
+ ftp://ftp.funet.fi/pub/languages/perl/CPAN/
+ http://mirror.eunet.fi/CPAN
=item France
- http://cpan.enstimac.fr/
- ftp://ftp.inria.fr/pub/CPAN/
- http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
- ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
- ftp://ftp.lip6.fr/pub/perl/CPAN/
- http://mir2.ovh.net/ftp.cpan.org
- ftp://mir1.ovh.net/ftp.cpan.org
- http://cpan.miroir-francais.fr/
- ftp://miroir-francais.fr/pub/cpan/
- ftp://ftp.oleane.net/pub/CPAN/
- http://ftp.crihan.fr/mirrors/ftp.cpan.org/
- ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
- http://ftp.u-strasbg.fr/CPAN
- ftp://ftp.u-strasbg.fr/CPAN
- http://cpan.cict.fr/
- ftp://cpan.cict.fr/pub/CPAN/
+ http://cpan.enstimac.fr/
+ ftp://ftp.inria.fr/pub/CPAN/
+ http://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
+ ftp://distrib-coffee.ipsl.jussieu.fr/pub/mirrors/cpan/
+ ftp://ftp.lip6.fr/pub/perl/CPAN/
+ http://mir2.ovh.net/ftp.cpan.org
+ ftp://mir1.ovh.net/ftp.cpan.org
+ ftp://ftp.oleane.net/pub/CPAN/
+ http://ftp.crihan.fr/mirrors/ftp.cpan.org/
+ ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
+ http://ftp.u-strasbg.fr/CPAN
+ ftp://ftp.u-strasbg.fr/CPAN
+ http://cpan.cict.fr/
+ ftp://cpan.cict.fr/pub/CPAN/
=item Germany
- ftp://ftp.fu-berlin.de/unix/languages/perl/
- http://mirrors.softliste.de/cpan/
- ftp://ftp.rub.de/pub/CPAN/
- http://www.planet-elektronik.de/CPAN/
- http://ftp.hosteurope.de/pub/CPAN/
- ftp://ftp.hosteurope.de/pub/CPAN/
- http://www.mirrorspace.org/cpan/
- http://mirror.netcologne.de/cpan/
- ftp://mirror.netcologne.de/cpan/
- ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
- http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
- ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
- http://mirrors.zerg.biz/cpan/
- http://ftp.gwdg.de/pub/languages/perl/CPAN/
- ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
- http://dl.ambiweb.de/mirrors/ftp.cpan.org/
- http://cpan.mirror.clusters.kg/
- http://cpan.mirror.iphh.net/
- ftp://cpan.mirror.iphh.net/pub/CPAN/
- http://cpan.mirroring.de/
- http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
- ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
- http://ftp.cw.net/pub/CPAN/
- ftp://ftp.cw.net/pub/CPAN/
- http://cpan.cpantesters.org/
- ftp://cpan.cpantesters.org/CPAN/
- http://cpan.mirrored.de/
- ftp://mirror.petamem.com/CPAN/
- http://cpan.noris.de/
- ftp://cpan.noris.de/pub/CPAN/
- ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
- ftp://ftp.gmd.de/mirrors/CPAN/
+ ftp://ftp.fu-berlin.de/unix/languages/perl/
+ http://mirrors.softliste.de/cpan/
+ ftp://ftp.rub.de/pub/CPAN/
+ http://www.planet-elektronik.de/CPAN/
+ http://ftp.hosteurope.de/pub/CPAN/
+ ftp://ftp.hosteurope.de/pub/CPAN/
+ http://www.mirrorspace.org/cpan/
+ http://mirror.netcologne.de/cpan/
+ ftp://mirror.netcologne.de/cpan/
+ ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
+ http://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
+ ftp://ftp-stud.hs-esslingen.de/pub/Mirrors/CPAN/
+ http://mirrors.zerg.biz/cpan/
+ http://ftp.gwdg.de/pub/languages/perl/CPAN/
+ ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
+ http://dl.ambiweb.de/mirrors/ftp.cpan.org/
+ http://cpan.mirror.clusters.kg/
+ http://cpan.mirror.iphh.net/
+ ftp://cpan.mirror.iphh.net/pub/CPAN/
+ http://cpan.mirroring.de/
+ http://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
+ ftp://mirror.informatik.uni-mannheim.de/pub/mirrors/CPAN/
+ http://www.chemmedia.de/mirrors/CPAN/
+ http://ftp.cw.net/pub/CPAN/
+ ftp://ftp.cw.net/pub/CPAN/
+ http://cpan.cpantesters.org/
+ ftp://cpan.cpantesters.org/CPAN/
+ http://cpan.mirrored.de/
+ ftp://mirror.petamem.com/CPAN/
+ http://cpan.noris.de/
+ ftp://cpan.noris.de/pub/CPAN/
+ ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
+ ftp://ftp.gmd.de/mirrors/CPAN/
=item Greece
- ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
- ftp://ftp.ntua.gr/pub/lang/perl/
- http://cpan.cc.uoc.gr/
- ftp://ftp.cc.uoc.gr/mirrors/CPAN/
+ ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
+ ftp://ftp.ntua.gr/pub/lang/perl/
+ http://cpan.cc.uoc.gr/
+ ftp://ftp.cc.uoc.gr/mirrors/CPAN/
=item Hungary
- http://cpan.mirrors.enexis.hu/
- ftp://cpan.mirrors.enexis.hu/mirrors/cpan/
- http://cpan.hu/
+ http://cpan.mirrors.enexis.hu/
+ ftp://cpan.mirrors.enexis.hu/mirrors/cpan/
+ http://cpan.hu/
=item Iceland
- http://ftp.rhnet.is/pub/CPAN/
- ftp://ftp.rhnet.is/pub/CPAN/
+ http://ftp.rhnet.is/pub/CPAN/
+ ftp://ftp.rhnet.is/pub/CPAN/
=item Ireland
- http://ftp.esat.net/pub/languages/perl/CPAN/
- ftp://ftp.esat.net/pub/languages/perl/CPAN/
- http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
- ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
+ http://ftp.esat.net/pub/languages/perl/CPAN/
+ ftp://ftp.esat.net/pub/languages/perl/CPAN/
+ http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
+ ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
=item Italy
- http://bo.mirror.garr.it/mirrors/CPAN/
- http://cpan.panu.it/
- ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
- http://cpan.fastbull.org/
+ http://bo.mirror.garr.it/mirrors/CPAN/
+ http://cpan.panu.it/
+ ftp://ftp.panu.it/pub/mirrors/perl/CPAN/
=item Latvia
- http://kvin.lv/pub/CPAN/
+ http://kvin.lv/pub/CPAN/
=item Lithuania
- http://ftp.litnet.lt/pub/CPAN/
- ftp://ftp.litnet.lt/pub/CPAN/
+ http://ftp.litnet.lt/pub/CPAN/
+ ftp://ftp.litnet.lt/pub/CPAN/
=item Malta
- http://cpan.waldonet.net.mt/
+ http://cpan.waldonet.net.mt/
=item Netherlands
- ftp://ftp.quicknet.nl/pub/CPAN/
- http://mirror.hostfuss.com/CPAN/
- ftp://mirror.hostfuss.com/CPAN/
- http://mirrors3.kernel.org/cpan/
- ftp://mirrors3.kernel.org/pub/CPAN/
- http://cpan.osmirror.nl/
- ftp://ftp.osmirror.nl/pub/cpan/
- http://cpan.mirror.versatel.nl/
- ftp://ftp.mirror.versatel.nl/cpan/
- ftp://download.xs4all.nl/pub/mirror/CPAN/
- http://mirror.leaseweb.com/CPAN/
- ftp://mirror.leaseweb.com/CPAN/
- ftp://ftp.cpan.nl/pub/CPAN/
- http://archive.cs.uu.nl/mirror/CPAN/
- ftp://ftp.cs.uu.nl/mirror/CPAN/
- http://https://luxitude.net/cpan/
+ ftp://ftp.quicknet.nl/pub/CPAN/
+ http://mirror.hostfuss.com/CPAN/
+ ftp://mirror.hostfuss.com/CPAN/
+ http://mirrors3.kernel.org/cpan/
+ ftp://mirrors3.kernel.org/pub/CPAN/
+ http://cpan.mirror.versatel.nl/
+ ftp://ftp.mirror.versatel.nl/cpan/
+ ftp://download.xs4all.nl/pub/mirror/CPAN/
+ http://mirror.leaseweb.com/CPAN/
+ ftp://mirror.leaseweb.com/CPAN/
+ ftp://ftp.cpan.nl/pub/CPAN/
+ http://archive.cs.uu.nl/mirror/CPAN/
+ ftp://ftp.cs.uu.nl/mirror/CPAN/
+ http://luxitude.net/cpan/
=item Norway
- ftp://ftp.uninett.no/pub/languages/perl/CPAN
- ftp://ftp.uit.no/pub/languages/perl/cpan/
+ ftp://ftp.uninett.no/pub/languages/perl/CPAN
+ ftp://ftp.uit.no/pub/languages/perl/cpan/
=item Poland
- http://mirror.icis.pcz.pl/CPAN/
- ftp://mirror.icis.pcz.pl/CPAN/
- http://piotrkosoft.net/pub/mirrors/CPAN/
- ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
- http://ftp.man.poznan.pl/pub/CPAN
- ftp://ftp.man.poznan.pl/pub/CPAN
- ftp://sunsite.icm.edu.pl/pub/CPAN/
- ftp://ftp.tpnet.pl/d4/CPAN/
+ http://piotrkosoft.net/pub/mirrors/CPAN/
+ ftp://ftp.piotrkosoft.net/pub/mirrors/CPAN/
+ http://ftp.man.poznan.pl/pub/CPAN
+ ftp://ftp.man.poznan.pl/pub/CPAN
+ ftp://ftp.ps.pl/pub/CPAN/
+ ftp://sunsite.icm.edu.pl/pub/CPAN/
+ ftp://ftp.tpnet.pl/d4/CPAN/
=item Portugal
- http://cpan.dei.uc.pt/
- ftp://ftp.dei.uc.pt/pub/CPAN
- ftp://ftp.ist.utl.pt/pub/CPAN/
- http://cpan.perl.pt/
- http://cpan.ip.pt/
- ftp://cpan.ip.pt/pub/cpan/
- http://mirrors.nfsi.pt/CPAN/
- ftp://mirrors.nfsi.pt/pub/CPAN/
- http://cpan.dcc.fc.up.pt/
+ http://cpan.dei.uc.pt/
+ ftp://ftp.dei.uc.pt/pub/CPAN
+ ftp://ftp.ist.utl.pt/pub/CPAN/
+ http://cpan.perl.pt/
+ http://cpan.ip.pt/
+ ftp://cpan.ip.pt/pub/cpan/
+ http://mirrors.nfsi.pt/CPAN/
+ ftp://mirrors.nfsi.pt/pub/CPAN/
+ http://cpan.dcc.fc.up.pt/
=item Romania
- http://ftp.astral.ro/pub/CPAN/
- ftp://ftp.astral.ro/pub/CPAN/
- ftp://ftp.lug.ro/CPAN
- http://mirrors.xservers.ro/CPAN/
- http://mirrors.hostingromania.ro/ftp.cpan.org/
- ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/
- ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
- ftp://ftp.ambra.ro/pub/CPAN
+ http://ftp.astral.ro/pub/CPAN/
+ ftp://ftp.astral.ro/pub/CPAN/
+ ftp://ftp.lug.ro/CPAN
+ http://mirrors.xservers.ro/CPAN/
+ http://mirrors.hostingromania.ro/ftp.cpan.org/
+ ftp://ftp.hostingromania.ro/mirrors/ftp.cpan.org/
+ ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
=item Russia
- ftp://ftp.aha.ru/CPAN/
- http://cpan.rinet.ru/
- ftp://cpan.rinet.ru/pub/mirror/CPAN/
- ftp://ftp.SpringDaemons.com/pub/CPAN/
- http://cpan.nx1.ru/
- ftp://cpan.nx1.ru/
- http://mirror.rol.ru/CPAN/
- http://ftp.silvernet.ru/CPAN/
- http://ftp.spbu.ru/CPAN/
- ftp://ftp.spbu.ru/CPAN/
+ ftp://ftp.aha.ru/CPAN/
+ http://cpan.rinet.ru/
+ ftp://cpan.rinet.ru/pub/mirror/CPAN/
+ ftp://ftp.SpringDaemons.com/pub/CPAN/
+ http://mirror.rol.ru/CPAN/
+ http://ftp.silvernet.ru/CPAN/
+ http://ftp.spbu.ru/CPAN/
+ ftp://ftp.spbu.ru/CPAN/
=item Slovakia
- http://cpan.fyxm.net/
+ http://cpan.fyxm.net/
=item Slovenia
- http://www.klevze.si/cpan
+ http://www.klevze.si/cpan
=item Spain
- http://osl.ugr.es/CPAN/
- ftp://ftp.rediris.es/mirror/CPAN/
- http://ftp.gui.uva.es/sites/cpan.org/
- ftp://ftp.gui.uva.es/sites/cpan.org/
+ http://osl.ugr.es/CPAN/
+ ftp://ftp.rediris.es/mirror/CPAN/
+ http://ftp.gui.uva.es/sites/cpan.org/
+ ftp://ftp.gui.uva.es/sites/cpan.org/
=item Sweden
- http://mirrors4.kernel.org/cpan/
- ftp://mirrors4.kernel.org/pub/CPAN/
+ http://mirrors4.kernel.org/cpan/
+ ftp://mirrors4.kernel.org/pub/CPAN/
=item Switzerland
- http://cpan.mirror.solnet.ch/
- ftp://ftp.solnet.ch/mirror/CPAN/
- http://mirror.switch.ch/ftp/mirror/CPAN/
- ftp://mirror.switch.ch/mirror/CPAN/
+ http://cpan.mirror.solnet.ch/
+ ftp://ftp.solnet.ch/mirror/CPAN/
+ ftp://ftp.adwired.ch/CPAN/
+ http://mirror.switch.ch/ftp/mirror/CPAN/
+ ftp://mirror.switch.ch/mirror/CPAN/
=item Ukraine
- http://cpan.makeperl.org/
- ftp://cpan.makeperl.org/pub/CPAN
- http://cpan.org.ua/
- http://no-more.kiev.ua/CPAN/
- ftp://no-more.kiev.ua/pub/CPAN/
- http://cpan.gafol.net/
- ftp://ftp.gafol.net/pub/cpan/
+ http://cpan.makeperl.org/
+ ftp://cpan.makeperl.org/pub/CPAN
+ http://cpan.org.ua/
+ http://cpan.gafol.net/
+ ftp://ftp.gafol.net/pub/cpan/
=item United Kingdom
- http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
- ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
- http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
- ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
- http://www.mirror.8086.net/sites/CPAN/
- ftp://ftp.mirror.8086.net/sites/CPAN/
- http://cpan.mirror.anlx.net/
- ftp://ftp.mirror.anlx.net/CPAN/
- http://mirror.bytemark.co.uk/CPAN/
- ftp://mirror.bytemark.co.uk/CPAN/
- http://cpan.etla.org/
- ftp://cpan.etla.org/pub/CPAN
- ftp://ftp.demon.co.uk/pub/CPAN/
- http://mirror.sov.uk.goscomb.net/CPAN/
- ftp://mirror.sov.uk.goscomb.net/pub/CPAN/
- http://ftp.plig.net/pub/CPAN/
- ftp://ftp.plig.net/pub/CPAN/
- http://ftp.ticklers.org/pub/CPAN/
- ftp://ftp.ticklers.org/pub/CPAN/
- http://cpan.mirrors.uk2.net/
- ftp://mirrors.uk2.net/pub/CPAN/
- http://mirror.ox.ac.uk/sites/www.cpan.org/
- ftp://mirror.ox.ac.uk/sites/www.cpan.org/
+ http://www.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
+ ftp://ftp.mirrorservice.org/sites/ftp.funet.fi/pub/languages/perl/CPAN/
+ http://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
+ ftp://mirror.tje.me.uk/pub/mirrors/ftp.cpan.org/
+ http://www.mirror.8086.net/sites/CPAN/
+ ftp://ftp.mirror.8086.net/sites/CPAN/
+ http://cpan.mirror.anlx.net/
+ ftp://ftp.mirror.anlx.net/CPAN/
+ http://mirror.bytemark.co.uk/CPAN/
+ ftp://mirror.bytemark.co.uk/CPAN/
+ http://cpan.etla.org/
+ ftp://cpan.etla.org/pub/CPAN
+ ftp://ftp.demon.co.uk/pub/CPAN/
+ http://mirror.sov.uk.goscomb.net/CPAN/
+ ftp://mirror.sov.uk.goscomb.net/pub/CPAN/
+ http://ftp.plig.net/pub/CPAN/
+ ftp://ftp.plig.net/pub/CPAN/
+ http://ftp.ticklers.org/pub/CPAN/
+ ftp://ftp.ticklers.org/pub/CPAN/
+ http://cpan.mirrors.uk2.net/
+ ftp://mirrors.uk2.net/pub/CPAN/
+ http://mirror.ox.ac.uk/sites/www.cpan.org/
+ ftp://mirror.ox.ac.uk/sites/www.cpan.org/
=back
@@ -734,30 +726,28 @@
=item Bahamas
- http://www.securehost.com/mirror/CPAN/
+ http://www.securehost.com/mirror/CPAN/
=item Canada
- http://cpan.justanotherperlhacker.com/pub/CPAN/
- ftp://cpan.justanotherperlhacker.com/pub/CPAN/
- http://cpan.arcticnetwork.ca
- ftp://mirror.arcticnetwork.ca/pub/CPAN
- http://cpan.sunsite.ualberta.ca/
- ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
- http://theoryx5.uwinnipeg.ca/pub/CPAN/
- ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
- http://arwen.cs.dal.ca/mirror/CPAN/
- ftp://arwen.cs.dal.ca/pub/mirror/CPAN/
- http://CPAN.mirror.rafal.ca/
- ftp://CPAN.mirror.rafal.ca/pub/CPAN/
- ftp://ftp.nrc.ca/pub/CPAN/
- http://mirror.csclub.uwaterloo.ca/pub/CPAN/
- ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/
+ http://cpan.arcticnetwork.ca
+ ftp://mirror.arcticnetwork.ca/pub/CPAN
+ http://cpan.sunsite.ualberta.ca/
+ ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
+ http://theoryx5.uwinnipeg.ca/pub/CPAN/
+ ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
+ http://arwen.cs.dal.ca/mirror/CPAN/
+ ftp://arwen.cs.dal.ca/pub/mirror/CPAN/
+ http://CPAN.mirror.rafal.ca/
+ ftp://CPAN.mirror.rafal.ca/pub/CPAN/
+ ftp://ftp.nrc.ca/pub/CPAN/
+ http://mirror.csclub.uwaterloo.ca/pub/CPAN/
+ ftp://mirror.csclub.uwaterloo.ca/pub/CPAN/
=item Mexico
- http://www.msg.com.mx/CPAN/
- ftp://ftp.msg.com.mx/pub/CPAN/
+ http://www.msg.com.mx/CPAN/
+ ftp://ftp.msg.com.mx/pub/CPAN/
=item United States
@@ -765,150 +755,145 @@
=item Alabama
- http://mirror.hiwaay.net/CPAN/
- ftp://mirror.hiwaay.net/CPAN/
+ http://mirror.hiwaay.net/CPAN/
+ ftp://mirror.hiwaay.net/CPAN/
+=item Arizona
+
+ http://cpan.ezarticleinformation.com/
+
=item California
- http://cpan.knowledgematters.net/
- http://cpan.binkerton.com/
- http://cpan.develooper.com/
- http://mirrors.gossamer-threads.com/CPAN
- http://cpan.schatt.com/
- http://mirrors.kernel.org/cpan/
- ftp://mirrors.kernel.org/pub/CPAN
- http://mirrors2.kernel.org/cpan/
- ftp://mirrors2.kernel.org/pub/CPAN/
- http://cpan.mirrors.redwire.net/
- http://cpan.mirror.facebook.net/
- http://mirrors1.kernel.org/cpan/
- ftp://mirrors1.kernel.org/pub/CPAN/
- http://cpan-sj.viaverio.com/
- ftp://cpan-sj.viaverio.com/pub/CPAN/
- http://www.perl.com/CPAN/
- http://cpan.yahoo.com/
+ http://cpan.knowledgematters.net/
+ http://cpan.binkerton.com/
+ http://cpan.develooper.com/
+ http://mirrors.gossamer-threads.com/CPAN
+ http://cpan.schatt.com/
+ http://mirrors.kernel.org/cpan/
+ ftp://mirrors.kernel.org/pub/CPAN
+ http://mirrors2.kernel.org/cpan/
+ ftp://mirrors2.kernel.org/pub/CPAN/
+ http://cpan.mirror.facebook.net/
+ http://mirrors1.kernel.org/cpan/
+ ftp://mirrors1.kernel.org/pub/CPAN/
+ http://cpan-sj.viaverio.com/
+ ftp://cpan-sj.viaverio.com/pub/CPAN/
+ http://www.perl.com/CPAN/
=item Florida
- ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
- http://mirror.atlantic.net/pub/CPAN/
- ftp://mirror.atlantic.net/pub/CPAN/
- http://mirror.candidhosting.com/pub/CPAN
- ftp://mirror.candidhosting.com/pub/CPAN
+ ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
+ http://mirror.atlantic.net/pub/CPAN/
+ ftp://mirror.atlantic.net/pub/CPAN/
=item Idaho
- http://mirror.its.uidaho.edu/pub/cpan/
- ftp://mirror.its.uidaho.edu/cpan/
+ http://mirror.its.uidaho.edu/pub/cpan/
+ ftp://mirror.its.uidaho.edu/cpan/
=item Illinois
- http://cpan.mirrors.hoobly.com/
- http://cpan.uchicago.edu/pub/CPAN/
- ftp://cpan.uchicago.edu/pub/CPAN/
- http://mirrors.servercentral.net/CPAN/
- http://www.stathy.com/CPAN/
- ftp://www.stathy.com/CPAN/
+ http://cpan.mirrors.hoobly.com/
+ http://cpan.uchicago.edu/pub/CPAN/
+ ftp://cpan.uchicago.edu/pub/CPAN/
+ http://mirrors.servercentral.net/CPAN/
+ http://www.stathy.com/CPAN/
+ ftp://www.stathy.com/CPAN/
=item Indiana
- ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
- http://cpan.netnitco.net/
- ftp://cpan.netnitco.net/pub/mirrors/CPAN/
- http://ftp.ndlug.nd.edu/pub/perl/
- ftp://ftp.ndlug.nd.edu/pub/perl/
- http://fx.saintjoe.edu/pub/CPAN
+ ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
+ http://cpan.netnitco.net/
+ ftp://cpan.netnitco.net/pub/mirrors/CPAN/
+ http://ftp.ndlug.nd.edu/pub/perl/
+ ftp://ftp.ndlug.nd.edu/pub/perl/
=item Massachusetts
- ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
+ http://mirrors.ccs.neu.edu/CPAN/
=item Michigan
- http://ftp.wayne.edu/cpan/
- ftp://ftp.wayne.edu/cpan/
+ http://ftp.wayne.edu/cpan/
+ ftp://ftp.wayne.edu/cpan/
=item Minnesota
- http://cpan.msi.umn.edu/
+ http://cpan.msi.umn.edu/
=item New Jersey
- http://mirror.datapipe.net/CPAN/
- ftp://mirror.datapipe.net/pub/CPAN/
+ http://mirror.datapipe.net/CPAN/
+ ftp://mirror.datapipe.net/pub/CPAN/
=item New York
- http://mirrors.24-7-solutions.net/pub/CPAN/
- ftp://mirrors.24-7-solutions.net/pub/CPAN/
- http://mirror.cc.columbia.edu/pub/software/cpan/
- ftp://mirror.cc.columbia.edu/pub/software/cpan/
- http://cpan.belfry.net/
- http://cpan.erlbaum.net/
- ftp://cpan.erlbaum.net/CPAN/
- http://cpan.hexten.net/
- ftp://cpan.hexten.net/
- http://ftp.fxcorporate.com/CPAN/
- ftp://ftp.fxcorporate.com/pub/CPAN/
- ftp://mirror.nyi.net/CPAN/
- http://mirror.rit.edu/CPAN/
- ftp://mirror.rit.edu/CPAN/
+ http://mirrors.24-7-solutions.net/pub/CPAN/
+ ftp://mirrors.24-7-solutions.net/pub/CPAN/
+ http://mirror.cc.columbia.edu/pub/software/cpan/
+ ftp://mirror.cc.columbia.edu/pub/software/cpan/
+ http://cpan.belfry.net/
+ http://cpan.erlbaum.net/
+ ftp://cpan.erlbaum.net/CPAN/
+ http://cpan.hexten.net/
+ ftp://cpan.hexten.net/
+ ftp://mirror.nyi.net/CPAN/
+ http://mirror.rit.edu/CPAN/
+ ftp://mirror.rit.edu/CPAN/
=item North Carolina
- http://www.ibiblio.org/pub/mirrors/CPAN
- ftp://ftp.ncsu.edu/pub/mirror/CPAN/
+ http://www.ibiblio.org/pub/mirrors/CPAN
+ ftp://ftp.ncsu.edu/pub/mirror/CPAN/
=item Oregon
- http://ftp.osuosl.org/pub/CPAN/
- ftp://ftp.osuosl.org/pub/CPAN/
+ http://ftp.osuosl.org/pub/CPAN/
+ ftp://ftp.osuosl.org/pub/CPAN/
=item Pennsylvania
- http://ftp.epix.net/CPAN/
- ftp://ftp.epix.net/pub/languages/perl/
- http://cpan.pair.com/
- ftp://cpan.pair.com/pub/CPAN/
+ http://ftp.epix.net/CPAN/
+ ftp://ftp.epix.net/pub/languages/perl/
+ http://cpan.pair.com/
+ ftp://cpan.pair.com/pub/CPAN/
=item South Carolina
- http://cpan.mirror.clemson.edu/
+ http://cpan.mirror.clemson.edu/
=item Tennessee
- http://mira.sunsite.utk.edu/CPAN/
+ http://mira.sunsite.utk.edu/CPAN/
=item Texas
- http://mirror.uta.edu/CPAN
+ http://mirror.uta.edu/CPAN
=item Utah
- http://cpan.cs.utah.edu
- ftp://cpan.cs.utah.edu/pub/CPAN/
- ftp://mirror.xmission.com/CPAN/
+ ftp://mirror.xmission.com/CPAN/
=item Virginia
- http://cpan-du.viaverio.com/
- ftp://cpan-du.viaverio.com/pub/CPAN/
- http://perl.secsup.org/
- ftp://perl.secsup.org/pub/perl/
- ftp://mirror.cogentco.com/pub/CPAN/
+ http://cpan-du.viaverio.com/
+ ftp://cpan-du.viaverio.com/pub/CPAN/
+ http://perl.secsup.org/
+ ftp://perl.secsup.org/pub/perl/
+ ftp://mirror.cogentco.com/pub/CPAN/
=item Washington
- http://cpan.llarian.net/
- ftp://cpan.llarian.net/pub/CPAN/
- ftp://ftp-mirror.internap.com/pub/CPAN/
+ http://cpan.llarian.net/
+ ftp://cpan.llarian.net/pub/CPAN/
+ ftp://ftp-mirror.internap.com/pub/CPAN/
=item Wisconsin
- http://cpan.mirrors.tds.net
- ftp://cpan.mirrors.tds.net/pub/CPAN
- http://mirror.sit.wisc.edu/pub/CPAN/
- ftp://mirror.sit.wisc.edu/pub/CPAN/
+ http://cpan.mirrors.tds.net
+ ftp://cpan.mirrors.tds.net/pub/CPAN
+ http://mirror.sit.wisc.edu/pub/CPAN/
+ ftp://mirror.sit.wisc.edu/pub/CPAN/
=back
@@ -920,19 +905,19 @@
=item Australia
- http://mirror.internode.on.net/pub/cpan/
- ftp://mirror.internode.on.net/pub/cpan/
- http://cpan.mirror.aussiehq.net.au/
- http://mirror.as24220.net/cpan/
- ftp://mirror.as24220.net/cpan/
+ http://mirror.internode.on.net/pub/cpan/
+ ftp://mirror.internode.on.net/pub/cpan/
+ http://cpan.mirror.aussiehq.net.au/
+ http://mirror.as24220.net/cpan/
+ ftp://mirror.as24220.net/cpan/
=item New Zealand
- ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
- http://cpan.inspire.net.nz
- ftp://cpan.inspire.net.nz/cpan
- http://cpan.catalyst.net.nz/CPAN/
- ftp://cpan.catalyst.net.nz/pub/CPAN/
+ ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
+ http://cpan.inspire.net.nz
+ ftp://cpan.inspire.net.nz/cpan
+ http://cpan.catalyst.net.nz/CPAN/
+ ftp://cpan.catalyst.net.nz/pub/CPAN/
=back
@@ -942,26 +927,25 @@
=item Argentina
- http://cpan.patan.com.ar/
- http://cpan.localhost.net.ar
- ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN
+ http://cpan.patan.com.ar/
+ http://cpan.localhost.net.ar
+ ftp://mirrors.localhost.net.ar/pub/mirrors/CPAN
=item Brazil
- ftp://cpan.pop-mg.com.br/pub/CPAN/
- http://ftp.pucpr.br/CPAN
- ftp://ftp.pucpr.br/CPAN
- http://cpan.kinghost.net/
- ftp://ftp.linorg.usp.br/CPAN
+ ftp://cpan.pop-mg.com.br/pub/CPAN/
+ http://ftp.pucpr.br/CPAN
+ ftp://ftp.pucpr.br/CPAN
+ http://cpan.kinghost.net/
=item Chile
- http://cpan.dcc.uchile.cl/
- ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
+ http://cpan.dcc.uchile.cl/
+ ftp://cpan.dcc.uchile.cl/pub/lang/cpan/
=item Colombia
- http://www.laqee.unal.edu.co/CPAN/
+ http://www.laqee.unal.edu.co/CPAN/
=back
@@ -1064,7 +1048,7 @@
totally transparent to the user of the module. Likewise, the module
might set up an AUTOLOAD function to slurp in subroutine definitions on
demand, but this is also transparent. Only the F<.pm> file is required to
-exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
+exist. See L<perlsub>, L<perlobj>, and L<AutoLoader> for details about
the AUTOLOAD mechanism.
=head2 Guidelines for Module Creation
@@ -1124,7 +1108,7 @@
class names as far as possible.
Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
-C<< $r->func() >> would work (see L<perlbot> for more details).
+C<< $r->func() >> would work.
Use autosplit so little used or newly added functions won't be a
burden to programs that don't use them. Add test functions to
@@ -1348,7 +1332,7 @@
To be fully compatible with the Exporter and MakeMaker modules you
should store your module's version number in a non-my package
-variable called $VERSION. This should be a floating point
+variable called $VERSION. This should be a positive floating point
number with at least two digits after the decimal (i.e., hundredths,
e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
See L<Exporter> for details.
@@ -1523,8 +1507,9 @@
written contract for the module (A.K.A. documentation) may make other
provisions. But then you know when you C<use RedefineTheWorld> that
you're redefining the world and willing to take the consequences.
-EOF
+=cut
+
close MANIFEST or warn "$0: failed to close MANIFEST (../MANIFEST): $!";
close OUT or warn "$0: failed to close OUT (perlmodlib.pod): $!";
Property changes on: trunk/contrib/perl/pod/perlmodlib.PL
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlmodlib.pod (from rev 6437, vendor/perl/5.18.1/pod/perlmodlib.pod)
===================================================================
--- trunk/contrib/perl/pod/perlmodlib.pod (rev 0)
+++ trunk/contrib/perl/pod/perlmodlib.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,3194 @@
+=for maintainers
+Generated by perlmodlib.PL -- DO NOT EDIT!
+
+=head1 NAME
+
+perlmodlib - constructing new Perl modules and finding existing ones
+
+=head1 THE PERL MODULE LIBRARY
+
+Many modules are included in the Perl distribution. These are described
+below, and all end in F<.pm>. You may discover compiled library
+files (usually ending in F<.so>) or small pieces of modules to be
+autoloaded (ending in F<.al>); these were automatically generated
+by the installation process. You may also discover files in the
+library directory that end in either F<.pl> or F<.ph>. These are
+old libraries supplied so that old programs that use them still
+run. The F<.pl> files will all eventually be converted into standard
+modules, and the F<.ph> files made by B<h2ph> will probably end up
+as extension modules made by B<h2xs>. (Some F<.ph> values may
+already be available through the POSIX, Errno, or Fcntl modules.)
+The B<pl2pm> file in the distribution may help in your conversion,
+but it's just a mechanical process and therefore far from bulletproof.
+
+=head2 Pragmatic Modules
+
+They work somewhat like compiler directives (pragmata) in that they
+tend to affect the compilation of your program, and thus will usually
+work well only when used within a C<use>, or C<no>. Most of these
+are lexically scoped, so an inner BLOCK may countermand them
+by saying:
+
+ no integer;
+ no strict 'refs';
+ no warnings;
+
+which lasts until the end of that BLOCK.
+
+Some pragmas are lexically scoped--typically those that affect the
+C<$^H> hints variable. Others affect the current package instead,
+like C<use vars> and C<use subs>, which allow you to predeclare a
+variables or subroutines within a particular I<file> rather than
+just a block. Such declarations are effective for the entire file
+for which they were declared. You cannot rescind them with C<no
+vars> or C<no subs>.
+
+The following pragmas are defined (and have their own documentation).
+
+=over 12
+
+=item attributes
+
+Get/set subroutine or variable attributes
+
+=item attrs
+
+Set/get attributes of a subroutine (deprecated)
+
+=item autouse
+
+Postpone load of modules until a function is used
+
+=item base
+
+Establish an ISA relationship with base classes at compile time
+
+=item bigint
+
+Transparent BigInteger support for Perl
+
+=item bignum
+
+Transparent BigNumber support for Perl
+
+=item bigrat
+
+Transparent BigNumber/BigRational support for Perl
+
+=item blib
+
+Use MakeMaker's uninstalled version of a package
+
+=item bytes
+
+Force byte semantics rather than character semantics
+
+=item charnames
+
+Define character names for C<\N{named}> string literal escapes
+
+=item constant
+
+Declare constants
+
+=item diagnostics
+
+Produce verbose warning diagnostics
+
+=item encoding
+
+Allows you to write your script in non-ascii or non-utf8
+
+=item encoding::warnings
+
+Warn on implicit encoding conversions
+
+=item feature
+
+Enable new syntactic features
+
+=item fields
+
+Compile-time class fields
+
+=item filetest
+
+Control the filetest permission operators
+
+=item if
+
+C<use> a Perl module if a condition holds
+
+=item integer
+
+Use integer arithmetic instead of floating point
+
+=item less
+
+Request less of something
+
+=item lib
+
+Manipulate @INC at compile time
+
+=item locale
+
+Use and avoid POSIX locales for built-in operations
+
+=item mro
+
+Method Resolution Order
+
+=item open
+
+Set default PerlIO layers for input and output
+
+=item ops
+
+Restrict unsafe operations when compiling
+
+=item overload
+
+Package for overloading Perl operations
+
+=item re
+
+Alter regular expression behaviour
+
+=item sigtrap
+
+Enable simple signal handling
+
+=item sort
+
+Control sort() behaviour
+
+=item strict
+
+Restrict unsafe constructs
+
+=item subs
+
+Predeclare sub names
+
+=item threads
+
+Perl interpreter-based threads
+
+=item threads::shared
+
+Perl extension for sharing data structures between threads
+
+=item utf8
+
+Enable/disable UTF-8 (or UTF-EBCDIC) in source code
+
+=item vars
+
+Predeclare global variable names (obsolete)
+
+=item version
+
+Perl extension for Version Objects
+
+=item vmsish
+
+Control VMS-specific language features
+
+=item warnings
+
+Control optional warnings
+
+=item warnings::register
+
+Warnings import function
+
+=back
+
+=head2 Standard Modules
+
+Standard, bundled modules are all expected to behave in a well-defined
+manner with respect to namespace pollution because they use the
+Exporter module. See their own documentation for details.
+
+It's possible that not all modules listed below are installed on your
+system. For example, the GDBM_File module will not be installed if you
+don't have the gdbm library.
+
+=over 12
+
+=item AnyDBM_File
+
+Provide framework for multiple DBMs
+
+=item Archive::Extract
+
+A generic archive extracting mechanism
+
+=item Archive::Tar
+
+Module for manipulations of tar archives
+
+=item Archive::Tar::File
+
+A subclass for in-memory extracted file from Archive::Tar
+
+=item Attribute::Handlers
+
+Simpler definition of attribute handlers
+
+=item AutoLoader
+
+Load subroutines only on demand
+
+=item AutoSplit
+
+Split a package for autoloading
+
+=item B
+
+The Perl Compiler
+
+=item B::Concise
+
+Walk Perl syntax tree, printing concise info about ops
+
+=item B::Debug
+
+Walk Perl syntax tree, printing debug info about ops
+
+=item B::Deparse
+
+Perl compiler backend to produce perl code
+
+=item B::Lint
+
+Perl lint
+
+=item B::Showlex
+
+Show lexical variables used in functions or files
+
+=item B::Terse
+
+Walk Perl syntax tree, printing terse info about ops
+
+=item B::Xref
+
+Generates cross reference reports for Perl programs
+
+=item Benchmark
+
+Benchmark running times of Perl code
+
+=item CGI
+
+Simple Common Gateway Interface Class
+
+=item CGI::Apache
+
+Backward compatibility module for CGI.pm
+
+=item CGI::Carp
+
+CGI routines for writing to the HTTPD (or other) error log
+
+=item CGI::Cookie
+
+Interface to Netscape Cookies
+
+=item CGI::Fast
+
+CGI Interface for Fast CGI
+
+=item CGI::Pretty
+
+Module to produce nicely formatted HTML code
+
+=item CGI::Push
+
+Simple Interface to Server Push
+
+=item CGI::Switch
+
+Backward compatibility module for defunct CGI::Switch
+
+=item CGI::Util
+
+Internal utilities used by CGI module
+
+=item CORE
+
+Pseudo-namespace for Perl's core routines
+
+=item CPAN
+
+Query, download and build perl modules from CPAN sites
+
+=item CPAN::API::HOWTO
+
+A recipe book for programming with CPAN.pm
+
+=item CPAN::FirstTime
+
+Utility for CPAN::Config file Initialization
+
+=item CPAN::Kwalify
+
+Interface between CPAN.pm and Kwalify.pm
+
+=item CPAN::Nox
+
+Wrapper around CPAN.pm without using any XS module
+
+=item CPAN::Version
+
+Utility functions to compare CPAN versions
+
+=item CPANPLUS
+
+API & CLI access to the CPAN mirrors
+
+=item CPANPLUS::Dist::Base
+
+Base class for custom distribution classes
+
+=item CPANPLUS::Dist::Sample
+
+Sample code to create your own Dist::* plugin
+
+=item CPANPLUS::Shell::Classic
+
+CPAN.pm emulation for CPANPLUS
+
+=item CPANPLUS::Shell::Default::Plugins::HOWTO
+
+Documentation on how to write your own plugins
+
+=item Carp
+
+Warn of errors (from perspective of caller)
+
+=item Carp::Heavy
+
+Heavy machinery, no user serviceable parts inside
+
+=item Class::ISA
+
+Report the search path for a class's ISA tree
+
+=item Class::Struct
+
+Declare struct-like datatypes as Perl classes
+
+=item Compress::Raw::Zlib
+
+Low-Level Interface to zlib compression library
+
+=item Compress::Zlib
+
+Interface to zlib compression library
+
+=item Config
+
+Access Perl configuration information
+
+=item Cwd
+
+Get pathname of current working directory
+
+=item DB
+
+Programmatic interface to the Perl debugging API
+
+=item DBM_Filter
+
+Filter DBM keys/values
+
+=item DBM_Filter::compress
+
+Filter for DBM_Filter
+
+=item DBM_Filter::encode
+
+Filter for DBM_Filter
+
+=item DBM_Filter::int32
+
+Filter for DBM_Filter
+
+=item DBM_Filter::null
+
+Filter for DBM_Filter
+
+=item DBM_Filter::utf8
+
+Filter for DBM_Filter
+
+=item DB_File
+
+Perl5 access to Berkeley DB version 1.x
+
+=item Data::Dumper
+
+Stringified perl data structures, suitable for both printing and C<eval>
+
+=item Devel::DProf
+
+A Perl code profiler
+
+=item Devel::InnerPackage
+
+Find all the inner packages of a package
+
+=item Devel::Peek
+
+A data debugging tool for the XS programmer
+
+=item Devel::SelfStubber
+
+Generate stubs for a SelfLoading module
+
+=item Digest
+
+Modules that calculate message digests
+
+=item Digest::MD5
+
+Perl interface to the MD5 Algorithm
+
+=item Digest::SHA
+
+Perl extension for SHA-1/224/256/384/512
+
+=item Digest::base
+
+Digest base class
+
+=item Digest::file
+
+Calculate digests of files
+
+=item DirHandle
+
+Supply object methods for directory handles
+
+=item Dumpvalue
+
+Provides screen dump of Perl data.
+
+=item DynaLoader
+
+Dynamically load C libraries into Perl code
+
+=item Encode
+
+Character encodings
+
+=item Encode::Alias
+
+Alias definitions to encodings
+
+=item Encode::Byte
+
+Single Byte Encodings
+
+=item Encode::CJKConstants
+
+Internally used by Encode::??::ISO_2022_*
+
+=item Encode::CN
+
+China-based Chinese Encodings
+
+=item Encode::CN::HZ
+
+Internally used by Encode::CN
+
+=item Encode::Config
+
+Internally used by Encode
+
+=item Encode::EBCDIC
+
+EBCDIC Encodings
+
+=item Encode::Encoder
+
+Object Oriented Encoder
+
+=item Encode::Encoding
+
+Encode Implementation Base Class
+
+=item Encode::GSM0338
+
+ESTI GSM 03.38 Encoding
+
+=item Encode::Guess
+
+Guesses encoding from data
+
+=item Encode::JP
+
+Japanese Encodings
+
+=item Encode::JP::H2Z
+
+Internally used by Encode::JP::2022_JP*
+
+=item Encode::JP::JIS7
+
+Internally used by Encode::JP
+
+=item Encode::KR
+
+Korean Encodings
+
+=item Encode::KR::2022_KR
+
+Internally used by Encode::KR
+
+=item Encode::MIME::Header
+
+MIME 'B' and 'Q' header encoding
+
+=item Encode::MIME::Name
+
+Internally used by Encode
+
+=item Encode::PerlIO
+
+A detailed document on Encode and PerlIO
+
+=item Encode::Supported
+
+Encodings supported by Encode
+
+=item Encode::Symbol
+
+Symbol Encodings
+
+=item Encode::TW
+
+Taiwan-based Chinese Encodings
+
+=item Encode::Unicode
+
+Various Unicode Transformation Formats
+
+=item Encode::Unicode::UTF7
+
+UTF-7 encoding
+
+=item English
+
+Use nice English (or awk) names for ugly punctuation variables
+
+=item Env
+
+Perl module that imports environment variables as scalars or arrays
+
+=item Errno
+
+System errno constants
+
+=item Exporter
+
+Implements default import method for modules
+
+=item Exporter::Heavy
+
+Exporter guts
+
+=item ExtUtils::CBuilder
+
+Compile and link C code for Perl modules
+
+=item ExtUtils::CBuilder::Platform::Windows
+
+Builder class for Windows platforms
+
+=item ExtUtils::Command
+
+Utilities to replace common UNIX commands in Makefiles etc.
+
+=item ExtUtils::Command::MM
+
+Commands for the MM's to use in Makefiles
+
+=item ExtUtils::Constant
+
+Generate XS code to import C header constants
+
+=item ExtUtils::Constant::Base
+
+Base class for ExtUtils::Constant objects
+
+=item ExtUtils::Constant::Utils
+
+Helper functions for ExtUtils::Constant
+
+=item ExtUtils::Constant::XS
+
+Base class for ExtUtils::Constant objects
+
+=item ExtUtils::Embed
+
+Utilities for embedding Perl in C/C++ applications
+
+=item ExtUtils::Install
+
+Install files from here to there
+
+=item ExtUtils::Installed
+
+Inventory management of installed modules
+
+=item ExtUtils::Liblist
+
+Determine libraries to use and how to use them
+
+=item ExtUtils::MM
+
+OS adjusted ExtUtils::MakeMaker subclass
+
+=item ExtUtils::MM_AIX
+
+AIX specific subclass of ExtUtils::MM_Unix
+
+=item ExtUtils::MM_Any
+
+Platform-agnostic MM methods
+
+=item ExtUtils::MM_BeOS
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_Cygwin
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_DOS
+
+DOS specific subclass of ExtUtils::MM_Unix
+
+=item ExtUtils::MM_MacOS
+
+Once produced Makefiles for MacOS Classic
+
+=item ExtUtils::MM_NW5
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_OS2
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_QNX
+
+QNX specific subclass of ExtUtils::MM_Unix
+
+=item ExtUtils::MM_UWIN
+
+U/WIN specific subclass of ExtUtils::MM_Unix
+
+=item ExtUtils::MM_Unix
+
+Methods used by ExtUtils::MakeMaker
+
+=item ExtUtils::MM_VMS
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_VOS
+
+VOS specific subclass of ExtUtils::MM_Unix
+
+=item ExtUtils::MM_Win32
+
+Methods to override UN*X behaviour in ExtUtils::MakeMaker
+
+=item ExtUtils::MM_Win95
+
+Method to customize MakeMaker for Win9X
+
+=item ExtUtils::MY
+
+ExtUtils::MakeMaker subclass for customization
+
+=item ExtUtils::MakeMaker
+
+Create a module Makefile
+
+=item ExtUtils::MakeMaker::Config
+
+Wrapper around Config.pm
+
+=item ExtUtils::MakeMaker::FAQ
+
+Frequently Asked Questions About MakeMaker
+
+=item ExtUtils::MakeMaker::Tutorial
+
+Writing a module with MakeMaker
+
+=item ExtUtils::MakeMaker::bytes
+
+Version-agnostic bytes.pm
+
+=item ExtUtils::MakeMaker::vmsish
+
+Platform-agnostic vmsish.pm
+
+=item ExtUtils::Manifest
+
+Utilities to write and check a MANIFEST file
+
+=item ExtUtils::Mkbootstrap
+
+Make a bootstrap file for use by DynaLoader
+
+=item ExtUtils::Mksymlists
+
+Write linker options files for dynamic extension
+
+=item ExtUtils::Packlist
+
+Manage .packlist files
+
+=item ExtUtils::ParseXS
+
+Converts Perl XS code into C code
+
+=item ExtUtils::testlib
+
+Add blib/* directories to @INC
+
+=item Fatal
+
+Replace functions with equivalents which succeed or die
+
+=item Fcntl
+
+Load the C Fcntl.h defines
+
+=item File::Basename
+
+Parse file paths into directory, filename and suffix.
+
+=item File::CheckTree
+
+Run many filetest checks on a tree
+
+=item File::Compare
+
+Compare files or filehandles
+
+=item File::Copy
+
+Copy files or filehandles
+
+=item File::DosGlob
+
+DOS like globbing and then some
+
+=item File::Fetch
+
+A generic file fetching mechanism
+
+=item File::Find
+
+Traverse a directory tree.
+
+=item File::Glob
+
+Perl extension for BSD glob routine
+
+=item File::GlobMapper
+
+Extend File Glob to Allow Input and Output Files
+
+=item File::Path
+
+Create or remove directory trees
+
+=item File::Spec
+
+Portably perform operations on file names
+
+=item File::Spec::Cygwin
+
+Methods for Cygwin file specs
+
+=item File::Spec::Epoc
+
+Methods for Epoc file specs
+
+=item File::Spec::Functions
+
+Portably perform operations on file names
+
+=item File::Spec::Mac
+
+File::Spec for Mac OS (Classic)
+
+=item File::Spec::OS2
+
+Methods for OS/2 file specs
+
+=item File::Spec::Unix
+
+File::Spec for Unix, base for other File::Spec modules
+
+=item File::Spec::VMS
+
+Methods for VMS file specs
+
+=item File::Spec::Win32
+
+Methods for Win32 file specs
+
+=item File::Temp
+
+Return name and handle of a temporary file safely
+
+=item File::stat
+
+By-name interface to Perl's built-in stat() functions
+
+=item FileCache
+
+Keep more files open than the system permits
+
+=item FileHandle
+
+Supply object methods for filehandles
+
+=item Filter::Simple
+
+Simplified source filtering
+
+=item Filter::Util::Call
+
+Perl Source Filter Utility Module
+
+=item FindBin
+
+Locate directory of original perl script
+
+=item GDBM_File
+
+Perl5 access to the gdbm library.
+
+=item Getopt::Long
+
+Extended processing of command line options
+
+=item Getopt::Std
+
+Process single-character switches with switch clustering
+
+=item Hash::Util
+
+A selection of general-utility hash subroutines
+
+=item Hash::Util::FieldHash
+
+Support for Inside-Out Classes
+
+=item I18N::Collate
+
+Compare 8-bit scalar data according to the current locale
+
+=item I18N::LangTags
+
+Functions for dealing with RFC3066-style language tags
+
+=item I18N::LangTags::Detect
+
+Detect the user's language preferences
+
+=item I18N::LangTags::List
+
+Tags and names for human languages
+
+=item I18N::Langinfo
+
+Query locale information
+
+=item IO
+
+Load various IO modules
+
+=item IO::Compress::Base
+
+Base Class for IO::Compress modules
+
+=item IO::Compress::Deflate
+
+Write RFC 1950 files/buffers
+
+=item IO::Compress::Gzip
+
+Write RFC 1952 files/buffers
+
+=item IO::Compress::RawDeflate
+
+Write RFC 1951 files/buffers
+
+=item IO::Compress::Zip
+
+Write zip files/buffers
+
+=item IO::Dir
+
+Supply object methods for directory handles
+
+=item IO::File
+
+Supply object methods for filehandles
+
+=item IO::Handle
+
+Supply object methods for I/O handles
+
+=item IO::Pipe
+
+Supply object methods for pipes
+
+=item IO::Poll
+
+Object interface to system poll call
+
+=item IO::Seekable
+
+Supply seek based methods for I/O objects
+
+=item IO::Select
+
+OO interface to the select system call
+
+=item IO::Socket
+
+Object interface to socket communications
+
+=item IO::Socket::INET
+
+Object interface for AF_INET domain sockets
+
+=item IO::Socket::UNIX
+
+Object interface for AF_UNIX domain sockets
+
+=item IO::Uncompress::AnyInflate
+
+Uncompress zlib-based (zip, gzip) file/buffer
+
+=item IO::Uncompress::AnyUncompress
+
+Uncompress gzip, zip, bzip2 or lzop file/buffer
+
+=item IO::Uncompress::Base
+
+Base Class for IO::Uncompress modules
+
+=item IO::Uncompress::Gunzip
+
+Read RFC 1952 files/buffers
+
+=item IO::Uncompress::Inflate
+
+Read RFC 1950 files/buffers
+
+=item IO::Uncompress::RawInflate
+
+Read RFC 1951 files/buffers
+
+=item IO::Uncompress::Unzip
+
+Read zip files/buffers
+
+=item IO::Zlib
+
+IO:: style interface to L<Compress::Zlib>
+
+=item IPC::Cmd
+
+Finding and running system commands made easy
+
+=item IPC::Open2
+
+Open a process for both reading and writing
+
+=item IPC::Open3
+
+Open a process for reading, writing, and error handling
+
+=item IPC::SysV
+
+SysV IPC constants
+
+=item IPC::SysV::Msg
+
+SysV Msg IPC object class
+
+=item IPC::SysV::Semaphore
+
+SysV Semaphore IPC object class
+
+=item List::Util
+
+A selection of general-utility list subroutines
+
+=item Locale::Constants
+
+Constants for Locale codes
+
+=item Locale::Country
+
+ISO codes for country identification (ISO 3166)
+
+=item Locale::Currency
+
+ISO three letter codes for currency identification (ISO 4217)
+
+=item Locale::Language
+
+ISO two letter codes for language identification (ISO 639)
+
+=item Locale::Maketext
+
+Framework for localization
+
+=item Locale::Maketext::Simple
+
+Simple interface to Locale::Maketext::Lexicon
+
+=item Locale::Maketext::TPJ13
+
+Article about software localization
+
+=item Locale::Script
+
+ISO codes for script identification (ISO 15924)
+
+=item Log::Message
+
+A generic message storing mechanism;
+
+=item Log::Message::Config
+
+Configuration options for Log::Message
+
+=item Log::Message::Handlers
+
+Message handlers for Log::Message
+
+=item Log::Message::Item
+
+Message objects for Log::Message
+
+=item MIME::Base64
+
+Encoding and decoding of base64 strings
+
+=item MIME::QuotedPrint
+
+Encoding and decoding of quoted-printable strings
+
+=item Math::BigFloat
+
+Arbitrary size floating point math package
+
+=item Math::BigInt
+
+Arbitrary size integer/float math package
+
+=item Math::BigInt::Calc
+
+Pure Perl module to support Math::BigInt
+
+=item Math::BigInt::CalcEmu
+
+Emulate low-level math with BigInt code
+
+=item Math::BigInt::FastCalc
+
+Math::BigInt::Calc with some XS for more speed
+
+=item Math::BigRat
+
+Arbitrary big rational numbers
+
+=item Math::Complex
+
+Complex numbers and associated mathematical functions
+
+=item Math::Trig
+
+Trigonometric functions
+
+=item Memoize
+
+Make functions faster by trading space for time
+
+=item Memoize::AnyDBM_File
+
+Glue to provide EXISTS for AnyDBM_File for Storable use
+
+=item Memoize::Expire
+
+Plug-in module for automatic expiration of memoized values
+
+=item Memoize::ExpireFile
+
+Test for Memoize expiration semantics
+
+=item Memoize::ExpireTest
+
+Test for Memoize expiration semantics
+
+=item Memoize::NDBM_File
+
+Glue to provide EXISTS for NDBM_File for Storable use
+
+=item Memoize::SDBM_File
+
+Glue to provide EXISTS for SDBM_File for Storable use
+
+=item Memoize::Storable
+
+Store Memoized data in Storable database
+
+=item Module::Build
+
+Build and install Perl modules
+
+=item Module::Build::API
+
+API Reference for Module Authors
+
+=item Module::Build::Authoring
+
+Authoring Module::Build modules
+
+=item Module::Build::Base
+
+Default methods for Module::Build
+
+=item Module::Build::Compat
+
+Compatibility with ExtUtils::MakeMaker
+
+=item Module::Build::ConfigData
+
+Configuration for Module::Build
+
+=item Module::Build::Cookbook
+
+Examples of Module::Build Usage
+
+=item Module::Build::ModuleInfo
+
+Gather package and POD information from a perl module files
+
+=item Module::Build::Notes
+
+Configuration for $module_name
+
+=item Module::Build::PPMMaker
+
+Perl Package Manager file creation
+
+=item Module::Build::Platform::Amiga
+
+Builder class for Amiga platforms
+
+=item Module::Build::Platform::Default
+
+Stub class for unknown platforms
+
+=item Module::Build::Platform::EBCDIC
+
+Builder class for EBCDIC platforms
+
+=item Module::Build::Platform::MPEiX
+
+Builder class for MPEiX platforms
+
+=item Module::Build::Platform::MacOS
+
+Builder class for MacOS platforms
+
+=item Module::Build::Platform::RiscOS
+
+Builder class for RiscOS platforms
+
+=item Module::Build::Platform::Unix
+
+Builder class for Unix platforms
+
+=item Module::Build::Platform::VMS
+
+Builder class for VMS platforms
+
+=item Module::Build::Platform::VOS
+
+Builder class for VOS platforms
+
+=item Module::Build::Platform::Windows
+
+Builder class for Windows platforms
+
+=item Module::Build::Platform::aix
+
+Builder class for AIX platform
+
+=item Module::Build::Platform::cygwin
+
+Builder class for Cygwin platform
+
+=item Module::Build::Platform::darwin
+
+Builder class for Mac OS X platform
+
+=item Module::Build::Platform::os2
+
+Builder class for OS/2 platform
+
+=item Module::Build::YAML
+
+Provides just enough YAML support so that Module::Build works even if YAML.pm is not installed
+
+=item Module::CoreList
+
+What modules shipped with versions of perl
+
+=item Module::Load
+
+Runtime require of both modules and files
+
+=item Module::Load::Conditional
+
+Looking up module information / loading at runtime
+
+=item Module::Loaded
+
+Mark modules as loaded or unloaded
+
+=item Module::Pluggable
+
+Automatically give your module the ability to have plugins
+
+=item Module::Pluggable::Object
+
+Automatically give your module the ability to have plugins
+
+=item NDBM_File
+
+Tied access to ndbm files
+
+=item NEXT
+
+Provide a pseudo-class NEXT (et al) that allows method redispatch
+
+=item Net::Cmd
+
+Network Command class (as used by FTP, SMTP etc)
+
+=item Net::Config
+
+Local configuration data for libnet
+
+=item Net::Domain
+
+Attempt to evaluate the current host's internet name and domain
+
+=item Net::FTP
+
+FTP Client class
+
+=item Net::NNTP
+
+NNTP Client class
+
+=item Net::Netrc
+
+OO interface to users netrc file
+
+=item Net::POP3
+
+Post Office Protocol 3 Client class (RFC1939)
+
+=item Net::Ping
+
+Check a remote host for reachability
+
+=item Net::SMTP
+
+Simple Mail Transfer Protocol Client
+
+=item Net::Time
+
+Time and daytime network client interface
+
+=item Net::hostent
+
+By-name interface to Perl's built-in gethost*() functions
+
+=item Net::libnetFAQ
+
+Libnet Frequently Asked Questions
+
+=item Net::netent
+
+By-name interface to Perl's built-in getnet*() functions
+
+=item Net::protoent
+
+By-name interface to Perl's built-in getproto*() functions
+
+=item Net::servent
+
+By-name interface to Perl's built-in getserv*() functions
+
+=item O
+
+Generic interface to Perl Compiler backends
+
+=item ODBM_File
+
+Tied access to odbm files
+
+=item Opcode
+
+Disable named opcodes when compiling perl code
+
+=item POSIX
+
+Perl interface to IEEE Std 1003.1
+
+=item Package::Constants
+
+List all constants declared in a package
+
+=item Params::Check
+
+A generic input parsing/checking mechanism.
+
+=item PerlIO
+
+On demand loader for PerlIO layers and root of PerlIO::* name space
+
+=item PerlIO::encoding
+
+Encoding layer
+
+=item PerlIO::scalar
+
+In-memory IO, scalar IO
+
+=item PerlIO::via
+
+Helper class for PerlIO layers implemented in perl
+
+=item PerlIO::via::QuotedPrint
+
+PerlIO layer for quoted-printable strings
+
+=item Pod::Checker
+
+Check pod documents for syntax errors
+
+=item Pod::Escapes
+
+For resolving Pod EE<lt>...E<gt> sequences
+
+=item Pod::Find
+
+Find POD documents in directory trees
+
+=item Pod::Functions
+
+Group Perl's functions a la perlfunc.pod
+
+=item Pod::Html
+
+Module to convert pod files to HTML
+
+=item Pod::InputObjects
+
+Objects representing POD input paragraphs, commands, etc.
+
+=item Pod::LaTeX
+
+Convert Pod data to formatted Latex
+
+=item Pod::Man
+
+Convert POD data to formatted *roff input
+
+=item Pod::ParseLink
+
+Parse an LE<lt>E<gt> formatting code in POD text
+
+=item Pod::ParseUtils
+
+Helpers for POD parsing and conversion
+
+=item Pod::Parser
+
+Base class for creating POD filters and translators
+
+=item Pod::Perldoc::ToChecker
+
+Let Perldoc check Pod for errors
+
+=item Pod::Perldoc::ToMan
+
+Let Perldoc render Pod as man pages
+
+=item Pod::Perldoc::ToNroff
+
+Let Perldoc convert Pod to nroff
+
+=item Pod::Perldoc::ToPod
+
+Let Perldoc render Pod as ... Pod!
+
+=item Pod::Perldoc::ToRtf
+
+Let Perldoc render Pod as RTF
+
+=item Pod::Perldoc::ToText
+
+Let Perldoc render Pod as plaintext
+
+=item Pod::Perldoc::ToTk
+
+Let Perldoc use Tk::Pod to render Pod
+
+=item Pod::Perldoc::ToXml
+
+Let Perldoc render Pod as XML
+
+=item Pod::PlainText
+
+Convert POD data to formatted ASCII text
+
+=item Pod::Plainer
+
+Perl extension for converting Pod to old style Pod.
+
+=item Pod::Select
+
+Extract selected sections of POD from input
+
+=item Pod::Simple
+
+Framework for parsing Pod
+
+=item Pod::Simple::Checker
+
+Check the Pod syntax of a document
+
+=item Pod::Simple::Debug
+
+Put Pod::Simple into trace/debug mode
+
+=item Pod::Simple::DumpAsText
+
+Dump Pod-parsing events as text
+
+=item Pod::Simple::DumpAsXML
+
+Turn Pod into XML
+
+=item Pod::Simple::HTML
+
+Convert Pod to HTML
+
+=item Pod::Simple::HTMLBatch
+
+Convert several Pod files to several HTML files
+
+=item Pod::Simple::LinkSection
+
+Represent "section" attributes of L codes
+
+=item Pod::Simple::Methody
+
+Turn Pod::Simple events into method calls
+
+=item Pod::Simple::PullParser
+
+A pull-parser interface to parsing Pod
+
+=item Pod::Simple::PullParserEndToken
+
+End-tokens from Pod::Simple::PullParser
+
+=item Pod::Simple::PullParserStartToken
+
+Start-tokens from Pod::Simple::PullParser
+
+=item Pod::Simple::PullParserTextToken
+
+Text-tokens from Pod::Simple::PullParser
+
+=item Pod::Simple::PullParserToken
+
+Tokens from Pod::Simple::PullParser
+
+=item Pod::Simple::RTF
+
+Format Pod as RTF
+
+=item Pod::Simple::Search
+
+Find POD documents in directory trees
+
+=item Pod::Simple::SimpleTree
+
+Parse Pod into a simple parse tree
+
+=item Pod::Simple::Subclassing
+
+Write a formatter as a Pod::Simple subclass
+
+=item Pod::Simple::Text
+
+Format Pod as plaintext
+
+=item Pod::Simple::TextContent
+
+Get the text content of Pod
+
+=item Pod::Simple::XMLOutStream
+
+Turn Pod into XML
+
+=item Pod::Text
+
+Convert POD data to formatted ASCII text
+
+=item Pod::Text::Color
+
+Convert POD data to formatted color ASCII text
+
+=item Pod::Text::Overstrike
+
+Convert POD data to formatted overstrike text
+
+=item Pod::Text::Termcap
+
+Convert POD data to ASCII text with format escapes
+
+=item Pod::Usage
+
+Print a usage message from embedded pod documentation
+
+=item SDBM_File
+
+Tied access to sdbm files
+
+=item Safe
+
+Compile and execute code in restricted compartments
+
+=item Scalar::Util
+
+A selection of general-utility scalar subroutines
+
+=item Search::Dict
+
+Search for key in dictionary file
+
+=item SelectSaver
+
+Save and restore selected file handle
+
+=item SelfLoader
+
+Load functions only on demand
+
+=item Shell
+
+Run shell commands transparently within perl
+
+=item Socket
+
+Load the C socket.h defines and structure manipulators
+
+=item Storable
+
+Persistence for Perl data structures
+
+=item Switch
+
+A switch statement for Perl
+
+=item Symbol
+
+Manipulate Perl symbols and their names
+
+=item Sys::Hostname
+
+Try every conceivable way to get hostname
+
+=item Sys::Syslog
+
+Perl interface to the UNIX syslog(3) calls
+
+=item Sys::Syslog::win32::Win32
+
+Win32 support for Sys::Syslog
+
+=item Term::ANSIColor
+
+Color screen output using ANSI escape sequences
+
+=item Term::Cap
+
+Perl termcap interface
+
+=item Term::Complete
+
+Perl word completion module
+
+=item Term::ReadLine
+
+Perl interface to various C<readline> packages.
+
+=item Term::UI
+
+Term::ReadLine UI made easy
+
+=item Test
+
+Provides a simple framework for writing test scripts
+
+=item Test::Builder
+
+Backend for building test libraries
+
+=item Test::Builder::Module
+
+Base class for test modules
+
+=item Test::Builder::Tester
+
+Test testsuites that have been built with
+
+=item Test::Builder::Tester::Color
+
+Turn on colour in Test::Builder::Tester
+
+=item Test::Harness
+
+Run Perl standard test scripts with statistics
+
+=item Test::Harness::Assert
+
+Simple assert
+
+=item Test::Harness::Iterator
+
+Internal Test::Harness Iterator
+
+=item Test::Harness::Point
+
+Object for tracking a single test point
+
+=item Test::Harness::Results
+
+Object for tracking results from a single test file
+
+=item Test::Harness::Straps
+
+Detailed analysis of test results
+
+=item Test::Harness::TAP
+
+Documentation for the TAP format
+
+=item Test::Harness::Util
+
+Utility functions for Test::Harness::*
+
+=item Test::More
+
+Yet another framework for writing test scripts
+
+=item Test::Simple
+
+Basic utilities for writing tests.
+
+=item Test::Tutorial
+
+A tutorial about writing really basic tests
+
+=item Text::Abbrev
+
+Create an abbreviation table from a list
+
+=item Text::Balanced
+
+Extract delimited text sequences from strings.
+
+=item Text::ParseWords
+
+Parse text into an array of tokens or array of arrays
+
+=item Text::Soundex
+
+Implementation of the soundex algorithm.
+
+=item Text::Tabs
+
+Expand and unexpand tabs per the unix expand(1) and unexpand(1)
+
+=item Text::Wrap
+
+Line wrapping to form simple paragraphs
+
+=item Thread
+
+Manipulate threads in Perl (for old code only)
+
+=item Thread::Queue
+
+Thread-safe queues
+
+=item Thread::Semaphore
+
+Thread-safe semaphores
+
+=item Tie::Array
+
+Base class for tied arrays
+
+=item Tie::File
+
+Access the lines of a disk file via a Perl array
+
+=item Tie::Handle
+
+Base class definitions for tied handles
+
+=item Tie::Hash
+
+Base class definitions for tied hashes
+
+=item Tie::Hash::NamedCapture
+
+Named regexp capture buffers
+
+=item Tie::Memoize
+
+Add data to hash when needed
+
+=item Tie::RefHash
+
+Use references as hash keys
+
+=item Tie::Scalar
+
+Base class definitions for tied scalars
+
+=item Tie::SubstrHash
+
+Fixed-table-size, fixed-key-length hashing
+
+=item Time::HiRes
+
+High resolution alarm, sleep, gettimeofday, interval timers
+
+=item Time::Local
+
+Efficiently compute time from local and GMT time
+
+=item Time::Piece
+
+Object Oriented time objects
+
+=item Time::Piece::Seconds
+
+A simple API to convert seconds to other date values
+
+=item Time::gmtime
+
+By-name interface to Perl's built-in gmtime() function
+
+=item Time::localtime
+
+By-name interface to Perl's built-in localtime() function
+
+=item Time::tm
+
+Internal object used by Time::gmtime and Time::localtime
+
+=item UNIVERSAL
+
+Base class for ALL classes (blessed references)
+
+=item Unicode::Collate
+
+Unicode Collation Algorithm
+
+=item Unicode::Normalize
+
+Unicode Normalization Forms
+
+=item Unicode::UCD
+
+Unicode character database
+
+=item User::grent
+
+By-name interface to Perl's built-in getgr*() functions
+
+=item User::pwent
+
+By-name interface to Perl's built-in getpw*() functions
+
+=item Win32
+
+Interfaces to some Win32 API Functions
+
+=item Win32API::File
+
+Low-level access to Win32 system API calls for files/dirs.
+
+=item Win32CORE
+
+Win32 CORE function stubs
+
+=item XS::APItest
+
+Test the perl C API
+
+=item XS::Typemap
+
+Module to test the XS typemaps distributed with perl
+
+=item XSLoader
+
+Dynamically load C libraries into Perl code
+
+=back
+
+To find out I<all> modules installed on your system, including
+those without documentation or outside the standard release,
+just use the following command (under the default win32 shell,
+double quotes should be used instead of single quotes).
+
+ % perl -MFile::Find=find -MFile::Spec::Functions -Tlwe \
+ 'find { wanted => sub { print canonpath $_ if /\.pm\z/ },
+ no_chdir => 1 }, @INC'
+
+(The -T is here to prevent '.' from being listed in @INC.)
+They should all have their own documentation installed and accessible
+via your system man(1) command. If you do not have a B<find>
+program, you can use the Perl B<find2perl> program instead, which
+generates Perl code as output you can run through perl. If you
+have a B<man> program but it doesn't find your modules, you'll have
+to fix your manpath. See L<perl> for details. If you have no
+system B<man> command, you might try the B<perldoc> program.
+
+Note also that the command C<perldoc perllocal> gives you a (possibly
+incomplete) list of the modules that have been further installed on
+your system. (The perllocal.pod file is updated by the standard MakeMaker
+install process.)
+
+=head2 Extension Modules
+
+Extension modules are written in C (or a mix of Perl and C). They
+are usually dynamically loaded into Perl if and when you need them,
+but may also be linked in statically. Supported extension modules
+include Socket, Fcntl, and POSIX.
+
+Many popular C extension modules do not come bundled (at least, not
+completely) due to their sizes, volatility, or simply lack of time
+for adequate testing and configuration across the multitude of
+platforms on which Perl was beta-tested. You are encouraged to
+look for them on CPAN (described below), or using web search engines
+like Alta Vista or Google.
+
+=head1 CPAN
+
+CPAN stands for Comprehensive Perl Archive Network; it's a globally
+replicated trove of Perl materials, including documentation, style
+guides, tricks and traps, alternate ports to non-Unix systems and
+occasional binary distributions for these. Search engines for
+CPAN can be found at http://www.cpan.org/
+
+Most importantly, CPAN includes around a thousand unbundled modules,
+some of which require a C compiler to build. Major categories of
+modules are:
+
+=over
+
+=item *
+
+Language Extensions and Documentation Tools
+
+=item *
+
+Development Support
+
+=item *
+
+Operating System Interfaces
+
+=item *
+
+Networking, Device Control (modems) and InterProcess Communication
+
+=item *
+
+Data Types and Data Type Utilities
+
+=item *
+
+Database Interfaces
+
+=item *
+
+User Interfaces
+
+=item *
+
+Interfaces to / Emulations of Other Programming Languages
+
+=item *
+
+File Names, File Systems and File Locking (see also File Handles)
+
+=item *
+
+String Processing, Language Text Processing, Parsing, and Searching
+
+=item *
+
+Option, Argument, Parameter, and Configuration File Processing
+
+=item *
+
+Internationalization and Locale
+
+=item *
+
+Authentication, Security, and Encryption
+
+=item *
+
+World Wide Web, HTML, HTTP, CGI, MIME
+
+=item *
+
+Server and Daemon Utilities
+
+=item *
+
+Archiving and Compression
+
+=item *
+
+Images, Pixmap and Bitmap Manipulation, Drawing, and Graphing
+
+=item *
+
+Mail and Usenet News
+
+=item *
+
+Control Flow Utilities (callbacks and exceptions etc)
+
+=item *
+
+File Handle and Input/Output Stream Utilities
+
+=item *
+
+Miscellaneous Modules
+
+=back
+
+The list of the registered CPAN sites as of this writing follows.
+Please note that the sorting order is alphabetical on fields:
+
+Continent
+ |
+ |-->Country
+ |
+ |-->[state/province]
+ |
+ |-->ftp
+ |
+ |-->[http]
+
+and thus the North American servers happen to be listed between the
+European and the South American sites.
+
+You should try to choose one close to you.
+
+=head2 Africa
+
+=over 4
+
+=item South Africa
+
+ http://ftp.rucus.ru.ac.za/pub/perl/CPAN/
+ ftp://ftp.rucus.ru.ac.za/pub/perl/CPAN/
+ ftp://ftp.is.co.za/programming/perl/CPAN/
+ ftp://ftp.saix.net/pub/CPAN/
+ ftp://ftp.sun.ac.za/CPAN/CPAN/
+
+=back
+
+=head2 Asia
+
+=over 4
+
+=item China
+
+ http://cpan.linuxforum.net/
+ http://cpan.shellhung.org/
+ ftp://ftp.shellhung.org/pub/CPAN
+ ftp://mirrors.hknet.com/CPAN
+
+=item Indonesia
+
+ http://mirrors.tf.itb.ac.id/cpan/
+ http://cpan.cbn.net.id/
+ ftp://ftp.cbn.net.id/mirror/CPAN
+
+=item Israel
+
+ ftp://ftp.iglu.org.il/pub/CPAN/
+ http://cpan.lerner.co.il/
+ http://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
+ ftp://bioinfo.weizmann.ac.il/pub/software/perl/CPAN/
+
+=item Japan
+
+ ftp://ftp.u-aizu.ac.jp/pub/CPAN
+ ftp://ftp.kddlabs.co.jp/CPAN/
+ ftp://ftp.ayamura.org/pub/CPAN/
+ ftp://ftp.jaist.ac.jp/pub/lang/perl/CPAN/
+ http://ftp.cpan.jp/
+ ftp://ftp.cpan.jp/CPAN/
+ ftp://ftp.dti.ad.jp/pub/lang/CPAN/
+ ftp://ftp.ring.gr.jp/pub/lang/perl/CPAN/
+
+=item Malaysia
+
+ http://cpan.MyBSD.org.my
+ http://mirror.leafbug.org/pub/CPAN
+ http://ossig.mncc.com.my/mirror/pub/CPAN
+
+=item Russian Federation
+
+ http://cpan.tomsk.ru
+ ftp://cpan.tomsk.ru/
+
+=item Saudi Arabia
+
+ ftp://ftp.isu.net.sa/pub/CPAN/
+
+=item Singapore
+
+ http://CPAN.en.com.sg/
+ ftp://cpan.en.com.sg/
+ http://mirror.averse.net/pub/CPAN
+ ftp://mirror.averse.net/pub/CPAN
+ http://cpan.oss.eznetsols.org
+ ftp://ftp.oss.eznetsols.org/cpan
+
+=item South Korea
+
+ http://CPAN.bora.net/
+ ftp://ftp.bora.net/pub/CPAN/
+ http://mirror.kr.FreeBSD.org/CPAN
+ ftp://ftp.kr.FreeBSD.org/pub/CPAN
+
+=item Taiwan
+
+ ftp://ftp.nctu.edu.tw/UNIX/perl/CPAN
+ http://cpan.cdpa.nsysu.edu.tw/
+ ftp://cpan.cdpa.nsysu.edu.tw/pub/CPAN
+ http://ftp.isu.edu.tw/pub/CPAN
+ ftp://ftp.isu.edu.tw/pub/CPAN
+ ftp://ftp1.sinica.edu.tw/pub1/perl/CPAN/
+ http://ftp.tku.edu.tw/pub/CPAN/
+ ftp://ftp.tku.edu.tw/pub/CPAN/
+
+=item Thailand
+
+ ftp://ftp.loxinfo.co.th/pub/cpan/
+ ftp://ftp.cs.riubon.ac.th/pub/mirrors/CPAN/
+
+=back
+
+=head2 Central America
+
+=over 4
+
+=item Costa Rica
+
+ http://ftp.ucr.ac.cr/Unix/CPAN/
+ ftp://ftp.ucr.ac.cr/pub/Unix/CPAN/
+
+=back
+
+=head2 Europe
+
+=over 4
+
+=item Austria
+
+ http://cpan.inode.at/
+ ftp://cpan.inode.at
+ ftp://ftp.tuwien.ac.at/pub/CPAN/
+
+=item Belgium
+
+ http://ftp.easynet.be/pub/CPAN/
+ ftp://ftp.easynet.be/pub/CPAN/
+ http://cpan.skynet.be
+ ftp://ftp.cpan.skynet.be/pub/CPAN
+ ftp://ftp.kulnet.kuleuven.ac.be/pub/mirror/CPAN/
+
+=item Bosnia and Herzegovina
+
+ http://cpan.blic.net/
+
+=item Bulgaria
+
+ http://cpan.online.bg
+ ftp://cpan.online.bg/cpan
+ http://cpan.zadnik.org
+ ftp://ftp.zadnik.org/mirrors/CPAN/
+ http://cpan.lirex.net/
+ ftp://ftp.lirex.net/pub/mirrors/CPAN
+
+=item Croatia
+
+ http://ftp.linux.hr/pub/CPAN/
+ ftp://ftp.linux.hr/pub/CPAN/
+
+=item Czech Republic
+
+ ftp://ftp.fi.muni.cz/pub/CPAN/
+ ftp://sunsite.mff.cuni.cz/MIRRORS/ftp.funet.fi/pub/languages/perl/CPAN/
+
+=item Denmark
+
+ http://mirrors.sunsite.dk/cpan/
+ ftp://sunsite.dk/mirrors/cpan/
+ http://cpan.cybercity.dk
+ http://www.cpan.dk/CPAN/
+ ftp://www.cpan.dk/ftp.cpan.org/CPAN/
+
+=item Estonia
+
+ ftp://ftp.ut.ee/pub/languages/perl/CPAN/
+
+=item Finland
+
+ ftp://ftp.funet.fi/pub/languages/perl/CPAN/
+ http://mirror.eunet.fi/CPAN
+
+=item France
+
+ http://www.enstimac.fr/Perl/CPAN
+ http://ftp.u-paris10.fr/perl/CPAN
+ ftp://ftp.u-paris10.fr/perl/CPAN
+ http://cpan.mirrors.easynet.fr/
+ ftp://cpan.mirrors.easynet.fr/pub/ftp.cpan.org/
+ ftp://ftp.club-internet.fr/pub/perl/CPAN/
+ http://fr.cpan.org/
+ ftp://ftp.lip6.fr/pub/perl/CPAN/
+ ftp://ftp.oleane.net/pub/mirrors/CPAN/
+ ftp://ftp.pasteur.fr/pub/computing/CPAN/
+ http://mir2.ovh.net/ftp.cpan.org
+ ftp://mir1.ovh.net/ftp.cpan.org
+ http://ftp.crihan.fr/mirrors/ftp.cpan.org/
+ ftp://ftp.crihan.fr/mirrors/ftp.cpan.org/
+ http://ftp.u-strasbg.fr/CPAN
+ ftp://ftp.u-strasbg.fr/CPAN
+ ftp://cpan.cict.fr/pub/CPAN/
+ ftp://ftp.uvsq.fr/pub/perl/CPAN/
+
+=item Germany
+
+ ftp://ftp.rub.de/pub/CPAN/
+ ftp://ftp.freenet.de/pub/ftp.cpan.org/pub/CPAN/
+ ftp://ftp.uni-erlangen.de/pub/source/CPAN/
+ ftp://ftp-stud.fht-esslingen.de/pub/Mirrors/CPAN
+ http://pandemonium.tiscali.de/pub/CPAN/
+ ftp://pandemonium.tiscali.de/pub/CPAN/
+ http://ftp.gwdg.de/pub/languages/perl/CPAN/
+ ftp://ftp.gwdg.de/pub/languages/perl/CPAN/
+ ftp://ftp.uni-hamburg.de/pub/soft/lang/perl/CPAN/
+ ftp://ftp.leo.org/pub/CPAN/
+ http://cpan.noris.de/
+ ftp://cpan.noris.de/pub/CPAN/
+ ftp://ftp.mpi-sb.mpg.de/pub/perl/CPAN/
+ ftp://ftp.gmd.de/mirrors/CPAN/
+
+=item Greece
+
+ ftp://ftp.acn.gr/pub/lang/perl
+ ftp://ftp.forthnet.gr/pub/languages/perl/CPAN
+ ftp://ftp.ntua.gr/pub/lang/perl/
+
+=item Hungary
+
+ http://ftp.kfki.hu/packages/perl/CPAN/
+ ftp://ftp.kfki.hu/pub/packages/perl/CPAN/
+
+=item Iceland
+
+ http://ftp.rhnet.is/pub/CPAN/
+ ftp://ftp.rhnet.is/pub/CPAN/
+
+=item Ireland
+
+ http://cpan.indigo.ie/
+ ftp://cpan.indigo.ie/pub/CPAN/
+ http://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
+ ftp://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
+ http://sunsite.compapp.dcu.ie/pub/perl/
+ ftp://sunsite.compapp.dcu.ie/pub/perl/
+
+=item Italy
+
+ http://cpan.nettuno.it/
+ http://gusp.dyndns.org/CPAN/
+ ftp://gusp.dyndns.org/pub/CPAN
+ http://softcity.iol.it/cpan
+ ftp://softcity.iol.it/pub/cpan
+ ftp://ftp.unina.it/pub/Other/CPAN/CPAN/
+ ftp://ftp.unipi.it/pub/mirror/perl/CPAN/
+ ftp://cis.uniRoma2.it/CPAN/
+ ftp://ftp.edisontel.it/pub/CPAN_Mirror/
+ http://cpan.flashnet.it/
+ ftp://ftp.flashnet.it/pub/CPAN/
+
+=item Latvia
+
+ http://kvin.lv/pub/CPAN/
+
+=item Lithuania
+
+ ftp://ftp.unix.lt/pub/CPAN/
+
+=item Netherlands
+
+ ftp://download.xs4all.nl/pub/mirror/CPAN/
+ ftp://ftp.nl.uu.net/pub/CPAN/
+ ftp://ftp.nluug.nl/pub/languages/perl/CPAN/
+ http://cpan.cybercomm.nl/
+ ftp://mirror.cybercomm.nl/pub/CPAN
+ ftp://mirror.vuurwerk.nl/pub/CPAN/
+ ftp://ftp.cpan.nl/pub/CPAN/
+ http://ftp.easynet.nl/mirror/CPAN
+ ftp://ftp.easynet.nl/mirror/CPAN
+ http://archive.cs.uu.nl/mirror/CPAN/
+ ftp://ftp.cs.uu.nl/mirror/CPAN/
+
+=item Norway
+
+ ftp://ftp.uninett.no/pub/languages/perl/CPAN
+ ftp://ftp.uit.no/pub/languages/perl/cpan/
+
+=item Poland
+
+ ftp://ftp.mega.net.pl/CPAN
+ ftp://ftp.man.torun.pl/pub/doc/CPAN/
+ ftp://sunsite.icm.edu.pl/pub/CPAN/
+
+=item Portugal
+
+ ftp://ftp.ua.pt/pub/CPAN/
+ ftp://perl.di.uminho.pt/pub/CPAN/
+ http://cpan.dei.uc.pt/
+ ftp://ftp.dei.uc.pt/pub/CPAN
+ ftp://ftp.nfsi.pt/pub/CPAN
+ http://ftp.linux.pt/pub/mirrors/CPAN
+ ftp://ftp.linux.pt/pub/mirrors/CPAN
+ http://cpan.ip.pt/
+ ftp://cpan.ip.pt/pub/cpan/
+ http://cpan.telepac.pt/
+ ftp://ftp.telepac.pt/pub/cpan/
+
+=item Romania
+
+ ftp://ftp.bio-net.ro/pub/CPAN
+ ftp://ftp.kappa.ro/pub/mirrors/ftp.perl.org/pub/CPAN/
+ ftp://ftp.lug.ro/CPAN
+ ftp://ftp.roedu.net/pub/CPAN/
+ ftp://ftp.dntis.ro/pub/cpan/
+ ftp://ftp.iasi.roedu.net/pub/mirrors/ftp.cpan.org/
+ http://cpan.ambra.ro/
+ ftp://ftp.ambra.ro/pub/CPAN
+ ftp://ftp.dnttm.ro/pub/CPAN/
+ ftp://ftp.lasting.ro/pub/CPAN
+ ftp://ftp.timisoara.roedu.net/mirrors/CPAN/
+
+=item Russia
+
+ ftp://ftp.chg.ru/pub/lang/perl/CPAN/
+ http://cpan.rinet.ru/
+ ftp://cpan.rinet.ru/pub/mirror/CPAN/
+ ftp://ftp.aha.ru/pub/CPAN/
+ ftp://ftp.corbina.ru/pub/CPAN/
+ http://cpan.sai.msu.ru/
+ ftp://ftp.sai.msu.su/pub/lang/perl/CPAN/
+
+=item Slovakia
+
+ ftp://ftp.cvt.stuba.sk/pub/CPAN/
+
+=item Slovenia
+
+ ftp://ftp.arnes.si/software/perl/CPAN/
+
+=item Spain
+
+ http://cpan.imasd.elmundo.es/
+ ftp://ftp.rediris.es/mirror/CPAN/
+ ftp://ftp.ri.telefonica-data.net/CPAN
+ ftp://ftp.etse.urv.es/pub/perl/
+
+=item Sweden
+
+ http://ftp.du.se/CPAN/
+ ftp://ftp.du.se/pub/CPAN/
+ http://mirror.dataphone.se/CPAN
+ ftp://mirror.dataphone.se/pub/CPAN
+ ftp://ftp.sunet.se/pub/lang/perl/CPAN/
+
+=item Switzerland
+
+ http://cpan.mirror.solnet.ch/
+ ftp://ftp.solnet.ch/mirror/CPAN/
+ ftp://ftp.danyk.ch/CPAN/
+ ftp://sunsite.cnlab-switch.ch/mirror/CPAN/
+
+=item Turkey
+
+ http://ftp.ulak.net.tr/perl/CPAN/
+ ftp://ftp.ulak.net.tr/perl/CPAN
+ ftp://sunsite.bilkent.edu.tr/pub/languages/CPAN/
+
+=item Ukraine
+
+ http://cpan.org.ua/
+ ftp://cpan.org.ua/
+ ftp://ftp.perl.org.ua/pub/CPAN/
+ http://no-more.kiev.ua/CPAN/
+ ftp://no-more.kiev.ua/pub/CPAN/
+
+=item United Kingdom
+
+ http://www.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN
+ ftp://ftp.mirror.ac.uk/sites/ftp.funet.fi/pub/languages/perl/CPAN/
+ http://cpan.teleglobe.net/
+ ftp://cpan.teleglobe.net/pub/CPAN
+ http://cpan.mirror.anlx.net/
+ ftp://ftp.mirror.anlx.net/CPAN/
+ http://cpan.etla.org/
+ ftp://cpan.etla.org/pub/CPAN
+ ftp://ftp.demon.co.uk/pub/CPAN/
+ http://cpan.m.flirble.org/
+ ftp://ftp.flirble.org/pub/languages/perl/CPAN/
+ ftp://ftp.plig.org/pub/CPAN/
+ http://cpan.hambule.co.uk/
+ http://cpan.mirrors.clockerz.net/
+ ftp://ftp.clockerz.net/pub/CPAN/
+ ftp://usit.shef.ac.uk/pub/packages/CPAN/
+
+=back
+
+=head2 North America
+
+=over 4
+
+=item Canada
+
+=over 8
+
+=item Alberta
+
+ http://cpan.sunsite.ualberta.ca/
+ ftp://cpan.sunsite.ualberta.ca/pub/CPAN/
+
+=item Manitoba
+
+ http://theoryx5.uwinnipeg.ca/pub/CPAN/
+ ftp://theoryx5.uwinnipeg.ca/pub/CPAN/
+
+=item Nova Scotia
+
+ ftp://cpan.chebucto.ns.ca/pub/CPAN/
+
+=item Ontario
+
+ ftp://ftp.nrc.ca/pub/CPAN/
+
+=back
+
+=item Mexico
+
+ http://cpan.azc.uam.mx
+ ftp://cpan.azc.uam.mx/mirrors/CPAN
+ http://www.cpan.unam.mx/
+ ftp://ftp.unam.mx/pub/CPAN
+ http://www.msg.com.mx/CPAN/
+ ftp://ftp.msg.com.mx/pub/CPAN/
+
+=item United States
+
+=over 8
+
+=item Alabama
+
+ http://mirror.hiwaay.net/CPAN/
+ ftp://mirror.hiwaay.net/CPAN/
+
+=item California
+
+ http://cpan.develooper.com/
+ http://www.cpan.org/
+ ftp://cpan.valueclick.com/pub/CPAN/
+ http://www.mednor.net/ftp/pub/mirrors/CPAN/
+ ftp://ftp.mednor.net/pub/mirrors/CPAN/
+ http://mirrors.gossamer-threads.com/CPAN
+ ftp://cpan.nas.nasa.gov/pub/perl/CPAN/
+ http://mirrors.kernel.org/cpan/
+ ftp://mirrors.kernel.org/pub/CPAN
+ http://cpan-sj.viaverio.com/
+ ftp://cpan-sj.viaverio.com/pub/CPAN/
+ http://cpan.digisle.net/
+ ftp://cpan.digisle.net/pub/CPAN
+ http://www.perl.com/CPAN/
+ http://www.uberlan.net/CPAN
+
+=item Colorado
+
+ ftp://ftp.cs.colorado.edu/pub/perl/CPAN/
+ http://cpan.four10.com
+
+=item Delaware
+
+ http://ftp.lug.udel.edu/pub/CPAN
+ ftp://ftp.lug.udel.edu/pub/CPAN
+
+=item District of Columbia
+
+ ftp://ftp.dc.aleron.net/pub/CPAN/
+
+=item Florida
+
+ ftp://ftp.cise.ufl.edu/pub/mirrors/CPAN/
+ http://mirror.csit.fsu.edu/pub/CPAN/
+ ftp://mirror.csit.fsu.edu/pub/CPAN/
+ http://cpan.mirrors.nks.net/
+
+=item Indiana
+
+ ftp://ftp.uwsg.iu.edu/pub/perl/CPAN/
+ http://cpan.netnitco.net/
+ ftp://cpan.netnitco.net/pub/mirrors/CPAN/
+ http://archive.progeny.com/CPAN/
+ ftp://archive.progeny.com/CPAN/
+ http://fx.saintjoe.edu/pub/CPAN
+ ftp://ftp.saintjoe.edu/pub/CPAN
+ http://csociety-ftp.ecn.purdue.edu/pub/CPAN
+ ftp://csociety-ftp.ecn.purdue.edu/pub/CPAN
+
+=item Kentucky
+
+ http://cpan.uky.edu/
+ ftp://cpan.uky.edu/pub/CPAN/
+ http://slugsite.louisville.edu/cpan
+ ftp://slugsite.louisville.edu/CPAN
+
+=item Massachusetts
+
+ http://mirrors.towardex.com/CPAN
+ ftp://mirrors.towardex.com/pub/CPAN
+ ftp://ftp.ccs.neu.edu/net/mirrors/ftp.funet.fi/pub/languages/perl/CPAN/
+
+=item Michigan
+
+ ftp://cpan.cse.msu.edu/
+ http://cpan.calvin.edu/pub/CPAN
+ ftp://cpan.calvin.edu/pub/CPAN
+
+=item Nevada
+
+ http://www.oss.redundant.com/pub/CPAN
+ ftp://www.oss.redundant.com/pub/CPAN
+
+=item New Jersey
+
+ http://ftp.cpanel.net/pub/CPAN/
+ ftp://ftp.cpanel.net/pub/CPAN/
+ http://cpan.teleglobe.net/
+ ftp://cpan.teleglobe.net/pub/CPAN
+
+=item New York
+
+ http://cpan.belfry.net/
+ http://cpan.erlbaum.net/
+ ftp://cpan.erlbaum.net/
+ http://cpan.thepirtgroup.com/
+ ftp://cpan.thepirtgroup.com/
+ ftp://ftp.stealth.net/pub/CPAN/
+ http://www.rge.com/pub/languages/perl/
+ ftp://ftp.rge.com/pub/languages/perl/
+
+=item North Carolina
+
+ http://www.ibiblio.org/pub/languages/perl/CPAN
+ ftp://ftp.ibiblio.org/pub/languages/perl/CPAN
+ ftp://ftp.duke.edu/pub/perl/
+ ftp://ftp.ncsu.edu/pub/mirror/CPAN/
+
+=item Oklahoma
+
+ ftp://ftp.ou.edu/mirrors/CPAN/
+
+=item Oregon
+
+ ftp://ftp.orst.edu/pub/CPAN
+
+=item Pennsylvania
+
+ http://ftp.epix.net/CPAN/
+ ftp://ftp.epix.net/pub/languages/perl/
+ http://mirrors.phenominet.com/pub/CPAN/
+ ftp://mirrors.phenominet.com/pub/CPAN/
+ http://cpan.pair.com/
+ ftp://cpan.pair.com/pub/CPAN/
+ ftp://carroll.cac.psu.edu/pub/CPAN/
+
+=item Tennessee
+
+ ftp://ftp.sunsite.utk.edu/pub/CPAN/
+
+=item Texas
+
+ http://ftp.sedl.org/pub/mirrors/CPAN/
+ http://www.binarycode.org/cpan
+ ftp://mirror.telentente.com/pub/CPAN
+ http://mirrors.theonlinerecordstore.com/CPAN
+
+=item Utah
+
+ ftp://mirror.xmission.com/CPAN/
+
+=item Virginia
+
+ http://cpan-du.viaverio.com/
+ ftp://cpan-du.viaverio.com/pub/CPAN/
+ http://mirrors.rcn.net/pub/lang/CPAN/
+ ftp://mirrors.rcn.net/pub/lang/CPAN/
+ http://perl.secsup.org/
+ ftp://perl.secsup.org/pub/perl/
+ http://noc.cvaix.com/mirrors/CPAN/
+
+=item Washington
+
+ http://cpan.llarian.net/
+ ftp://cpan.llarian.net/pub/CPAN/
+ http://cpan.mirrorcentral.com/
+ ftp://ftp.mirrorcentral.com/pub/CPAN/
+ ftp://ftp-mirror.internap.com/pub/CPAN/
+
+=item Wisconsin
+
+ http://mirror.sit.wisc.edu/pub/CPAN/
+ ftp://mirror.sit.wisc.edu/pub/CPAN/
+ http://mirror.aphix.com/CPAN
+ ftp://mirror.aphix.com/pub/CPAN
+
+=back
+
+=back
+
+=head2 Oceania
+
+=over 4
+
+=item Australia
+
+ http://ftp.planetmirror.com/pub/CPAN/
+ ftp://ftp.planetmirror.com/pub/CPAN/
+ ftp://mirror.aarnet.edu.au/pub/perl/CPAN/
+ ftp://cpan.topend.com.au/pub/CPAN/
+ http://cpan.mirrors.ilisys.com.au
+
+=item New Zealand
+
+ ftp://ftp.auckland.ac.nz/pub/perl/CPAN/
+
+=item United States
+
+ http://aniani.ifa.hawaii.edu/CPAN/
+ ftp://aniani.ifa.hawaii.edu/CPAN/
+
+=back
+
+=head2 South America
+
+=over 4
+
+=item Argentina
+
+ ftp://mirrors.bannerlandia.com.ar/mirrors/CPAN/
+ http://www.linux.org.ar/mirrors/cpan
+ ftp://ftp.linux.org.ar/mirrors/cpan
+
+=item Brazil
+
+ ftp://cpan.pop-mg.com.br/pub/CPAN/
+ ftp://ftp.matrix.com.br/pub/perl/CPAN/
+ http://cpan.hostsul.com.br/
+ ftp://cpan.hostsul.com.br/
+
+=item Chile
+
+ http://cpan.netglobalis.net/
+ ftp://cpan.netglobalis.net/pub/CPAN/
+
+=back
+
+=head2 RSYNC Mirrors
+
+ www.linux.org.ar::cpan
+ theoryx5.uwinnipeg.ca::CPAN
+ ftp.shellhung.org::CPAN
+ rsync.nic.funet.fi::CPAN
+ ftp.u-paris10.fr::CPAN
+ mir1.ovh.net::CPAN
+ rsync://ftp.crihan.fr::CPAN
+ ftp.gwdg.de::FTP/languages/perl/CPAN/
+ ftp.leo.org::CPAN
+ ftp.cbn.net.id::CPAN
+ rsync://ftp.heanet.ie/mirrors/ftp.perl.org/pub/CPAN
+ ftp.iglu.org.il::CPAN
+ gusp.dyndns.org::cpan
+ ftp.kddlabs.co.jp::cpan
+ ftp.ayamura.org::pub/CPAN/
+ mirror.leafbug.org::CPAN
+ rsync.en.com.sg::CPAN
+ mirror.averse.net::cpan
+ rsync.oss.eznetsols.org
+ ftp.kr.FreeBSD.org::CPAN
+ ftp.solnet.ch::CPAN
+ cpan.cdpa.nsysu.edu.tw::CPAN
+ cpan.teleglobe.net::CPAN
+ rsync://rsync.mirror.anlx.net::CPAN
+ ftp.sedl.org::cpan
+ ibiblio.org::CPAN
+ cpan-du.viaverio.com::CPAN
+ aniani.ifa.hawaii.edu::CPAN
+ archive.progeny.com::CPAN
+ rsync://slugsite.louisville.edu::CPAN
+ mirror.aphix.com::CPAN
+ cpan.teleglobe.net::CPAN
+ ftp.lug.udel.edu::cpan
+ mirrors.kernel.org::mirrors/CPAN
+ mirrors.phenominet.com::CPAN
+ cpan.pair.com::CPAN
+ cpan-sj.viaverio.com::CPAN
+ mirror.csit.fsu.edu::CPAN
+ csociety-ftp.ecn.purdue.edu::CPAN
+
+For an up-to-date listing of CPAN sites,
+see http://www.cpan.org/SITES or ftp://www.cpan.org/SITES .
+
+=head1 Modules: Creation, Use, and Abuse
+
+(The following section is borrowed directly from Tim Bunce's modules
+file, available at your nearest CPAN site.)
+
+Perl implements a class using a package, but the presence of a
+package doesn't imply the presence of a class. A package is just a
+namespace. A class is a package that provides subroutines that can be
+used as methods. A method is just a subroutine that expects, as its
+first argument, either the name of a package (for "static" methods),
+or a reference to something (for "virtual" methods).
+
+A module is a file that (by convention) provides a class of the same
+name (sans the .pm), plus an import method in that class that can be
+called to fetch exported symbols. This module may implement some of
+its methods by loading dynamic C or C++ objects, but that should be
+totally transparent to the user of the module. Likewise, the module
+might set up an AUTOLOAD function to slurp in subroutine definitions on
+demand, but this is also transparent. Only the F<.pm> file is required to
+exist. See L<perlsub>, L<perltoot>, and L<AutoLoader> for details about
+the AUTOLOAD mechanism.
+
+=head2 Guidelines for Module Creation
+
+=over 4
+
+=item *
+
+Do similar modules already exist in some form?
+
+If so, please try to reuse the existing modules either in whole or
+by inheriting useful features into a new class. If this is not
+practical try to get together with the module authors to work on
+extending or enhancing the functionality of the existing modules.
+A perfect example is the plethora of packages in perl4 for dealing
+with command line options.
+
+If you are writing a module to expand an already existing set of
+modules, please coordinate with the author of the package. It
+helps if you follow the same naming scheme and module interaction
+scheme as the original author.
+
+=item *
+
+Try to design the new module to be easy to extend and reuse.
+
+Try to C<use warnings;> (or C<use warnings qw(...);>).
+Remember that you can add C<no warnings qw(...);> to individual blocks
+of code that need less warnings.
+
+Use blessed references. Use the two argument form of bless to bless
+into the class name given as the first parameter of the constructor,
+e.g.,:
+
+ sub new {
+ my $class = shift;
+ return bless {}, $class;
+ }
+
+or even this if you'd like it to be used as either a static
+or a virtual method.
+
+ sub new {
+ my $self = shift;
+ my $class = ref($self) || $self;
+ return bless {}, $class;
+ }
+
+Pass arrays as references so more parameters can be added later
+(it's also faster). Convert functions into methods where
+appropriate. Split large methods into smaller more flexible ones.
+Inherit methods from other modules if appropriate.
+
+Avoid class name tests like: C<die "Invalid" unless ref $ref eq 'FOO'>.
+Generally you can delete the C<eq 'FOO'> part with no harm at all.
+Let the objects look after themselves! Generally, avoid hard-wired
+class names as far as possible.
+
+Avoid C<< $r->Class::func() >> where using C<@ISA=qw(... Class ...)> and
+C<< $r->func() >> would work (see L<perlbot> for more details).
+
+Use autosplit so little used or newly added functions won't be a
+burden to programs that don't use them. Add test functions to
+the module after __END__ either using AutoSplit or by saying:
+
+ eval join('',<main::DATA>) || die $@ unless caller();
+
+Does your module pass the 'empty subclass' test? If you say
+C<@SUBCLASS::ISA = qw(YOURCLASS);> your applications should be able
+to use SUBCLASS in exactly the same way as YOURCLASS. For example,
+does your application still work if you change: C<< $obj = YOURCLASS->new(); >>
+into: C<< $obj = SUBCLASS->new(); >> ?
+
+Avoid keeping any state information in your packages. It makes it
+difficult for multiple other packages to use yours. Keep state
+information in objects.
+
+Always use B<-w>.
+
+Try to C<use strict;> (or C<use strict qw(...);>).
+Remember that you can add C<no strict qw(...);> to individual blocks
+of code that need less strictness.
+
+Always use B<-w>.
+
+Follow the guidelines in the perlstyle(1) manual.
+
+Always use B<-w>.
+
+=item *
+
+Some simple style guidelines
+
+The perlstyle manual supplied with Perl has many helpful points.
+
+Coding style is a matter of personal taste. Many people evolve their
+style over several years as they learn what helps them write and
+maintain good code. Here's one set of assorted suggestions that
+seem to be widely used by experienced developers:
+
+Use underscores to separate words. It is generally easier to read
+$var_names_like_this than $VarNamesLikeThis, especially for
+non-native speakers of English. It's also a simple rule that works
+consistently with VAR_NAMES_LIKE_THIS.
+
+Package/Module names are an exception to this rule. Perl informally
+reserves lowercase module names for 'pragma' modules like integer
+and strict. Other modules normally begin with a capital letter and
+use mixed case with no underscores (need to be short and portable).
+
+You may find it helpful to use letter case to indicate the scope
+or nature of a variable. For example:
+
+ $ALL_CAPS_HERE constants only (beware clashes with Perl vars)
+ $Some_Caps_Here package-wide global/static
+ $no_caps_here function scope my() or local() variables
+
+Function and method names seem to work best as all lowercase.
+e.g., C<< $obj->as_string() >>.
+
+You can use a leading underscore to indicate that a variable or
+function should not be used outside the package that defined it.
+
+=item *
+
+Select what to export.
+
+Do NOT export method names!
+
+Do NOT export anything else by default without a good reason!
+
+Exports pollute the namespace of the module user. If you must
+export try to use @EXPORT_OK in preference to @EXPORT and avoid
+short or common names to reduce the risk of name clashes.
+
+Generally anything not exported is still accessible from outside the
+module using the ModuleName::item_name (or C<< $blessed_ref->method >>)
+syntax. By convention you can use a leading underscore on names to
+indicate informally that they are 'internal' and not for public use.
+
+(It is actually possible to get private functions by saying:
+C<my $subref = sub { ... }; &$subref;>. But there's no way to call that
+directly as a method, because a method must have a name in the symbol
+table.)
+
+As a general rule, if the module is trying to be object oriented
+then export nothing. If it's just a collection of functions then
+ at EXPORT_OK anything but use @EXPORT with caution.
+
+=item *
+
+Select a name for the module.
+
+This name should be as descriptive, accurate, and complete as
+possible. Avoid any risk of ambiguity. Always try to use two or
+more whole words. Generally the name should reflect what is special
+about what the module does rather than how it does it. Please use
+nested module names to group informally or categorize a module.
+There should be a very good reason for a module not to have a nested name.
+Module names should begin with a capital letter.
+
+Having 57 modules all called Sort will not make life easy for anyone
+(though having 23 called Sort::Quick is only marginally better :-).
+Imagine someone trying to install your module alongside many others.
+If in any doubt ask for suggestions in comp.lang.perl.misc.
+
+If you are developing a suite of related modules/classes it's good
+practice to use nested classes with a common prefix as this will
+avoid namespace clashes. For example: Xyz::Control, Xyz::View,
+Xyz::Model etc. Use the modules in this list as a naming guide.
+
+If adding a new module to a set, follow the original author's
+standards for naming modules and the interface to methods in
+those modules.
+
+If developing modules for private internal or project specific use,
+that will never be released to the public, then you should ensure
+that their names will not clash with any future public module. You
+can do this either by using the reserved Local::* category or by
+using a category name that includes an underscore like Foo_Corp::*.
+
+To be portable each component of a module name should be limited to
+11 characters. If it might be used on MS-DOS then try to ensure each is
+unique in the first 8 characters. Nested modules make this easier.
+
+=item *
+
+Have you got it right?
+
+How do you know that you've made the right decisions? Have you
+picked an interface design that will cause problems later? Have
+you picked the most appropriate name? Do you have any questions?
+
+The best way to know for sure, and pick up many helpful suggestions,
+is to ask someone who knows. Comp.lang.perl.misc is read by just about
+all the people who develop modules and it's the best place to ask.
+
+All you need to do is post a short summary of the module, its
+purpose and interfaces. A few lines on each of the main methods is
+probably enough. (If you post the whole module it might be ignored
+by busy people - generally the very people you want to read it!)
+
+Don't worry about posting if you can't say when the module will be
+ready - just say so in the message. It might be worth inviting
+others to help you, they may be able to complete it for you!
+
+=item *
+
+README and other Additional Files.
+
+It's well known that software developers usually fully document the
+software they write. If, however, the world is in urgent need of
+your software and there is not enough time to write the full
+documentation please at least provide a README file containing:
+
+=over 10
+
+=item *
+
+A description of the module/package/extension etc.
+
+=item *
+
+A copyright notice - see below.
+
+=item *
+
+Prerequisites - what else you may need to have.
+
+=item *
+
+How to build it - possible changes to Makefile.PL etc.
+
+=item *
+
+How to install it.
+
+=item *
+
+Recent changes in this release, especially incompatibilities
+
+=item *
+
+Changes / enhancements you plan to make in the future.
+
+=back
+
+If the README file seems to be getting too large you may wish to
+split out some of the sections into separate files: INSTALL,
+Copying, ToDo etc.
+
+=over 4
+
+=item *
+
+Adding a Copyright Notice.
+
+How you choose to license your work is a personal decision.
+The general mechanism is to assert your Copyright and then make
+a declaration of how others may copy/use/modify your work.
+
+Perl, for example, is supplied with two types of licence: The GNU GPL
+and The Artistic Licence (see the files README, Copying, and Artistic,
+or L<perlgpl> and L<perlartistic>). Larry has good reasons for NOT
+just using the GNU GPL.
+
+My personal recommendation, out of respect for Larry, Perl, and the
+Perl community at large is to state something simply like:
+
+ Copyright (c) 1995 Your Name. All rights reserved.
+ This program is free software; you can redistribute it and/or
+ modify it under the same terms as Perl itself.
+
+This statement should at least appear in the README file. You may
+also wish to include it in a Copying file and your source files.
+Remember to include the other words in addition to the Copyright.
+
+=item *
+
+Give the module a version/issue/release number.
+
+To be fully compatible with the Exporter and MakeMaker modules you
+should store your module's version number in a non-my package
+variable called $VERSION. This should be a floating point
+number with at least two digits after the decimal (i.e., hundredths,
+e.g, C<$VERSION = "0.01">). Don't use a "1.3.2" style version.
+See L<Exporter> for details.
+
+It may be handy to add a function or method to retrieve the number.
+Use the number in announcements and archive file names when
+releasing the module (ModuleName-1.02.tar.Z).
+See perldoc ExtUtils::MakeMaker.pm for details.
+
+=item *
+
+How to release and distribute a module.
+
+It's good idea to post an announcement of the availability of your
+module (or the module itself if small) to the comp.lang.perl.announce
+Usenet newsgroup. This will at least ensure very wide once-off
+distribution.
+
+If possible, register the module with CPAN. You should
+include details of its location in your announcement.
+
+Some notes about ftp archives: Please use a long descriptive file
+name that includes the version number. Most incoming directories
+will not be readable/listable, i.e., you won't be able to see your
+file after uploading it. Remember to send your email notification
+message as soon as possible after uploading else your file may get
+deleted automatically. Allow time for the file to be processed
+and/or check the file has been processed before announcing its
+location.
+
+FTP Archives for Perl Modules:
+
+Follow the instructions and links on:
+
+ http://www.cpan.org/modules/00modlist.long.html
+ http://www.cpan.org/modules/04pause.html
+
+or upload to one of these sites:
+
+ https://pause.kbx.de/pause/
+ http://pause.perl.org/pause/
+
+and notify <modules at perl.org>.
+
+By using the WWW interface you can ask the Upload Server to mirror
+your modules from your ftp or WWW site into your own directory on
+CPAN!
+
+Please remember to send me an updated entry for the Module list!
+
+=item *
+
+Take care when changing a released module.
+
+Always strive to remain compatible with previous released versions.
+Otherwise try to add a mechanism to revert to the
+old behavior if people rely on it. Document incompatible changes.
+
+=back
+
+=back
+
+=head2 Guidelines for Converting Perl 4 Library Scripts into Modules
+
+=over 4
+
+=item *
+
+There is no requirement to convert anything.
+
+If it ain't broke, don't fix it! Perl 4 library scripts should
+continue to work with no problems. You may need to make some minor
+changes (like escaping non-array @'s in double quoted strings) but
+there is no need to convert a .pl file into a Module for just that.
+
+=item *
+
+Consider the implications.
+
+All Perl applications that make use of the script will need to
+be changed (slightly) if the script is converted into a module. Is
+it worth it unless you plan to make other changes at the same time?
+
+=item *
+
+Make the most of the opportunity.
+
+If you are going to convert the script to a module you can use the
+opportunity to redesign the interface. The guidelines for module
+creation above include many of the issues you should consider.
+
+=item *
+
+The pl2pm utility will get you started.
+
+This utility will read *.pl files (given as parameters) and write
+corresponding *.pm files. The pl2pm utilities does the following:
+
+=over 10
+
+=item *
+
+Adds the standard Module prologue lines
+
+=item *
+
+Converts package specifiers from ' to ::
+
+=item *
+
+Converts die(...) to croak(...)
+
+=item *
+
+Several other minor changes
+
+=back
+
+Being a mechanical process pl2pm is not bullet proof. The converted
+code will need careful checking, especially any package statements.
+Don't delete the original .pl file till the new .pm one works!
+
+=back
+
+=head2 Guidelines for Reusing Application Code
+
+=over 4
+
+=item *
+
+Complete applications rarely belong in the Perl Module Library.
+
+=item *
+
+Many applications contain some Perl code that could be reused.
+
+Help save the world! Share your code in a form that makes it easy
+to reuse.
+
+=item *
+
+Break-out the reusable code into one or more separate module files.
+
+=item *
+
+Take the opportunity to reconsider and redesign the interfaces.
+
+=item *
+
+In some cases the 'application' can then be reduced to a small
+
+fragment of code built on top of the reusable modules. In these cases
+the application could invoked as:
+
+ % perl -e 'use Module::Name; method(@ARGV)' ...
+or
+ % perl -mModule::Name ... (in perl5.002 or higher)
+
+=back
+
+=head1 NOTE
+
+Perl does not enforce private and public parts of its modules as you may
+have been used to in other languages like C++, Ada, or Modula-17. Perl
+doesn't have an infatuation with enforced privacy. It would prefer
+that you stayed out of its living room because you weren't invited, not
+because it has a shotgun.
+
+The module and its user have a contract, part of which is common law,
+and part of which is "written". Part of the common law contract is
+that a module doesn't pollute any namespace it wasn't asked to. The
+written contract for the module (A.K.A. documentation) may make other
+provisions. But then you know when you C<use RedefineTheWorld> that
+you're redefining the world and willing to take the consequences.
Modified: trunk/contrib/perl/pod/perlmodstyle.pod
===================================================================
--- trunk/contrib/perl/pod/perlmodstyle.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlmodstyle.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -254,55 +254,58 @@
of interfaces available. There are pros and cons of each technique, which
should be considered when you design your API.
-According to Damian Conway, you should consider using OO:
+In I<Perl Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is the
+right fit for your problem:
=over 4
-=item *
+=item *
-When the system is large or likely to become so
+The system being designed is large, or is likely to become large.
-=item *
+=item *
-When the data is aggregated in obvious structures that will become objects
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
-=item *
+=item *
-When the types of data form a natural hierarchy that can make use of inheritance
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
=item *
-When operations on data vary according to data type (making
-polymorphic invocation of methods feasible)
+You have a piece of data on which many different operations are
+applied.
=item *
-When it is likely that new data types may be later introduced
-into the system, and will need to be handled by existing code
+You need to perform the same general operations on related types of
+data, but with slight variations depending on the specific type of data
+the operations are applied to.
=item *
-When interactions between data are best represented by
-overloaded operators
+It's likely you'll have to add new data types later.
=item *
-When the implementation of system components is likely to
-change over time (and hence should be encapsulated)
+The typical interactions between pieces of data are best represented by
+operators.
=item *
-When the system design is itself object-oriented
+The implementation of individual components of the system is likely to
+change over time.
=item *
-When large amounts of client code will use the software (and
-should be insulated from changes in its implementation)
+The system design is already object-oriented.
=item *
-When many separate operations will need to be applied to the
-same set of data
+Large numbers of other programmers will be using your code modules.
=back
Property changes on: trunk/contrib/perl/pod/perlmodstyle.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlmroapi.pod
===================================================================
--- trunk/contrib/perl/pod/perlmroapi.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlmroapi.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -9,7 +9,7 @@
The C3 method resolution order added in 5.10.0 has been re-implemented as
a plugin, without changing its Perl-space interface.
-Each plugin should register itself with C<Perl_mro_register> by providing
+Each plugin should register itself by providing
the following structure
struct mro_alg {
@@ -20,6 +20,10 @@
U32 hash;
};
+and calling C<Perl_mro_register>:
+
+ Perl_mro_register(aTHX_ &my_mro_alg);
+
=over 4
=item resolve
Property changes on: trunk/contrib/perl/pod/perlmroapi.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlnewmod.pod
===================================================================
--- trunk/contrib/perl/pod/perlnewmod.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlnewmod.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlnewmod.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlnumber.pod
===================================================================
--- trunk/contrib/perl/pod/perlnumber.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlnumber.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlnumber.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlobj.pod
===================================================================
--- trunk/contrib/perl/pod/perlobj.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlobj.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,595 +1,1047 @@
+=encoding utf8
+
+=for comment
+Consistent formatting of this file is achieved with:
+ perl ./Porting/podtidy pod/perlobj.pod
+
=head1 NAME
X<object> X<OOP>
-perlobj - Perl objects
+perlobj - Perl object reference
=head1 DESCRIPTION
-First you need to understand what references are in Perl.
-See L<perlref> for that. Second, if you still find the following
-reference work too complicated, a tutorial on object-oriented programming
-in Perl can be found in L<perltoot> and L<perltooc>.
+This document provides a reference for Perl's object orientation
+features. If you're looking for an introduction to object-oriented
+programming in Perl, please see L<perlootut>.
-If you're still with us, then
-here are three very simple definitions that you should find reassuring.
+In order to understand Perl objects, you first need to understand
+references in Perl. See L<perlref> for details.
+This document describes all of Perl's object-oriented (OO) features
+from the ground up. If you're just looking to write some
+object-oriented code of your own, you are probably better served by
+using one of the object systems from CPAN described in L<perlootut>.
+
+If you're looking to write your own object system, or you need to
+maintain code which implements objects from scratch then this document
+will help you understand exactly how Perl does object orientation.
+
+There are a few basic principles which define object oriented Perl:
+
=over 4
=item 1.
-An object is simply a reference that happens to know which class it
-belongs to.
+An object is simply a data structure that knows to which class it
+belongs.
=item 2.
-A class is simply a package that happens to provide methods to deal
-with object references.
+A class is simply a package. A class provides methods that expect to
+operate on objects.
=item 3.
-A method is simply a subroutine that expects an object reference (or
-a package name, for class methods) as the first argument.
+A method is simply a subroutine that expects a reference to an object
+(or a package name, for class methods) as the first argument.
=back
-We'll cover these points now in more depth.
+Let's look at each of these principles in depth.
-=head2 An Object is Simply a Reference
+=head2 An Object is Simply a Data Structure
X<object> X<bless> X<constructor> X<new>
-Unlike say C++, Perl doesn't provide any special syntax for
-constructors. A constructor is merely a subroutine that returns a
-reference to something "blessed" into a class, generally the
-class that the subroutine is defined in. Here is a typical
-constructor:
+Unlike many other languages which support object orientation, Perl does
+not provide any special syntax for constructing an object. Objects are
+merely Perl data structures (hashes, arrays, scalars, filehandles,
+etc.) that have been explicitly associated with a particular class.
- package Critter;
- sub new { bless {} }
+That explicit association is created by the built-in C<bless> function,
+which is typically used within the I<constructor> subroutine of the
+class.
-That word C<new> isn't special. You could have written
-a construct this way, too:
+Here is a simple constructor:
- package Critter;
- sub spawn { bless {} }
+ package File;
-This might even be preferable, because the C++ programmers won't
-be tricked into thinking that C<new> works in Perl as it does in C++.
-It doesn't. We recommend that you name your constructors whatever
-makes sense in the context of the problem you're solving. For example,
-constructors in the Tk extension to Perl are named after the widgets
-they create.
+ sub new {
+ my $class = shift;
-One thing that's different about Perl constructors compared with those in
-C++ is that in Perl, they have to allocate their own memory. (The other
-things is that they don't automatically call overridden base-class
-constructors.) The C<{}> allocates an anonymous hash containing no
-key/value pairs, and returns it The bless() takes that reference and
-tells the object it references that it's now a Critter, and returns
-the reference. This is for convenience, because the referenced object
-itself knows that it has been blessed, and the reference to it could
-have been returned directly, like this:
+ return bless {}, $class;
+ }
- sub new {
- my $self = {};
- bless $self;
- return $self;
- }
+The name C<new> isn't special. We could name our constructor something
+else:
-You often see such a thing in more complicated constructors
-that wish to call methods in the class as part of the construction:
+ package File;
- sub new {
- my $self = {};
- bless $self;
- $self->initialize();
- return $self;
- }
+ sub load {
+ my $class = shift;
-If you care about inheritance (and you should; see
-L<perlmodlib/"Modules: Creation, Use, and Abuse">),
-then you want to use the two-arg form of bless
-so that your constructors may be inherited:
+ return bless {}, $class;
+ }
- sub new {
- my $class = shift;
- my $self = {};
- bless $self, $class;
- $self->initialize();
- return $self;
- }
+The modern convention for OO modules is to always use C<new> as the
+name for the constructor, but there is no requirement to do so. Any
+subroutine that blesses a data structure into a class is a valid
+constructor in Perl.
-Or if you expect people to call not just C<< CLASS->new() >> but also
-C<< $obj->new() >>, then use something like the following. (Note that using
-this to call new() on an instance does not automatically perform any
-copying. If you want a shallow or deep copy of an object, you'll have to
-specifically allow for that.) The initialize() method used will be of
-whatever $class we blessed the object into:
+In the previous examples, the C<{}> code creates a reference to an
+empty anonymous hash. The C<bless> function then takes that reference
+and associates the hash with the class in C<$class>. In the simplest
+case, the C<$class> variable will end up containing the string "File".
- sub new {
- my $this = shift;
- my $class = ref($this) || $this;
- my $self = {};
- bless $self, $class;
- $self->initialize();
- return $self;
- }
+We can also use a variable to store a reference to the data structure
+that is being blessed as our object:
-Within the class package, the methods will typically deal with the
-reference as an ordinary reference. Outside the class package,
-the reference is generally treated as an opaque value that may
-be accessed only through the class's methods.
+ sub new {
+ my $class = shift;
-Although a constructor can in theory re-bless a referenced object
-currently belonging to another class, this is almost certainly going
-to get you into trouble. The new class is responsible for all
-cleanup later. The previous blessing is forgotten, as an object
-may belong to only one class at a time. (Although of course it's
-free to inherit methods from many classes.) If you find yourself
-having to do this, the parent class is probably misbehaving, though.
+ my $self = {};
+ bless $self, $class;
-A clarification: Perl objects are blessed. References are not. Objects
-know which package they belong to. References do not. The bless()
-function uses the reference to find the object. Consider
-the following example:
+ return $self;
+ }
- $a = {};
- $b = $a;
- bless $a, BLAH;
- print "\$b is a ", ref($b), "\n";
+Once we've blessed the hash referred to by C<$self> we can start
+calling methods on it. This is useful if you want to put object
+initialization in its own separate method:
-This reports $b as being a BLAH, so obviously bless()
-operated on the object and not on the reference.
+ sub new {
+ my $class = shift;
-=head2 A Class is Simply a Package
-X<class> X<package> X<@ISA> X<inheritance>
+ my $self = {};
+ bless $self, $class;
-Unlike say C++, Perl doesn't provide any special syntax for class
-definitions. You use a package as a class by putting method
-definitions into the class.
+ $self->_initialize();
-There is a special array within each package called @ISA, which says
-where else to look for a method if you can't find it in the current
-package. This is how Perl implements inheritance. Each element of the
- at ISA array is just the name of another package that happens to be a
-class package. The classes are searched for missing methods in
-depth-first, left-to-right order by default (see L<mro> for alternative
-search order and other in-depth information). The classes accessible
-through @ISA are known as base classes of the current class.
+ return $self;
+ }
-All classes implicitly inherit from class C<UNIVERSAL> as their
-last base class. Several commonly used methods are automatically
-supplied in the UNIVERSAL class; see L<"Default UNIVERSAL methods"> or
-L<UNIVERSAL|UNIVERSAL> for more details.
-X<UNIVERSAL> X<base class> X<class, base>
+Since the object is also a hash, you can treat it as one, using it to
+store data associated with the object. Typically, code inside the class
+can treat the hash as an accessible data structure, while code outside
+the class should always treat the object as opaque. This is called
+B<encapsulation>. Encapsulation means that the user of an object does
+not have to know how it is implemented. The user simply calls
+documented methods on the object.
-If a missing method is found in a base class, it is cached
-in the current class for efficiency. Changing @ISA or defining new
-subroutines invalidates the cache and causes Perl to do the lookup again.
+Note, however, that (unlike most other OO languages) Perl does not
+ensure or enforce encapsulation in any way. If you want objects to
+actually I<be> opaque you need to arrange for that yourself. This can
+be done in a varierty of ways, including using L<"Inside-Out objects">
+or modules from CPAN.
-If neither the current class, its named base classes, nor the UNIVERSAL
-class contains the requested method, these three places are searched
-all over again, this time looking for a method named AUTOLOAD(). If an
-AUTOLOAD is found, this method is called on behalf of the missing method,
-setting the package global $AUTOLOAD to be the fully qualified name of
-the method that was intended to be called.
-X<AUTOLOAD>
+=head3 Objects Are Blessed; Variables Are Not
-If none of that works, Perl finally gives up and complains.
+When we bless something, we are not blessing the variable which
+contains a reference to that thing, nor are we blessing the reference
+that the variable stores; we are blessing the thing that the variable
+refers to (sometimes known as the I<referent>). This is best
+demonstrated with this code:
-If you want to stop the AUTOLOAD inheritance say simply
-X<AUTOLOAD>
+ use Scalar::Util 'blessed';
- sub AUTOLOAD;
+ my $foo = {};
+ my $bar = $foo;
-and the call will die using the name of the sub being called.
+ bless $foo, 'Class';
+ print blessed( $bar ); # prints "Class"
-Perl classes do method inheritance only. Data inheritance is left up
-to the class itself. By and large, this is not a problem in Perl,
-because most classes model the attributes of their object using an
-anonymous hash, which serves as its own little namespace to be carved up
-by the various classes that might want to do something with the object.
-The only problem with this is that you can't sure that you aren't using
-a piece of the hash that isn't already used. A reasonable workaround
-is to prepend your fieldname in the hash with the package name.
-X<inheritance, method> X<inheritance, data>
+ $bar = "some other value";
+ print blessed( $bar ); # prints undef
- sub bump {
- my $self = shift;
- $self->{ __PACKAGE__ . ".count"}++;
- }
+When we call C<bless> on a variable, we are actually blessing the
+underlying data structure that the variable refers to. We are not
+blessing the reference itself, nor the variable that contains that
+reference. That's why the second call to C<blessed( $bar )> returns
+false. At that point C<$bar> is no longer storing a reference to an
+object.
+You will sometimes see older books or documentation mention "blessing a
+reference" or describe an object as a "blessed reference", but this is
+incorrect. It isn't the reference that is blessed as an object; it's
+the thing the reference refers to (i.e. the referent).
+
+=head2 A Class is Simply a Package
+X<class> X<package> X<@ISA> X<inheritance>
+
+Perl does not provide any special syntax for class definitions. A
+package is simply a namespace containing variables and subroutines. The
+only difference is that in a class, the subroutines may expect a
+reference to an object or the name of a class as the first argument.
+This is purely a matter of convention, so a class may contain both
+methods and subroutines which I<don't> operate on an object or class.
+
+Each package contains a special array called C<@ISA>. The C<@ISA> array
+contains a list of that class's parent classes, if any. This array is
+examined when Perl does method resolution, which we will cover later.
+
+It is possible to manually set C<@ISA>, and you may see this in older
+Perl code. Much older code also uses the L<base> pragma. For new code,
+we recommend that you use the L<parent> pragma to declare your parents.
+This pragma will take care of setting C<@ISA>. It will also load the
+parent classes and make sure that the package doesn't inherit from
+itself.
+
+However the parent classes are set, the package's C<@ISA> variable will
+contain a list of those parents. This is simply a list of scalars, each
+of which is a string that corresponds to a package name.
+
+All classes inherit from the L<UNIVERSAL> class implicitly. The
+L<UNIVERSAL> class is implemented by the Perl core, and provides
+several default methods, such as C<isa()>, C<can()>, and C<VERSION()>.
+The C<UNIVERSAL> class will I<never> appear in a package's C<@ISA>
+variable.
+
+Perl I<only> provides method inheritance as a built-in feature.
+Attribute inheritance is left up the class to implement. See the
+L</Writing Accessors> section for details.
+
=head2 A Method is Simply a Subroutine
X<method>
-Unlike say C++, Perl doesn't provide any special syntax for method
-definition. (It does provide a little syntax for method invocation
-though. More on that later.) A method expects its first argument
-to be the object (reference) or package (string) it is being invoked
-on. There are two ways of calling methods, which we'll call class
-methods and instance methods.
+Perl does not provide any special syntax for defining a method. A
+method is simply a regular subroutine, and is declared with C<sub>.
+What makes a method special is that it expects to receive either an
+object or a class name as its first argument.
-A class method expects a class name as the first argument. It
-provides functionality for the class as a whole, not for any
-individual object belonging to the class. Constructors are often
-class methods, but see L<perltoot> and L<perltooc> for alternatives.
-Many class methods simply ignore their first argument, because they
-already know what package they're in and don't care what package
-they were invoked via. (These aren't necessarily the same, because
-class methods follow the inheritance tree just like ordinary instance
-methods.) Another typical use for class methods is to look up an
-object by name:
+Perl I<does> provide special syntax for method invocation, the C<< ->
+>> operator. We will cover this in more detail later.
- sub find {
- my ($class, $name) = @_;
- $objtable{$name};
- }
+Most methods you write will expect to operate on objects:
-An instance method expects an object reference as its first argument.
-Typically it shifts the first argument into a "self" or "this" variable,
-and then uses that as an ordinary reference.
+ sub save {
+ my $self = shift;
- sub display {
- my $self = shift;
- my @keys = @_ ? @_ : sort keys %$self;
- foreach $key (@keys) {
- print "\t$key => $self->{$key}\n";
- }
- }
+ open my $fh, '>', $self->path() or die $!;
+ print {$fh} $self->data() or die $!;
+ close $fh or die $!;
+ }
=head2 Method Invocation
X<invocation> X<method> X<arrow> X<< -> >>
-For various historical and other reasons, Perl offers two equivalent
-ways to write a method call. The simpler and more common way is to use
-the arrow notation:
+Calling a method on an object is written as C<< $object->method >>.
- my $fred = Critter->find("Fred");
- $fred->display("Height", "Weight");
+The left hand side of the method invocation (or arrow) operator is the
+object (or class name), and the right hand side is the method name.
-You should already be familiar with the use of the C<< -> >> operator with
-references. In fact, since C<$fred> above is a reference to an object,
-you could think of the method call as just another form of
-dereferencing.
+ my $pod = File->new( 'perlobj.pod', $data );
+ $pod->save();
-Whatever is on the left side of the arrow, whether a reference or a
-class name, is passed to the method subroutine as its first argument.
-So the above code is mostly equivalent to:
+The C<< -> >> syntax is also used when dereferencing a reference. It
+looks like the same operator, but these are two different operations.
- my $fred = Critter::find("Critter", "Fred");
- Critter::display($fred, "Height", "Weight");
+When you call a method, the thing on the left side of the arrow is
+passed as the first argument to the method. That means when we call C<<
+Critter->new() >>, the C<new()> method receives the string C<"Critter">
+as its first argument. When we call C<< $fred->speak() >>, the C<$fred>
+variable is passed as the first argument to C<speak()>.
-How does Perl know which package the subroutine is in? By looking at
-the left side of the arrow, which must be either a package name or a
-reference to an object, i.e. something that has been blessed to a
-package. Either way, that's the package where Perl starts looking. If
-that package has no subroutine with that name, Perl starts looking for
-it in any base classes of that package, and so on.
+Just as with any Perl subroutine, all of the arguments passed in C<@_>
+are aliases to the original argument. This includes the object itself.
+If you assign directly to C<$_[0]> you will change the contents of the
+variable that holds the reference to the object. We recommend that you
+don't do this unless you know exactly what you're doing.
-If you need to, you I<can> force Perl to start looking in some other package:
+Perl knows what package the method is in by looking at the left side of
+the arrow. If the left hand side is a package name, it looks for the
+method in that package. If the left hand side is an object, then Perl
+looks for the method in the package that the object has been blessed
+into.
- my $barney = MyCritter->Critter::find("Barney");
- $barney->Critter::display("Height", "Weight");
+If the left hand side is neither a package name nor an object, then the
+method call will cause an error, but see the section on L</Method Call
+Variations> for more nuances.
-Here C<MyCritter> is presumably a subclass of C<Critter> that defines
-its own versions of find() and display(). We haven't specified what
-those methods do, but that doesn't matter above since we've forced Perl
-to start looking for the subroutines in C<Critter>.
+=head2 Inheritance
+X<inheritance>
-As a special case of the above, you may use the C<SUPER> pseudo-class to
-tell Perl to start looking for the method in the packages named in the
-current class's C<@ISA> list.
-X<SUPER>
+We already talked about the special C<@ISA> array and the L<parent>
+pragma.
- package MyCritter;
- use base 'Critter'; # sets @MyCritter::ISA = ('Critter');
+When a class inherits from another class, any methods defined in the
+parent class are available to the child class. If you attempt to call a
+method on an object that isn't defined in its own class, Perl will also
+look for that method in any parent classes it may have.
- sub display {
- my ($self, @args) = @_;
- $self->SUPER::display("Name", @args);
- }
+ package File::MP3;
+ use parent 'File'; # sets @File::MP3::ISA = ('File');
-It is important to note that C<SUPER> refers to the superclass(es) of the
-I<current package> and not to the superclass(es) of the object. Also, the
-C<SUPER> pseudo-class can only currently be used as a modifier to a method
-name, but not in any of the other ways that class names are normally used,
-eg:
+ my $mp3 = File::MP3->new( 'Andvari.mp3', $data );
+ $mp3->save();
+
+Since we didn't define a C<save()> method in the C<File::MP3> class,
+Perl will look at the C<File::MP3> class's parent classes to find the
+C<save()> method. If Perl cannot find a C<save()> method anywhere in
+the inheritance hierarchy, it will die.
+
+In this case, it finds a C<save()> method in the C<File> class. Note
+that the object passed to C<save()> in this case is still a
+C<File::MP3> object, even though the method is found in the C<File>
+class.
+
+We can override a parent's method in a child class. When we do so, we
+can still call the parent class's method with the C<SUPER>
+pseudo-class.
+
+ sub save {
+ my $self = shift;
+
+ say 'Prepare to rock';
+ $self->SUPER::save();
+ }
+
+The C<SUPER> modifier can I<only> be used for method calls. You can't
+use it for regular subroutine calls or class methods:
+
+ SUPER::save($thing); # FAIL: looks for save() sub in package SUPER
+
+ SUPER->save($thing); # FAIL: looks for save() method in class
+ # SUPER
+
+ $thing->SUPER::save(); # Okay: looks for save() method in parent
+ # classes
+
+
+=head3 How SUPER is Resolved
X<SUPER>
- something->SUPER::method(...); # OK
- SUPER::method(...); # WRONG
- SUPER->method(...); # WRONG
+The C<SUPER> pseudo-class is resolved from the package where the call
+is made. It is I<not> resolved based on the object's class. This is
+important, because it lets methods at different levels within a deep
+inheritance hierarchy each correctly call their respective parent
+methods.
-Instead of a class name or an object reference, you can also use any
-expression that returns either of those on the left side of the arrow.
-So the following statement is valid:
+ package A;
- Critter->find("Fred")->display("Height", "Weight");
+ sub new {
+ return bless {}, shift;
+ }
-and so is the following:
+ sub speak {
+ my $self = shift;
- my $fred = (reverse "rettirC")->find(reverse "derF");
+ say 'A';
+ }
-The right side of the arrow typically is the method name, but a simple
-scalar variable containing either the method name or a subroutine
-reference can also be used.
+ package B;
-If the right side of the arrow is a scalar containing a reference
-to a subroutine, then this is equivalent to calling the referenced
-subroutine directly with the class name or object on the left side
-of the arrow as its first argument. No lookup is done and there is
-no requirement that the subroutine be defined in any package related
-to the class name or object on the left side of the arrow.
+ use parent -norequire, 'A';
-For example, the following calls to $display are equivalent:
+ sub speak {
+ my $self = shift;
- my $display = sub { my $self = shift; ... };
- $fred->$display("Height", "Weight");
- $display->($fred, "Height", "Weight");
+ $self->SUPER::speak();
-=head2 Indirect Object Syntax
-X<indirect object syntax> X<invocation, indirect> X<indirect>
+ say 'B';
+ }
-The other way to invoke a method is by using the so-called "indirect
-object" notation. This syntax was available in Perl 4 long before
-objects were introduced, and is still used with filehandles like this:
+ package C;
- print STDERR "help!!!\n";
+ use parent -norequire, 'B';
-The same syntax can be used to call either object or class methods.
+ sub speak {
+ my $self = shift;
- my $fred = find Critter "Fred";
- display $fred "Height", "Weight";
+ $self->SUPER::speak();
-Notice that there is no comma between the object or class name and the
-parameters. This is how Perl can tell you want an indirect method call
-instead of an ordinary subroutine call.
+ say 'C';
+ }
-But what if there are no arguments? In that case, Perl must guess what
-you want. Even worse, it must make that guess I<at compile time>.
-Usually Perl gets it right, but when it doesn't you get a function
-call compiled as a method, or vice versa. This can introduce subtle bugs
-that are hard to detect.
+ my $c = C->new();
+ $c->speak();
-For example, a call to a method C<new> in indirect notation (as C++
-programmers are wont to make) can be miscompiled into a subroutine
-call if there's already a C<new> function in scope. You'd end up
-calling the current package's C<new> as a subroutine, rather than the
-desired class's method. The compiler tries to cheat by remembering
-bareword C<require>s, but the grief when it messes up just isn't worth the
-years of debugging it will take you to track down such subtle bugs.
+In this example, we will get the following output:
-There is another problem with this syntax: the indirect object is
-limited to a name, a scalar variable, or a block, because it would have
-to do too much lookahead otherwise, just like any other postfix
-dereference in the language. (These are the same quirky rules as are
-used for the filehandle slot in functions like C<print> and C<printf>.)
-This can lead to horribly confusing precedence problems, as in these
-next two lines:
+ A
+ B
+ C
- move $obj->{FIELD}; # probably wrong!
- move $ary[$i]; # probably wrong!
+This demonstrates how C<SUPER> is resolved. Even though the object is
+blessed into the C<C> class, the C<speak()> method in the C<B> class
+can still call C<SUPER::speak()> and expect it to correctly look in the
+parent class of C<B> (i.e the class the method call is in), not in the
+parent class of C<C> (i.e. the class the object belongs to).
-Those actually parse as the very surprising:
+There are rare cases where this package-based resolution can be a
+problem. If you copy a subroutine from one package to another, C<SUPER>
+resolution will be done based on the original package.
- $obj->move->{FIELD}; # Well, lookee here
- $ary->move([$i]); # Didn't expect this one, eh?
+=head3 Multiple Inheritance
+X<multiple inheritance>
-Rather than what you might have expected:
+Multiple inheritance often indicates a design problem, but Perl always
+gives you enough rope to hang yourself with if you ask for it.
- $obj->{FIELD}->move(); # You should be so lucky.
- $ary[$i]->move; # Yeah, sure.
+To declare multiple parents, you simply need to pass multiple class
+names to C<use parent>:
-To get the correct behavior with indirect object syntax, you would have
-to use a block around the indirect object:
+ package MultiChild;
- move {$obj->{FIELD}};
- move {$ary[$i]};
+ use parent 'Parent1', 'Parent2';
-Even then, you still have the same potential problem if there happens to
-be a function named C<move> in the current package. B<The C<< -> >>
-notation suffers from neither of these disturbing ambiguities, so we
-recommend you use it exclusively.> However, you may still end up having
-to read code using the indirect object notation, so it's important to be
-familiar with it.
+=head3 Method Resolution Order
+X<method resolution order> X<mro>
-=head2 Default UNIVERSAL methods
+Method resolution order only matters in the case of multiple
+inheritance. In the case of single inheritance, Perl simply looks up
+the inheritance chain to find a method:
+
+ Grandparent
+ |
+ Parent
+ |
+ Child
+
+If we call a method on a C<Child> object and that method is not defined
+in the C<Child> class, Perl will look for that method in the C<Parent>
+class and then, if necessary, in the C<Grandparent> class.
+
+If Perl cannot find the method in any of these classes, it will die
+with an error message.
+
+When a class has multiple parents, the method lookup order becomes more
+complicated.
+
+By default, Perl does a depth-first left-to-right search for a method.
+That means it starts with the first parent in the C<@ISA> array, and
+then searches all of its parents, grandparents, etc. If it fails to
+find the method, it then goes to the next parent in the original
+class's C<@ISA> array and searches from there.
+
+ SharedGreatGrandParent
+ / \
+ PaternalGrandparent MaternalGrandparent
+ \ /
+ Father Mother
+ \ /
+ Child
+
+So given the diagram above, Perl will search C<Child>, C<Father>,
+C<PaternalGrandparent>, C<SharedGreatGrandParent>, C<Mother>, and
+finally C<MaternalGrandparent>. This may be a problem because now we're
+looking in C<SharedGreatGrandParent> I<before> we've checked all its
+derived classes (i.e. before we tried C<Mother> and
+C<MaternalGrandparent>).
+
+It is possible to ask for a different method resolution order with the
+L<mro> pragma.
+
+ package Child;
+
+ use mro 'c3';
+ use parent 'Father', 'Mother';
+
+This pragma lets you switch to the "C3" resolution order. In simple
+terms, "C3" order ensures that shared parent classes are never searched
+before child classes, so Perl will now search: C<Child>, C<Father>,
+C<PaternalGrandparent>, C<Mother> C<MaternalGrandparent>, and finally
+C<SharedGreatGrandParent>. Note however that this is not
+"breadth-first" searching: All the C<Father> ancestors (except the
+common ancestor) are searched before any of the C<Mother> ancestors are
+considered.
+
+The C3 order also lets you call methods in sibling classes with the
+C<next> pseudo-class. See the L<mro> documentation for more details on
+this feature.
+
+=head3 Method Resolution Caching
+
+When Perl searches for a method, it caches the lookup so that future
+calls to the method do not need to search for it again. Changing a
+class's parent class or adding subroutines to a class will invalidate
+the cache for that class.
+
+The L<mro> pragma provides some functions for manipulating the method
+cache directly.
+
+=head2 Writing Constructors
+X<constructor>
+
+As we mentioned earlier, Perl provides no special constructor syntax.
+This means that a class must implement its own constructor. A
+constructor is simply a class method that returns a reference to a new
+object.
+
+The constructor can also accept additional parameters that define the
+object. Let's write a real constructor for the C<File> class we used
+earlier:
+
+ package File;
+
+ sub new {
+ my $class = shift;
+ my ( $path, $data ) = @_;
+
+ my $self = bless {
+ path => $path,
+ data => $data,
+ }, $class;
+
+ return $self;
+ }
+
+As you can see, we've stored the path and file data in the object
+itself. Remember, under the hood, this object is still just a hash.
+Later, we'll write accessors to manipulate this data.
+
+For our File::MP3 class, we can check to make sure that the path we're
+given ends with ".mp3":
+
+ package File::MP3;
+
+ sub new {
+ my $class = shift;
+ my ( $path, $data ) = @_;
+
+ die "You cannot create a File::MP3 without an mp3 extension\n"
+ unless $path =~ /\.mp3\z/;
+
+ return $class->SUPER::new(@_);
+ }
+
+This constructor lets its parent class do the actual object
+construction.
+
+=head2 Attributes
+X<attribute>
+
+An attribute is a piece of data belonging to a particular object.
+Unlike most object-oriented languages, Perl provides no special syntax
+or support for declaring and manipulating attributes.
+
+Attributes are often stored in the object itself. For example, if the
+object is an anonymous hash, we can store the attribute values in the
+hash using the attribute name as the key.
+
+While it's possible to refer directly to these hash keys outside of the
+class, it's considered a best practice to wrap all access to the
+attribute with accessor methods.
+
+This has several advantages. Accessors make it easier to change the
+implementation of an object later while still preserving the original
+API.
+
+An accessor lets you add additional code around attribute access. For
+example, you could apply a default to an attribute that wasn't set in
+the constructor, or you could validate that a new value for the
+attribute is acceptable.
+
+Finally, using accessors makes inheritance much simpler. Subclasses can
+use the accessors rather than having to know how a parent class is
+implemented internally.
+
+=head3 Writing Accessors
+X<accessor>
+
+As with constructors, Perl provides no special accessor declaration
+syntax, so classes must provide explicitly written accessor methods.
+There are two common types of accessors, read-only and read-write.
+
+A simple read-only accessor simply gets the value of a single
+attribute:
+
+ sub path {
+ my $self = shift;
+
+ return $self->{path};
+ }
+
+A read-write accessor will allow the caller to set the value as well as
+get it:
+
+ sub path {
+ my $self = shift;
+
+ if (@_) {
+ $self->{path} = shift;
+ }
+
+ return $self->{path};
+ }
+
+=head2 An Aside About Smarter and Safer Code
+
+Our constructor and accessors are not very smart. They don't check that
+a C<$path> is defined, nor do they check that a C<$path> is a valid
+filesystem path.
+
+Doing these checks by hand can quickly become tedious. Writing a bunch
+of accessors by hand is also incredibly tedious. There are a lot of
+modules on CPAN that can help you write safer and more concise code,
+including the modules we recommend in L<perlootut>.
+
+=head2 Method Call Variations
+X<method>
+
+Perl supports several other ways to call methods besides the C<<
+$object->method() >> usage we've seen so far.
+
+=head3 Method Names as Strings
+
+Perl lets you use a scalar variable containing a string as a method
+name:
+
+ my $file = File->new( $path, $data );
+
+ my $method = 'save';
+ $file->$method();
+
+This works exactly like calling C<< $file->save() >>. This can be very
+useful for writing dynamic code. For example, it allows you to pass a
+method name to be called as a parameter to another method.
+
+=head3 Class Names as Strings
+
+Perl also lets you use a scalar containing a string as a class name:
+
+ my $class = 'File';
+
+ my $file = $class->new( $path, $data );
+
+Again, this allows for very dynamic code.
+
+=head3 Subroutine References as Methods
+
+You can also use a subroutine reference as a method:
+
+ my $sub = sub {
+ my $self = shift;
+
+ $self->save();
+ };
+
+ $file->$sub();
+
+This is exactly equivalent to writing C<< $sub->($file) >>. You may see
+this idiom in the wild combined with a call to C<can>:
+
+ if ( my $meth = $object->can('foo') ) {
+ $object->$meth();
+ }
+
+=head3 Deferencing Method Call
+
+Perl also lets you use a dereferenced scalar reference in a method
+call. That's a mouthful, so let's look at some code:
+
+ $file->${ \'save' };
+ $file->${ returns_scalar_ref() };
+ $file->${ \( returns_scalar() ) };
+ $file->${ returns_ref_to_sub_ref() };
+
+This works if the dereference produces a string I<or> a subroutine
+reference.
+
+=head3 Method Calls on Filehandles
+
+Under the hood, Perl filehandles are instances of the C<IO::Handle> or
+C<IO::File> class. Once you have an open filehandle, you can call
+methods on it. Additionally, you can call methods on the C<STDIN>,
+C<STDOUT>, and C<STDERR> filehandles.
+
+ open my $fh, '>', 'path/to/file';
+ $fh->autoflush();
+ $fh->print('content');
+
+ STDOUT->autoflush();
+
+=head2 Invoking Class Methods
+X<invocation>
+
+Because Perl allows you to use barewords for package names and
+subroutine names, it sometimes interprets a bareword's meaning
+incorrectly. For example, the construct C<< Class->new() >> can be
+interpreted as either C<< 'Class'->new() >> or C<< Class()->new() >>.
+In English, that second interpretation reads as "call a subroutine
+named Class(), then call new() as a method on the return value of
+Class()". If there is a subroutine named C<Class()> in the current
+namespace, Perl will always interpret C<< Class->new() >> as the second
+alternative: a call to C<new()> on the object returned by a call to
+C<Class()>
+
+You can force Perl to use the first interpretation (i.e. as a method
+call on the class named "Class") in two ways. First, you can append a
+C<::> to the class name:
+
+ Class::->new()
+
+Perl will always interpret this as a method call.
+
+Alternatively, you can quote the class name:
+
+ 'Class'->new()
+
+Of course, if the class name is in a scalar Perl will do the right
+thing as well:
+
+ my $class = 'Class';
+ $class->new();
+
+=head3 Indirect Object Syntax
+X<indirect object>
+
+B<Outside of the file handle case, use of this syntax is discouraged as
+it can confuse the Perl interpreter. See below for more details.>
+
+Perl suports another method invocation syntax called "indirect object"
+notation. This syntax is called "indirect" because the method comes
+before the object it is being invoked on.
+
+This syntax can be used with any class or object method:
+
+ my $file = new File $path, $data;
+ save $file;
+
+We recommend that you avoid this syntax, for several reasons.
+
+First, it can be confusing to read. In the above example, it's not
+clear if C<save> is a method provided by the C<File> class or simply a
+subroutine that expects a file object as its first argument.
+
+When used with class methods, the problem is even worse. Because Perl
+allows subroutine names to be written as barewords, Perl has to guess
+whether the bareword after the method is a class name or subroutine
+name. In other words, Perl can resolve the syntax as either C<<
+File->new( $path, $data ) >> B<or> C<< new( File( $path, $data ) ) >>.
+
+To parse this code, Perl uses a heuristic based on what package names
+it has seen, what subroutines exist in the current package, what
+barewords it has previously seen, and other input. Needless to say,
+heuristics can produce very surprising results!
+
+Older documentation (and some CPAN modules) encouraged this syntax,
+particularly for constructors, so you may still find it in the wild.
+However, we encourage you to avoid using it in new code.
+
+You can force Perl to interpret the bareword as a class name by
+appending "::" to it, like we saw earlier:
+
+ my $file = new File:: $path, $data;
+
+=head2 C<bless>, C<blessed>, and C<ref>
+
+As we saw earlier, an object is simply a data structure that has been
+blessed into a class via the C<bless> function. The C<bless> function
+can take either one or two arguments:
+
+ my $object = bless {}, $class;
+ my $object = bless {};
+
+In the first form, the anonymous hash is being blessed into the class
+in C<$class>. In the second form, the anonymous hash is blessed into
+the current package.
+
+The second form is strongly discouraged, because it breaks the ability
+of a subclass to reuse the parent's constructor, but you may still run
+across it in existing code.
+
+If you want to know whether a particular scalar refers to an object,
+you can use the C<blessed> function exported by L<Scalar::Util>, which
+is shipped with the Perl core.
+
+ use Scalar::Util 'blessed';
+
+ if ( defined blessed($thing) ) { ... }
+
+If C<$thing> refers to an object, then this function returns the name
+of the package the object has been blessed into. If C<$thing> doesn't
+contain a reference to a blessed object, the C<blessed> function
+returns C<undef>.
+
+Note that C<blessed($thing)> will also return false if C<$thing> has
+been blessed into a class named "0". This is a possible, but quite
+pathological. Don't create a class named "0" unless you know what
+you're doing.
+
+Similarly, Perl's built-in C<ref> function treats a reference to a
+blessed object specially. If you call C<ref($thing)> and C<$thing>
+holds a reference to an object, it will return the name of the class
+that the object has been blessed into.
+
+If you simply want to check that a variable contains an object
+reference, we recommend that you use C<defined blessed($object)>, since
+C<ref> returns true values for all references, not just objects.
+
+=head2 The UNIVERSAL Class
X<UNIVERSAL>
-The C<UNIVERSAL> package automatically contains the following methods that
-are inherited by all other classes:
+All classes automatically inherit from the L<UNIVERSAL> class, which is
+built-in to the Perl core. This class provides a number of methods, all
+of which can be called on either a class or an object. You can also
+choose to override some of these methods in your class. If you do so,
+we recommend that you follow the built-in semantics described below.
=over 4
-=item isa(CLASS)
+=item isa($class)
X<isa>
-C<isa> returns I<true> if its object is blessed into a subclass of C<CLASS>
+The C<isa> method returns I<true> if the object is a member of the
+class in C<$class>, or a member of a subclass of C<$class>.
-=item DOES(ROLE)
+If you override this method, it should never throw an exception.
+
+=item DOES($role)
X<DOES>
-C<DOES> returns I<true> if its object claims to perform the role C<ROLE>. By
-default, this is equivalent to C<isa>.
+The C<DOES> method returns I<true> if its object claims to perform the
+role C<$role>. By default, this is equivalent to C<isa>. This method is
+provided for use by object system extensions that implement roles, like
+C<Moose> and C<Role::Tiny>.
-=item can(METHOD)
+You can also override C<DOES> directly in your own classes. If you
+override this method, it should never throw an exception.
+
+=item can($method)
X<can>
-C<can> checks to see if its object has a method called C<METHOD>,
-if it does then a reference to the sub is returned, if it does not then
-C<undef> is returned.
+The C<can> method checks to see if the class or object it was called on
+has a method named C<$method>. This checks for the method in the class
+and all of its parents. If the method exists, then a reference to the
+subroutine is returned. If it does not then C<undef> is returned.
-=item VERSION( [NEED] )
+If your class responds to method calls via C<AUTOLOAD>, you may want to
+overload C<can> to return a subroutine reference for methods which your
+C<AUTOLOAD> method handles.
+
+If you override this method, it should never throw an exception.
+
+=item VERSION($need)
X<VERSION>
-C<VERSION> returns the version number of the class (package). If the
-NEED argument is given then it will check that the current version (as
-defined by the $VERSION variable in the given package) not less than
-NEED; it will die if this is not the case. This method is called automatically
-by the C<VERSION> form of C<use>.
+The C<VERSION> method returns the version number of the class
+(package).
+If the C<$need> argument is given then it will check that the current
+version (as defined by the $VERSION variable in the package) is greater
+than or equal to C<$need>; it will die if this is not the case. This
+method is called automatically by the C<VERSION> form of C<use>.
+
use Package 1.2 qw(some imported subs);
# implies:
Package->VERSION(1.2);
+We recommend that you use this method to access another package's
+version, rather than looking directly at C<$Package::VERSION>. The
+package you are looking at could have overridden the C<VERSION> method.
+
+We also recommend using this method to check whether a module has a
+sufficient version. The internal implementation uses the L<version>
+module to make sure that different types of version numbers are
+compared correctly.
+
=back
+=head2 AUTOLOAD
+X<AUTOLOAD>
+
+If you call a method that doesn't exist in a class, Perl will throw an
+error. However, if that class or any of its parent classes defines an
+C<AUTOLOAD> method, that C<AUTOLOAD> method is called instead.
+
+C<AUTOLOAD> is called as a regular method, and the caller will not know
+the difference. Whatever value your C<AUTOLOAD> method returns is
+returned to the caller.
+
+The fully qualified method name that was called is available in the
+C<$AUTOLOAD> package global for your class. Since this is a global, if
+you want to refer to do it without a package name prefix under C<strict
+'vars'>, you need to declare it.
+
+ # XXX - this is a terrible way to implement accessors, but it makes
+ # for a simple example.
+ our $AUTOLOAD;
+ sub AUTOLOAD {
+ my $self = shift;
+
+ # Remove qualifier from original method name...
+ my $called = $AUTOLOAD =~ s/.*:://r;
+
+ # Is there an attribute of that name?
+ die "No such attribute: $called"
+ unless exists $self->{$called};
+
+ # If so, return it...
+ return $self->{$called};
+ }
+
+ sub DESTROY { } # see below
+
+Without the C<our $AUTOLOAD> declaration, this code will not compile
+under the L<strict> pragma.
+
+As the comment says, this is not a good way to implement accessors.
+It's slow and too clever by far. However, you may see this as a way to
+provide accessors in older Perl code. See L<perlootut> for
+recommendations on OO coding in Perl.
+
+If your class does have an C<AUTOLOAD> method, we strongly recommend
+that you override C<can> in your class as well. Your overridden C<can>
+method should return a subroutine reference for any method that your
+C<AUTOLOAD> responds to.
+
=head2 Destructors
X<destructor> X<DESTROY>
When the last reference to an object goes away, the object is
-automatically destroyed. (This may even be after you exit, if you've
-stored references in global variables.) If you want to capture control
-just before the object is freed, you may define a DESTROY method in
-your class. It will automatically be called at the appropriate moment,
-and you can do any extra cleanup you need to do. Perl passes a reference
-to the object under destruction as the first (and only) argument. Beware
-that the reference is a read-only value, and cannot be modified by
-manipulating C<$_[0]> within the destructor. The object itself (i.e.
-the thingy the reference points to, namely C<${$_[0]}>, C<@{$_[0]}>,
-C<%{$_[0]}> etc.) is not similarly constrained.
+destroyed. If you only have one reference to an object stored in a
+lexical scalar, the object is destroyed when that scalar goes out of
+scope. If you store the object in a package global, that object may not
+go out of scope until the program exits.
-Since DESTROY methods can be called at unpredictable times, it is
-important that you localise any global variables that the method may
-update. In particular, localise C<$@> if you use C<eval {}> and
-localise C<$?> if you use C<system> or backticks.
+If you want to do something when the object is destroyed, you can
+define a C<DESTROY> method in your class. This method will always be
+called by Perl at the appropriate time, unless the method is empty.
-If you arrange to re-bless the reference before the destructor returns,
-perl will again call the DESTROY method for the re-blessed object after
-the current one returns. This can be used for clean delegation of
-object destruction, or for ensuring that destructors in the base classes
-of your choosing get called. Explicitly calling DESTROY is also possible,
-but is usually never needed.
+This is called just like any other method, with the object as the first
+argument. It does not receive any additional arguments. However, the
+C<$_[0]> variable will be read-only in the destructor, so you cannot
+assign a value to it.
-DESTROY is subject to AUTOLOAD lookup, just like any other method. Hence, if
-your class has an AUTOLOAD method, but does not need any DESTROY actions,
-you probably want to provide a DESTROY method anyway, to prevent an
-expensive call to AUTOLOAD each time an object is freed. As this technique
-makes empty DESTROY methods common, the implementation is optimised so that
-a DESTROY method that is an empty or constant subroutine, and hence could
-have no side effects anyway, is not actually called.
-X<AUTOLOAD> X<DESTROY>
+If your C<DESTROY> method throws an error, this error will be ignored.
+It will not be sent to C<STDERR> and it will not cause the program to
+die. However, if your destructor is running inside an C<eval {}> block,
+then the error will change the value of C<$@>.
-Do not confuse the previous discussion with how objects I<CONTAINED> in the current
-one are destroyed. Such objects will be freed and destroyed automatically
-when the current object is freed, provided no other references to them exist
-elsewhere.
+Because C<DESTROY> methods can be called at any time, you should
+localize any global variables you might update in your C<DESTROY>. In
+particular, if you use C<eval {}> you should localize C<$@>, and if you
+use C<system> or backticks you should localize C<$?>.
-=head2 Summary
+If you define an C<AUTOLOAD> in your class, then Perl will call your
+C<AUTOLOAD> to handle the C<DESTROY> method. You can prevent this by
+defining an empty C<DESTROY>, like we did in the autoloading example.
+You can also check the value of C<$AUTOLOAD> and return without doing
+anything when called to handle C<DESTROY>.
-That's about all there is to it. Now you need just to go off and buy a
-book about object-oriented design methodology, and bang your forehead
-with it for the next six months or so.
+=head3 Global Destruction
-=head2 Two-Phased Garbage Collection
-X<garbage collection> X<GC> X<circular reference>
-X<reference, circular> X<DESTROY> X<destructor>
+The order in which objects are destroyed during the global destruction
+before the program exits is unpredictable. This means that any objects
+contained by your object may already have been destroyed. You should
+check that a contained object is defined before calling a method on it:
-For most purposes, Perl uses a fast and simple, reference-based
-garbage collection system. That means there's an extra
-dereference going on at some level, so if you haven't built
-your Perl executable using your C compiler's C<-O> flag, performance
-will suffer. If you I<have> built Perl with C<cc -O>, then this
-probably won't matter.
+ sub DESTROY {
+ my $self = shift;
-A more serious concern is that unreachable memory with a non-zero
-reference count will not normally get freed. Therefore, this is a bad
-idea:
+ $self->{handle}->close() if $self->{handle};
+ }
- {
- my $a;
- $a = \$a;
- }
+You can use the C<${^GLOBAL_PHASE}> variable to detect if you are
+currently in the global destruction phase:
-Even thought $a I<should> go away, it can't. When building recursive data
-structures, you'll have to break the self-reference yourself explicitly
-if you don't care to leak. For example, here's a self-referential
-node such as one might use in a sophisticated tree structure:
+ sub DESTROY {
+ my $self = shift;
- sub new_node {
- my $class = shift;
- my $node = {};
- $node->{LEFT} = $node->{RIGHT} = $node;
- $node->{DATA} = [ @_ ];
- return bless $node => $class;
- }
+ return if ${^GLOBAL_PHASE} eq 'DESTRUCT';
-If you create nodes like that, they (currently) won't go away unless you
-break their self reference yourself. (In other words, this is not to be
-construed as a feature, and you shouldn't depend on it.)
+ $self->{handle}->close();
+ }
-Almost.
+Note that this variable was added in Perl 5.14.0. If you want to detect
+the global destruction phase on older versions of Perl, you can use the
+C<Devel::GlobalDestruction> module on CPAN.
-When an interpreter thread finally shuts down (usually when your program
-exits), then a rather costly but complete mark-and-sweep style of garbage
-collection is performed, and everything allocated by that thread gets
-destroyed. This is essential to support Perl as an embedded or a
-multithreadable language. For example, this program demonstrates Perl's
-two-phased garbage collection:
+If your C<DESTROY> method issues a warning during global destruction,
+the Perl interpreter will append the string " during global
+destruction" the warning.
- #!/usr/bin/perl
- package Subtle;
+During global destruction, Perl will always garbage collect objects
+before unblessed references. See L<perlhacktips/PERL_DESTRUCT_LEVEL>
+for more information about global destruction.
- sub new {
- my $test;
- $test = \$test;
- warn "CREATING " . \$test;
- return bless \$test;
- }
+=head2 Non-Hash Objects
- sub DESTROY {
- my $self = shift;
- warn "DESTROYING $self";
- }
+All the examples so far have shown objects based on a blessed hash.
+However, it's possible to bless any type of data structure or referent,
+including scalars, globs, and subroutines. You may see this sort of
+thing when looking at code in the wild.
- package main;
+Here's an example of a module as a blessed scalar:
- warn "starting program";
- {
- my $a = Subtle->new;
- my $b = Subtle->new;
- $$a = 0; # break selfref
- warn "leaving block";
- }
+ package Time;
- warn "just exited block";
- warn "time to die...";
- exit;
+ use strict;
+ use warnings;
-When run as F</foo/test>, the following output is produced:
+ sub new {
+ my $class = shift;
- starting program at /foo/test line 18.
- CREATING SCALAR(0x8e5b8) at /foo/test line 7.
- CREATING SCALAR(0x8e57c) at /foo/test line 7.
- leaving block at /foo/test line 23.
- DESTROYING Subtle=SCALAR(0x8e5b8) at /foo/test line 13.
- just exited block at /foo/test line 26.
- time to die... at /foo/test line 27.
- DESTROYING Subtle=SCALAR(0x8e57c) during global destruction.
+ my $time = time;
+ return bless \$time, $class;
+ }
-Notice that "global destruction" bit there? That's the thread
-garbage collector reaching the unreachable.
+ sub epoch {
+ my $self = shift;
+ return ${ $self };
+ }
-Objects are always destructed, even when regular refs aren't. Objects
-are destructed in a separate pass before ordinary refs just to
-prevent object destructors from using refs that have been themselves
-destructed. Plain refs are only garbage-collected if the destruct level
-is greater than 0. You can test the higher levels of global destruction
-by setting the PERL_DESTRUCT_LEVEL environment variable, presuming
-C<-DDEBUGGING> was enabled during perl build time.
-See L<perlhacktips/PERL_DESTRUCT_LEVEL> for more information.
+ my $time = Time->new();
+ print $time->epoch();
-A more complete garbage collection strategy will be implemented
-at a future date.
+=head2 Inside-Out objects
-In the meantime, the best solution is to create a non-recursive container
-class that holds a pointer to the self-referential data structure.
-Define a DESTROY method for the containing object's class that manually
-breaks the circularities in the self-referential structure.
+In the past, the Perl community experimented with a technique called
+"inside-out objects". An inside-out object stores its data outside of
+the object's reference, indexed on a unique property of the object,
+such as its memory address, rather than in the object itself. This has
+the advantage of enforcing the encapsulation of object attributes,
+since their data is not stored in the object itself.
+This technique was popular for a while (and was recommended in Damian
+Conway's I<Perl Best Practices>), but never achieved universal
+adoption. The L<Object::InsideOut> module on CPAN provides a
+comprehensive implementation of this technique, and you may see it or
+other inside-out modules in the wild.
+
+Here is a simple example of the technique, using the
+L<Hash::Util::FieldHash> core module. This module was added to the core
+to support inside-out object implementations.
+
+ package Time;
+
+ use strict;
+ use warnings;
+
+ use Hash::Util::FieldHash 'fieldhash';
+
+ fieldhash my %time_for;
+
+ sub new {
+ my $class = shift;
+
+ my $self = bless \( my $object ), $class;
+
+ $time_for{$self} = time;
+
+ return $self;
+ }
+
+ sub epoch {
+ my $self = shift;
+
+ return $time_for{$self};
+ }
+
+ my $time = Time->new;
+ print $time->epoch;
+
+=head2 Pseudo-hashes
+
+The pseudo-hash feature was an experimental feature introduced in
+earlier versions of Perl and removed in 5.10.0. A pseudo-hash is an
+array reference which can be accessed using named keys like a hash. You
+may run in to some code in the wild which uses it. See the L<fields>
+pragma for more information.
+
=head1 SEE ALSO
A kinder, gentler tutorial on object-oriented programming in Perl can
-be found in L<perltoot>, L<perlboot> and L<perltooc>. You should
-also check out L<perlbot> for other object tricks, traps, and tips, as
-well as L<perlmodlib> for some style guides on constructing both
-modules and classes.
+be found in L<perlootut>. You should also check out L<perlmodlib> for
+some style guides on constructing both modules and classes.
+
Property changes on: trunk/contrib/perl/pod/perlobj.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlootut.pod (from rev 6437, vendor/perl/5.18.1/pod/perlootut.pod)
===================================================================
--- trunk/contrib/perl/pod/perlootut.pod (rev 0)
+++ trunk/contrib/perl/pod/perlootut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,750 @@
+=encoding utf8
+
+=for comment
+Consistent formatting of this file is achieved with:
+ perl ./Porting/podtidy pod/perlootut.pod
+
+=head1 NAME
+
+perlootut - Object-Oriented Programming in Perl Tutorial
+
+=head1 DATE
+
+This document was created in February, 2011, and the last major
+revision was in February, 2013.
+
+If you are reading this in the future then it's possible that the state
+of the art has changed. We recommend you start by reading the perlootut
+document in the latest stable release of Perl, rather than this
+version.
+
+=head1 DESCRIPTION
+
+This document provides an introduction to object-oriented programming
+in Perl. It begins with a brief overview of the concepts behind object
+oriented design. Then it introduces several different OO systems from
+L<CPAN|http://search.cpan.org> which build on top of what Perl
+provides.
+
+By default, Perl's built-in OO system is very minimal, leaving you to
+do most of the work. This minimalism made a lot of sense in 1994, but
+in the years since Perl 5.0 we've seen a number of common patterns
+emerge in Perl OO. Fortunately, Perl's flexibility has allowed a rich
+ecosystem of Perl OO systems to flourish.
+
+If you want to know how Perl OO works under the hood, the L<perlobj>
+document explains the nitty gritty details.
+
+This document assumes that you already understand the basics of Perl
+syntax, variable types, operators, and subroutine calls. If you don't
+understand these concepts yet, please read L<perlintro> first. You
+should also read the L<perlsyn>, L<perlop>, and L<perlsub> documents.
+
+=head1 OBJECT-ORIENTED FUNDAMENTALS
+
+Most object systems share a number of common concepts. You've probably
+heard terms like "class", "object, "method", and "attribute" before.
+Understanding the concepts will make it much easier to read and write
+object-oriented code. If you're already familiar with these terms, you
+should still skim this section, since it explains each concept in terms
+of Perl's OO implementation.
+
+Perl's OO system is class-based. Class-based OO is fairly common. It's
+used by Java, C++, C#, Python, Ruby, and many other languages. There
+are other object orientation paradigms as well. JavaScript is the most
+popular language to use another paradigm. JavaScript's OO system is
+prototype-based.
+
+=head2 Object
+
+An B<object> is a data structure that bundles together data and
+subroutines which operate on that data. An object's data is called
+B<attributes>, and its subroutines are called B<methods>. An object can
+be thought of as a noun (a person, a web service, a computer).
+
+An object represents a single discrete thing. For example, an object
+might represent a file. The attributes for a file object might include
+its path, content, and last modification time. If we created an object
+to represent F</etc/hostname> on a machine named "foo.example.com",
+that object's path would be "/etc/hostname", its content would be
+"foo\n", and it's last modification time would be 1304974868 seconds
+since the beginning of the epoch.
+
+The methods associated with a file might include C<rename()> and
+C<write()>.
+
+In Perl most objects are hashes, but the OO systems we recommend keep
+you from having to worry about this. In practice, it's best to consider
+an object's internal data structure opaque.
+
+=head2 Class
+
+A B<class> defines the behavior of a category of objects. A class is a
+name for a category (like "File"), and a class also defines the
+behavior of objects in that category.
+
+All objects belong to a specific class. For example, our
+F</etc/hostname> object belongs to the C<File> class. When we want to
+create a specific object, we start with its class, and B<construct> or
+B<instantiate> an object. A specific object is often referred to as an
+B<instance> of a class.
+
+In Perl, any package can be a class. The difference between a package
+which is a class and one which isn't is based on how the package is
+used. Here's our "class declaration" for the C<File> class:
+
+ package File;
+
+In Perl, there is no special keyword for constructing an object.
+However, most OO modules on CPAN use a method named C<new()> to
+construct a new object:
+
+ my $hostname = File->new(
+ path => '/etc/hostname',
+ content => "foo\n",
+ last_mod_time => 1304974868,
+ );
+
+(Don't worry about that C<< -> >> operator, it will be explained
+later.)
+
+=head3 Blessing
+
+As we said earlier, most Perl objects are hashes, but an object can be
+an instance of any Perl data type (scalar, array, etc.). Turning a
+plain data structure into an object is done by B<blessing> that data
+structure using Perl's C<bless> function.
+
+While we strongly suggest you don't build your objects from scratch,
+you should know the term B<bless>. A B<blessed> data structure (aka "a
+referent") is an object. We sometimes say that an object has been
+"blessed into a class".
+
+Once a referent has been blessed, the C<blessed> function from the
+L<Scalar::Util> core module can tell us its class name. This subroutine
+returns an object's class when passed an object, and false otherwise.
+
+ use Scalar::Util 'blessed';
+
+ print blessed($hash); # undef
+ print blessed($hostname); # File
+
+=head3 Constructor
+
+A B<constructor> creates a new object. In Perl, a class's constructor
+is just another method, unlike some other languages, which provide
+syntax for constructors. Most Perl classes use C<new> as the name for
+their constructor:
+
+ my $file = File->new(...);
+
+=head2 Methods
+
+You already learned that a B<method> is a subroutine that operates on
+an object. You can think of a method as the things that an object can
+I<do>. If an object is a noun, then methods are its verbs (save, print,
+open).
+
+In Perl, methods are simply subroutines that live in a class's package.
+Methods are always written to receive the object as their first
+argument:
+
+ sub print_info {
+ my $self = shift;
+
+ print "This file is at ", $self->path, "\n";
+ }
+
+ $file->print_info;
+ # The file is at /etc/hostname
+
+What makes a method special is I<how it's called>. The arrow operator
+(C<< -> >>) tells Perl that we are calling a method.
+
+When we make a method call, Perl arranges for the method's B<invocant>
+to be passed as the first argument. B<Invocant> is a fancy name for the
+thing on the left side of the arrow. The invocant can either be a class
+name or an object. We can also pass additional arguments to the method:
+
+ sub print_info {
+ my $self = shift;
+ my $prefix = shift // "This file is at ";
+
+ print $prefix, ", ", $self->path, "\n";
+ }
+
+ $file->print_info("The file is located at ");
+ # The file is located at /etc/hostname
+
+=head2 Attributes
+
+Each class can define its B<attributes>. When we instantiate an object,
+we assign values to those attributes. For example, every C<File> object
+has a path. Attributes are sometimes called B<properties>.
+
+Perl has no special syntax for attributes. Under the hood, attributes
+are often stored as keys in the object's underlying hash, but don't
+worry about this.
+
+We recommend that you only access attributes via B<accessor> methods.
+These are methods that can get or set the value of each attribute. We
+saw this earlier in the C<print_info()> example, which calls C<<
+$self->path >>.
+
+You might also see the terms B<getter> and B<setter>. These are two
+types of accessors. A getter gets the attribute's value, while a setter
+sets it. Another term for a setter is B<mutator>
+
+Attributes are typically defined as read-only or read-write. Read-only
+attributes can only be set when the object is first created, while
+read-write attributes can be altered at any time.
+
+The value of an attribute may itself be another object. For example,
+instead of returning its last mod time as a number, the C<File> class
+could return a L<DateTime> object representing that value.
+
+It's possible to have a class that does not expose any publicly
+settable attributes. Not every class has attributes and methods.
+
+=head2 Polymorphism
+
+B<Polymorphism> is a fancy way of saying that objects from two
+different classes share an API. For example, we could have C<File> and
+C<WebPage> classes which both have a C<print_content()> method. This
+method might produce different output for each class, but they share a
+common interface.
+
+While the two classes may differ in many ways, when it comes to the
+C<print_content()> method, they are the same. This means that we can
+try to call the C<print_content()> method on an object of either class,
+and B<we don't have to know what class the object belongs to!>
+
+Polymorphism is one of the key concepts of object-oriented design.
+
+=head2 Inheritance
+
+B<Inheritance> lets you create a specialized version of an existing
+class. Inheritance lets the new class reuse the methods and attributes
+of another class.
+
+For example, we could create an C<File::MP3> class which B<inherits>
+from C<File>. An C<File::MP3> B<is-a> I<more specific> type of C<File>.
+All mp3 files are files, but not all files are mp3 files.
+
+We often refer to inheritance relationships as B<parent-child> or
+C<superclass/subclass> relationships. Sometimes we say that the child
+has an B<is-a> relationship with its parent class.
+
+C<File> is a B<superclass> of C<File::MP3>, and C<File::MP3> is a
+B<subclass> of C<File>.
+
+ package File::MP3;
+
+ use parent 'File';
+
+The L<parent> module is one of several ways that Perl lets you define
+inheritance relationships.
+
+Perl allows multiple inheritance, which means that a class can inherit
+from multiple parents. While this is possible, we strongly recommend
+against it. Generally, you can use B<roles> to do everything you can do
+with multiple inheritance, but in a cleaner way.
+
+Note that there's nothing wrong with defining multiple subclasses of a
+given class. This is both common and safe. For example, we might define
+C<File::MP3::FixedBitrate> and C<File::MP3::VariableBitrate> classes to
+distinguish between different types of mp3 file.
+
+=head3 Overriding methods and method resolution
+
+Inheritance allows two classes to share code. By default, every method
+in the parent class is also available in the child. The child can
+explicitly B<override> a parent's method to provide its own
+implementation. For example, if we have an C<File::MP3> object, it has
+the C<print_info()> method from C<File>:
+
+ my $cage = File::MP3->new(
+ path => 'mp3s/My-Body-Is-a-Cage.mp3',
+ content => $mp3_data,
+ last_mod_time => 1304974868,
+ title => 'My Body Is a Cage',
+ );
+
+ $cage->print_info;
+ # The file is at mp3s/My-Body-Is-a-Cage.mp3
+
+If we wanted to include the mp3's title in the greeting, we could
+override the method:
+
+ package File::MP3;
+
+ use parent 'File';
+
+ sub print_info {
+ my $self = shift;
+
+ print "This file is at ", $self->path, "\n";
+ print "Its title is ", $self->title, "\n";
+ }
+
+ $cage->print_info;
+ # The file is at mp3s/My-Body-Is-a-Cage.mp3
+ # Its title is My Body Is a Cage
+
+The process of determining what method should be used is called
+B<method resolution>. What Perl does is look at the object's class
+first (C<File::MP3> in this case). If that class defines the method,
+then that class's version of the method is called. If not, Perl looks
+at each parent class in turn. For C<File::MP3>, its only parent is
+C<File>. If C<File::MP3> does not define the method, but C<File> does,
+then Perl calls the method in C<File>.
+
+If C<File> inherited from C<DataSource>, which inherited from C<Thing>,
+then Perl would keep looking "up the chain" if necessary.
+
+It is possible to explicitly call a parent method from a child:
+
+ package File::MP3;
+
+ use parent 'File';
+
+ sub print_info {
+ my $self = shift;
+
+ $self->SUPER::print_info();
+ print "Its title is ", $self->title, "\n";
+ }
+
+The C<SUPER::> bit tells Perl to look for the C<print_info()> in the
+C<File::MP3> class's inheritance chain. When it finds the parent class
+that implements this method, the method is called.
+
+We mentioned multiple inheritance earlier. The main problem with
+multiple inheritance is that it greatly complicates method resolution.
+See L<perlobj> for more details.
+
+=head2 Encapsulation
+
+B<Encapsulation> is the idea that an object is opaque. When another
+developer uses your class, they don't need to know I<how> it is
+implemented, they just need to know I<what> it does.
+
+Encapsulation is important for several reasons. First, it allows you to
+separate the public API from the private implementation. This means you
+can change that implementation without breaking the API.
+
+Second, when classes are well encapsulated, they become easier to
+subclass. Ideally, a subclass uses the same APIs to access object data
+that its parent class uses. In reality, subclassing sometimes involves
+violating encapsulation, but a good API can minimize the need to do
+this.
+
+We mentioned earlier that most Perl objects are implemented as hashes
+under the hood. The principle of encapsulation tells us that we should
+not rely on this. Instead, we should use accessor methods to access the
+data in that hash. The object systems that we recommend below all
+automate the generation of accessor methods. If you use one of them,
+you should never have to access the object as a hash directly.
+
+=head2 Composition
+
+In object-oriented code, we often find that one object references
+another object. This is called B<composition>, or a B<has-a>
+relationship.
+
+Earlier, we mentioned that the C<File> class's C<last_mod_time>
+accessor could return a L<DateTime> object. This is a perfect example
+of composition. We could go even further, and make the C<path> and
+C<content> accessors return objects as well. The C<File> class would
+then be B<composed> of several other objects.
+
+=head2 Roles
+
+B<Roles> are something that a class I<does>, rather than something that
+it I<is>. Roles are relatively new to Perl, but have become rather
+popular. Roles are B<applied> to classes. Sometimes we say that classes
+B<consume> roles.
+
+Roles are an alternative to inheritance for providing polymorphism.
+Let's assume we have two classes, C<Radio> and C<Computer>. Both of
+these things have on/off switches. We want to model that in our class
+definitions.
+
+We could have both classes inherit from a common parent, like
+C<Machine>, but not all machines have on/off switches. We could create
+a parent class called C<HasOnOffSwitch>, but that is very artificial.
+Radios and computers are not specializations of this parent. This
+parent is really a rather ridiculous creation.
+
+This is where roles come in. It makes a lot of sense to create a
+C<HasOnOffSwitch> role and apply it to both classes. This role would
+define a known API like providing C<turn_on()> and C<turn_off()>
+methods.
+
+Perl does not have any built-in way to express roles. In the past,
+people just bit the bullet and used multiple inheritance. Nowadays,
+there are several good choices on CPAN for using roles.
+
+=head2 When to Use OO
+
+Object Orientation is not the best solution to every problem. In I<Perl
+Best Practices> (copyright 2004, Published by O'Reilly Media, Inc.),
+Damian Conway provides a list of criteria to use when deciding if OO is
+the right fit for your problem:
+
+=over 4
+
+=item *
+
+The system being designed is large, or is likely to become large.
+
+=item *
+
+The data can be aggregated into obvious structures, especially if
+there's a large amount of data in each aggregate.
+
+=item *
+
+The various types of data aggregate form a natural hierarchy that
+facilitates the use of inheritance and polymorphism.
+
+=item *
+
+You have a piece of data on which many different operations are
+applied.
+
+=item *
+
+You need to perform the same general operations on related types of
+data, but with slight variations depending on the specific type of data
+the operations are applied to.
+
+=item *
+
+It's likely you'll have to add new data types later.
+
+=item *
+
+The typical interactions between pieces of data are best represented by
+operators.
+
+=item *
+
+The implementation of individual components of the system is likely to
+change over time.
+
+=item *
+
+The system design is already object-oriented.
+
+=item *
+
+Large numbers of other programmers will be using your code modules.
+
+=back
+
+=head1 PERL OO SYSTEMS
+
+As we mentioned before, Perl's built-in OO system is very minimal, but
+also quite flexible. Over the years, many people have developed systems
+which build on top of Perl's built-in system to provide more features
+and convenience.
+
+We strongly recommend that you use one of these systems. Even the most
+minimal of them eliminates a lot of repetitive boilerplate. There's
+really no good reason to write your classes from scratch in Perl.
+
+If you are interested in the guts underlying these systems, check out
+L<perlobj>.
+
+=head2 Moose
+
+L<Moose> bills itself as a "postmodern object system for Perl 5". Don't
+be scared, the "postmodern" label is a callback to Larry's description
+of Perl as "the first postmodern computer language".
+
+C<Moose> provides a complete, modern OO system. Its biggest influence
+is the Common Lisp Object System, but it also borrows ideas from
+Smalltalk and several other languages. C<Moose> was created by Stevan
+Little, and draws heavily from his work on the Perl 6 OO design.
+
+Here is our C<File> class using C<Moose>:
+
+ package File;
+ use Moose;
+
+ has path => ( is => 'ro' );
+ has content => ( is => 'ro' );
+ has last_mod_time => ( is => 'ro' );
+
+ sub print_info {
+ my $self = shift;
+
+ print "This file is at ", $self->path, "\n";
+ }
+
+C<Moose> provides a number of features:
+
+=over 4
+
+=item * Declarative sugar
+
+C<Moose> provides a layer of declarative "sugar" for defining classes.
+That sugar is just a set of exported functions that make declaring how
+your class works simpler and more palatable. This lets you describe
+I<what> your class is, rather than having to tell Perl I<how> to
+implement your class.
+
+The C<has()> subroutine declares an attribute, and C<Moose>
+automatically creates accessors for these attributes. It also takes
+care of creating a C<new()> method for you. This constructor knows
+about the attributes you declared, so you can set them when creating a
+new C<File>.
+
+=item * Roles built-in
+
+C<Moose> lets you define roles the same way you define classes:
+
+ package HasOnOfSwitch;
+ use Moose::Role;
+
+ has is_on => (
+ is => 'rw',
+ isa => 'Bool',
+ );
+
+ sub turn_on {
+ my $self = shift;
+ $self->is_on(1);
+ }
+
+ sub turn_off {
+ my $self = shift;
+ $self->is_on(0);
+ }
+
+=item * A miniature type system
+
+In the example above, you can see that we passed C<< isa => 'Bool' >>
+to C<has()> when creating our C<is_on> attribute. This tells C<Moose>
+that this attribute must be a boolean value. If we try to set it to an
+invalid value, our code will throw an error.
+
+=item * Full introspection and manipulation
+
+Perl's built-in introspection features are fairly minimal. C<Moose>
+builds on top of them and creates a full introspection layer for your
+classes. This lets you ask questions like "what methods does the File
+class implement?" It also lets you modify your classes
+programmatically.
+
+=item * Self-hosted and extensible
+
+C<Moose> describes itself using its own introspection API. Besides
+being a cool trick, this means that you can extend C<Moose> using
+C<Moose> itself.
+
+=item * Rich ecosystem
+
+There is a rich ecosystem of C<Moose> extensions on CPAN under the
+L<MooseX|http://search.cpan.org/search?query=MooseX&mode=dist>
+namespace. In addition, many modules on CPAN already use C<Moose>,
+providing you with lots of examples to learn from.
+
+=item * Many more features
+
+C<Moose> is a very powerful tool, and we can't cover all of its
+features here. We encourage you to learn more by reading the C<Moose>
+documentation, starting with
+L<Moose::Manual|http://search.cpan.org/perldoc?Moose::Manual>.
+
+=back
+
+Of course, C<Moose> isn't perfect.
+
+C<Moose> can make your code slower to load. C<Moose> itself is not
+small, and it does a I<lot> of code generation when you define your
+class. This code generation means that your runtime code is as fast as
+it can be, but you pay for this when your modules are first loaded.
+
+This load time hit can be a problem when startup speed is important,
+such as with a command-line script or a "plain vanilla" CGI script that
+must be loaded each time it is executed.
+
+Before you panic, know that many people do use C<Moose> for
+command-line tools and other startup-sensitive code. We encourage you
+to try C<Moose> out first before worrying about startup speed.
+
+C<Moose> also has several dependencies on other modules. Most of these
+are small stand-alone modules, a number of which have been spun off
+from C<Moose>. C<Moose> itself, and some of its dependencies, require a
+compiler. If you need to install your software on a system without a
+compiler, or if having I<any> dependencies is a problem, then C<Moose>
+may not be right for you.
+
+=head3 Moo
+
+If you try C<Moose> and find that one of these issues is preventing you
+from using C<Moose>, we encourage you to consider L<Moo> next. C<Moo>
+implements a subset of C<Moose>'s functionality in a simpler package.
+For most features that it does implement, the end-user API is
+I<identical> to C<Moose>, meaning you can switch from C<Moo> to
+C<Moose> quite easily.
+
+C<Moo> does not implement most of C<Moose>'s introspection API, so it's
+often faster when loading your modules. Additionally, none of its
+dependencies require XS, so it can be installed on machines without a
+compiler.
+
+One of C<Moo>'s most compelling features is its interoperability with
+C<Moose>. When someone tries to use C<Moose>'s introspection API on a
+C<Moo> class or role, it is transparently inflated into a C<Moose>
+class or role. This makes it easier to incorporate C<Moo>-using code
+into a C<Moose> code base and vice versa.
+
+For example, a C<Moose> class can subclass a C<Moo> class using
+C<extends> or consume a C<Moo> role using C<with>.
+
+The C<Moose> authors hope that one day C<Moo> can be made obsolete by
+improving C<Moose> enough, but for now it provides a worthwhile
+alternative to C<Moose>.
+
+=head2 Class::Accessor
+
+L<Class::Accessor> is the polar opposite of C<Moose>. It provides very
+few features, nor is it self-hosting.
+
+It is, however, very simple, pure Perl, and it has no non-core
+dependencies. It also provides a "Moose-like" API on demand for the
+features it supports.
+
+Even though it doesn't do much, it is still preferable to writing your
+own classes from scratch.
+
+Here's our C<File> class with C<Class::Accessor>:
+
+ package File;
+ use Class::Accessor 'antlers';
+
+ has path => ( is => 'ro' );
+ has content => ( is => 'ro' );
+ has last_mod_time => ( is => 'ro' );
+
+ sub print_info {
+ my $self = shift;
+
+ print "This file is at ", $self->path, "\n";
+ }
+
+The C<antlers> import flag tells C<Class::Accessor> that you want to
+define your attributes using C<Moose>-like syntax. The only parameter
+that you can pass to C<has> is C<is>. We recommend that you use this
+Moose-like syntax if you choose C<Class::Accessor> since it means you
+will have a smoother upgrade path if you later decide to move to
+C<Moose>.
+
+Like C<Moose>, C<Class::Accessor> generates accessor methods and a
+constructor for your class.
+
+=head2 Object::Tiny
+
+Finally, we have L<Object::Tiny>. This module truly lives up to its
+name. It has an incredibly minimal API and absolutely no dependencies
+(core or not). Still, we think it's a lot easier to use than writing
+your own OO code from scratch.
+
+Here's our C<File> class once more:
+
+ package File;
+ use Object::Tiny qw( path content last_mod_time );
+
+ sub print_info {
+ my $self = shift;
+
+ print "This file is at ", $self->path, "\n";
+ }
+
+That's it!
+
+With C<Object::Tiny>, all accessors are read-only. It generates a
+constructor for you, as well as the accessors you define.
+
+=head2 Role::Tiny
+
+As we mentioned before, roles provide an alternative to inheritance,
+but Perl does not have any built-in role support. If you choose to use
+Moose, it comes with a full-fledged role implementation. However, if
+you use one of our other recommended OO modules, you can still use
+roles with L<Role::Tiny>
+
+C<Role::Tiny> provides some of the same features as Moose's role
+system, but in a much smaller package. Most notably, it doesn't support
+any sort of attribute declaration, so you have to do that by hand.
+Still, it's useful, and works well with C<Class::Accessor> and
+C<Object::Tiny>
+
+=head2 OO System Summary
+
+Here's a brief recap of the options we covered:
+
+=over 4
+
+=item * L<Moose>
+
+C<Moose> is the maximal option. It has a lot of features, a big
+ecosystem, and a thriving user base. We also covered L<Moo> briefly.
+C<Moo> is C<Moose> lite, and a reasonable alternative when Moose
+doesn't work for your application.
+
+=item * L<Class::Accessor>
+
+C<Class::Accessor> does a lot less than C<Moose>, and is a nice
+alternative if you find C<Moose> overwhelming. It's been around a long
+time and is well battle-tested. It also has a minimal C<Moose>
+compatibility mode which makes moving from C<Class::Accessor> to
+C<Moose> easy.
+
+=item * L<Object::Tiny>
+
+C<Object::Tiny> is the absolute minimal option. It has no dependencies,
+and almost no syntax to learn. It's a good option for a super minimal
+environment and for throwing something together quickly without having
+to worry about details.
+
+=item * L<Role::Tiny>
+
+Use C<Role::Tiny> with C<Class::Accessor> or C<Object::Tiny> if you
+find yourself considering multiple inheritance. If you go with
+C<Moose>, it comes with its own role implementation.
+
+=back
+
+=head2 Other OO Systems
+
+There are literally dozens of other OO-related modules on CPAN besides
+those covered here, and you're likely to run across one or more of them
+if you work with other people's code.
+
+In addition, plenty of code in the wild does all of its OO "by hand",
+using just the Perl built-in OO features. If you need to maintain such
+code, you should read L<perlobj> to understand exactly how Perl's
+built-in OO works.
+
+=head1 CONCLUSION
+
+As we said before, Perl's minimal OO system has led to a profusion of
+OO systems on CPAN. While you can still drop down to the bare metal and
+write your classes by hand, there's really no reason to do that with
+modern Perl.
+
+For small systems, L<Object::Tiny> and L<Class::Accessor> both provide
+minimal object systems that take care of basic boilerplate for you.
+
+For bigger projects, L<Moose> provides a rich set of features that will
+let you focus on implementing your business logic.
+
+We encourage you to play with and evaluate L<Moose>,
+L<Class::Accessor>, and L<Object::Tiny> to see which OO system is right
+for you.
+
+=cut
Modified: trunk/contrib/perl/pod/perlop.pod
===================================================================
--- trunk/contrib/perl/pod/perlop.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlop.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -48,7 +48,7 @@
left || //
nonassoc .. ...
right ?:
- right = += -= *= etc.
+ right = += -= *= etc. goto last next redo dump
left , =>
nonassoc list operators (rightward)
right not
@@ -190,7 +190,7 @@
=head2 Symbolic Unary Operators
X<unary operator> X<operator, unary>
-Unary "!" performs logical negation, i.e., "not". See also C<not> for a lower
+Unary "!" performs logical negation, that is, "not". See also C<not> for a lower
precedence version of this.
X<!>
@@ -207,7 +207,7 @@
B<Argument "the string" isn't numeric in negation (-) at ...>.
X<-> X<negation, arithmetic>
-Unary "~" performs bitwise negation, i.e., 1's complement. For
+Unary "~" performs bitwise negation, that is, 1's complement. For
example, C<0666 & ~027> is 0640. (See also L<Integer Arithmetic> and
L<Bitwise String Operators>.) Note that the width of the result is
platform-dependent: ~0 is 32 bits wide on a 32-bit platform, but 64
@@ -253,7 +253,7 @@
substitution, or transliteration, it is interpreted as a search pattern at run
time. Note that this means that its contents will be interpolated twice, so
- '\\' =~ q'\\';
+ '\\' =~ q'\\';
is not ok, as the regex engine will end up trying to compile the
pattern C<\>, which it will consider a syntax error.
@@ -279,7 +279,7 @@
operands C<$a> and C<$b>: If C<$b> is positive, then C<$a % $b> is
C<$a> minus the largest multiple of C<$b> less than or equal to
C<$a>. If C<$b> is negative, then C<$a % $b> is C<$a> minus the
-smallest multiple of C<$b> that is not less than C<$a> (i.e. the
+smallest multiple of C<$b> that is not less than C<$a> (that is, the
result will be less than or equal to zero). If the operands
C<$a> and C<$b> are floating point values and the absolute value of
C<$b> (that is C<abs($b)>) is less than C<(UV_MAX + 1)>, only
@@ -317,13 +317,13 @@
=head2 Additive Operators
X<operator, additive>
-Binary "+" returns the sum of two numbers.
+Binary C<+> returns the sum of two numbers.
X<+>
-Binary "-" returns the difference of two numbers.
+Binary C<-> returns the difference of two numbers.
X<->
-Binary "." concatenates two strings.
+Binary C<.> concatenates two strings.
X<string, concatenation> X<concatenation>
X<cat> X<concat> X<concatenate> X<.>
@@ -332,16 +332,16 @@
X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
X<shl> X<shr> X<shift, right> X<shift, left>
-Binary "<<" returns the value of its left argument shifted left by the
+Binary C<<< << >>> returns the value of its left argument shifted left by the
number of bits specified by the right argument. Arguments should be
integers. (See also L<Integer Arithmetic>.)
-Binary ">>" returns the value of its left argument shifted right by
+Binary C<<< >> >>> returns the value of its left argument shifted right by
the number of bits specified by the right argument. Arguments should
be integers. (See also L<Integer Arithmetic>.)
-Note that both "<<" and ">>" in Perl are implemented directly using
-"<<" and ">>" in C. If C<use integer> (see L<Integer Arithmetic>) is
+Note that both C<<< << >>> and C<<< >> >>> in Perl are implemented directly using
+C<<< << >>> and C<<< >> >>> in C. If C<use integer> (see L<Integer Arithmetic>) is
in force then signed C integers are used, else unsigned C integers are
used. Either way, the implementation isn't going to generate results
larger than the size of the integer type Perl was built with (32 bits
@@ -352,6 +352,15 @@
integers, C<< 1 << 32 >> is undefined. Shifting by a negative number
of bits is also undefined.
+If you get tired of being subject to your platform's native integers,
+the C<use bigint> pragma neatly sidesteps the issue altogether:
+
+ print 20 << 20; # 20971520
+ print 20 << 40; # 5120 on 32-bit machines,
+ # 21990232555520 on 64-bit machines
+ use bigint;
+ print 20 << 100; # 25353012004564588029934064107520
+
=head2 Named Unary Operators
X<operator, named unary>
@@ -362,7 +371,7 @@
is followed by a left parenthesis as the next token, the operator and
arguments within parentheses are taken to be of highest precedence,
just like a normal function call. For example,
-because named unary operators are higher precedence than ||:
+because named unary operators are higher precedence than C<||>:
chdir $foo || die; # (chdir $foo) || die
chdir($foo) || die; # (chdir $foo) || die
@@ -392,6 +401,13 @@
=head2 Relational Operators
X<relational operator> X<operator, relational>
+Perl operators that return true or false generally return values
+that can be safely used as numbers. For example, the relational
+operators in this section and the equality operators in the next
+one return C<1> for true and a special version of the defined empty
+string, C<"">, which counts as a zero but is exempt from warnings
+about improper numeric conversions, just as C<"0 but true"> is.
+
Binary "<" returns true if the left argument is numerically less than
the right argument.
X<< < >>
@@ -444,9 +460,12 @@
support NaNs then NaN is just a string with numeric value 0.
X<< <=> >> X<spaceship>
- perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
- perl -le '$a = "NaN"; print "NaN support here" if $a != $a'
+ $ perl -le '$a = "NaN"; print "No NaN support here" if $a == $a'
+ $ perl -le '$a = "NaN"; print "NaN support here" if $a != $a'
+(Note that the L<bigint>, L<bigrat>, and L<bignum> pragmas all
+support "NaN".)
+
Binary "eq" returns true if the left argument is stringwise equal to
the right argument.
X<eq>
@@ -460,13 +479,308 @@
argument.
X<cmp>
-Binary "~~" does a smart match between its arguments. Smart matching
-is described in L<perlsyn/"Smart matching in detail">.
+Binary "~~" does a smartmatch between its arguments. Smart matching
+is described in the next section.
X<~~>
"lt", "le", "ge", "gt" and "cmp" use the collation (sort) order specified
-by the current locale if C<use locale> is in effect. See L<perllocale>.
+by the current locale if a legacy C<use locale> (but not
+C<use locale ':not_characters'>) is in effect. See
+L<perllocale>. Do not mix these with Unicode, only with legacy binary
+encodings. The standard L<Unicode::Collate> and
+L<Unicode::Collate::Locale> modules offer much more powerful solutions to
+collation issues.
+=head2 Smartmatch Operator
+
+First available in Perl 5.10.1 (the 5.10.0 version behaved differently),
+binary C<~~> does a "smartmatch" between its arguments. This is mostly
+used implicitly in the C<when> construct described in L<perlsyn>, although
+not all C<when> clauses call the smartmatch operator. Unique among all of
+Perl's operators, the smartmatch operator can recurse.
+
+It is also unique in that all other Perl operators impose a context
+(usually string or numeric context) on their operands, autoconverting
+those operands to those imposed contexts. In contrast, smartmatch
+I<infers> contexts from the actual types of its operands and uses that
+type information to select a suitable comparison mechanism.
+
+The C<~~> operator compares its operands "polymorphically", determining how
+to compare them according to their actual types (numeric, string, array,
+hash, etc.) Like the equality operators with which it shares the same
+precedence, C<~~> returns 1 for true and C<""> for false. It is often best
+read aloud as "in", "inside of", or "is contained in", because the left
+operand is often looked for I<inside> the right operand. That makes the
+order of the operands to the smartmatch operand often opposite that of
+the regular match operator. In other words, the "smaller" thing is usually
+placed in the left operand and the larger one in the right.
+
+The behavior of a smartmatch depends on what type of things its arguments
+are, as determined by the following table. The first row of the table
+whose types apply determines the smartmatch behavior. Because what
+actually happens is mostly determined by the type of the second operand,
+the table is sorted on the right operand instead of on the left.
+
+ Left Right Description and pseudocode
+ ===============================================================
+ Any undef check whether Any is undefined
+ like: !defined Any
+
+ Any Object invoke ~~ overloading on Object, or die
+
+ Right operand is an ARRAY:
+
+ Left Right Description and pseudocode
+ ===============================================================
+ ARRAY1 ARRAY2 recurse on paired elements of ARRAY1 and ARRAY2[2]
+ like: (ARRAY1[0] ~~ ARRAY2[0])
+ && (ARRAY1[1] ~~ ARRAY2[1]) && ...
+ HASH ARRAY any ARRAY elements exist as HASH keys
+ like: grep { exists HASH->{$_} } ARRAY
+ Regexp ARRAY any ARRAY elements pattern match Regexp
+ like: grep { /Regexp/ } ARRAY
+ undef ARRAY undef in ARRAY
+ like: grep { !defined } ARRAY
+ Any ARRAY smartmatch each ARRAY element[3]
+ like: grep { Any ~~ $_ } ARRAY
+
+ Right operand is a HASH:
+
+ Left Right Description and pseudocode
+ ===============================================================
+ HASH1 HASH2 all same keys in both HASHes
+ like: keys HASH1 ==
+ grep { exists HASH2->{$_} } keys HASH1
+ ARRAY HASH any ARRAY elements exist as HASH keys
+ like: grep { exists HASH->{$_} } ARRAY
+ Regexp HASH any HASH keys pattern match Regexp
+ like: grep { /Regexp/ } keys HASH
+ undef HASH always false (undef can't be a key)
+ like: 0 == 1
+ Any HASH HASH key existence
+ like: exists HASH->{Any}
+
+ Right operand is CODE:
+
+ Left Right Description and pseudocode
+ ===============================================================
+ ARRAY CODE sub returns true on all ARRAY elements[1]
+ like: !grep { !CODE->($_) } ARRAY
+ HASH CODE sub returns true on all HASH keys[1]
+ like: !grep { !CODE->($_) } keys HASH
+ Any CODE sub passed Any returns true
+ like: CODE->(Any)
+
+Right operand is a Regexp:
+
+ Left Right Description and pseudocode
+ ===============================================================
+ ARRAY Regexp any ARRAY elements match Regexp
+ like: grep { /Regexp/ } ARRAY
+ HASH Regexp any HASH keys match Regexp
+ like: grep { /Regexp/ } keys HASH
+ Any Regexp pattern match
+ like: Any =~ /Regexp/
+
+ Other:
+
+ Left Right Description and pseudocode
+ ===============================================================
+ Object Any invoke ~~ overloading on Object,
+ or fall back to...
+
+ Any Num numeric equality
+ like: Any == Num
+ Num nummy[4] numeric equality
+ like: Num == nummy
+ undef Any check whether undefined
+ like: !defined(Any)
+ Any Any string equality
+ like: Any eq Any
+
+
+Notes:
+
+=over
+
+=item 1.
+Empty hashes or arrays match.
+
+=item 2.
+That is, each element smartmatches the element of the same index in the other array.[3]
+
+=item 3.
+If a circular reference is found, fall back to referential equality.
+
+=item 4.
+Either an actual number, or a string that looks like one.
+
+=back
+
+The smartmatch implicitly dereferences any non-blessed hash or array
+reference, so the C<I<HASH>> and C<I<ARRAY>> entries apply in those cases.
+For blessed references, the C<I<Object>> entries apply. Smartmatches
+involving hashes only consider hash keys, never hash values.
+
+The "like" code entry is not always an exact rendition. For example, the
+smartmatch operator short-circuits whenever possible, but C<grep> does
+not. Also, C<grep> in scalar context returns the number of matches, but
+C<~~> returns only true or false.
+
+Unlike most operators, the smartmatch operator knows to treat C<undef>
+specially:
+
+ use v5.10.1;
+ @array = (1, 2, 3, undef, 4, 5);
+ say "some elements undefined" if undef ~~ @array;
+
+Each operand is considered in a modified scalar context, the modification
+being that array and hash variables are passed by reference to the
+operator, which implicitly dereferences them. Both elements
+of each pair are the same:
+
+ use v5.10.1;
+
+ my %hash = (red => 1, blue => 2, green => 3,
+ orange => 4, yellow => 5, purple => 6,
+ black => 7, grey => 8, white => 9);
+
+ my @array = qw(red blue green);
+
+ say "some array elements in hash keys" if @array ~~ %hash;
+ say "some array elements in hash keys" if \@array ~~ \%hash;
+
+ say "red in array" if "red" ~~ @array;
+ say "red in array" if "red" ~~ \@array;
+
+ say "some keys end in e" if /e$/ ~~ %hash;
+ say "some keys end in e" if /e$/ ~~ \%hash;
+
+Two arrays smartmatch if each element in the first array smartmatches
+(that is, is "in") the corresponding element in the second array,
+recursively.
+
+ use v5.10.1;
+ my @little = qw(red blue green);
+ my @bigger = ("red", "blue", [ "orange", "green" ] );
+ if (@little ~~ @bigger) { # true!
+ say "little is contained in bigger";
+ }
+
+Because the smartmatch operator recurses on nested arrays, this
+will still report that "red" is in the array.
+
+ use v5.10.1;
+ my @array = qw(red blue green);
+ my $nested_array = [[[[[[[ @array ]]]]]]];
+ say "red in array" if "red" ~~ $nested_array;
+
+If two arrays smartmatch each other, then they are deep
+copies of each others' values, as this example reports:
+
+ use v5.12.0;
+ my @a = (0, 1, 2, [3, [4, 5], 6], 7);
+ my @b = (0, 1, 2, [3, [4, 5], 6], 7);
+
+ if (@a ~~ @b && @b ~~ @a) {
+ say "a and b are deep copies of each other";
+ }
+ elsif (@a ~~ @b) {
+ say "a smartmatches in b";
+ }
+ elsif (@b ~~ @a) {
+ say "b smartmatches in a";
+ }
+ else {
+ say "a and b don't smartmatch each other at all";
+ }
+
+
+If you were to set C<$b[3] = 4>, then instead of reporting that "a and b
+are deep copies of each other", it now reports that "b smartmatches in a".
+That because the corresponding position in C<@a> contains an array that
+(eventually) has a 4 in it.
+
+Smartmatching one hash against another reports whether both contain the
+same keys, no more and no less. This could be used to see whether two
+records have the same field names, without caring what values those fields
+might have. For example:
+
+ use v5.10.1;
+ sub make_dogtag {
+ state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
+
+ my ($class, $init_fields) = @_;
+
+ die "Must supply (only) name, rank, and serial number"
+ unless $init_fields ~~ $REQUIRED_FIELDS;
+
+ ...
+ }
+
+or, if other non-required fields are allowed, use ARRAY ~~ HASH:
+
+ use v5.10.1;
+ sub make_dogtag {
+ state $REQUIRED_FIELDS = { name=>1, rank=>1, serial_num=>1 };
+
+ my ($class, $init_fields) = @_;
+
+ die "Must supply (at least) name, rank, and serial number"
+ unless [keys %{$init_fields}] ~~ $REQUIRED_FIELDS;
+
+ ...
+ }
+
+The smartmatch operator is most often used as the implicit operator of a
+C<when> clause. See the section on "Switch Statements" in L<perlsyn>.
+
+=head3 Smartmatching of Objects
+
+To avoid relying on an object's underlying representation, if the
+smartmatch's right operand is an object that doesn't overload C<~~>,
+it raises the exception "C<Smartmatching a non-overloaded object
+breaks encapsulation>". That's because one has no business digging
+around to see whether something is "in" an object. These are all
+illegal on objects without a C<~~> overload:
+
+ %hash ~~ $object
+ 42 ~~ $object
+ "fred" ~~ $object
+
+However, you can change the way an object is smartmatched by overloading
+the C<~~> operator. This is allowed to extend the usual smartmatch semantics.
+For objects that do have an C<~~> overload, see L<overload>.
+
+Using an object as the left operand is allowed, although not very useful.
+Smartmatching rules take precedence over overloading, so even if the
+object in the left operand has smartmatch overloading, this will be
+ignored. A left operand that is a non-overloaded object falls back on a
+string or numeric comparison of whatever the C<ref> operator returns. That
+means that
+
+ $object ~~ X
+
+does I<not> invoke the overload method with C<I<X>> as an argument.
+Instead the above table is consulted as normal, and based on the type of
+C<I<X>>, overloading may or may not be invoked. For simple strings or
+numbers, in becomes equivalent to this:
+
+ $object ~~ $number ref($object) == $number
+ $object ~~ $string ref($object) eq $string
+
+For example, this reports that the handle smells IOish
+(but please don't really do this!):
+
+ use IO::Handle;
+ my $fh = IO::Handle->new();
+ if ($fh ~~ /\bIO\b/) {
+ say "handle smells IOish";
+ }
+
+That's because it treats C<$fh> as a string like
+C<"IO::Handle=GLOB(0x8039e0)">, then pattern matches against that.
+
=head2 Bitwise And
X<operator, bitwise, and> X<bitwise and> X<&>
@@ -474,9 +788,9 @@
(See also L<Integer Arithmetic> and L<Bitwise String Operators>.)
Note that "&" has lower priority than relational operators, so for example
-the brackets are essential in a test like
+the parentheses are essential in a test like
- print "Even\n" if ($x & 1) == 0;
+ print "Even\n" if ($x & 1) == 0;
=head2 Bitwise Or and Exclusive Or
X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
@@ -491,7 +805,7 @@
Note that "|" and "^" have lower priority than relational operators, so
for example the brackets are essential in a test like
- print "false\n" if (8 | 2) != 10;
+ print "false\n" if (8 | 2) != 10;
=head2 C-style Logical And
X<&&> X<logical and> X<operator, logical, and>
@@ -509,16 +823,18 @@
Scalar or list context propagates down to the right operand if it
is evaluated.
-=head2 C-style Logical Defined-Or
+=head2 Logical Defined-Or
X<//> X<operator, logical, defined-or>
Although it has no direct equivalent in C, Perl's C<//> operator is related
to its C-style or. In fact, it's exactly the same as C<||>, except that it
-tests the left hand side's definedness instead of its truth. Thus, C<$a // $b>
-is similar to C<defined($a) || $b> (except that it returns the value of C<$a>
-rather than the value of C<defined($a)>) and yields the same result as
-C<defined($a) ? $a : $b> (except that the ternary-operator form can be
-used as a lvalue, while C<$a // $b> cannot). This is very useful for
+tests the left hand side's definedness instead of its truth. Thus,
+C<< EXPR1 // EXPR2 >> returns the value of C<< EXPR1 >> if it's defined,
+otherwise, the value of C<< EXPR2 >> is returned. (C<< EXPR1 >> is evaluated
+in scalar context, C<< EXPR2 >> in the context of C<< // >> itself). Usually,
+this is the same result as C<< defined(EXPR1) ? EXPR1 : EXPR2 >> (except that
+the ternary-operator form can be used as a lvalue, while C<< EXPR1 // EXPR2 >>
+cannot). This is very useful for
providing default values for variables. If you actually want to test if
at least one of C<$a> and C<$b> is defined, use C<defined($a // $b)>.
@@ -538,7 +854,7 @@
@a = scalar(@b) || @c; # really meant this
@a = @b ? @b : @c; # this works fine, though
-As more readable alternatives to C<&&> and C<||> when used for
+As alternatives to C<&&> and C<||> when used for
control flow, Perl provides the C<and> and C<or> operators (see below).
The short-circuit behavior is identical. The precedence of "and"
and "or" is much lower, however, so that you can safely use them after a
@@ -552,6 +868,13 @@
unlink("alpha", "beta", "gamma")
|| (gripe(), next LINE);
+It would be even more readable to write that this way:
+
+ unless(unlink("alpha", "beta", "gamma")) {
+ gripe();
+ next LINE;
+ }
+
Using "or" for assignment is unlikely to do what you want; see below.
=head2 Range Operators
@@ -659,9 +982,9 @@
And now some examples as a list operator:
- for (101 .. 200) { print; } # print $_ 100 times
- @foo = @foo[0 .. $#foo]; # an expensive no-op
- @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
+ for (101 .. 200) { print } # print $_ 100 times
+ @foo = @foo[0 .. $#foo]; # an expensive no-op
+ @foo = @foo[$#foo-4 .. $#foo]; # slice last 5 items
The range operator (in list context) makes use of the magical
auto-increment algorithm if the operands are strings. You
@@ -675,7 +998,8 @@
to get a hexadecimal digit, or
- @z2 = ("01" .. "31"); print $z2[$mday];
+ @z2 = ("01" .. "31");
+ print $z2[$mday];
to get dates with leading zeros.
@@ -695,8 +1019,10 @@
you could use this instead:
use charnames "greek";
- my @greek_small = map { chr }
- ord "\N{alpha}" .. ord "\N{omega}";
+ my @greek_small = map { chr } ( ord("\N{alpha}")
+ ..
+ ord("\N{omega}")
+ );
However, because there are I<many> other lowercase Greek characters than
just those, to match lowercase Greek characters in a regular expression,
@@ -779,8 +1105,13 @@
then modifying the variable that was assigned to. This is useful
for modifying a copy of something, like this:
- ($tmp = $global) =~ tr [0-9] [a-j];
+ ($tmp = $global) =~ tr/13579/24680/;
+Although as of 5.14, that can be also be accomplished this way:
+
+ use v5.14;
+ $tmp = ($global =~ tr/13579/24680/r);
+
Likewise,
($a += 2) *= 3;
@@ -795,72 +1126,6 @@
the number of elements produced by the expression on the right hand
side of the assignment.
-=head2 The Triple-Dot Operator
-X<...> X<... operator> X<yada-yada operator> X<whatever operator>
-X<triple-dot operator>
-
-The triple-dot operator, C<...>, sometimes called the "whatever operator", the
-"yada-yada operator", or the "I<et cetera>" operator, is a placeholder for
-code. Perl parses it without error, but when you try to execute a whatever,
-it throws an exception with the text C<Unimplemented>:
-
- sub unimplemented { ... }
-
- eval { unimplemented() };
- if ($@ eq "Unimplemented" ) {
- say "Oh look, an exception--whatever.";
- }
-
-You can only use the triple-dot operator to stand in for a complete statement.
-These examples of the triple-dot work:
-
- { ... }
-
- sub foo { ... }
-
- ...;
-
- eval { ... };
-
- sub foo {
- my ($self) = shift;
- ...;
- }
-
- do {
- my $variable;
- ...;
- say "Hurrah!";
- } while $cheering;
-
-The yada-yada--or whatever--cannot stand in for an expression that is
-part of a larger statement since the C<...> is also the three-dot version
-of the binary range operator (see L<Range Operators>). These examples of
-the whatever operator are still syntax errors:
-
- print ...;
-
- open(PASSWD, ">", "/dev/passwd") or ...;
-
- if ($condition && ...) { say "Hello" }
-
-There are some cases where Perl can't immediately tell the difference
-between an expression and a statement. For instance, the syntax for a
-block and an anonymous hash reference constructor look the same unless
-there's something in the braces that give Perl a hint. The whatever
-is a syntax error if Perl doesn't guess that the C<{ ... }> is a
-block. In that case, it doesn't think the C<...> is the whatever
-because it's expecting an expression instead of a statement:
-
- my @transformed = map { ... } @input; # syntax error
-
-You can use a C<;> inside your block to denote that the C<{ ... }> is
-a block and not a hash reference constructor. Now the whatever works:
-
- my @transformed = map {; ... } @input; # ; disambiguates
-
- my @transformed = map { ...; } @input; # ; disambiguates
-
=head2 Comma Operator
X<comma> X<operator, comma> X<,>
@@ -872,8 +1137,8 @@
both its arguments into the list. These arguments are also evaluated
from left to right.
-The C<< => >> operator is a synonym for the comma except that it causes
-its left operand to be interpreted as a string if it begins with a letter
+The C<< => >> operator is a synonym for the comma except that it causes a
+word on its left to be interpreted as a string if it begins with a letter
or underscore and is composed only of letters, digits and underscores.
This includes operands that might otherwise be interpreted as operators,
constants, single number v-strings or function calls. If in doubt about
@@ -899,9 +1164,18 @@
The C<< => >> operator is helpful in documenting the correspondence
between keys and values in hashes, and other paired elements in lists.
- %hash = ( $key => $value );
- login( $username => $password );
+ %hash = ( $key => $value );
+ login( $username => $password );
+The special quoting behavior ignores precedence, and hence may apply to
+I<part> of the left operand:
+
+ print time.shift => "bbb";
+
+That example prints something like "1314363215shiftbbb", because the
+C<< => >> implicitly quotes the C<shift> immediately on its left, ignoring
+the fact that C<time.shift> is the entire left operand.
+
=head2 List Operators (Rightward)
X<operator, list, rightward> X<list operator>
@@ -909,11 +1183,19 @@
such that it controls all comma-separated expressions found there.
The only operators with lower precedence are the logical operators
"and", "or", and "not", which may be used to evaluate calls to list
-operators without the need for extra parentheses:
+operators without the need for parentheses:
- open HANDLE, "< $file"
- or die "Can't open $file: $!\n";
+ open HANDLE, "< :utf8", "filename" or die "Can't open: $!\n";
+However, some people find that code harder to read than writing
+it with parentheses:
+
+ open(HANDLE, "< :utf8", "filename") or die "Can't open: $!\n";
+
+in which case you might as well just use the more customary "||" operator:
+
+ open(HANDLE, "< :utf8", "filename") || die "Can't open: $!\n";
+
See also discussion of list operators in L<Terms and List Operators (Leftward)>.
=head2 Logical Not
@@ -930,9 +1212,9 @@
precedence. This means that it short-circuits: the right
expression is evaluated only if the left expression is true.
-=head2 Logical or, Defined or, and Exclusive Or
+=head2 Logical or and Exclusive Or
X<operator, logical, or> X<operator, logical, xor>
-X<operator, logical, defined or> X<operator, logical, exclusive or>
+X<operator, logical, exclusive or>
X<or> X<xor>
Binary "or" returns the logical disjunction of the two surrounding
@@ -959,9 +1241,11 @@
Then again, you could always use parentheses.
-Binary "xor" returns the exclusive-OR of the two surrounding expressions.
+Binary C<xor> returns the exclusive-OR of the two surrounding expressions.
It cannot short-circuit (of course).
+There is no low precedence operator for defined-OR.
+
=head2 C Operators Missing From Perl
X<operator, missing from perl> X<&> X<*>
X<typecasting> X<(TYPE)>
@@ -1123,6 +1407,10 @@
\c^ chr(30)
\c? chr(127)
+In other words, it's the character whose code point has had 64 xor'd with
+its uppercase. C<\c?> is DELETE because C<ord("?") ^ 64> is 127, and
+C<\c@> is NULL because the ord of "@" is 64, so xor'ing 64 itself produces 0.
+
Also, C<\c\I<X>> yields C< chr(28) . "I<X>"> for any I<X>, but cannot come at the
end of a string, because the backslash would be parsed as escaping the end
quote.
@@ -1134,9 +1422,9 @@
Use of any other character following the "c" besides those listed above is
discouraged, and some are deprecated with the intention of removing
-those in Perl 5.16. What happens for any of these
-other characters currently though, is that the value is derived by inverting
-the 7th bit (0x40).
+those in a later Perl version. What happens for any of these
+other characters currently though, is that the value is derived by xor'ing
+with the seventh bit, which is 64.
To get platform independent controls, you can use C<\N{...}>.
@@ -1158,18 +1446,19 @@
Some contexts allow 2 or even 1 digit, but any usage without exactly
three digits, the first being a zero, may give unintended results. (For
-example, see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
+example, in a regular expression it may be confused with a backreference;
+see L<perlrebackslash/Octal escapes>.) Starting in Perl 5.14, you may
use C<\o{}> instead, which avoids all these problems. Otherwise, it is best to
use this construct only for ordinals C<\077> and below, remembering to pad to
the left with zeros to make three digits. For larger ordinals, either use
-C<\o{}> , or convert to something else, such as to hex and use C<\x{}>
+C<\o{}>, or convert to something else, such as to hex and use C<\x{}>
instead.
Having fewer than 3 digits may lead to a misleading warning message that says
that what follows is ignored. For example, C<"\128"> in the ASCII character set
is equivalent to the two characters C<"\n8">, but the warning C<Illegal octal
-digit '8' ignored> will be thrown. To avoid this warning, make sure to pad
-your octal number with C<0>'s: C<"\0128">.
+digit '8' ignored> will be thrown. If C<"\n8"> is what you want, you can
+avoid this warning by padding your octal number with C<0>'s: C<"\0128">.
=item [8]
@@ -1187,10 +1476,10 @@
from 0) is the letter "P", and in EBCDIC it is the ampersand symbol "&".
C<\x{100}> and C<\o{400}> are both 256 in decimal, so the number is interpreted
as a Unicode code point no matter what the native encoding is. The name of the
-character in the 100th position (indexed by 0) in Unicode is
+character in the 256th position (indexed by 0) in Unicode is
C<LATIN CAPITAL LETTER A WITH MACRON>.
-There are a couple of exceptions to the above rule. C<\N{U+I<hex number>}> is
+There are a couple of exceptions to the above rule. S<C<\N{U+I<hex number>}>> is
always interpreted as a Unicode code point, so that C<\N{U+0050}> is "P" even
on EBCDIC platforms. And if L<C<S<use encoding>>|encoding> is in effect, the
number is considered to be in that encoding, and is translated from that into
@@ -1200,33 +1489,42 @@
=back
B<NOTE>: Unlike C and other languages, Perl has no C<\v> escape sequence for
-the vertical tab (VT - ASCII 11), but you may use C<\ck> or C<\x0b>. (C<\v>
+the vertical tab (VT, which is 11 in both ASCII and EBCDIC), but you may
+use C<\ck> or
+C<\x0b>. (C<\v>
does have meaning in regular expression patterns in Perl, see L<perlre>.)
The following escape sequences are available in constructs that interpolate,
but not in transliterations.
-X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q>
+X<\l> X<\u> X<\L> X<\U> X<\E> X<\Q> X<\F>
\l lowercase next character only
\u titlecase (not uppercase!) next character only
- \L lowercase all characters till \E seen
- \U uppercase all characters till \E seen
- \Q quote non-word characters till \E
+ \L lowercase all characters till \E or end of string
+ \U uppercase all characters till \E or end of string
+ \F foldcase all characters till \E or end of string
+ \Q quote (disable) pattern metacharacters till \E or
+ end of string
\E end either case modification or quoted section
(whichever was last seen)
-C<\L>, C<\U>, and C<\Q> can stack, in which case you need one
+See L<perlfunc/quotemeta> for the exact definition of characters that
+are quoted by C<\Q>.
+
+C<\L>, C<\U>, C<\F>, and C<\Q> can stack, in which case you need one
C<\E> for each. For example:
- say "This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
- This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
+ say"This \Qquoting \ubusiness \Uhere isn't quite\E done yet,\E is it?";
+ This quoting\ Business\ HERE\ ISN\'T\ QUITE\ done\ yet\, is it?
-If C<use locale> is in effect, the case map used by C<\l>, C<\L>,
+If C<use locale> is in effect (but not C<use locale ':not_characters'>),
+the case map used by C<\l>, C<\L>,
C<\u>, and C<\U> is taken from the current locale. See L<perllocale>.
If Unicode (for example, C<\N{}> or code points of 0x100 or
beyond) is being used, the case map used by C<\l>, C<\L>, C<\u>, and
C<\U> is as defined by Unicode. That means that case-mapping
a single character can sometimes produce several characters.
+Under C<use locale>, C<\F> produces the same results as C<\L>.
All systems use the virtual C<"\n"> to represent a line terminator,
called a "newline". There is no such thing as an unvarying, physical
@@ -1304,9 +1602,11 @@
is done. Returns a Perl value which may be used instead of the
corresponding C</STRING/msixpodual> expression. The returned value is a
normalized version of the original pattern. It magically differs from
-a string containing the same characters: C<ref(qr/x/)> returns "Regexp",
-even though dereferencing the result returns undef.
+a string containing the same characters: C<ref(qr/x/)> returns "Regexp";
+however, dereferencing it is not well defined (you currently get the
+normalized version of the original pattern, but this may change).
+
For example,
$rex = qr/my.STRING/is;
@@ -1320,7 +1620,8 @@
The result may be used as a subpattern in a match:
$re = qr/$pattern/;
- $string =~ /foo${re}bar/; # can be interpolated in other patterns
+ $string =~ /foo${re}bar/; # can be interpolated in other
+ # patterns
$string =~ $re; # or used standalone
$string =~ /$re/; # or this way
@@ -1353,14 +1654,15 @@
i Do case-insensitive pattern matching.
x Use extended regular expressions.
p When matching preserve a copy of the matched string so
- that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be defined.
+ that ${^PREMATCH}, ${^MATCH}, ${^POSTMATCH} will be
+ defined.
o Compile pattern only once.
- l Use the locale
- u Use Unicode rules
- a Use ASCII for \d, \s, \w; specifying two a's further restricts
- /i matching so that no ASCII character will match a non-ASCII
- one
- d Use Unicode or native charset, as in 5.12 and earlier
+ a ASCII-restrict: Use ASCII for \d, \s, \w; specifying two
+ a's further restricts /i matching so that no ASCII
+ character will match a non-ASCII one.
+ l Use the locale.
+ u Use Unicode rules.
+ d Use Unicode or native charset, as in 5.12 and earlier.
If a precompiled pattern is embedded in a larger pattern then the effect
of "msixpluad" will be propagated appropriately. The effect the "o"
@@ -1368,12 +1670,14 @@
explicitly using it.
The last four modifiers listed above, added in Perl 5.14,
-control the character set semantics.
+control the character set semantics, but C</a> is the only one you are likely
+to want to specify explicitly; the other three are selected
+automatically by various pragmas.
See L<perlre> for additional information on valid syntax for STRING, and
for a detailed look at the semantics of regular expressions. In
-particular, all the modifiers execpt C</o> are further explained in
-L<perlre/Modifiers>. C</o> is described in the next section.
+particular, all modifiers except the largely obsolete C</o> are further
+explained in L<perlre/Modifiers>. C</o> is described in the next section.
=item m/PATTERN/msixpodualgc
X<m> X<operator, match>
@@ -1393,7 +1697,8 @@
process modifiers are available:
g Match globally, i.e., find all occurrences.
- c Do not reset search position on a failed match when /g is in effect.
+ c Do not reset search position on a failed match when /g is
+ in effect.
If "/" is the delimiter then the initial C<m> is optional. With the C<m>
you can use any pair of non-whitespace (ASCII) characters
@@ -1425,7 +1730,7 @@
don't change, and you need to wring out the last little bit of speed by
having Perl skip testing for that. (There is a maintenance penalty for
doing this, as mentioning C</o> constitutes a promise that you won't
-change the variables in the pattern. If you change them, Perl won't
+change the variables in the pattern. If you do change them, Perl won't
even notice.)
=item 2
@@ -1434,8 +1739,22 @@
regardless of whether they change or not. (But there are saner ways
of accomplishing this than using C</o>.)
+=item 3
+
+If the pattern contains embedded code, such as
+
+ use re 'eval';
+ $code = 'foo(?{ $x })';
+ /$code/
+
+then perl will recompile each time, even though the pattern string hasn't
+changed, to ensure that the current value of C<$x> is seen each time.
+Use C</o> if you want to avoid this.
+
=back
+The bottom line is that using C</o> is almost never a good idea.
+
=item The empty pattern //
If the PATTERN evaluates to the empty string, the last
@@ -1458,30 +1777,29 @@
If the C</g> option is not used, C<m//> in list context returns a
list consisting of the subexpressions matched by the parentheses in the
-pattern, i.e., (C<$1>, C<$2>, C<$3>...). (Note that here C<$1> etc. are
-also set, and that this differs from Perl 4's behavior.) When there are
-no parentheses in the pattern, the return value is the list C<(1)> for
-success. With or without parentheses, an empty list is returned upon
-failure.
+pattern, that is, (C<$1>, C<$2>, C<$3>...) (Note that here C<$1> etc. are
+also set). When there are no parentheses in the pattern, the return
+value is the list C<(1)> for success.
+With or without parentheses, an empty list is returned upon failure.
Examples:
- open(TTY, "+>/dev/tty")
- || die "can't access /dev/tty: $!";
+ open(TTY, "+</dev/tty")
+ || die "can't access /dev/tty: $!";
- <TTY> =~ /^y/i && foo(); # do foo if desired
+ <TTY> =~ /^y/i && foo(); # do foo if desired
- if (/Version: *([0-9.]*)/) { $version = $1; }
+ if (/Version: *([0-9.]*)/) { $version = $1; }
- next if m#^/usr/spool/uucp#;
+ next if m#^/usr/spool/uucp#;
- # poor man's grep
- $arg = shift;
- while (<>) {
- print if /$arg/o; # compile only once (no longer needed!)
- }
+ # poor man's grep
+ $arg = shift;
+ while (<>) {
+ print if /$arg/o; # compile only once (no longer needed!)
+ }
- if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
+ if (($F1, $F2, $Etc) = ($foo =~ /^(\S+)\s+(\S+)\s*(.*)/))
This last example splits $foo into the first two words and the
remainder of the line, and assigns those three fields to $F1, $F2, and
@@ -1501,7 +1819,7 @@
The position after the last match can be read or set using the C<pos()>
function; see L<perlfunc/pos>. A failed match normally resets the
search position to the beginning of the string, but you can avoid that
-by adding the C</c> modifier (e.g. C<m//gc>). Modifying the target
+by adding the C</c> modifier (for example, C<m//gc>). Modifying the target
string also resets the search position.
=item \G assertion
@@ -1533,26 +1851,30 @@
Here's another way to check for sentences in a paragraph:
- my $sentence_rx = qr{
- (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or whitespace
- \p{Lu} # capital letter
- .*? # a bunch of anything
- (?<= \S ) # that ends in non-whitespace
- (?<! \b [DMS]r ) # but isn't a common abbreviation
- (?<! \b Mrs )
- (?<! \b Sra )
- (?<! \b St )
- [.?!] # followed by a sentence ender
- (?= $ | \s ) # in front of end-of-string or whitespace
- }sx;
- local $/ = "";
- while (my $paragraph = <>) {
- say "NEW PARAGRAPH";
- my $count = 0;
- while ($paragraph =~ /($sentence_rx)/g) {
- printf "\tgot sentence %d: <%s>\n", ++$count, $1;
- }
+ my $sentence_rx = qr{
+ (?: (?<= ^ ) | (?<= \s ) ) # after start-of-string or
+ # whitespace
+ \p{Lu} # capital letter
+ .*? # a bunch of anything
+ (?<= \S ) # that ends in non-
+ # whitespace
+ (?<! \b [DMS]r ) # but isn't a common abbr.
+ (?<! \b Mrs )
+ (?<! \b Sra )
+ (?<! \b St )
+ [.?!] # followed by a sentence
+ # ender
+ (?= $ | \s ) # in front of end-of-string
+ # or whitespace
+ }sx;
+ local $/ = "";
+ while (my $paragraph = <>) {
+ say "NEW PARAGRAPH";
+ my $count = 0;
+ while ($paragraph =~ /($sentence_rx)/g) {
+ printf "\tgot sentence %d: <%s>\n", ++$count, $1;
}
+ }
Here's how to use C<m//gc> with C<\G>:
@@ -1589,16 +1911,21 @@
regexp tries to match where the previous one leaves off.
$_ = <<'EOL';
- $url = URI::URL->new( "http://example.com/" ); die if $url eq "xXx";
+ $url = URI::URL->new( "http://example.com/" );
+ die if $url eq "xXx";
EOL
LOOP: {
print(" digits"), redo LOOP if /\G\d+\b[,.;]?\s*/gc;
- print(" lowercase"), redo LOOP if /\G\p{Ll}+\b[,.;]?\s*/gc;
- print(" UPPERCASE"), redo LOOP if /\G\p{Lu}+\b[,.;]?\s*/gc;
- print(" Capitalized"), redo LOOP if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
+ print(" lowercase"), redo LOOP
+ if /\G\p{Ll}+\b[,.;]?\s*/gc;
+ print(" UPPERCASE"), redo LOOP
+ if /\G\p{Lu}+\b[,.;]?\s*/gc;
+ print(" Capitalized"), redo LOOP
+ if /\G\p{Lu}\p{Ll}+\b[,.;]?\s*/gc;
print(" MiXeD"), redo LOOP if /\G\pL+\b[,.;]?\s*/gc;
- print(" alphanumeric"), redo LOOP if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
+ print(" alphanumeric"), redo LOOP
+ if /\G[\p{Alpha}\pN]+\b[,.;]?\s*/gc;
print(" line-noise"), redo LOOP if /\G\W+/gc;
print ". That's all!\n";
}
@@ -1605,10 +1932,10 @@
Here is the output (split into several lines):
- line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
- line-noise lowercase line-noise lowercase line-noise lowercase
- lowercase line-noise lowercase lowercase line-noise lowercase
- lowercase line-noise MiXeD line-noise. That's all!
+ line-noise lowercase line-noise UPPERCASE line-noise UPPERCASE
+ line-noise lowercase line-noise lowercase line-noise lowercase
+ lowercase line-noise lowercase lowercase line-noise lowercase
+ lowercase line-noise MiXeD line-noise. That's all!
=item m?PATTERN?msixpodualgc
X<?> X<operator, match-once>
@@ -1676,16 +2003,18 @@
specific options:
e Evaluate the right side as an expression.
- ee Evaluate the right side as a string then eval the result.
- r Return substitution and leave the original string untouched.
+ ee Evaluate the right side as a string then eval the
+ result.
+ r Return substitution and leave the original string
+ untouched.
Any non-whitespace delimiter may replace the slashes. Add space after
the C<s> when using a character allowed in identifiers. If single quotes
are used, no interpretation is done on the replacement string (the C</e>
-modifier overrides this, however). Unlike Perl 4, Perl 5 treats backticks
+modifier overrides this, however). Note that Perl treats backticks
as normal delimiters; the replacement text is not evaluated as a command.
If the PATTERN is delimited by bracketing quotes, the REPLACEMENT has
-its own pair of quotes, which may or may not be bracketing quotes, e.g.,
+its own pair of quotes, which may or may not be bracketing quotes, for example,
C<s(foo)(bar)> or C<< s<foo>/bar/ >>. A C</e> will cause the
replacement portion to be treated as a full-fledged Perl expression
and evaluated right then and there. It is, however, syntax checked at
@@ -1694,20 +2023,24 @@
Examples:
- s/\bgreen\b/mauve/g; # don't change wintergreen
+ s/\bgreen\b/mauve/g; # don't change wintergreen
$path =~ s|/usr/bin|/usr/local/bin|;
s/Login: $foo/Login: $bar/; # run-time pattern
- ($foo = $bar) =~ s/this/that/; # copy first, then change
- ($foo = "$bar") =~ s/this/that/; # convert to string, copy, then change
+ ($foo = $bar) =~ s/this/that/; # copy first, then
+ # change
+ ($foo = "$bar") =~ s/this/that/; # convert to string,
+ # copy, then change
$foo = $bar =~ s/this/that/r; # Same as above using /r
$foo = $bar =~ s/this/that/r
- =~ s/that/the other/r; # Chained substitutes using /r
- @foo = map { s/this/that/r } @bar # /r is very useful in maps
+ =~ s/that/the other/r; # Chained substitutes
+ # using /r
+ @foo = map { s/this/that/r } @bar # /r is very useful in
+ # maps
- $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-count
+ $count = ($paragraph =~ s/Mister\b/Mr./g); # get change-cnt
$_ = 'abc123xyz';
s/\d+/$&*2/e; # yields 'abc246xyz'
@@ -1744,9 +2077,11 @@
\*/ # Match the closing delimiter.
} []gsx;
- s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_, expensively
+ s/^\s*(.*?)\s*$/$1/; # trim whitespace in $_,
+ # expensively
- for ($variable) { # trim whitespace in $variable, cheap
+ for ($variable) { # trim whitespace in $variable,
+ # cheap
s/^\s+//;
s/\s+$//;
}
@@ -1766,14 +2101,6 @@
# expand tabs to 8-column spacing
1 while s/\t+/' ' x (length($&)*8 - length($`)%8)/e;
-C<s///le> is treated as a substitution followed by the C<le> operator, not
-the C</le> flags. This may change in a future version of Perl. It
-produces a warning if warnings are enabled. To disambiguate, use a space
-or change the order of the flags:
-
- s/foo/bar/ le 5; # "le" infix operator
- s/foo/bar/el; # "e" and "l" flags
-
=back
=head2 Quote-Like Operators
@@ -1812,7 +2139,7 @@
=item `STRING`
A string which is (possibly) interpolated and then executed as a
-system command with C</bin/sh> or its equivalent. Shell wildcards,
+system command with F</bin/sh> or its equivalent. Shell wildcards,
pipes, and redirections will be honored. The collected standard
output of the command is returned; standard error is unaffected. In
scalar context, it comes back as a single (potentially multi-line)
@@ -1872,10 +2199,10 @@
capable of dealing with multiline commands, so putting newlines in
the string may not get you what you want. You may be able to evaluate
multiple commands in a single line by separating them with the command
-separator character, if your shell supports that (e.g. C<;> on many Unix
-shells; C<&> on the Windows NT C<cmd> shell).
+separator character, if your shell supports that (for example, C<;> on
+many Unix shells and C<&> on the Windows NT C<cmd> shell).
-Beginning with v5.6.0, Perl will attempt to flush all files opened for
+Perl will attempt to flush all files opened for
output before starting the child process, but this may not be supported
on some platforms (see L<perlport>). To be safe, you may need to set
C<$|> ($AUTOFLUSH in English) or call the C<autoflush()> method of
@@ -2147,8 +2474,9 @@
FINIS
If you use a here-doc within a delimited construct, such as in C<s///eg>,
-the quoted material must come on the lines following the final delimiter.
-So instead of
+the quoted material must still come on the line following the
+C<<< <<FOO >>> marker, which means it may be inside the delimited
+construct:
s/this/<<E . 'that'
the other
@@ -2155,7 +2483,8 @@
E
. 'more '/eg;
-you have to write
+It works this way as of Perl 5.18. Historically, it was inconsistent, and
+you would have to write
s/this/<<E . 'that'
. 'more '/eg;
@@ -2162,9 +2491,7 @@
the other
E
-If the terminating identifier is on the last line of the program, you
-must be sure there is a newline after it; otherwise, Perl will give the
-warning B<Can't find string terminator "END" anywhere before EOF...>.
+outside of string evals.
Additionally, quoting rules for the end-of-string identifier are
unrelated to Perl's quoting rules. C<q()>, C<qq()>, and the like are not
@@ -2235,7 +2562,7 @@
C<qq[]> and C<qq]]> constructs.
When searching for single-character delimiters, escaped delimiters
-and C<\\> are skipped. For example, while searching for terminating C</>,
+and C<\\> are skipped. For example, while searching for terminating C</>,
combinations of C<\\> and C<\/> are skipped. If the delimiters are
bracketing, nested pairs are also skipped. For example, while searching
for closing C<]> paired with the opening C<[>, combinations of C<\\>, C<\]>,
@@ -2242,8 +2569,9 @@
and C<\[> are all skipped, and nested C<[> and C<]> are skipped as well.
However, when backslashes are used as the delimiters (like C<qq\\> and
C<tr\\\>), nothing is skipped.
-During the search for the end, backslashes that escape delimiters
-are removed (exactly speaking, they are not copied to the safe location).
+During the search for the end, backslashes that escape delimiters or
+other backslashes are removed (exactly speaking, they are not copied to the
+safe location).
For constructs with three-part delimiters (C<s///>, C<y///>, and
C<tr///>), the search is repeated once more.
@@ -2317,7 +2645,7 @@
=item C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob> >>, C<<<"EOF">
-C<\Q>, C<\U>, C<\u>, C<\L>, C<\l> (possibly paired with C<\E>) are
+C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> (possibly paired with C<\E>) are
converted to corresponding Perl constructs. Thus, C<"$foo\Qbaz$bar">
is converted to C<$foo . (quotemeta("baz" . $bar))> internally.
The other escape sequences such as C<\200> and C<\t> and backslashed
@@ -2326,7 +2654,7 @@
Let it be stressed that I<whatever falls between C<\Q> and C<\E>>
is interpolated in the usual way. Something like C<"\Q\\E"> has
-no C<\E> inside. instead, it has C<\Q>, C<\\>, and C<E>, so the
+no C<\E> inside. Instead, it has C<\Q>, C<\\>, and C<E>, so the
result is the same as for C<"\\\\E">. As a general rule, backslashes
between C<\Q> and C<\E> may lead to counterintuitive results. So,
C<"\Q\t\E"> is converted to C<quotemeta("\t")>, which is the same
@@ -2368,7 +2696,7 @@
=item the replacement of C<s///>
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, and interpolation
+Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F> and interpolation
happens as with C<qq//> constructs.
It is at this step that C<\1> is begrudgingly converted to C<$1> in
@@ -2379,7 +2707,7 @@
=item C<RE> in C<?RE?>, C</RE/>, C<m/RE/>, C<s/RE/foo/>,
-Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\E>,
+Processing of C<\Q>, C<\U>, C<\u>, C<\L>, C<\l>, C<\F>, C<\E>,
and interpolation happens (almost) as with C<qq//> constructs.
Processing of C<\N{...}> is also done here, and compiled into an intermediate
@@ -2394,6 +2722,10 @@
treated as an array symbol (for example C<@foo>),
even though the same text in C<qq//> gives interpolation of C<\c@>.
+Code blocks such as C<(?{BLOCK})> are handled by temporarily passing control
+back to the perl parser, in a similar way that an interpolated array
+subscript expression such as C<"foo$array[1+f("[xyz")]bar"> would be.
+
Moreover, inside C<(?{BLOCK})>, C<(?# comment )>, and
a C<#>-comment in a C<//x>-regular expression, no processing is
performed whatsoever. This is the first step at which the presence
@@ -2462,10 +2794,12 @@
The terminator of this construct is found using the same rules as
for finding the terminator of a C<{}>-delimited construct, the only
exception being that C<]> immediately following C<[> is treated as
-though preceded by a backslash. Similarly, the terminator of
-C<(?{...})> is found using the same rules as for finding the
-terminator of a C<{}>-delimited construct.
+though preceded by a backslash.
+The terminator of runtime C<(?{...})> is found by temporarily switching
+control to the perl parser, which should stop at the point where the
+logically balancing terminating C<}> is found.
+
It is possible to inspect both the string given to RE engine and the
resulting finite automaton. See the arguments C<debug>/C<debugcolor>
in the C<use L<re>> pragma, as well as Perl's B<-Dr> command-line
@@ -2535,14 +2869,15 @@
print while ($_ = <STDIN>);
print while <STDIN>;
-This also behaves similarly, but avoids $_ :
+This also behaves similarly, but assigns to a lexical variable
+instead of to C<$_>:
while (my $line = <STDIN>) { print $line }
In these loop constructs, the assigned value (whether assignment
is automatic or explicit) is then tested to see whether it is
-defined. The defined test avoids problems where line has a string
-value that would be treated as false by Perl, for example a "" or
+defined. The defined test avoids problems where the line has a string
+value that would be treated as false by Perl; for example a "" or
a "0" with no trailing newline. If you really mean for such values
to terminate the loop, they should be tested for explicitly:
@@ -2549,7 +2884,7 @@
while (($_ = <STDIN>) ne '0') { ... }
while (<STDIN>) { last unless $_; ... }
-In other boolean contexts, C<< <filehandle> >> without an
+In other boolean contexts, C<< <FILEHANDLE> >> without an
explicit C<defined> test or comparison elicits a warning if the
C<use warnings> pragma or the B<-w>
command-line switch (the C<$^W> variable) is in effect.
@@ -2571,7 +2906,9 @@
See L<perlfunc/readline>.
The null filehandle <> is special: it can be used to emulate the
-behavior of B<sed> and B<awk>. Input from <> comes either from
+behavior of B<sed> and B<awk>, and any other Unix filter program
+that takes a list of filenames, doing the same to each line
+of input from all of them. Input from <> comes either from
standard input, or from each file listed on the command line. Here's
how it works: the first time <> is evaluated, the @ARGV array is
checked, and if it is empty, C<$ARGV[0]> is set to "-", which when opened
@@ -2645,7 +2982,7 @@
If you call it again after this, it will assume you are processing another
@ARGV list, and if you haven't set @ARGV, will read input from STDIN.
-If what the angle brackets contain is a simple scalar variable (e.g.,
+If what the angle brackets contain is a simple scalar variable (for example,
<$foo>), then that variable contains the name of the
filehandle to input from, or its typeglob, or a reference to the
same. For example:
@@ -2696,7 +3033,8 @@
the next value each time it's called, or C<undef> when the list has
run out. As with filehandle reads, an automatic C<defined> is
generated when the glob occurs in the test part of a C<while>,
-because legal glob returns (e.g. a file called F<0>) would otherwise
+because legal glob returns (for example,
+a file called F<0>) would otherwise
terminate the loop. Again, C<undef> is returned only once. So if
you're expecting a single value from a glob, it is much better to
say
@@ -2727,8 +3065,9 @@
variable substitution. Backslash interpolation also happens at
compile time. You can say
- 'Now is the time for all' . "\n" .
- 'good men to come to.'
+ 'Now is the time for all'
+ . "\n"
+ . 'good men to come to.'
and this all reduces to one string internally. Likewise, if
you say
@@ -2737,7 +3076,7 @@
if (-s $file > 5 + 100 * 2**16) { }
}
-the compiler will precompute the number which that expression
+the compiler precomputes the number which that expression
represents so that the interpreter won't have to.
=head2 No-ops
@@ -2744,7 +3083,7 @@
X<no-op> X<nop>
Perl doesn't officially have a no-op operator, but the bare constants
-C<0> and C<1> are special-cased to not produce a warning in a void
+C<0> and C<1> are special-cased not to produce a warning in void
context, so you can for example safely do
1 while foo();
@@ -2814,6 +3153,7 @@
machines.
=head2 Floating-point Arithmetic
+
X<floating-point> X<floating point> X<float> X<real>
While C<use integer> provides integer-only arithmetic, there is no
@@ -2860,7 +3200,7 @@
X<number, arbitrary precision>
The standard C<Math::BigInt>, C<Math::BigRat>, and C<Math::BigFloat> modules,
-along with the C<bigint>, C<bigrat>, and C<bitfloat> pragmas, provide
+along with the C<bignum>, C<bigint>, and C<bigrat> pragmas, provide
variable-precision arithmetic and overloaded operators, although
they're currently pretty slow. At the cost of some space and
considerable speed, they avoid the normal pitfalls associated with
@@ -2889,7 +3229,6 @@
Here is a short, but incomplete summary:
- Math::Fraction big, unlimited fractions like 9973 / 12967
Math::String treat string sequences like numbers
Math::FixedPrecision calculate with a fixed precision
Math::Currency for currency calculations
@@ -2896,10 +3235,13 @@
Bit::Vector manipulate bit vectors fast (uses C)
Math::BigIntFast Bit::Vector wrapper for big numbers
Math::Pari provides access to the Pari C library
- Math::BigInteger uses an external C library
- Math::Cephes uses external Cephes C library (no big numbers)
+ Math::Cephes uses the external Cephes C library (no
+ big numbers)
Math::Cephes::Fraction fractions via the Cephes library
Math::GMP another one using an external C library
+ Math::GMPz an alternative interface to libgmp's big ints
+ Math::GMPq an interface to libgmp's fraction numbers
+ Math::GMPf an interface to libgmp's floating point numbers
Choose wisely.
Property changes on: trunk/contrib/perl/pod/perlop.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlopentut.pod
===================================================================
--- trunk/contrib/perl/pod/perlopentut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlopentut.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlopentut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlothrtut.pod (from rev 6437, vendor/perl/5.18.1/pod/perlothrtut.pod)
===================================================================
--- trunk/contrib/perl/pod/perlothrtut.pod (rev 0)
+++ trunk/contrib/perl/pod/perlothrtut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,1067 @@
+=head1 NAME
+
+perlothrtut - old tutorial on threads in Perl
+
+=head1 DESCRIPTION
+
+B<WARNING>:
+This tutorial describes the old-style thread model that was introduced in
+release 5.005. This model is deprecated, and has been removed
+for version 5.10. The interfaces described here were considered
+experimental, and are likely to be buggy.
+
+For information about the new interpreter threads ("ithreads") model, see
+the F<perlthrtut> tutorial, and the L<threads> and L<threads::shared>
+modules.
+
+You are strongly encouraged to migrate any existing threads code to the
+new model as soon as possible.
+
+=head1 What Is A Thread Anyway?
+
+A thread is a flow of control through a program with a single
+execution point.
+
+Sounds an awful lot like a process, doesn't it? Well, it should.
+Threads are one of the pieces of a process. Every process has at least
+one thread and, up until now, every process running Perl had only one
+thread. With 5.005, though, you can create extra threads. We're going
+to show you how, when, and why.
+
+=head1 Threaded Program Models
+
+There are three basic ways that you can structure a threaded
+program. Which model you choose depends on what you need your program
+to do. For many non-trivial threaded programs you'll need to choose
+different models for different pieces of your program.
+
+=head2 Boss/Worker
+
+The boss/worker model usually has one `boss' thread and one or more
+`worker' threads. The boss thread gathers or generates tasks that need
+to be done, then parcels those tasks out to the appropriate worker
+thread.
+
+This model is common in GUI and server programs, where a main thread
+waits for some event and then passes that event to the appropriate
+worker threads for processing. Once the event has been passed on, the
+boss thread goes back to waiting for another event.
+
+The boss thread does relatively little work. While tasks aren't
+necessarily performed faster than with any other method, it tends to
+have the best user-response times.
+
+=head2 Work Crew
+
+In the work crew model, several threads are created that do
+essentially the same thing to different pieces of data. It closely
+mirrors classical parallel processing and vector processors, where a
+large array of processors do the exact same thing to many pieces of
+data.
+
+This model is particularly useful if the system running the program
+will distribute multiple threads across different processors. It can
+also be useful in ray tracing or rendering engines, where the
+individual threads can pass on interim results to give the user visual
+feedback.
+
+=head2 Pipeline
+
+The pipeline model divides up a task into a series of steps, and
+passes the results of one step on to the thread processing the
+next. Each thread does one thing to each piece of data and passes the
+results to the next thread in line.
+
+This model makes the most sense if you have multiple processors so two
+or more threads will be executing in parallel, though it can often
+make sense in other contexts as well. It tends to keep the individual
+tasks small and simple, as well as allowing some parts of the pipeline
+to block (on I/O or system calls, for example) while other parts keep
+going. If you're running different parts of the pipeline on different
+processors you may also take advantage of the caches on each
+processor.
+
+This model is also handy for a form of recursive programming where,
+rather than having a subroutine call itself, it instead creates
+another thread. Prime and Fibonacci generators both map well to this
+form of the pipeline model. (A version of a prime number generator is
+presented later on.)
+
+=head1 Native threads
+
+There are several different ways to implement threads on a system. How
+threads are implemented depends both on the vendor and, in some cases,
+the version of the operating system. Often the first implementation
+will be relatively simple, but later versions of the OS will be more
+sophisticated.
+
+While the information in this section is useful, it's not necessary,
+so you can skip it if you don't feel up to it.
+
+There are three basic categories of threads-user-mode threads, kernel
+threads, and multiprocessor kernel threads.
+
+User-mode threads are threads that live entirely within a program and
+its libraries. In this model, the OS knows nothing about threads. As
+far as it's concerned, your process is just a process.
+
+This is the easiest way to implement threads, and the way most OSes
+start. The big disadvantage is that, since the OS knows nothing about
+threads, if one thread blocks they all do. Typical blocking activities
+include most system calls, most I/O, and things like sleep().
+
+Kernel threads are the next step in thread evolution. The OS knows
+about kernel threads, and makes allowances for them. The main
+difference between a kernel thread and a user-mode thread is
+blocking. With kernel threads, things that block a single thread don't
+block other threads. This is not the case with user-mode threads,
+where the kernel blocks at the process level and not the thread level.
+
+This is a big step forward, and can give a threaded program quite a
+performance boost over non-threaded programs. Threads that block
+performing I/O, for example, won't block threads that are doing other
+things. Each process still has only one thread running at once,
+though, regardless of how many CPUs a system might have.
+
+Since kernel threading can interrupt a thread at any time, they will
+uncover some of the implicit locking assumptions you may make in your
+program. For example, something as simple as C<$a = $a + 2> can behave
+unpredictably with kernel threads if $a is visible to other
+threads, as another thread may have changed $a between the time it
+was fetched on the right hand side and the time the new value is
+stored.
+
+Multiprocessor Kernel Threads are the final step in thread
+support. With multiprocessor kernel threads on a machine with multiple
+CPUs, the OS may schedule two or more threads to run simultaneously on
+different CPUs.
+
+This can give a serious performance boost to your threaded program,
+since more than one thread will be executing at the same time. As a
+tradeoff, though, any of those nagging synchronization issues that
+might not have shown with basic kernel threads will appear with a
+vengeance.
+
+In addition to the different levels of OS involvement in threads,
+different OSes (and different thread implementations for a particular
+OS) allocate CPU cycles to threads in different ways.
+
+Cooperative multitasking systems have running threads give up control
+if one of two things happen. If a thread calls a yield function, it
+gives up control. It also gives up control if the thread does
+something that would cause it to block, such as perform I/O. In a
+cooperative multitasking implementation, one thread can starve all the
+others for CPU time if it so chooses.
+
+Preemptive multitasking systems interrupt threads at regular intervals
+while the system decides which thread should run next. In a preemptive
+multitasking system, one thread usually won't monopolize the CPU.
+
+On some systems, there can be cooperative and preemptive threads
+running simultaneously. (Threads running with realtime priorities
+often behave cooperatively, for example, while threads running at
+normal priorities behave preemptively.)
+
+=head1 What kind of threads are perl threads?
+
+If you have experience with other thread implementations, you might
+find that things aren't quite what you expect. It's very important to
+remember when dealing with Perl threads that Perl Threads Are Not X
+Threads, for all values of X. They aren't POSIX threads, or
+DecThreads, or Java's Green threads, or Win32 threads. There are
+similarities, and the broad concepts are the same, but if you start
+looking for implementation details you're going to be either
+disappointed or confused. Possibly both.
+
+This is not to say that Perl threads are completely different from
+everything that's ever come before--they're not. Perl's threading
+model owes a lot to other thread models, especially POSIX. Just as
+Perl is not C, though, Perl threads are not POSIX threads. So if you
+find yourself looking for mutexes, or thread priorities, it's time to
+step back a bit and think about what you want to do and how Perl can
+do it.
+
+=head1 Threadsafe Modules
+
+The addition of threads has changed Perl's internals
+substantially. There are implications for people who write
+modules--especially modules with XS code or external libraries. While
+most modules won't encounter any problems, modules that aren't
+explicitly tagged as thread-safe should be tested before being used in
+production code.
+
+Not all modules that you might use are thread-safe, and you should
+always assume a module is unsafe unless the documentation says
+otherwise. This includes modules that are distributed as part of the
+core. Threads are a beta feature, and even some of the standard
+modules aren't thread-safe.
+
+If you're using a module that's not thread-safe for some reason, you
+can protect yourself by using semaphores and lots of programming
+discipline to control access to the module. Semaphores are covered
+later in the article. Perl Threads Are Different
+
+=head1 Thread Basics
+
+The core Thread module provides the basic functions you need to write
+threaded programs. In the following sections we'll cover the basics,
+showing you what you need to do to create a threaded program. After
+that, we'll go over some of the features of the Thread module that
+make threaded programming easier.
+
+=head2 Basic Thread Support
+
+Thread support is a Perl compile-time option-it's something that's
+turned on or off when Perl is built at your site, rather than when
+your programs are compiled. If your Perl wasn't compiled with thread
+support enabled, then any attempt to use threads will fail.
+
+Remember that the threading support in 5.005 is in beta release, and
+should be treated as such. You should expect that it may not function
+entirely properly, and the thread interface may well change some
+before it is a fully supported, production release. The beta version
+shouldn't be used for mission-critical projects. Having said that,
+threaded Perl is pretty nifty, and worth a look.
+
+Your programs can use the Config module to check whether threads are
+enabled. If your program can't run without them, you can say something
+like:
+
+ $Config{usethreads} or die "Recompile Perl with threads to run this program.";
+
+A possibly-threaded program using a possibly-threaded module might
+have code like this:
+
+ use Config;
+ use MyMod;
+
+ if ($Config{usethreads}) {
+ # We have threads
+ require MyMod_threaded;
+ import MyMod_threaded;
+ } else {
+ require MyMod_unthreaded;
+ import MyMod_unthreaded;
+ }
+
+Since code that runs both with and without threads is usually pretty
+messy, it's best to isolate the thread-specific code in its own
+module. In our example above, that's what MyMod_threaded is, and it's
+only imported if we're running on a threaded Perl.
+
+=head2 Creating Threads
+
+The Thread package provides the tools you need to create new
+threads. Like any other module, you need to tell Perl you want to use
+it; use Thread imports all the pieces you need to create basic
+threads.
+
+The simplest, straightforward way to create a thread is with new():
+
+ use Thread;
+
+ $thr = Thread->new( \&sub1 );
+
+ sub sub1 {
+ print "In the thread\n";
+ }
+
+The new() method takes a reference to a subroutine and creates a new
+thread, which starts executing in the referenced subroutine. Control
+then passes both to the subroutine and the caller.
+
+If you need to, your program can pass parameters to the subroutine as
+part of the thread startup. Just include the list of parameters as
+part of the C<Thread::new> call, like this:
+
+ use Thread;
+ $Param3 = "foo";
+ $thr = Thread->new( \&sub1, "Param 1", "Param 2", $Param3 );
+ $thr = Thread->new( \&sub1, @ParamList );
+ $thr = Thread->new( \&sub1, qw(Param1 Param2 $Param3) );
+
+ sub sub1 {
+ my @InboundParameters = @_;
+ print "In the thread\n";
+ print "got parameters >", join("<>", @InboundParameters), "<\n";
+ }
+
+
+The subroutine runs like a normal Perl subroutine, and the call to new
+Thread returns whatever the subroutine returns.
+
+The last example illustrates another feature of threads. You can spawn
+off several threads using the same subroutine. Each thread executes
+the same subroutine, but in a separate thread with a separate
+environment and potentially separate arguments.
+
+The other way to spawn a new thread is with async(), which is a way to
+spin off a chunk of code like eval(), but into its own thread:
+
+ use Thread qw(async);
+
+ $LineCount = 0;
+
+ $thr = async {
+ while(<>) {$LineCount++}
+ print "Got $LineCount lines\n";
+ };
+
+ print "Waiting for the linecount to end\n";
+ $thr->join;
+ print "All done\n";
+
+You'll notice we did a use Thread qw(async) in that example. async is
+not exported by default, so if you want it, you'll either need to
+import it before you use it or fully qualify it as
+Thread::async. You'll also note that there's a semicolon after the
+closing brace. That's because async() treats the following block as an
+anonymous subroutine, so the semicolon is necessary.
+
+Like eval(), the code executes in the same context as it would if it
+weren't spun off. Since both the code inside and after the async start
+executing, you need to be careful with any shared resources. Locking
+and other synchronization techniques are covered later.
+
+=head2 Giving up control
+
+There are times when you may find it useful to have a thread
+explicitly give up the CPU to another thread. Your threading package
+might not support preemptive multitasking for threads, for example, or
+you may be doing something compute-intensive and want to make sure
+that the user-interface thread gets called frequently. Regardless,
+there are times that you might want a thread to give up the processor.
+
+Perl's threading package provides the yield() function that does
+this. yield() is pretty straightforward, and works like this:
+
+ use Thread qw(yield async);
+ async {
+ my $foo = 50;
+ while ($foo--) { print "first async\n" }
+ yield;
+ $foo = 50;
+ while ($foo--) { print "first async\n" }
+ };
+ async {
+ my $foo = 50;
+ while ($foo--) { print "second async\n" }
+ yield;
+ $foo = 50;
+ while ($foo--) { print "second async\n" }
+ };
+
+=head2 Waiting For A Thread To Exit
+
+Since threads are also subroutines, they can return values. To wait
+for a thread to exit and extract any scalars it might return, you can
+use the join() method.
+
+ use Thread;
+ $thr = Thread->new( \&sub1 );
+
+ @ReturnData = $thr->join;
+ print "Thread returned @ReturnData";
+
+ sub sub1 { return "Fifty-six", "foo", 2; }
+
+In the example above, the join() method returns as soon as the thread
+ends. In addition to waiting for a thread to finish and gathering up
+any values that the thread might have returned, join() also performs
+any OS cleanup necessary for the thread. That cleanup might be
+important, especially for long-running programs that spawn lots of
+threads. If you don't want the return values and don't want to wait
+for the thread to finish, you should call the detach() method
+instead. detach() is covered later in the article.
+
+=head2 Errors In Threads
+
+So what happens when an error occurs in a thread? Any errors that
+could be caught with eval() are postponed until the thread is
+joined. If your program never joins, the errors appear when your
+program exits.
+
+Errors deferred until a join() can be caught with eval():
+
+ use Thread qw(async);
+ $thr = async {$b = 3/0}; # Divide by zero error
+ $foo = eval {$thr->join};
+ if ($@) {
+ print "died with error $@\n";
+ } else {
+ print "Hey, why aren't you dead?\n";
+ }
+
+eval() passes any results from the joined thread back unmodified, so
+if you want the return value of the thread, this is your only chance
+to get them.
+
+=head2 Ignoring A Thread
+
+join() does three things: it waits for a thread to exit, cleans up
+after it, and returns any data the thread may have produced. But what
+if you're not interested in the thread's return values, and you don't
+really care when the thread finishes? All you want is for the thread
+to get cleaned up after when it's done.
+
+In this case, you use the detach() method. Once a thread is detached,
+it'll run until it's finished, then Perl will clean up after it
+automatically.
+
+ use Thread;
+ $thr = Thread->new( \&sub1 ); # Spawn the thread
+
+ $thr->detach; # Now we officially don't care any more
+
+ sub sub1 {
+ $a = 0;
+ while (1) {
+ $a++;
+ print "\$a is $a\n";
+ sleep 1;
+ }
+ }
+
+
+Once a thread is detached, it may not be joined, and any output that
+it might have produced (if it was done and waiting for a join) is
+lost.
+
+=head1 Threads And Data
+
+Now that we've covered the basics of threads, it's time for our next
+topic: data. Threading introduces a couple of complications to data
+access that non-threaded programs never need to worry about.
+
+=head2 Shared And Unshared Data
+
+The single most important thing to remember when using threads is that
+all threads potentially have access to all the data anywhere in your
+program. While this is true with a nonthreaded Perl program as well,
+it's especially important to remember with a threaded program, since
+more than one thread can be accessing this data at once.
+
+Perl's scoping rules don't change because you're using threads. If a
+subroutine (or block, in the case of async()) could see a variable if
+you weren't running with threads, it can see it if you are. This is
+especially important for the subroutines that create, and makes C<my>
+variables even more important. Remember--if your variables aren't
+lexically scoped (declared with C<my>) you're probably sharing them
+between threads.
+
+=head2 Thread Pitfall: Races
+
+While threads bring a new set of useful tools, they also bring a
+number of pitfalls. One pitfall is the race condition:
+
+ use Thread;
+ $a = 1;
+ $thr1 = Thread->new(\&sub1);
+ $thr2 = Thread->new(\&sub2);
+
+ sleep 10;
+ print "$a\n";
+
+ sub sub1 { $foo = $a; $a = $foo + 1; }
+ sub sub2 { $bar = $a; $a = $bar + 1; }
+
+What do you think $a will be? The answer, unfortunately, is "it
+depends." Both sub1() and sub2() access the global variable $a, once
+to read and once to write. Depending on factors ranging from your
+thread implementation's scheduling algorithm to the phase of the moon,
+$a can be 2 or 3.
+
+Race conditions are caused by unsynchronized access to shared
+data. Without explicit synchronization, there's no way to be sure that
+nothing has happened to the shared data between the time you access it
+and the time you update it. Even this simple code fragment has the
+possibility of error:
+
+ use Thread qw(async);
+ $a = 2;
+ async{ $b = $a; $a = $b + 1; };
+ async{ $c = $a; $a = $c + 1; };
+
+Two threads both access $a. Each thread can potentially be interrupted
+at any point, or be executed in any order. At the end, $a could be 3
+or 4, and both $b and $c could be 2 or 3.
+
+Whenever your program accesses data or resources that can be accessed
+by other threads, you must take steps to coordinate access or risk
+data corruption and race conditions.
+
+=head2 Controlling access: lock()
+
+The lock() function takes a variable (or subroutine, but we'll get to
+that later) and puts a lock on it. No other thread may lock the
+variable until the locking thread exits the innermost block containing
+the lock. Using lock() is straightforward:
+
+ use Thread qw(async);
+ $a = 4;
+ $thr1 = async {
+ $foo = 12;
+ {
+ lock ($a); # Block until we get access to $a
+ $b = $a;
+ $a = $b * $foo;
+ }
+ print "\$foo was $foo\n";
+ };
+ $thr2 = async {
+ $bar = 7;
+ {
+ lock ($a); # Block until we can get access to $a
+ $c = $a;
+ $a = $c * $bar;
+ }
+ print "\$bar was $bar\n";
+ };
+ $thr1->join;
+ $thr2->join;
+ print "\$a is $a\n";
+
+lock() blocks the thread until the variable being locked is
+available. When lock() returns, your thread can be sure that no other
+thread can lock that variable until the innermost block containing the
+lock exits.
+
+It's important to note that locks don't prevent access to the variable
+in question, only lock attempts. This is in keeping with Perl's
+longstanding tradition of courteous programming, and the advisory file
+locking that flock() gives you. Locked subroutines behave differently,
+however. We'll cover that later in the article.
+
+You may lock arrays and hashes as well as scalars. Locking an array,
+though, will not block subsequent locks on array elements, just lock
+attempts on the array itself.
+
+Finally, locks are recursive, which means it's okay for a thread to
+lock a variable more than once. The lock will last until the outermost
+lock() on the variable goes out of scope.
+
+=head2 Thread Pitfall: Deadlocks
+
+Locks are a handy tool to synchronize access to data. Using them
+properly is the key to safe shared data. Unfortunately, locks aren't
+without their dangers. Consider the following code:
+
+ use Thread qw(async yield);
+ $a = 4;
+ $b = "foo";
+ async {
+ lock($a);
+ yield;
+ sleep 20;
+ lock ($b);
+ };
+ async {
+ lock($b);
+ yield;
+ sleep 20;
+ lock ($a);
+ };
+
+This program will probably hang until you kill it. The only way it
+won't hang is if one of the two async() routines acquires both locks
+first. A guaranteed-to-hang version is more complicated, but the
+principle is the same.
+
+The first thread spawned by async() will grab a lock on $a then, a
+second or two later, try to grab a lock on $b. Meanwhile, the second
+thread grabs a lock on $b, then later tries to grab a lock on $a. The
+second lock attempt for both threads will block, each waiting for the
+other to release its lock.
+
+This condition is called a deadlock, and it occurs whenever two or
+more threads are trying to get locks on resources that the others
+own. Each thread will block, waiting for the other to release a lock
+on a resource. That never happens, though, since the thread with the
+resource is itself waiting for a lock to be released.
+
+There are a number of ways to handle this sort of problem. The best
+way is to always have all threads acquire locks in the exact same
+order. If, for example, you lock variables $a, $b, and $c, always lock
+$a before $b, and $b before $c. It's also best to hold on to locks for
+as short a period of time to minimize the risks of deadlock.
+
+=head2 Queues: Passing Data Around
+
+A queue is a special thread-safe object that lets you put data in one
+end and take it out the other without having to worry about
+synchronization issues. They're pretty straightforward, and look like
+this:
+
+ use Thread qw(async);
+ use Thread::Queue;
+
+ my $DataQueue = Thread::Queue->new();
+ $thr = async {
+ while ($DataElement = $DataQueue->dequeue) {
+ print "Popped $DataElement off the queue\n";
+ }
+ };
+
+ $DataQueue->enqueue(12);
+ $DataQueue->enqueue("A", "B", "C");
+ sleep 10;
+ $DataQueue->enqueue(undef);
+
+You create the queue with C<< Thread::Queue->new >>. Then you can add
+lists of scalars onto the end with enqueue(), and pop scalars off the
+front of it with dequeue(). A queue has no fixed size, and can grow as
+needed to hold everything pushed on to it.
+
+If a queue is empty, dequeue() blocks until another thread enqueues
+something. This makes queues ideal for event loops and other
+communications between threads.
+
+=head1 Threads And Code
+
+In addition to providing thread-safe access to data via locks and
+queues, threaded Perl also provides general-purpose semaphores for
+coarser synchronization than locks provide and thread-safe access to
+entire subroutines.
+
+=head2 Semaphores: Synchronizing Data Access
+
+Semaphores are a kind of generic locking mechanism. Unlike lock, which
+gets a lock on a particular scalar, Perl doesn't associate any
+particular thing with a semaphore so you can use them to control
+access to anything you like. In addition, semaphores can allow more
+than one thread to access a resource at once, though by default
+semaphores only allow one thread access at a time.
+
+=over 4
+
+=item Basic semaphores
+
+Semaphores have two methods, down and up. down decrements the resource
+count, while up increments it. down calls will block if the
+semaphore's current count would decrement below zero. This program
+gives a quick demonstration:
+
+ use Thread qw(yield);
+ use Thread::Semaphore;
+ my $semaphore = Thread::Semaphore->new();
+ $GlobalVariable = 0;
+
+ $thr1 = Thread->new( \&sample_sub, 1 );
+ $thr2 = Thread->new( \&sample_sub, 2 );
+ $thr3 = Thread->new( \&sample_sub, 3 );
+
+ sub sample_sub {
+ my $SubNumber = shift @_;
+ my $TryCount = 10;
+ my $LocalCopy;
+ sleep 1;
+ while ($TryCount--) {
+ $semaphore->down;
+ $LocalCopy = $GlobalVariable;
+ print "$TryCount tries left for sub $SubNumber (\$GlobalVariable is $GlobalVariable)\n";
+ yield;
+ sleep 2;
+ $LocalCopy++;
+ $GlobalVariable = $LocalCopy;
+ $semaphore->up;
+ }
+ }
+
+The three invocations of the subroutine all operate in sync. The
+semaphore, though, makes sure that only one thread is accessing the
+global variable at once.
+
+=item Advanced Semaphores
+
+By default, semaphores behave like locks, letting only one thread
+down() them at a time. However, there are other uses for semaphores.
+
+Each semaphore has a counter attached to it. down() decrements the
+counter and up() increments the counter. By default, semaphores are
+created with the counter set to one, down() decrements by one, and
+up() increments by one. If down() attempts to decrement the counter
+below zero, it blocks until the counter is large enough. Note that
+while a semaphore can be created with a starting count of zero, any
+up() or down() always changes the counter by at least
+one. $semaphore->down(0) is the same as $semaphore->down(1).
+
+The question, of course, is why would you do something like this? Why
+create a semaphore with a starting count that's not one, or why
+decrement/increment it by more than one? The answer is resource
+availability. Many resources that you want to manage access for can be
+safely used by more than one thread at once.
+
+For example, let's take a GUI driven program. It has a semaphore that
+it uses to synchronize access to the display, so only one thread is
+ever drawing at once. Handy, but of course you don't want any thread
+to start drawing until things are properly set up. In this case, you
+can create a semaphore with a counter set to zero, and up it when
+things are ready for drawing.
+
+Semaphores with counters greater than one are also useful for
+establishing quotas. Say, for example, that you have a number of
+threads that can do I/O at once. You don't want all the threads
+reading or writing at once though, since that can potentially swamp
+your I/O channels, or deplete your process' quota of filehandles. You
+can use a semaphore initialized to the number of concurrent I/O
+requests (or open files) that you want at any one time, and have your
+threads quietly block and unblock themselves.
+
+Larger increments or decrements are handy in those cases where a
+thread needs to check out or return a number of resources at once.
+
+=back
+
+=head2 Attributes: Restricting Access To Subroutines
+
+In addition to synchronizing access to data or resources, you might
+find it useful to synchronize access to subroutines. You may be
+accessing a singular machine resource (perhaps a vector processor), or
+find it easier to serialize calls to a particular subroutine than to
+have a set of locks and semaphores.
+
+One of the additions to Perl 5.005 is subroutine attributes. The
+Thread package uses these to provide several flavors of
+serialization. It's important to remember that these attributes are
+used in the compilation phase of your program so you can't change a
+subroutine's behavior while your program is actually running.
+
+=head2 Subroutine Locks
+
+The basic subroutine lock looks like this:
+
+ sub test_sub :locked {
+ }
+
+This ensures that only one thread will be executing this subroutine at
+any one time. Once a thread calls this subroutine, any other thread
+that calls it will block until the thread in the subroutine exits
+it. A more elaborate example looks like this:
+
+ use Thread qw(yield);
+
+ Thread->new(\&thread_sub, 1);
+ Thread->new(\&thread_sub, 2);
+ Thread->new(\&thread_sub, 3);
+ Thread->new(\&thread_sub, 4);
+
+ sub sync_sub :locked {
+ my $CallingThread = shift @_;
+ print "In sync_sub for thread $CallingThread\n";
+ yield;
+ sleep 3;
+ print "Leaving sync_sub for thread $CallingThread\n";
+ }
+
+ sub thread_sub {
+ my $ThreadID = shift @_;
+ print "Thread $ThreadID calling sync_sub\n";
+ sync_sub($ThreadID);
+ print "$ThreadID is done with sync_sub\n";
+ }
+
+The C<locked> attribute tells perl to lock sync_sub(), and if you run
+this, you can see that only one thread is in it at any one time.
+
+=head2 Methods
+
+Locking an entire subroutine can sometimes be overkill, especially
+when dealing with Perl objects. When calling a method for an object,
+for example, you want to serialize calls to a method, so that only one
+thread will be in the subroutine for a particular object, but threads
+calling that subroutine for a different object aren't blocked. The
+method attribute indicates whether the subroutine is really a method.
+
+ use Thread;
+
+ sub tester {
+ my $thrnum = shift @_;
+ my $bar = Foo->new();
+ foreach (1..10) {
+ print "$thrnum calling per_object\n";
+ $bar->per_object($thrnum);
+ print "$thrnum out of per_object\n";
+ yield;
+ print "$thrnum calling one_at_a_time\n";
+ $bar->one_at_a_time($thrnum);
+ print "$thrnum out of one_at_a_time\n";
+ yield;
+ }
+ }
+
+ foreach my $thrnum (1..10) {
+ Thread->new(\&tester, $thrnum);
+ }
+
+ package Foo;
+ sub new {
+ my $class = shift @_;
+ return bless [@_], $class;
+ }
+
+ sub per_object :locked :method {
+ my ($class, $thrnum) = @_;
+ print "In per_object for thread $thrnum\n";
+ yield;
+ sleep 2;
+ print "Exiting per_object for thread $thrnum\n";
+ }
+
+ sub one_at_a_time :locked {
+ my ($class, $thrnum) = @_;
+ print "In one_at_a_time for thread $thrnum\n";
+ yield;
+ sleep 2;
+ print "Exiting one_at_a_time for thread $thrnum\n";
+ }
+
+As you can see from the output (omitted for brevity; it's 800 lines)
+all the threads can be in per_object() simultaneously, but only one
+thread is ever in one_at_a_time() at once.
+
+=head2 Locking A Subroutine
+
+You can lock a subroutine as you would lock a variable. Subroutine locks
+work the same as specifying a C<locked> attribute for the subroutine,
+and block all access to the subroutine for other threads until the
+lock goes out of scope. When the subroutine isn't locked, any number
+of threads can be in it at once, and getting a lock on a subroutine
+doesn't affect threads already in the subroutine. Getting a lock on a
+subroutine looks like this:
+
+ lock(\&sub_to_lock);
+
+Simple enough. Unlike the C<locked> attribute, which is a compile time
+option, locking and unlocking a subroutine can be done at runtime at your
+discretion. There is some runtime penalty to using lock(\&sub) instead
+of the C<locked> attribute, so make sure you're choosing the proper
+method to do the locking.
+
+You'd choose lock(\&sub) when writing modules and code to run on both
+threaded and unthreaded Perl, especially for code that will run on
+5.004 or earlier Perls. In that case, it's useful to have subroutines
+that should be serialized lock themselves if they're running threaded,
+like so:
+
+ package Foo;
+ use Config;
+ $Running_Threaded = 0;
+
+ BEGIN { $Running_Threaded = $Config{'usethreads'} }
+
+ sub sub1 { lock(\&sub1) if $Running_Threaded }
+
+
+This way you can ensure single-threadedness regardless of which
+version of Perl you're running.
+
+=head1 General Thread Utility Routines
+
+We've covered the workhorse parts of Perl's threading package, and
+with these tools you should be well on your way to writing threaded
+code and packages. There are a few useful little pieces that didn't
+really fit in anyplace else.
+
+=head2 What Thread Am I In?
+
+The Thread->self method provides your program with a way to get an
+object representing the thread it's currently in. You can use this
+object in the same way as the ones returned from the thread creation.
+
+=head2 Thread IDs
+
+tid() is a thread object method that returns the thread ID of the
+thread the object represents. Thread IDs are integers, with the main
+thread in a program being 0. Currently Perl assigns a unique tid to
+every thread ever created in your program, assigning the first thread
+to be created a tid of 1, and increasing the tid by 1 for each new
+thread that's created.
+
+=head2 Are These Threads The Same?
+
+The equal() method takes two thread objects and returns true
+if the objects represent the same thread, and false if they don't.
+
+=head2 What Threads Are Running?
+
+Thread->list returns a list of thread objects, one for each thread
+that's currently running. Handy for a number of things, including
+cleaning up at the end of your program:
+
+ # Loop through all the threads
+ foreach $thr (Thread->list) {
+ # Don't join the main thread or ourselves
+ if ($thr->tid && !Thread::equal($thr, Thread->self)) {
+ $thr->join;
+ }
+ }
+
+The example above is just for illustration. It isn't strictly
+necessary to join all the threads you create, since Perl detaches all
+the threads before it exits.
+
+=head1 A Complete Example
+
+Confused yet? It's time for an example program to show some of the
+things we've covered. This program finds prime numbers using threads.
+
+ 1 #!/usr/bin/perl -w
+ 2 # prime-pthread, courtesy of Tom Christiansen
+ 3
+ 4 use strict;
+ 5
+ 6 use Thread;
+ 7 use Thread::Queue;
+ 8
+ 9 my $stream = Thread::Queue->new();
+ 10 my $kid = Thread->new(\&check_num, $stream, 2);
+ 11
+ 12 for my $i ( 3 .. 1000 ) {
+ 13 $stream->enqueue($i);
+ 14 }
+ 15
+ 16 $stream->enqueue(undef);
+ 17 $kid->join();
+ 18
+ 19 sub check_num {
+ 20 my ($upstream, $cur_prime) = @_;
+ 21 my $kid;
+ 22 my $downstream = Thread::Queue->new();
+ 23 while (my $num = $upstream->dequeue) {
+ 24 next unless $num % $cur_prime;
+ 25 if ($kid) {
+ 26 $downstream->enqueue($num);
+ 27 } else {
+ 28 print "Found prime $num\n";
+ 29 $kid = Thread->new(\&check_num, $downstream, $num);
+ 30 }
+ 31 }
+ 32 $downstream->enqueue(undef) if $kid;
+ 33 $kid->join() if $kid;
+ 34 }
+
+This program uses the pipeline model to generate prime numbers. Each
+thread in the pipeline has an input queue that feeds numbers to be
+checked, a prime number that it's responsible for, and an output queue
+that it funnels numbers that have failed the check into. If the thread
+has a number that's failed its check and there's no child thread, then
+the thread must have found a new prime number. In that case, a new
+child thread is created for that prime and stuck on the end of the
+pipeline.
+
+This probably sounds a bit more confusing than it really is, so lets
+go through this program piece by piece and see what it does. (For
+those of you who might be trying to remember exactly what a prime
+number is, it's a number that's only evenly divisible by itself and 1)
+
+The bulk of the work is done by the check_num() subroutine, which
+takes a reference to its input queue and a prime number that it's
+responsible for. After pulling in the input queue and the prime that
+the subroutine's checking (line 20), we create a new queue (line 22)
+and reserve a scalar for the thread that we're likely to create later
+(line 21).
+
+The while loop from lines 23 to line 31 grabs a scalar off the input
+queue and checks against the prime this thread is responsible
+for. Line 24 checks to see if there's a remainder when we modulo the
+number to be checked against our prime. If there is one, the number
+must not be evenly divisible by our prime, so we need to either pass
+it on to the next thread if we've created one (line 26) or create a
+new thread if we haven't.
+
+The new thread creation is line 29. We pass on to it a reference to
+the queue we've created, and the prime number we've found.
+
+Finally, once the loop terminates (because we got a 0 or undef in the
+queue, which serves as a note to die), we pass on the notice to our
+child and wait for it to exit if we've created a child (Lines 32 and
+37).
+
+Meanwhile, back in the main thread, we create a queue (line 9) and the
+initial child thread (line 10), and pre-seed it with the first prime:
+2. Then we queue all the numbers from 3 to 1000 for checking (lines
+12-14), then queue a die notice (line 16) and wait for the first child
+thread to terminate (line 17). Because a child won't die until its
+child has died, we know that we're done once we return from the join.
+
+That's how it works. It's pretty simple; as with many Perl programs,
+the explanation is much longer than the program.
+
+=head1 Conclusion
+
+A complete thread tutorial could fill a book (and has, many times),
+but this should get you well on your way. The final authority on how
+Perl's threads behave is the documentation bundled with the Perl
+distribution, but with what we've covered in this article, you should
+be well on your way to becoming a threaded Perl expert.
+
+=head1 Bibliography
+
+Here's a short bibliography courtesy of J\xFCrgen Christoffel:
+
+=head2 Introductory Texts
+
+Birrell, Andrew D. An Introduction to Programming with
+Threads. Digital Equipment Corporation, 1989, DEC-SRC Research Report
+#35 online as
+http://www.research.digital.com/SRC/staff/birrell/bib.html (highly
+recommended)
+
+Robbins, Kay. A., and Steven Robbins. Practical Unix Programming: A
+Guide to Concurrency, Communication, and
+Multithreading. Prentice-Hall, 1996.
+
+Lewis, Bill, and Daniel J. Berg. Multithreaded Programming with
+Pthreads. Prentice Hall, 1997, ISBN 0-13-443698-9 (a well-written
+introduction to threads).
+
+Nelson, Greg (editor). Systems Programming with Modula-3. Prentice
+Hall, 1991, ISBN 0-13-590464-1.
+
+Nichols, Bradford, Dick Buttlar, and Jacqueline Proulx Farrell.
+Pthreads Programming. O'Reilly & Associates, 1996, ISBN 156592-115-1
+(covers POSIX threads).
+
+=head2 OS-Related References
+
+Boykin, Joseph, David Kirschen, Alan Langerman, and Susan
+LoVerso. Programming under Mach. Addison-Wesley, 1994, ISBN
+0-201-52739-1.
+
+Tanenbaum, Andrew S. Distributed Operating Systems. Prentice Hall,
+1995, ISBN 0-13-219908-4 (great textbook).
+
+Silberschatz, Abraham, and Peter B. Galvin. Operating System Concepts,
+4th ed. Addison-Wesley, 1995, ISBN 0-201-59292-4
+
+=head2 Other References
+
+Arnold, Ken and James Gosling. The Java Programming Language, 2nd
+ed. Addison-Wesley, 1998, ISBN 0-201-31006-6.
+
+Le Sergent, T. and B. Berthomieu. "Incremental MultiThreaded Garbage
+Collection on Virtually Shared Memory Architectures" in Memory
+Management: Proc. of the International Workshop IWMM 92, St. Malo,
+France, September 1992, Yves Bekkers and Jacques Cohen, eds. Springer,
+1992, ISBN 3540-55940-X (real-life thread applications).
+
+=head1 Acknowledgements
+
+Thanks (in no particular order) to Chaim Frenkel, Steve Fink, Gurusamy
+Sarathy, Ilya Zakharevich, Benjamin Sugars, J\xFCrgen Christoffel, Joshua
+Pritikin, and Alan Burlison, for their help in reality-checking and
+polishing this article. Big thanks to Tom Christiansen for his rewrite
+of the prime number generator.
+
+=head1 AUTHOR
+
+Dan Sugalski E<lt>sugalskd at ous.eduE<gt>
+
+=head1 Copyrights
+
+This article originally appeared in The Perl Journal #10, and is
+copyright 1998 The Perl Journal. It appears courtesy of Jon Orwant and
+The Perl Journal. This document may be distributed under the same terms
+as Perl itself.
+
+
Modified: trunk/contrib/perl/pod/perlpacktut.pod
===================================================================
--- trunk/contrib/perl/pod/perlpacktut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpacktut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -73,7 +73,7 @@
The inverse operation - packing byte contents from a string of hexadecimal
digits - is just as easily written. For instance:
- my $s = pack( 'H2' x 10, map { "3$_" } ( 0..9 ) );
+ my $s = pack( 'H2' x 10, 30..39 );
print "$s\n";
Since we feed a list of ten 2-digit hexadecimal strings to C<pack>, the
@@ -80,13 +80,12 @@
pack template should contain ten pack codes. If this is run on a computer
with ASCII character coding, it will print C<0123456789>.
-
=head1 Packing Text
Let's suppose you've got to read in a data file like this:
Date |Description | Income|Expenditure
- 01/24/2001 Ahmed's Camel Emporium 1147.99
+ 01/24/2001 Zed's Camel Emporium 1147.99
01/28/2001 Flea spray 24.99
01/29/2001 Camel rides to tourists 235.00
@@ -201,7 +200,7 @@
Oh, hmm. That didn't quite work. Let's see what happened:
- 01/24/2001 Ahmed's Camel Emporium 1147.99
+ 01/24/2001 Zed's Camel Emporium 1147.99
01/28/2001 Flea spray 24.99
01/29/2001 Camel rides to tourists 1235.00
03/23/2001Totals 1235.001172.98
@@ -226,7 +225,7 @@
but they don't translate to spaces in the output.) Here's what we got
this time:
- 01/24/2001 Ahmed's Camel Emporium 1147.99
+ 01/24/2001 Zed's Camel Emporium 1147.99
01/28/2001 Flea spray 24.99
01/29/2001 Camel rides to tourists 1235.00
03/23/2001 Totals 1235.00 1172.98
Property changes on: trunk/contrib/perl/pod/perlpacktut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlperf.pod
===================================================================
--- trunk/contrib/perl/pod/perlperf.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlperf.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -30,7 +30,7 @@
Firstly, you need to establish a baseline time for the existing code, which
timing needs to be reliable and repeatable. You'll probably want to use the
-C<Benchmark> or C<Devel::DProf> modules, or something similar, for this step,
+C<Benchmark> or C<Devel::NYTProf> modules, or something similar, for this step,
or perhaps the Unix system C<time> utility, whichever is appropriate. See the
base of this document for a longer list of benchmarking and profiling modules,
and recommended further reading.
@@ -597,7 +597,7 @@
C<NYTProf> will generate a report database into the file F<nytprof.out> by
default. Human readable reports can be generated from here by using the
supplied C<nytprofhtml> (HTML output) and C<nytprofcsv> (CSV output) programs.
-We've used the Unix sytem C<html2text> utility to convert the
+We've used the Unix system C<html2text> utility to convert the
F<nytprof/index.html> file for convenience here.
$> html2text nytprof/index.html
Property changes on: trunk/contrib/perl/pod/perlperf.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlpod.pod
===================================================================
--- trunk/contrib/perl/pod/perlpod.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpod.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -98,10 +98,8 @@
=head2 Object Attributes
-The text "Object Attributes" comprises the heading there. (Note that
-head3 and head4 are recent additions, not supported in older Pod
-translators.) The text in these heading commands can use
-formatting codes, as seen here:
+The text "Object Attributes" comprises the heading there.
+The text in these heading commands can use formatting codes, as seen here:
=head2 Possible Values for C<$/>
@@ -238,9 +236,9 @@
That is, with "=for", you can have only one paragraph's worth
of text (i.e., the text in "=foo targetname text..."), but with
"=begin targetname" ... "=end targetname", you can have any amount
-of stuff inbetween. (Note that there still must be a blank line
+of stuff in between. (Note that there still must be a blank line
after the "=begin" command and a blank line before the "=end"
-command.
+command.)
Here are some examples of how to use these:
@@ -293,9 +291,9 @@
=encoding utf8
=encoding koi8-r
-
+
=encoding ShiftJIS
-
+
=encoding big5
=back
@@ -533,7 +531,7 @@
"C<NEE<lt>ltE<gt>3>" (for "NE<lt>3") you could write
"C<NZE<lt>E<gt>E<lt>3>" (the "ZE<lt>E<gt>" breaks up the "N" and
the "E<lt>" so they can't be considered
-the part of a (fictitious) "NE<lt>...E<gt>" code.
+the part of a (fictitious) "NE<lt>...E<gt>" code).
=for comment
This was formerly explained as a "zero-width character". But it in
Property changes on: trunk/contrib/perl/pod/perlpod.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlpodspec.pod
===================================================================
--- trunk/contrib/perl/pod/perlpodspec.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpodspec.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -305,7 +305,7 @@
L</About Data Paragraphs and "=beginE<sol>=end" Regions>.
It is advised that formatnames match the regexp
-C<m/\A:?[−a−zA−Z0−9_]+\z/>. Everything following whitespace after the
+C<m/\A:?[-a-zA-Z0-9_]+\z/>. Everything following whitespace after the
formatname is a parameter that may be used by the formatter when dealing
with this region. This parameter must not be repeated in the "=end"
paragraph. Implementors should anticipate future expansion in the
@@ -1301,14 +1301,6 @@
=item *
-Authors wanting to link to a particular (absolute) URL, must do so
-only with "LE<lt>scheme:...>" codes (like
-LE<lt>http://www.perl.org>), and must not attempt "LE<lt>Some Site
-Name|scheme:...>" codes. This restriction avoids many problems
-in parsing and rendering LE<lt>...> codes.
-
-=item *
-
In a C<LE<lt>text|...E<gt>> code, text may contain formatting codes
for formatting or for EE<lt>...> escapes, as in:
Property changes on: trunk/contrib/perl/pod/perlpodspec.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlpodstyle.pod
===================================================================
--- trunk/contrib/perl/pod/perlpodstyle.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpodstyle.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlpodstyle.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlpolicy.pod
===================================================================
--- trunk/contrib/perl/pod/perlpolicy.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpolicy.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -8,6 +8,57 @@
policies about how the Perl 5 Porters collectively develop and maintain
the Perl core.
+=head1 GOVERNANCE
+
+=head2 Perl 5 Porters
+
+Subscribers to perl5-porters (the porters themselves) come in several flavours.
+Some are quiet curious lurkers, who rarely pitch in and instead watch
+the ongoing development to ensure they're forewarned of new changes or
+features in Perl. Some are representatives of vendors, who are there
+to make sure that Perl continues to compile and work on their
+platforms. Some patch any reported bug that they know how to fix,
+some are actively patching their pet area (threads, Win32, the regexp
+-engine), while others seem to do nothing but complain. In other
+words, it's your usual mix of technical people.
+
+Over this group of porters presides Larry Wall. He has the final word
+in what does and does not change in any of the Perl programming languages.
+These days, Larry spends most of his time on Perl 6, while Perl 5 is
+shepherded by a "pumpking", a porter responsible for deciding what
+goes into each release and ensuring that releases happen on a regular
+basis.
+
+Larry sees Perl development along the lines of the US government:
+there's the Legislature (the porters), the Executive branch (the
+-pumpking), and the Supreme Court (Larry). The legislature can
+discuss and submit patches to the executive branch all they like, but
+the executive branch is free to veto them. Rarely, the Supreme Court
+will side with the executive branch over the legislature, or the
+legislature over the executive branch. Mostly, however, the
+legislature and the executive branch are supposed to get along and
+work out their differences without impeachment or court cases.
+
+You might sometimes see reference to Rule 1 and Rule 2. Larry's power
+as Supreme Court is expressed in The Rules:
+
+=over 4
+
+=item 1
+
+Larry is always by definition right about how Perl should behave.
+This means he has final veto power on the core functionality.
+
+=item 2
+
+Larry is allowed to change his mind about any matter at a later date,
+regardless of whether he previously invoked Rule 1.
+
+=back
+
+Got that? Larry is always right, even when he was wrong. It's rare
+to see either Rule exercised, but they are often alluded to.
+
=head1 MAINTENANCE AND SUPPORT
Perl 5 is developed by a community, not a corporate entity. Every change
@@ -31,9 +82,9 @@
=item *
-We "officially" support the two most recent stable release
-series. As of the release of 5.14.0, we will "officially"
-end support for Perl 5.10, other than providing security
+We "officially" support the two most recent stable release series. 5.12.x
+and earlier are now out of support. As of the release of 5.18.0, we will
+"officially" end support for Perl 5.14.x, other than providing security
updates as described below.
=item *
@@ -156,12 +207,16 @@
If something in the Perl core is marked as B<deprecated>, we may remove it
from the core in the next stable release series, though we may not. As of
Perl 5.12, deprecated features and modules warn the user as they're used.
-If you use a deprecated feature and believe that its removal from the Perl
-core would be a mistake, please contact the perl5-porters mailinglist and
-plead your case. We don't deprecate things without a good reason, but
-sometimes there's a counterargument we haven't considered. Historically,
-we did not distinguish between "deprecated" and "discouraged" features.
+When a module is deprecated, it will also be made available on CPAN.
+Installing it from CPAN will silence deprecation warnings for that module.
+If you use a deprecated feature or module and believe that its removal from
+the Perl core would be a mistake, please contact the perl5-porters
+mailinglist and plead your case. We don't deprecate things without a good
+reason, but sometimes there's a counterargument we haven't considered.
+Historically, we did not distinguish between "deprecated" and "discouraged"
+features.
+
=item discouraged
From time to time, we may mark language constructs and features which we
@@ -174,7 +229,8 @@
Once a feature, construct or module has been marked as deprecated for a
stable release cycle, we may remove it from the Perl core. Unsurprisingly,
-we say we've B<removed> these things.
+we say we've B<removed> these things. When a module is removed, it will
+no longer ship with Perl, but will continue to be available on CPAN.
=back
@@ -220,6 +276,11 @@
=item *
+Patches that fix regressions in perl's behavior relative to previous
+releases are acceptable.
+
+=item *
+
Updates to dual-life modules should consist of minimal patches to
fix crashing or security issues (as above).
@@ -250,12 +311,12 @@
=head2 Getting changes into a maint branch
Historically, only the pumpking cherry-picked changes from bleadperl
-into maintperl. This has...scaling problems. At the same time,
+into maintperl. This has scaling problems. At the same time,
maintenance branches of stable versions of Perl need to be treated with
-great care. To that end, we're going to try out a new process for
-maint-5.12.
+great care. To that end, as of Perl 5.12, we have a new process for
+maint branches.
-Any committer may cherry-pick any commit from blead to maint-5.12 if
+Any committer may cherry-pick any commit from blead to a maint branch if
they send mail to perl5-porters announcing their intent to cherry-pick
a specific commit along with a rationale for doing so and at least two
other committers respond to the list giving their assent. (This policy
Property changes on: trunk/contrib/perl/pod/perlpolicy.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlport.pod
===================================================================
--- trunk/contrib/perl/pod/perlport.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlport.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -212,7 +212,7 @@
connections use the C<pack> and C<unpack> formats C<n> and C<N>, the
"network" orders. These are guaranteed to be portable.
-As of perl 5.9.2, you can also use the C<E<gt>> and C<E<lt>> modifiers
+As of perl 5.10.0, you can also use the C<E<gt>> and C<E<lt>> modifiers
to force big- or little-endian byte-order. This is useful if you want
to store signed integers or 64-bit integers, for example.
@@ -236,9 +236,9 @@
One can circumnavigate both these problems in two ways. Either
transfer and store numbers always in text format, instead of raw
-binary, or else consider using modules like Data::Dumper (included in
-the standard distribution as of Perl 5.005) and Storable (included as
-of perl 5.8). Keeping all data as text significantly simplifies matters.
+binary, or else consider using modules like Data::Dumper and Storable
+(included as of perl 5.8). Keeping all data as text significantly
+simplifies matters.
The v-strings are portable only up to v2147483647 (0x7FFFFFFF), that's
how far EBCDIC, or more precisely UTF-EBCDIC will go.
@@ -622,7 +622,7 @@
Don't assume that the epoch starts at 00:00:00, January 1, 1970,
because that is OS- and implementation-specific. It is better to
store a date in an unambiguous representation. The ISO 8601 standard
-defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH-MM-SS
+defines YYYY-MM-DD as the date format, or YYYY-MM-DDTHH:MM:SS
(that's a literal "T" separating the date from the time).
Please do use the ISO 8601 instead of making us guess what
date 02/03/04 might be. ISO 8601 even sorts nicely as-is.
@@ -679,9 +679,8 @@
later. If the bytes are native 8-bit bytes, you can use the C<bytes>
pragma. If the bytes are in a string (regular expression being a
curious string), you can often also use the C<\xHH> notation instead
-of embedding the bytes as-is. (If you want to write your code in UTF-8,
-you can use the C<utf8>.) The C<bytes> and C<utf8> pragmata are
-available since Perl 5.6.0.
+of embedding the bytes as-is. If you want to write your code in UTF-8,
+you can use the C<utf8>.
=head2 System Resources
@@ -689,10 +688,6 @@
missing!) virtual memory systems then you want to be I<especially> mindful
of avoiding wasteful constructs such as:
- # NOTE: this is no longer "bad" in perl5.005
- for (0..10000000) {} # bad
- for (my $x = 0; $x <= 10000000; ++$x) {} # good
-
my @lines = <$very_large_file>; # bad
while (<$fh>) {$file .= $_} # sometimes bad
@@ -781,8 +776,8 @@
=head1 PLATFORMS
-As of version 5.002, Perl is built with a C<$^O> variable that
-indicates the operating system it was built on. This was implemented
+Perl is built with a C<$^O> variable that indicates the operating
+system it was built on. This was implemented
to help speed up code that would otherwise have to C<use Config>
and use the value of C<$Config{osname}>. Of course, to get more
detailed information about the system, looking into C<%Config> is
@@ -904,6 +899,8 @@
Windows Vista MSWin32 MSWin32-x86 2 6 00
Windows 7 MSWin32 MSWin32-x86 2 6 01
Windows 7 MSWin32 MSWin32-x64 2 6 01
+ Windows 2008 MSWin32 MSWin32-x86 2 6 01
+ Windows 2008 MSWin32 MSWin32-x64 2 6 01
Windows CE MSWin32 ? 3
Cygwin cygwin cygwin
@@ -1198,12 +1195,12 @@
to 255 characters, a path name is still limited to 256
characters.
-The value of C<$^O> on VOS is "VOS". To determine the
+The value of C<$^O> on VOS is "vos". To determine the
architecture that you are running on without resorting to loading
all of C<%Config> you can examine the content of the @INC array
like so:
- if ($^O =~ /VOS/) {
+ if ($^O =~ /vos/) {
print "I'm on a Stratus box!\n";
} else {
print "I'm not on a Stratus box!\n";
@@ -1222,15 +1219,19 @@
The VOS mailing list.
-There is no specific mailing list for Perl on VOS. You can post
-comments to the comp.sys.stratus newsgroup, or use the contact
-information located in the distribution files on the Stratus
-Anonymous FTP site.
+There is no specific mailing list for Perl on VOS. You can contact
+the Stratus Technologies Customer Assistance Center (CAC) for your
+region, or you can use the contact information located in the
+distribution files on the Stratus Anonymous FTP site.
=item *
-VOS Perl on the web at L<http://ftp.stratus.com/pub/vos/posix/posix.html>
+Stratus Technologies on the web at L<http://www.stratus.com>
+=item *
+
+VOS Open-Source Software on the web at L<http://ftp.stratus.com/pub/vos/vos.html>
+
=back
=head2 EBCDIC Platforms
@@ -1243,7 +1244,7 @@
services for OS/390" (formerly known as OpenEdition), VM/ESA OpenEdition, or
the BS200 POSIX-BC system (BS2000 is supported in perl 5.6 and greater).
See L<perlos390> for details. Note that for OS/400 there is also a port of
-Perl 5.8.1/5.9.0 or later to the PASE which is ASCII-based (as opposed to
+Perl 5.8.1/5.10.0 or later to the PASE which is ASCII-based (as opposed to
ILE which is EBCDIC-based), see L<perlos400>.
As of R2.5 of USS for OS/390 and Version 2.3 of VM/ESA these Unix
@@ -1282,7 +1283,7 @@
Fortunately, most web servers for the mainframe will correctly
translate the C<\n> in the following statement to its ASCII equivalent
-(C<\r> is the same under both Unix and OS/390 & VM/ESA):
+(C<\r> is the same under both Unix and OS/390):
print "Content-type: text/html\r\n\r\n";
@@ -1293,7 +1294,6 @@
OS/390 os390 os390
OS400 os400 os400
POSIX-BC posix-bc BS2000-posix-bc
- VM/ESA vmesa vmesa
Some simple tricks for determining if you are running on an EBCDIC
platform could include any of the following (perhaps all):
@@ -1315,8 +1315,7 @@
=item *
-L<perlos390>, F<README.os390>, F<perlbs2000>, F<README.vmesa>,
-L<perlebcdic>.
+L<perlos390>, F<README.os390>, F<perlbs2000>, L<perlebcdic>.
=item *
@@ -1394,8 +1393,8 @@
The Unix emulation library's translation of filenames to native assumes
that this sort of translation is required, and it allows a user-defined list
of known suffixes that it will transpose in this fashion. This may
-seem transparent, but consider that with these rules C<foo/bar/baz.h>
-and C<foo/bar/h/baz> both map to C<foo.bar.h.baz>, and that C<readdir> and
+seem transparent, but consider that with these rules F<foo/bar/baz.h>
+and F<foo/bar/h/baz> both map to F<foo.bar.h.baz>, and that C<readdir> and
C<glob> cannot and do not attempt to emulate the reverse mapping. Other
C<.>'s in filenames are translated to C</>.
@@ -1438,7 +1437,7 @@
=head2 Other perls
Perl has been ported to many platforms that do not fit into any of
-the categories listed above. Some, such as AmigaOS, BeOS, HP MPE/iX,
+the categories listed above. Some, such as AmigaOS,
QNX, Plan 9, and VOS, have been well-integrated into the standard
Perl source code kit. You may need to see the F<ports/> directory
on CPAN for information, and possibly binaries, for the likes of:
@@ -1452,8 +1451,6 @@
OS $^O $Config{'archname'}
------------------------------------------
Amiga DOS amigaos m68k-amigos
- BeOS beos
- MPE/iX mpeix PA-RISC1.1
See also:
@@ -1465,15 +1462,6 @@
=item *
-Be OS, F<README.beos>
-
-=item *
-
-HP 300 MPE/iX, F<README.mpeix> and Mark Bixby's web page
-L<http://www.bixby.org/mark/porting.html>
-
-=item *
-
A free perl5-based PERL.NLM for Novell Netware is available in
precompiled binary and source code form from L<http://www.novell.com/>
as well as from CPAN.
@@ -1588,7 +1576,7 @@
=item chroot
-Not implemented. (Win32, VMS, S<Plan 9>, S<RISC OS>, VOS, VM/ESA)
+Not implemented. (Win32, VMS, S<Plan 9>, S<RISC OS>, VOS)
=item crypt
@@ -1613,8 +1601,6 @@
=item exec
-Implemented via Spawn. (VM/ESA)
-
Does not automatically flush output handles on some platforms.
(SunOS, Solaris, HP-UX)
@@ -1653,7 +1639,7 @@
=item fork
-Not implemented. (AmigaOS, S<RISC OS>, VM/ESA, VMS)
+Not implemented. (AmigaOS, S<RISC OS>, VMS)
Emulated using multiple interpreters. See L<perlfork>. (Win32)
@@ -1674,7 +1660,7 @@
=item getpriority
-Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
+Not implemented. (Win32, VMS, S<RISC OS>, VOS)
=item getpwnam
@@ -1710,11 +1696,11 @@
=item getpwent
-Not implemented. (Win32, VM/ESA)
+Not implemented. (Win32)
=item getgrent
-Not implemented. (Win32, VMS, VM/ESA)
+Not implemented. (Win32, VMS)
=item gethostbyname
@@ -1755,11 +1741,11 @@
=item endpwent
-Not implemented. (MPE/iX, VM/ESA, Win32)
+Not implemented. (Win32)
=item endgrent
-Not implemented. (MPE/iX, S<RISC OS>, VM/ESA, VMS, Win32)
+Not implemented. (S<RISC OS>, VMS, Win32)
=item endhostent
@@ -1826,7 +1812,7 @@
=item link
-Not implemented. (MPE/iX, S<RISC OS>, VOS)
+Not implemented. (S<RISC OS>, VOS)
Link count not updated because hard links are not quite that hard
(They are sort of half-way between hard and soft links). (AmigaOS)
@@ -1900,7 +1886,7 @@
=item setgrent
-Not implemented. (MPE/iX, VMS, Win32, S<RISC OS>)
+Not implemented. (VMS, Win32, S<RISC OS>)
=item setpgrp
@@ -1912,7 +1898,7 @@
=item setpwent
-Not implemented. (MPE/iX, Win32, S<RISC OS>)
+Not implemented. (Win32, S<RISC OS>)
=item setsockopt
@@ -1926,8 +1912,14 @@
=item shmwrite
-Not implemented. (Win32, VMS, S<RISC OS>, VOS)
+Not implemented. (Win32, VMS, S<RISC OS>)
+=item sleep
+
+Emulated using synchronization functions such that it can be
+interrupted by alarm(), and limited to a maximum of 4294967 seconds,
+approximately 49 days. (Win32)
+
=item sockatmark
A relatively recent addition to socket functions, may not
@@ -1935,10 +1927,8 @@
=item socketpair
-Not implemented. (S<RISC OS>, VM/ESA)
+Not implemented. (S<RISC OS>)
-Available on OpenVOS Release 17.0 or later. (VOS)
-
Available on 64 bit OpenVMS 8.2 and later. (VMS)
=item stat
@@ -1978,7 +1968,7 @@
=item syscall
-Not implemented. (Win32, VMS, S<RISC OS>, VOS, VM/ESA)
+Not implemented. (Win32, VMS, S<RISC OS>, VOS)
=item sysopen
@@ -1985,7 +1975,7 @@
The traditional "0", "1", and "2" MODEs are implemented with different
numeric values on some systems. The flags exported by C<Fcntl>
(O_RDONLY, O_WRONLY, O_RDWR) should work everywhere though. (S<Mac
-OS>, OS/390, VM/ESA)
+OS>, OS/390)
=item system
@@ -2040,7 +2030,7 @@
=item umask
-Returns undef where unavailable, as of version 5.005.
+Returns undef where unavailable.
C<umask> works but the correct permissions are set only when the file
is finally closed. (AmigaOS)
@@ -2047,7 +2037,7 @@
=item utime
-Only the modification time is updated. (S<BeOS>, VMS, S<RISC OS>)
+Only the modification time is updated. (VMS, S<RISC OS>)
May not behave as expected. Behavior depends on the C runtime
library's implementation of utime(), and the filesystem being
@@ -2129,10 +2119,14 @@
=item Dragonfly BSD
+=item Midnight BSD
+
=item QNX Neutrino RTOS (6.5.0)
=item MirOS BSD
+=item Stratus OpenVOS (17.0 or later)
+
Caveats:
=over
@@ -2141,7 +2135,6 @@
=back
-
=item Symbian (Series 60 v3, 3.2 and 5 - what else?)
=item Stratus VOS / OpenVOS
@@ -2224,7 +2217,7 @@
UNICOS
UNICOS/mk
UTS
- VOS
+ VOS / OpenVOS
Win95/98/ME/2K/XP 2)
WinCE
z/OS (formerly OS/390)
@@ -2315,14 +2308,13 @@
=head1 SEE ALSO
-L<perlaix>, L<perlamiga>, L<perlapollo>, L<perlbeos>, L<perlbs2000>,
-L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>, L<perlepoc>,
+L<perlaix>, L<perlamiga>, L<perlbs2000>,
+L<perlce>, L<perlcygwin>, L<perldgux>, L<perldos>,
L<perlebcdic>, L<perlfreebsd>, L<perlhurd>, L<perlhpux>, L<perlirix>,
-L<perlmacos>, L<perlmacosx>, L<perlmpeix>,
+L<perlmacos>, L<perlmacosx>,
L<perlnetware>, L<perlos2>, L<perlos390>, L<perlos400>,
L<perlplan9>, L<perlqnx>, L<perlsolaris>, L<perltru64>,
-L<perlunicode>, L<perlvmesa>, L<perlvms>, L<perlvos>,
-L<perlwin32>, and L<Win32>.
+L<perlunicode>, L<perlvms>, L<perlvos>, L<perlwin32>, and L<Win32>.
=head1 AUTHORS / CONTRIBUTORS
Property changes on: trunk/contrib/perl/pod/perlport.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlpragma.pod
===================================================================
--- trunk/contrib/perl/pod/perlpragma.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlpragma.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -16,22 +16,22 @@
functions much like C<use integer;> You'd like this code
use MyMaths;
-
+
my $l = MyMaths->new(1.2);
my $r = MyMaths->new(3.4);
-
+
print "A: ", $l + $r, "\n";
-
+
use myint;
print "B: ", $l + $r, "\n";
-
+
{
no myint;
print "C: ", $l + $r, "\n";
}
-
+
print "D: ", $l + $r, "\n";
-
+
no myint;
print "E: ", $l + $r, "\n";
@@ -63,12 +63,12 @@
$$l + $$r;
}
};
-
+
sub new {
my ($class, $value) = @_;
bless \$value, $class;
}
-
+
1;
Note how we load the user pragma C<myint> with an empty list C<()> to
@@ -77,24 +77,24 @@
The interaction with the Perl compilation happens inside package C<myint>:
package myint;
-
+
use strict;
use warnings;
-
+
sub import {
- $^H{myint} = 1;
+ $^H{"myint/in_effect"} = 1;
}
-
+
sub unimport {
- $^H{myint} = 0;
+ $^H{"myint/in_effect"} = 0;
}
-
+
sub in_effect {
my $level = shift // 0;
my $hinthash = (caller($level))[10];
- return $hinthash->{myint};
+ return $hinthash->{"myint/in_effect"};
}
-
+
1;
As pragmata are implemented as modules, like any other module, C<use myint;>
@@ -122,10 +122,26 @@
is encapsulated into the routine C<in_effect()>, which takes as parameter
the number of call frames to go up to find the value of the pragma in the
user's script. This uses C<caller()> to determine the value of
-C<$^H{myint}> when each line of the user's script was called, and
+C<$^H{"myint/in_effect"}> when each line of the user's script was called, and
therefore provide the correct semantics in the subroutine implementing the
overloaded addition.
+=head1 Key naming
+
+There is only a single C<%^H>, but arbitrarily many modules that want
+to use its scoping semantics. To avoid stepping on each other's toes,
+they need to be sure to use different keys in the hash. It is therefore
+conventional for a module to use only keys that begin with the module's
+name (the name of its main package) and a "/" character. After this
+module-identifying prefix, the rest of the key is entirely up to the
+module: it may include any characters whatsoever. For example, a module
+C<Foo::Bar> should use keys such as C<Foo::Bar/baz> and C<Foo::Bar/$%/_!>.
+Modules following this convention all play nicely with each other.
+
+The Perl core uses a handful of keys in C<%^H> which do not follow this
+convention, because they predate it. Keys that follow the convention
+won't conflict with the core's historical keys.
+
=head1 Implementation details
The optree is shared between threads. This means there is a possibility that
Property changes on: trunk/contrib/perl/pod/perlpragma.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlre.pod
===================================================================
--- trunk/contrib/perl/pod/perlre.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlre.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -31,8 +31,8 @@
X</m> X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
Treat string as multiple lines. That is, change "^" and "$" from matching
-the start or end of the string to matching the start or end of any
-line anywhere within the string.
+the start or end of line only at the left and right ends of the string to
+matching them anywhere within the string.
=item s
X</s> X<regex, single-line> X<regexp, single-line>
@@ -72,15 +72,13 @@
# be even if it did!!
"\N{LATIN SMALL LIGATURE FI}" =~ /(f)(i)/i; # Doesn't match!
-Perl doesn't match multiple characters in an inverted bracketed
-character class, which otherwise could be highly confusing. See
+Perl doesn't match multiple characters in a bracketed
+character class unless the character that maps to them is explicitly
+mentioned, and it doesn't match them at all if the character class is
+inverted, which otherwise could be highly confusing. See
+L<perlrecharclass/Bracketed Character Classes>, and
L<perlrecharclass/Negation>.
-Also, Perl matching doesn't fully conform to the current Unicode C</i>
-recommendations, which ask that the matching be made upon the NFD
-(Normalization Form Decomposed) of the text. However, Unicode is
-in the process of reconsidering and revising their recommendations.
-
=item x
X</x>
@@ -105,20 +103,18 @@
=item a, d, l and u
X</a> X</d> X</l> X</u>
-These modifiers, new in 5.14, affect which character-set semantics
-(Unicode, ASCII, etc.) are used, as described below in
+These modifiers, all new in 5.14, affect which character-set semantics
+(Unicode, etc.) are used, as described below in
L</Character set modifiers>.
=back
-These are usually written as "the C</x> modifier", even though the delimiter
+Regular expression modifiers are usually written in documentation
+as e.g., "the C</x> modifier", even though the delimiter
in question might not really be a slash. The modifiers C</imsxadlup>
may also be embedded within the regular expression itself using
the C<(?...)> construct, see L</Extended Patterns> below.
-The C</x>, C</l>, C</u>, C</a> and C</d> modifiers need a little more
-explanation.
-
=head3 /x
C</x> tells
@@ -139,8 +135,8 @@
space interpretation within a single multi-character construct. For
example in C<\x{...}>, regardless of the C</x> modifier, there can be no
spaces. Same for a L<quantifier|/Quantifiers> such as C<{3}> or
-C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<?> and C<:>,
-but can between the C<(> and C<?>. Within any delimiters for such a
+C<{5,}>. Similarly, C<(?:...)> can't have a space between the C<(>,
+C<?>, and C<:>. Within any delimiters for such a
construct, allowed spaces are not affected by C</x>, and depend on the
construct. For example, C<\x{...}> can't have spaces because hexadecimal
numbers don't have spaces in them. But, Unicode properties can have spaces, so
@@ -154,22 +150,64 @@
the character set modifiers; they affect the character set semantics
used for the regular expression.
-At any given time, exactly one of these modifiers is in effect. Once
-compiled, the behavior doesn't change regardless of what rules are in
-effect when the regular expression is executed. And if a regular
-expression is interpolated into a larger one, the original's rules
-continue to apply to it, and only it.
+The C</d>, C</u>, and C</l> modifiers are not likely to be of much use
+to you, and so you need not worry about them very much. They exist for
+Perl's internal use, so that complex regular expression data structures
+can be automatically serialized and later exactly reconstituted,
+including all their nuances. But, since Perl can't keep a secret, and
+there may be rare instances where they are useful, they are documented
+here.
-Note that the modifiers affect only pattern matching, and do not extend
-to any replacement done. For example,
+The C</a> modifier, on the other hand, may be useful. Its purpose is to
+allow code that is to work mostly on ASCII data to not have to concern
+itself with Unicode.
- s/foo/\Ubar/l
+Briefly, C</l> sets the character set to that of whatever B<L>ocale is in
+effect at the time of the execution of the pattern match.
-will uppercase "bar", but the C</l> does not affect how the C<\U>
-operates. If C<use locale> is in effect, the C<\U> will use locale
-rules; if C<use feature 'unicode_strings'> is in effect, it will
-use Unicode rules, etc.
+C</u> sets the character set to B<U>nicode.
+C</a> also sets the character set to Unicode, BUT adds several
+restrictions for B<A>SCII-safe matching.
+
+C</d> is the old, problematic, pre-5.14 B<D>efault character set
+behavior. Its only use is to force that old behavior.
+
+At any given time, exactly one of these modifiers is in effect. Their
+existence allows Perl to keep the originally compiled behavior of a
+regular expression, regardless of what rules are in effect when it is
+actually executed. And if it is interpolated into a larger regex, the
+original's rules continue to apply to it, and only it.
+
+The C</l> and C</u> modifiers are automatically selected for
+regular expressions compiled within the scope of various pragmas,
+and we recommend that in general, you use those pragmas instead of
+specifying these modifiers explicitly. For one thing, the modifiers
+affect only pattern matching, and do not extend to even any replacement
+done, whereas using the pragmas give consistent results for all
+appropriate operations within their scopes. For example,
+
+ s/foo/\Ubar/il
+
+will match "foo" using the locale's rules for case-insensitive matching,
+but the C</l> does not affect how the C<\U> operates. Most likely you
+want both of them to use locale rules. To do this, instead compile the
+regular expression within the scope of C<use locale>. This both
+implicitly adds the C</l> and applies locale rules to the C<\U>. The
+lesson is to C<use locale> and not C</l> explicitly.
+
+Similarly, it would be better to use C<use feature 'unicode_strings'>
+instead of,
+
+ s/foo/\Lbar/iu
+
+to get Unicode rules, as the C<\L> in the former (but not necessarily
+the latter) would also use Unicode rules.
+
+More detail on each of the modifiers follows. Most likely you don't
+need to know this detail for C</l>, C</u>, and C</d>, and can skip ahead
+to L<E<sol>a|/E<sol>a (and E<sol>aa)>.
+
=head4 /l
means to use the current locale's rules (see L<perllocale>) when pattern
@@ -185,11 +223,11 @@
above 255 are treated as Unicode no matter what locale is in effect.
Under Unicode rules, there are a few case-insensitive matches that cross
the 255/256 boundary. These are disallowed under C</l>. For example,
-0xFF does not caselessly match the character at 0x178, C<LATIN CAPITAL
-LETTER Y WITH DIAERESIS>, because 0xFF may not be C<LATIN SMALL LETTER Y
-WITH DIAERESIS> in the current locale, and Perl has no way of knowing if
-that character even exists in the locale, much less what code point it
-is.
+0xFF (on ASCII platforms) does not caselessly match the character at
+0x178, C<LATIN CAPITAL LETTER Y WITH DIAERESIS>, because 0xFF may not be
+C<LATIN SMALL LETTER Y WITH DIAERESIS> in the current locale, and Perl
+has no way of knowing if that character even exists in the locale, much
+less what code point it is.
This modifier may be specified to be the default by C<use locale>, but
see L</Which character set modifier is in effect?>.
@@ -199,13 +237,15 @@
means to use Unicode rules when pattern matching. On ASCII platforms,
this means that the code points between 128 and 255 take on their
-Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's), whereas
-in strict ASCII their meanings are undefined. Thus the platform
-effectively becomes a Unicode platform, hence, for example, C<\w> will
-match any of the more than 100_000 word characters in Unicode.
+Latin-1 (ISO-8859-1) meanings (which are the same as Unicode's).
+(Otherwise Perl considers their meanings to be undefined.) Thus,
+under this modifier, the ASCII platform effectively becomes a Unicode
+platform; and hence, for example, C<\w> will match any of the more than
+100_000 word characters in Unicode.
Unlike most locales, which are specific to a language and country pair,
-Unicode classifies all the characters that are letters I<somewhere> as
+Unicode classifies all the characters that are letters I<somewhere> in
+the world as
C<\w>. For example, your locale might not think that C<LATIN SMALL
LETTER ETH> is a letter (unless you happen to speak Icelandic), but
Unicode does. Similarly, all the characters that are decimal digits
@@ -216,9 +256,12 @@
C<BENGALI DIGIT FOUR> (U+09EA) looks very much like an
C<ASCII DIGIT EIGHT> (U+0038). And, C<\d+>, may match strings of digits
that are a mixture from different writing systems, creating a security
-issue. L<Unicode::UCD/num()> can be used to sort this out.
+issue. L<Unicode::UCD/num()> can be used to sort
+this out. Or the C</a> modifier can be used to force C<\d> to match
+just the ASCII 0 through 9.
-Also, case-insensitive matching works on the full set of Unicode
+Also, under this modifier, case-insensitive matching works on the full
+set of Unicode
characters. The C<KELVIN SIGN>, for example matches the letters "k" and
"K"; and C<LATIN SMALL LIGATURE FF> matches the sequence "ff", which,
if you're not prepared, might make it look like a hexadecimal constant,
@@ -226,61 +269,12 @@
L<http://unicode.org/reports/tr36> for a detailed discussion of Unicode
security issues.
-On the EBCDIC platforms that Perl handles, the native character set is
-equivalent to Latin-1. Thus this modifier changes behavior only when
-the C<"/i"> modifier is also specified, and it turns out it affects only
-two characters, giving them full Unicode semantics: the C<MICRO SIGN>
-will match the Greek capital and small letters C<MU>, otherwise not; and
-the C<LATIN CAPITAL LETTER SHARP S> will match any of C<SS>, C<Ss>,
-C<sS>, and C<ss>, otherwise not.
-
This modifier may be specified to be the default by C<use feature
-'unicode_strings>, but see
-L</Which character set modifier is in effect?>.
+'unicode_strings>, C<use locale ':not_characters'>, or
+C<L<use 5.012|perlfunc/use VERSION>> (or higher),
+but see L</Which character set modifier is in effect?>.
X</u>
-=head4 /a
-
-is the same as C</u>, except that C<\d>, C<\s>, C<\w>, and the
-Posix character classes are restricted to matching in the ASCII range
-only. That is, with this modifier, C<\d> always means precisely the
-digits C<"0"> to C<"9">; C<\s> means the five characters C<[ \f\n\r\t]>;
-C<\w> means the 63 characters C<[A-Za-z0-9_]>; and likewise, all the
-Posix classes such as C<[[:print:]]> match only the appropriate
-ASCII-range characters.
-
-This modifier is useful for people who only incidentally use Unicode.
-With it, one can write C<\d> with confidence that it will only match
-ASCII characters, and should the need arise to match beyond ASCII, you
-can use C<\p{Digit}>, or C<\p{Word}> for C<\w>. There are similar
-C<\p{...}> constructs that can match white space and Posix classes
-beyond ASCII. See L<perlrecharclass/POSIX Character Classes>.
-
-As you would expect, this modifier causes, for example, C<\D> to mean
-the same thing as C<[^0-9]>; in fact, all non-ASCII characters match
-C<\D>, C<\S>, and C<\W>. C<\b> still means to match at the boundary
-between C<\w> and C<\W>, using the C</a> definitions of them (similarly
-for C<\B>).
-
-Otherwise, C</a> behaves like the C</u> modifier, in that
-case-insensitive matching uses Unicode semantics; for example, "k" will
-match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code
-points in the Latin1 range, above ASCII will have Unicode rules when it
-comes to case-insensitive matching.
-
-To forbid ASCII/non-ASCII matches (like "k" with C<\N{KELVIN SIGN}>),
-specify the "a" twice, for example C</aai> or C</aia>
-
-To reiterate, this modifier provides protection for applications that
-don't wish to be exposed to all of Unicode. Specifying it twice
-gives added protection.
-
-This modifier may be specified to be the default by C<use re '/a'>
-or C<use re '/aa'>, but see
-L</Which character set modifier is in effect?>.
-X</a>
-X</aa>
-
=head4 /d
This modifier means to use the "Default" native rules of the platform
@@ -307,16 +301,22 @@
=item 5
-the pattern uses a Unicode property (C<\p{...}>)
+the pattern uses a Unicode property (C<\p{...}>); or
+=item 6
+
+the pattern uses L</C<(?[ ])>>
+
=back
Another mnemonic for this modifier is "Depends", as the rules actually
used depend on various things, and as a result you can get unexpected
-results. See L<perlunicode/The "Unicode Bug">.
+results. See L<perlunicode/The "Unicode Bug">. The Unicode Bug has
+become rather infamous, leading to yet another (printable) name for this
+modifier, "Dodgy".
-On ASCII platforms, the native rules are ASCII, and on EBCDIC platforms
-(at least the ones that Perl handles), they are Latin-1.
+Unless the pattern or string are encoded in UTF-8, only ASCII characters
+can match positively.
Here are some examples of how that works on an ASCII platform:
@@ -327,10 +327,80 @@
chop $str;
$str =~ /^\w/; # Still a match! $str remains in UTF-8 format.
+This modifier is automatically selected by default when none of the
+others are, so yet another name for it is "Default".
+
+Because of the unexpected behaviors associated with this modifier, you
+probably should only use it to maintain weird backward compatibilities.
+
+=head4 /a (and /aa)
+
+This modifier stands for ASCII-restrict (or ASCII-safe). This modifier,
+unlike the others, may be doubled-up to increase its effect.
+
+When it appears singly, it causes the sequences C<\d>, C<\s>, C<\w>, and
+the Posix character classes to match only in the ASCII range. They thus
+revert to their pre-5.6, pre-Unicode meanings. Under C</a>, C<\d>
+always means precisely the digits C<"0"> to C<"9">; C<\s> means the five
+characters C<[ \f\n\r\t]>, and starting in Perl v5.18, experimentally,
+the vertical tab; C<\w> means the 63 characters
+C<[A-Za-z0-9_]>; and likewise, all the Posix classes such as
+C<[[:print:]]> match only the appropriate ASCII-range characters.
+
+This modifier is useful for people who only incidentally use Unicode,
+and who do not wish to be burdened with its complexities and security
+concerns.
+
+With C</a>, one can write C<\d> with confidence that it will only match
+ASCII characters, and should the need arise to match beyond ASCII, you
+can instead use C<\p{Digit}> (or C<\p{Word}> for C<\w>). There are
+similar C<\p{...}> constructs that can match beyond ASCII both white
+space (see L<perlrecharclass/Whitespace>), and Posix classes (see
+L<perlrecharclass/POSIX Character Classes>). Thus, this modifier
+doesn't mean you can't use Unicode, it means that to get Unicode
+matching you must explicitly use a construct (C<\p{}>, C<\P{}>) that
+signals Unicode.
+
+As you would expect, this modifier causes, for example, C<\D> to mean
+the same thing as C<[^0-9]>; in fact, all non-ASCII characters match
+C<\D>, C<\S>, and C<\W>. C<\b> still means to match at the boundary
+between C<\w> and C<\W>, using the C</a> definitions of them (similarly
+for C<\B>).
+
+Otherwise, C</a> behaves like the C</u> modifier, in that
+case-insensitive matching uses Unicode semantics; for example, "k" will
+match the Unicode C<\N{KELVIN SIGN}> under C</i> matching, and code
+points in the Latin1 range, above ASCII will have Unicode rules when it
+comes to case-insensitive matching.
+
+To forbid ASCII/non-ASCII matches (like "k" with C<\N{KELVIN SIGN}>),
+specify the "a" twice, for example C</aai> or C</aia>. (The first
+occurrence of "a" restricts the C<\d>, etc., and the second occurrence
+adds the C</i> restrictions.) But, note that code points outside the
+ASCII range will use Unicode rules for C</i> matching, so the modifier
+doesn't really restrict things to just ASCII; it just forbids the
+intermixing of ASCII and non-ASCII.
+
+To summarize, this modifier provides protection for applications that
+don't wish to be exposed to all of Unicode. Specifying it twice
+gives added protection.
+
+This modifier may be specified to be the default by C<use re '/a'>
+or C<use re '/aa'>. If you do so, you may actually have occasion to use
+the C</u> modifier explictly if there are a few regular expressions
+where you do want full Unicode rules (but even here, it's best if
+everything were under feature C<"unicode_strings">, along with the
+C<use re '/aa'>). Also see L</Which character set modifier is in
+effect?>.
+X</a>
+X</aa>
+
=head4 Which character set modifier is in effect?
Which of these modifiers is in effect at any given point in a regular
-expression depends on a fairly complex set of interactions. As
+expression depends on a fairly complex set of interactions. These have
+been designed so that in general you don't have to worry about it, but
+this section gives the gory details. As
explained below in L</Extended Patterns> it is possible to explicitly
specify modifiers that apply only to portions of a regular expression.
The innermost always has priority over any outer ones, and one applying
@@ -337,16 +407,19 @@
to the whole expression has priority over any of the default settings that are
described in the remainder of this section.
-The C<L<use re 'E<sol>foo'|re/'E<sol>flags' mode">> pragma can be used to set
+The C<L<use re 'E<sol>foo'|re/"'/flags' mode">> pragma can be used to set
default modifiers (including these) for regular expressions compiled
within its scope. This pragma has precedence over the other pragmas
-listed below that change the defaults.
+listed below that also change the defaults.
Otherwise, C<L<use locale|perllocale>> sets the default modifier to C</l>;
-and C<L<use feature 'unicode_strings|feature>> or
+and C<L<use feature 'unicode_strings|feature>>, or
C<L<use 5.012|perlfunc/use VERSION>> (or higher) set the default to
C</u> when not in the same scope as either C<L<use locale|perllocale>>
-or C<L<use bytes|bytes>>. Unlike the mechanisms mentioned above, these
+or C<L<use bytes|bytes>>.
+(C<L<use locale ':not_characters'|perllocale/Unicode and UTF-8>> also
+sets the default to C</u>, overriding any plain C<use locale>.)
+Unlike the mechanisms mentioned above, these
affect operations besides regular expressions pattern matching, and so
give more consistent results with other operators, including using
C<\U>, C<\l>, etc. in substitution replacements.
@@ -401,7 +474,7 @@
the string), and "$" will match before any newline. At the
cost of a little more overhead, you can do this by using the /m modifier
on the pattern match operator. (Older programs did this by setting C<$*>,
-but this option was removed in perl 5.9.)
+but this option was removed in perl 5.10.)
X<^> X<$> X</m>
To simplify multi-line substitutions, the "." character never matches a
@@ -422,9 +495,24 @@
{n,m} Match at least n but not more than m times
(If a curly bracket occurs in any other context and does not form part of
-a backslashed sequence like C<\x{...}>, it is treated
-as a regular character. In particular, the lower bound
-is not optional.) The "*" quantifier is equivalent to C<{0,}>, the "+"
+a backslashed sequence like C<\x{...}>, it is treated as a regular
+character. In particular, the lower quantifier bound is not optional,
+and a typo in a quantifier silently causes it to be treated as the
+literal characters. For example,
+
+ /o{4,3}/
+
+looks like a quantifier that matches 0 times, since 4 is greater than 3,
+but it really means to match the sequence of six characters
+S<C<"o { 4 , 3 }">>. It is planned to eventually require literal uses
+of curly brackets to be escaped, say by preceding them with a backslash
+or enclosing them within square brackets, (C<"\{"> or C<"[{]">). This
+change will allow for future syntax extensions (like making the lower
+bound of a quantifier optional), and better error checking. In the
+meantime, you should get in the habit of escaping all instances where
+you mean a literal "{".)
+
+The "*" quantifier is equivalent to C<{0,}>, the "+"
quantifier to C<{1,}>, and the "?" quantifier to C<{0,1}>. n and m are limited
to non-negative integral values less than a preset limit defined when perl is built.
This is usually 32766 on the most common platforms. The actual limit can
@@ -517,6 +605,7 @@
character class "..." within the outer bracketed
character class. Example: [[:upper:]] matches any
uppercase character.
+ (?[...]) [8] Extended bracketed character class
\w [3] Match a "word" character (alphanumeric plus "_", plus
other connector punctuation chars plus Unicode
marks)
@@ -542,8 +631,7 @@
\g{name} [5] Named backreference
\k<name> [5] Named backreference
\K [6] Keep the stuff left of the \K, don't include it in $&
- \N [7] Any character but \n (experimental). Not affected by
- /s modifier
+ \N [7] Any character but \n. Not affected by /s modifier
\v [3] Vertical whitespace
\V [3] Not vertical whitespace
\h [3] Horizontal whitespace
@@ -583,6 +671,10 @@
when of the form C<\N{U+I<hex>}>, it matches the character whose Unicode
code point is I<hex>. Otherwise it matches any character but C<\n>.
+=item [8]
+
+See L<perlrecharclass/Extended Bracketed Character Classes> for details.
+
=back
=head3 Assertions
@@ -791,8 +883,10 @@
parentheses will not be penalized. So avoid C<$&>, C<$'>, and C<$`>
if you can, but if you can't (and some algorithms really appreciate
them), once you've used them once, use them at will, because you've
-already paid the price. As of 5.005, C<$&> is not so costly as the
-other two.
+already paid the price. As of 5.17.4, the presence of each of the three
+variables in a program is recorded separately, and depending on
+circumstances, perl may be able be more efficient knowing that only C<$&>
+rather than all three have been seen, for example.
X<$&> X<$`> X<$'>
As a workaround for this problem, Perl 5.10.0 introduces C<${^PREMATCH}>,
@@ -809,7 +903,7 @@
Backslashed metacharacters in Perl are alphanumeric, such as C<\b>,
C<\w>, C<\n>. Unlike some other regular expression languages, there
are no backslashed symbols that aren't alphanumeric. So anything
-that looks like \\, \(, \), \<, \>, \{, or \} is always
+that looks like \\, \(, \), \[, \], \{, or \} is always
interpreted as a literal character, not a metacharacter. This was
once used in a common idiom to disable or quote the special meanings
of regular expression metacharacters in a string that you want to
@@ -830,6 +924,8 @@
I<need> to use literal backslashes within C<\Q...\E>,
consult L<perlop/"Gory details of parsing quoted constructs">.
+C<quotemeta()> and C<\Q> are fully described in L<perlfunc/quotemeta>.
+
=head2 Extended Patterns
Perl also defines a consistent extension syntax for features not
@@ -850,7 +946,7 @@
expressions, and 2) whenever you see one, you should stop and
"question" exactly what is going on. That's psychology....
-=over 10
+=over 4
=item C<(?#text)>
X<(?#)>
@@ -892,7 +988,7 @@
modifier outside this group.
These modifiers do not carry over into named subpatterns called in the
-enclosing group. In other words, a pattern such as C<((?i)(&NAME))> does not
+enclosing group. In other words, a pattern such as C<((?i)(?&NAME))> does not
change the case-sensitivity of the "NAME" pattern.
Any of these modifiers can be set to apply globally to all regular
@@ -1144,88 +1240,125 @@
B<WARNING>: This extended regular expression feature is considered
experimental, and may be changed without notice. Code executed that
has side effects may not perform identically from version to version
-due to the effect of future optimisations in the regex engine.
+due to the effect of future optimisations in the regex engine. The
+implementation of this feature was radically overhauled for the 5.18.0
+release, and its behaviour in earlier versions of perl was much buggier,
+especially in relation to parsing, lexical vars, scoping, recursion and
+reentrancy.
-This zero-width assertion evaluates any embedded Perl code. It
-always succeeds, and its C<code> is not interpolated. Currently,
-the rules to determine where the C<code> ends are somewhat convoluted.
+This zero-width assertion executes any embedded Perl code. It always
+succeeds, and its return value is set as C<$^R>.
-This feature can be used together with the special variable C<$^N> to
-capture the results of submatches in variables without having to keep
-track of the number of nested parentheses. For example:
+In literal patterns, the code is parsed at the same time as the
+surrounding code. While within the pattern, control is passed temporarily
+back to the perl parser, until the logically-balancing closing brace is
+encountered. This is similar to the way that an array index expression in
+a literal string is handled, for example
- $_ = "The brown fox jumps over the lazy dog";
- /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
- print "color = $color, animal = $animal\n";
+ "abc$array[ 1 + f('[') + g()]def"
-Inside the C<(?{...})> block, C<$_> refers to the string the regular
+In particular, braces do not need to be balanced:
+
+ s/abc(?{ f('{'); })/def/
+
+Even in a pattern that is interpolated and compiled at run-time, literal
+code blocks will be compiled once, at perl compile time; the following
+prints "ABCD":
+
+ print "D";
+ my $qr = qr/(?{ BEGIN { print "A" } })/;
+ my $foo = "foo";
+ /$foo$qr(?{ BEGIN { print "B" } })/;
+ BEGIN { print "C" }
+
+In patterns where the text of the code is derived from run-time
+information rather than appearing literally in a source code /pattern/,
+the code is compiled at the same time that the pattern is compiled, and
+for reasons of security, C<use re 'eval'> must be in scope. This is to
+stop user-supplied patterns containing code snippets from being
+executable.
+
+In situations where you need to enable this with C<use re 'eval'>, you should
+also have taint checking enabled. Better yet, use the carefully
+constrained evaluation within a Safe compartment. See L<perlsec> for
+details about both these mechanisms.
+
+From the viewpoint of parsing, lexical variable scope and closures,
+
+ /AAA(?{ BBB })CCC/
+
+behaves approximately like
+
+ /AAA/ && do { BBB } && /CCC/
+
+Similarly,
+
+ qr/AAA(?{ BBB })CCC/
+
+behaves approximately like
+
+ sub { /AAA/ && do { BBB } && /CCC/ }
+
+In particular:
+
+ { my $i = 1; $r = qr/(?{ print $i })/ }
+ my $i = 2;
+ /$r/; # prints "1"
+
+Inside a C<(?{...})> block, C<$_> refers to the string the regular
expression is matching against. You can also use C<pos()> to know what is
the current position of matching within this string.
-The C<code> is properly scoped in the following sense: If the assertion
-is backtracked (compare L<"Backtracking">), all changes introduced after
-C<local>ization are undone, so that
+The code block introduces a new scope from the perspective of lexical
+variable declarations, but B<not> from the perspective of C<local> and
+similar localizing behaviours. So later code blocks within the same
+pattern will still see the values which were localized in earlier blocks.
+These accumulated localizations are undone either at the end of a
+successful match, or if the assertion is backtracked (compare
+L<"Backtracking">). For example,
$_ = 'a' x 8;
m<
- (?{ $cnt = 0 }) # Initialize $cnt.
+ (?{ $cnt = 0 }) # Initialize $cnt.
(
a
(?{
- local $cnt = $cnt + 1; # Update $cnt, backtracking-safe.
+ local $cnt = $cnt + 1; # Update $cnt,
+ # backtracking-safe.
})
)*
aaaa
- (?{ $res = $cnt }) # On success copy to
- # non-localized location.
+ (?{ $res = $cnt }) # On success copy to
+ # non-localized location.
>x;
-will set C<$res = 4>. Note that after the match, C<$cnt> returns to the globally
-introduced value, because the scopes that restrict C<local> operators
-are unwound.
+will initially increment C<$cnt> up to 8; then during backtracking, its
+value will be unwound back to 4, which is the value assigned to C<$res>.
+At the end of the regex execution, $cnt will be wound back to its initial
+value of 0.
-This assertion may be used as a C<(?(condition)yes-pattern|no-pattern)>
-switch. If I<not> used in this way, the result of evaluation of
-C<code> is put into the special variable C<$^R>. This happens
-immediately, so C<$^R> can be used from other C<(?{ code })> assertions
-inside the same regular expression.
+This assertion may be used as the condition in a
+ (?(condition)yes-pattern|no-pattern)
+
+switch. If I<not> used in this way, the result of evaluation of C<code>
+is put into the special variable C<$^R>. This happens immediately, so
+C<$^R> can be used from other C<(?{ code })> assertions inside the same
+regular expression.
+
The assignment to C<$^R> above is properly localized, so the old
value of C<$^R> is restored if the assertion is backtracked; compare
L<"Backtracking">.
-For reasons of security, this construct is forbidden if the regular
-expression involves run-time interpolation of variables, unless the
-perilous C<use re 'eval'> pragma has been used (see L<re>), or the
-variables contain results of the C<qr//> operator (see
-L<perlop/"qr/STRINGE<sol>msixpodual">).
+Note that the special variable C<$^N> is particularly useful with code
+blocks to capture the results of submatches in variables without having to
+keep track of the number of nested parentheses. For example:
-This restriction is due to the wide-spread and remarkably convenient
-custom of using run-time determined strings as patterns. For example:
+ $_ = "The brown fox jumps over the lazy dog";
+ /the (\S+)(?{ $color = $^N }) (\S+)(?{ $animal = $^N })/i;
+ print "color = $color, animal = $animal\n";
- $re = <>;
- chomp $re;
- $string =~ /$re/;
-Before Perl knew how to execute interpolated code within a pattern,
-this operation was completely safe from a security point of view,
-although it could raise an exception from an illegal pattern. If
-you turn on the C<use re 'eval'>, though, it is no longer secure,
-so you should only do so if you are also using taint checking.
-Better yet, use the carefully constrained evaluation within a Safe
-compartment. See L<perlsec> for details about both these mechanisms.
-
-B<WARNING>: Use of lexical (C<my>) variables in these blocks is
-broken. The result is unpredictable and will make perl unstable. The
-workaround is to use global (C<our>) variables.
-
-B<WARNING>: In perl 5.12.x and earlier, the regex engine
-was not re-entrant, so interpolated code could not
-safely invoke the regex engine either directly with
-C<m//> or C<s///>), or indirectly with functions such as
-C<split>. Invoking the regex engine in these blocks would make perl
-unstable.
-
=item C<(??{ code })>
X<(??{})>
X<regex, postponed> X<regexp, postponed> X<regular expression, postponed>
@@ -1235,66 +1368,67 @@
has side effects may not perform identically from version to version
due to the effect of future optimisations in the regex engine.
-This is a "postponed" regular subexpression. The C<code> is evaluated
-at run time, at the moment this subexpression may match. The result
-of evaluation is considered a regular expression and matched as
-if it were inserted instead of this construct. Note that this means
-that the contents of capture groups defined inside an eval'ed pattern
-are not available outside of the pattern, and vice versa, there is no
-way for the inner pattern to refer to a capture group defined outside.
-Thus,
+This is a "postponed" regular subexpression. It behaves in I<exactly> the
+same way as a C<(?{ code })> code block as described above, except that
+its return value, rather than being assigned to C<$^R>, is treated as a
+pattern, compiled if it's a string (or used as-is if its a qr// object),
+then matched as if it were inserted instead of this construct.
+During the matching of this sub-pattern, it has its own set of
+captures which are valid during the sub-match, but are discarded once
+control returns to the main pattern. For example, the following matches,
+with the inner pattern capturing "B" and matching "BB", while the outer
+pattern captures "A";
+
+ my $inner = '(.)\1';
+ "ABBA" =~ /^(.)(??{ $inner })\1/;
+ print $1; # prints "A";
+
+Note that this means that there is no way for the inner pattern to refer
+to a capture group defined outside. (The code block itself can use C<$1>,
+etc., to refer to the enclosing pattern's capture groups.) Thus, although
+
('a' x 100)=~/(??{'(.)' x 100})/
-B<will> match, it will B<not> set $1.
+I<will> match, it will I<not> set $1 on exit.
-The C<code> is not interpolated. As before, the rules to determine
-where the C<code> ends are currently somewhat convoluted.
-
The following pattern matches a parenthesized group:
- $re = qr{
- \(
- (?:
- (?> [^()]+ ) # Non-parens without backtracking
- |
- (??{ $re }) # Group with matching parens
- )*
- \)
- }x;
+ $re = qr{
+ \(
+ (?:
+ (?> [^()]+ ) # Non-parens without backtracking
+ |
+ (??{ $re }) # Group with matching parens
+ )*
+ \)
+ }x;
-See also C<(?PARNO)> for a different, more efficient way to accomplish
+See also
+L<C<(?I<PARNO>)>|/(?PARNO) (?-PARNO) (?+PARNO) (?R) (?0)>
+for a different, more efficient way to accomplish
the same task.
-For reasons of security, this construct is forbidden if the regular
-expression involves run-time interpolation of variables, unless the
-perilous C<use re 'eval'> pragma has been used (see L<re>), or the
-variables contain results of the C<qr//> operator (see
-L<perlop/"qrE<sol>STRINGE<sol>msixpodual">).
+Executing a postponed regular expression 50 times without consuming any
+input string will result in a fatal error. The maximum depth is compiled
+into perl, so changing it requires a custom build.
-In perl 5.12.x and earlier, because the regex engine was not re-entrant,
-delayed code could not safely invoke the regex engine either directly with
-C<m//> or C<s///>), or indirectly with functions such as C<split>.
-
-Recursing deeper than 50 times without consuming any input string will
-result in a fatal error. The maximum depth is compiled into perl, so
-changing it requires a custom build.
-
-=item C<(?PARNO)> C<(?-PARNO)> C<(?+PARNO)> C<(?R)> C<(?0)>
+=item C<(?I<PARNO>)> C<(?-I<PARNO>)> C<(?+I<PARNO>)> C<(?R)> C<(?0)>
X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)> X<(?+1)> X<(?-PARNO)> X<(?+PARNO)>
X<regex, recursive> X<regexp, recursive> X<regular expression, recursive>
X<regex, relative recursion>
-Similar to C<(??{ code })> except it does not involve compiling any code,
-instead it treats the contents of a capture group as an independent
-pattern that must match at the current position. Capture groups
-contained by the pattern will have the value as determined by the
-outermost recursion.
+Similar to C<(??{ code })> except that it does not involve executing any
+code or potentially compiling a returned pattern string; instead it treats
+the part of the current pattern contained within a specified capture group
+as an independent pattern that must match at the current position.
+Capture groups contained by the pattern will have the value as determined
+by the outermost recursion.
-PARNO is a sequence of digits (not starting with 0) whose value reflects
+I<PARNO> is a sequence of digits (not starting with 0) whose value reflects
the paren-number of the capture group to recurse to. C<(?R)> recurses to
the beginning of the whole pattern. C<(?0)> is an alternate syntax for
-C<(?R)>. If PARNO is preceded by a plus or minus sign then it is assumed
+C<(?R)>. If I<PARNO> is preceded by a plus or minus sign then it is assumed
to be relative, with negative numbers indicating preceding capture groups
and positive ones following. Thus C<(?-1)> refers to the most recently
declared group, and C<(?+1)> indicates the next group to be declared.
@@ -1305,15 +1439,15 @@
The following pattern matches a function foo() which may contain
balanced parentheses as the argument.
- $re = qr{ ( # paren group 1 (full function)
+ $re = qr{ ( # paren group 1 (full function)
foo
- ( # paren group 2 (parens)
+ ( # paren group 2 (parens)
\(
- ( # paren group 3 (contents of parens)
+ ( # paren group 3 (contents of parens)
(?:
- (?> [^()]+ ) # Non-parens without backtracking
+ (?> [^()]+ ) # Non-parens without backtracking
|
- (?2) # Recurse to start of paren group 2
+ (?2) # Recurse to start of paren group 2
)*
)
\)
@@ -1344,7 +1478,7 @@
for later use:
my $parens = qr/(\((?:[^()]++|(?-1))*+\))/;
- if (/foo $parens \s+ + \s+ bar $parens/x) {
+ if (/foo $parens \s+ \+ \s+ bar $parens/x) {
# do something here...
}
@@ -1358,7 +1492,7 @@
=item C<(?&NAME)>
X<(?&NAME)>
-Recurse to a named subpattern. Identical to C<(?PARNO)> except that the
+Recurse to a named subpattern. Identical to C<(?I<PARNO>)> except that the
parenthesis to recurse to is determined by name. If multiple parentheses have
the same name, then it recurses to the leftmost.
@@ -1378,11 +1512,11 @@
a true value, matches C<no-pattern> otherwise. A missing pattern always
matches.
-C<(condition)> should be either an integer in
+C<(condition)> should be one of: 1) an integer in
parentheses (which is valid if the corresponding pair of parentheses
-matched), a look-ahead/look-behind/evaluate zero-width assertion, a
+matched); 2) a look-ahead/look-behind/evaluate zero-width assertion; 3) a
name in angle brackets or single quotes (which is valid if a group
-with the given name matched), or the special symbol (R) (true when
+with the given name matched); or 4) the special symbol (R) (true when
evaluated inside of recursion or eval). Additionally the R may be
followed by a number, (which will be true when evaluated when recursing
inside of the appropriate group), or by C<&NAME>, in which case it will
@@ -1473,6 +1607,19 @@
necessary. Thus C<$+{NAME_PAT}> would not be defined even though
C<$+{NAME}> would be.
+Finally, keep in mind that subpatterns created inside a DEFINE block
+count towards the absolute and relative number of captures, so this:
+
+ my @captures = "a" =~ /(.) # First capture
+ (?(DEFINE)
+ (?<EXAMPLE> 1 ) # Second capture
+ )/x;
+ say scalar @captures;
+
+Will output 2, not 1. This is particularly important if you intend to
+compile the definitions with the C<qr//> operator, and later
+interpolate them in another pattern.
+
=item C<< (?>pattern) >>
X<backtrack> X<backtracking> X<atomic> X<possessive>
@@ -1582,6 +1729,10 @@
PAT?+ (?>PAT?)
PAT{min,max}+ (?>PAT{min,max})
+=item C<(?[ ])>
+
+See L<perlrecharclass/Extended Bracketed Character Classes>.
+
=back
=head2 Special Backtracking Control Verbs
@@ -1618,7 +1769,7 @@
If a pattern does not contain a special backtracking verb that allows an
argument, then C<$REGERROR> and C<$REGMARK> are not touched at all.
-=over 4
+=over 3
=item Verbs that take an argument
@@ -1675,7 +1826,6 @@
C<(*PRUNE)> can be used to handle cases that cannot be expressed using a
C<< (?>pattern) >> alone.
-
=item C<(*SKIP)> C<(*SKIP:NAME)>
X<(*SKIP)>
@@ -1696,8 +1846,8 @@
Compare the following to the examples in C<(*PRUNE)>; note the string
is twice as long:
- 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
+ 'aaabaaab' =~ /a+b?(*SKIP)(?{print "$&\n"; $count++})(*FAIL)/;
+ print "Count=$count\n";
outputs
@@ -1710,7 +1860,7 @@
C<(*SKIP)> was executed.
=item C<(*MARK:NAME)> C<(*:NAME)>
-X<(*MARK)> C<(*MARK:NAME)> C<(*:NAME)>
+X<(*MARK)> X<(*MARK:NAME)> X<(*:NAME)>
This zero-width pattern can be used to mark the point reached in a string
when a certain part of the pattern has been successfully matched. This
@@ -1738,16 +1888,18 @@
variable will be set to the name of the most recently executed
C<(*MARK:NAME)>.
-See C<(*SKIP)> for more details.
+See L</(*SKIP)> for more details.
As a shortcut C<(*MARK:NAME)> can be written C<(*:NAME)>.
=item C<(*THEN)> C<(*THEN:NAME)>
-This is similar to the "cut group" operator C<::> from Perl 6. Like
+This is similar to the "cut group" operator C<::> from Perl 6. Like
C<(*PRUNE)>, this verb always matches, and when backtracked into on
failure, it causes the regex engine to try the next alternation in the
-innermost enclosing group (capturing or otherwise).
+innermost enclosing group (capturing or otherwise) that has alternations.
+The two branches of a C<(?(condition)yes-pattern|no-pattern)> do not
+count as an alternation, as far as C<(*THEN)> is concerned.
Its name comes from the observation that this operation combined with the
alternation operator (C<|>) can be used to create what is essentially a
@@ -1766,15 +1918,21 @@
but
- / ( A (*THEN) B | C (*THEN) D ) /
+ / ( A (*THEN) B | C ) /
is not the same as
- / ( A (*PRUNE) B | C (*PRUNE) D ) /
+ / ( A (*PRUNE) B | C ) /
as after matching the A but failing on the B the C<(*THEN)> verb will
backtrack and try C; but the C<(*PRUNE)> verb will simply fail.
+=back
+
+=item Verbs without an argument
+
+=over 4
+
=item C<(*COMMIT)>
X<(*COMMIT)>
@@ -1784,8 +1942,8 @@
to find a valid match by advancing the start pointer will occur again.
For example,
- 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
- print "Count=$count\n";
+ 'aaabaaab' =~ /a+b?(*COMMIT)(?{print "$&\n"; $count++})(*FAIL)/;
+ print "Count=$count\n";
outputs
@@ -1796,12 +1954,6 @@
does not match, the regex engine will not try any further matching on the
rest of the string.
-=back
-
-=item Verbs without an argument
-
-=over 4
-
=item C<(*FAIL)> C<(*F)>
X<(*FAIL)> X<(*F)>
@@ -2181,7 +2333,7 @@
be significantly simplified by using repeated subexpressions that
may match zero-length substrings. Here's a simple example being:
- @chars = split //, $string; # // is not magic in split
+ @chars = split //, $string; # // is not magic in split
($whitewashed = $string) =~ s/()/ /g; # parens avoid magic s// /
Thus Perl allows such constructs, by I<forcefully breaking
@@ -2332,10 +2484,10 @@
For this grouping operator there is no need to describe the ordering, since
only whether or not C<S> can match is important.
-=item C<(??{ EXPR })>, C<(?PARNO)>
+=item C<(??{ EXPR })>, C<(?I<PARNO>)>
The ordering is the same as for the regular expression which is
-the result of EXPR, or the pattern contained by capture group PARNO.
+the result of EXPR, or the pattern contained by capture group I<PARNO>.
=item C<(?(condition)yes-pattern|no-pattern)>
Property changes on: trunk/contrib/perl/pod/perlre.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlreapi.pod
===================================================================
--- trunk/contrib/perl/pod/perlreapi.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlreapi.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,40 +1,58 @@
=head1 NAME
-perlreapi - perl regular expression plugin interface
+perlreapi - Perl regular expression plugin interface
=head1 DESCRIPTION
-As of Perl 5.9.5 there is a new interface for plugging and using other
-regular expression engines than the default one.
+As of Perl 5.9.5 there is a new interface for plugging and using
+regular expression engines other than the default one.
Each engine is supposed to provide access to a constant structure of the
following format:
typedef struct regexp_engine {
- REGEXP* (*comp) (pTHX_ const SV * const pattern, const U32 flags);
- I32 (*exec) (pTHX_ REGEXP * const rx, char* stringarg, char* strend,
- char* strbeg, I32 minend, SV* screamer,
+ REGEXP* (*comp) (pTHX_
+ const SV * const pattern, const U32 flags);
+ I32 (*exec) (pTHX_
+ REGEXP * const rx,
+ char* stringarg,
+ char* strend, char* strbeg,
+ I32 minend, SV* screamer,
void* data, U32 flags);
- char* (*intuit) (pTHX_ REGEXP * const rx, SV *sv, char *strpos,
- char *strend, U32 flags,
+ char* (*intuit) (pTHX_
+ REGEXP * const rx, SV *sv,
+ char *strpos, char *strend, U32 flags,
struct re_scream_pos_data_s *data);
SV* (*checkstr) (pTHX_ REGEXP * const rx);
void (*free) (pTHX_ REGEXP * const rx);
- void (*numbered_buff_FETCH) (pTHX_ REGEXP * const rx, const I32 paren,
- SV * const sv);
- void (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
- SV const * const value);
- I32 (*numbered_buff_LENGTH) (pTHX_ REGEXP * const rx, const SV * const sv,
- const I32 paren);
- SV* (*named_buff) (pTHX_ REGEXP * const rx, SV * const key,
- SV * const value, U32 flags);
- SV* (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
+ void (*numbered_buff_FETCH) (pTHX_
+ REGEXP * const rx,
+ const I32 paren,
+ SV * const sv);
+ void (*numbered_buff_STORE) (pTHX_
+ REGEXP * const rx,
+ const I32 paren,
+ SV const * const value);
+ I32 (*numbered_buff_LENGTH) (pTHX_
+ REGEXP * const rx,
+ const SV * const sv,
+ const I32 paren);
+ SV* (*named_buff) (pTHX_
+ REGEXP * const rx,
+ SV * const key,
+ SV * const value,
+ U32 flags);
+ SV* (*named_buff_iter) (pTHX_
+ REGEXP * const rx,
+ const SV * const lastkey,
const U32 flags);
SV* (*qr_package)(pTHX_ REGEXP * const rx);
#ifdef USE_ITHREADS
void* (*dupe) (pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
#endif
+ REGEXP* (*op_comp) (...);
+
When a regexp is compiled, its C<engine> field is then set to point at
the appropriate structure, so that when it needs to be used Perl can find
the right routines to do so.
@@ -41,11 +59,11 @@
In order to install a new regexp handler, C<$^H{regcomp}> is set
to an integer which (when casted appropriately) resolves to one of these
-structures. When compiling, the C<comp> method is executed, and the
-resulting regexp structure's engine field is expected to point back at
+structures. When compiling, the C<comp> method is executed, and the
+resulting C<regexp> structure's engine field is expected to point back at
the same structure.
-The pTHX_ symbol in the definition is a macro used by perl under threading
+The pTHX_ symbol in the definition is a macro used by Perl under threading
to provide an extra argument to the routine holding a pointer back to
the interpreter that is executing the regexp. So under threading all
routines get an extra argument.
@@ -58,12 +76,12 @@
Compile the pattern stored in C<pattern> using the given C<flags> and
return a pointer to a prepared C<REGEXP> structure that can perform
-the match. See L</The REGEXP structure> below for an explanation of
+the match. See L</The REGEXP structure> below for an explanation of
the individual fields in the REGEXP struct.
The C<pattern> parameter is the scalar that was used as the
-pattern. previous versions of perl would pass two C<char*> indicating
-the start and end of the stringified pattern, the following snippet can
+pattern. Previous versions of Perl would pass two C<char*> indicating
+the start and end of the stringified pattern; the following snippet can
be used to get the old parameters:
STRLEN plen;
@@ -70,31 +88,31 @@
char* exp = SvPV(pattern, plen);
char* xend = exp + plen;
-Since any scalar can be passed as a pattern it's possible to implement
+Since any scalar can be passed as a pattern, it's possible to implement
an engine that does something with an array (C<< "ook" =~ [ qw/ eek
hlagh / ] >>) or with the non-stringified form of a compiled regular
-expression (C<< "ook" =~ qr/eek/ >>). perl's own engine will always
-stringify everything using the snippet above but that doesn't mean
+expression (C<< "ook" =~ qr/eek/ >>). Perl's own engine will always
+stringify everything using the snippet above, but that doesn't mean
other engines have to.
The C<flags> parameter is a bitfield which indicates which of the
-C<msixp> flags the regex was compiled with. It also contains
-additional info such as whether C<use locale> is in effect.
+C<msixp> flags the regex was compiled with. It also contains
+additional info, such as if C<use locale> is in effect.
The C<eogc> flags are stripped out before being passed to the comp
-routine. The regex engine does not need to know whether any of these
-are set as those flags should only affect what perl does with the
+routine. The regex engine does not need to know if any of these
+are set, as those flags should only affect what Perl does with the
pattern and its match variables, not how it gets compiled and
executed.
By the time the comp callback is called, some of these flags have
-already had effect (noted below where applicable). However most of
-their effect occurs after the comp callback has run in routines that
+already had effect (noted below where applicable). However most of
+their effect occurs after the comp callback has run, in routines that
read the C<< rx->extflags >> field which it populates.
In general the flags should be preserved in C<< rx->extflags >> after
compilation, although the regex engine might want to add or delete
-some of them to invoke or disable some special behavior in perl. The
+some of them to invoke or disable some special behavior in Perl. The
flags along with any special behavior they cause are documented below:
The pattern modifiers:
@@ -113,7 +131,7 @@
=item C</x> - RXf_PMf_EXTENDED
-If present on a regex C<#> comments will be handled differently by the
+If present on a regex, C<"#"> comments will be handled differently by the
tokenizer in some cases.
TODO: Document those cases.
@@ -120,6 +138,8 @@
=item C</p> - RXf_PMf_KEEPCOPY
+TODO: Document this
+
=item Character set
The character set semantics are determined by an enum that is contained
@@ -127,11 +147,11 @@
the current interface returns the rules by use of the in-line function
C<get_regex_charset(const U32 flags)>. The only currently documented
value returned from it is REGEX_LOCALE_CHARSET, which is set if
-C<use locale> is in effect. If present in C<< rx->extflags >>
-C<split> will use the locale dependent definition of whitespace under
-when RXf_SKIPWHITE or RXf_WHITE are in effect. Under ASCII whitespace
+C<use locale> is in effect. If present in C<< rx->extflags >>,
+C<split> will use the locale dependent definition of whitespace
+when RXf_SKIPWHITE or RXf_WHITE is in effect. ASCII whitespace
is defined as per L<isSPACE|perlapi/isSPACE>, and by the internal
-macros C<is_utf8_space> under UTF-8 and C<isSPACE_LC> under C<use
+macros C<is_utf8_space> under UTF-8, and C<isSPACE_LC> under C<use
locale>.
=back
@@ -140,21 +160,16 @@
=over 4
-=item RXf_UTF8
+=item RXf_SPLIT
-Set if the pattern is L<SvUTF8()|perlapi/SvUTF8>, set by Perl_pmruntime.
+This flag was removed in perl 5.18.0. C<split ' '> is now special-cased
+solely in the parser. RXf_SPLIT is still #defined, so you can test for it.
+This is how it used to work:
-A regex engine may want to set or disable this flag during
-compilation. The perl engine for instance may upgrade non-UTF-8
-strings to UTF-8 if the pattern includes constructs such as C<\x{...}>
-that can only match Unicode values.
-
-=item RXf_SPLIT
-
If C<split> is invoked as C<split ' '> or with no arguments (which
-really means C<split(' ', $_)>, see L<split|perlfunc/split>), perl will
-set this flag. The regex engine can then check for it and set the
-SKIPWHITE and WHITE extflags. To do this the perl engine does:
+really means C<split(' ', $_)>, see L<split|perlfunc/split>), Perl will
+set this flag. The regex engine can then check for it and set the
+SKIPWHITE and WHITE extflags. To do this, the Perl engine does:
if (flags & RXf_SPLIT && r->prelen == 1 && r->precomp[0] == ' ')
r->extflags |= (RXf_SKIPWHITE|RXf_WHITE);
@@ -168,13 +183,16 @@
=item RXf_SKIPWHITE
+This flag was removed in perl 5.18.0. It is still #defined, so you can
+set it, but doing so will have no effect. This is how it used to work:
+
If the flag is present in C<< rx->extflags >> C<split> will delete
whitespace from the start of the subject string before it's operated
-on. What is considered whitespace depends on whether the subject is a
-UTF-8 string and whether the C<RXf_PMf_LOCALE> flag is set.
+on. What is considered whitespace depends on if the subject is a
+UTF-8 string and if the C<RXf_PMf_LOCALE> flag is set.
-If RXf_WHITE is set in addition to this flag C<split> will behave like
-C<split " "> under the perl engine.
+If RXf_WHITE is set in addition to this flag, C<split> will behave like
+C<split " "> under the Perl engine.
=item RXf_START_ONLY
@@ -182,7 +200,7 @@
(C<\n>) without invoking the regex engine.
Perl's engine sets this if the pattern is C</^/> (C<plen == 1 && *exp
-== '^'>), even under C</^/s>, see L<split|perlfunc>. Of course a
+== '^'>), even under C</^/s>; see L<split|perlfunc>. Of course a
different regex engine might want to use the same optimizations
with a different syntax.
@@ -189,9 +207,9 @@
=item RXf_WHITE
Tells the split operator to split the target string on whitespace
-without invoking the regex engine. The definition of whitespace varies
-depending on whether the target string is a UTF-8 string and on
-whether RXf_PMf_LOCALE is set.
+without invoking the regex engine. The definition of whitespace varies
+depending on if the target string is a UTF-8 string and on
+if RXf_PMf_LOCALE is set.
Perl's engine sets this flag if the pattern is C<\s+>.
@@ -198,13 +216,21 @@
=item RXf_NULL
Tells the split operator to split the target string on
-characters. The definition of character varies depending on whether
+characters. The definition of character varies depending on if
the target string is a UTF-8 string.
Perl's engine sets this flag on empty patterns, this optimization
-makes C<split //> much faster than it would otherwise be. It's even
+makes C<split //> much faster than it would otherwise be. It's even
faster than C<unpack>.
+=item RXf_NO_INPLACE_SUBST
+
+Added in perl 5.18.0, this flag indicates that a regular expression might
+perform an operation that would interfere with inplace substituion. For
+instance it might contain lookbehind, or assign to non-magical variables
+(such as $REGMARK and $REGERROR) during matching. C<s///> will skip
+certain optimisations when this is set.
+
=back
=head2 exec
@@ -214,8 +240,50 @@
I32 minend, SV* screamer,
void* data, U32 flags);
-Execute a regexp.
+Execute a regexp. The arguments are
+=over 4
+
+=item rx
+
+The regular expression to execute.
+
+=item screamer
+
+This strangely-named arg is the SV to be matched against. Note that the
+actual char array to be matched against is supplied by the arguments
+described below; the SV is just used to determine UTF8ness, C<pos()> etc.
+
+=item strbeg
+
+Pointer to the physical start of the string.
+
+=item strend
+
+Pointer to the character following the physical end of the string (i.e.
+the C<\0>).
+
+=item stringarg
+
+Pointer to the position in the string where matching should start; it might
+not be equal to C<strbeg> (for example in a later iteration of C</.../g>).
+
+=item minend
+
+Minimum length of string (measured in bytes from C<stringarg>) that must
+match; if the engine reaches the end of the match but hasn't reached this
+position in the string, it should fail.
+
+=item data
+
+Optimisation data; subject to change.
+
+=item flags
+
+Optimisation flags; subject to change.
+
+=back
+
=head2 intuit
char* intuit(pTHX_ REGEXP * const rx,
@@ -223,9 +291,9 @@
const U32 flags, struct re_scream_pos_data_s *data);
Find the start position where a regex match should be attempted,
-or possibly whether the regex engine should not be run because the
-pattern can't match. This is called as appropriate by the core
-depending on the values of the extflags member of the regexp
+or possibly if the regex engine should not be run because the
+pattern can't match. This is called, as appropriate, by the core,
+depending on the values of the C<extflags> member of the C<regexp>
structure.
=head2 checkstr
@@ -239,10 +307,10 @@
void free(pTHX_ REGEXP * const rx);
-Called by perl when it is freeing a regexp pattern so that the engine
+Called by Perl when it is freeing a regexp pattern so that the engine
can release any resources pointed to by the C<pprivate> member of the
-regexp structure. This is only responsible for freeing private data;
-perl will handle releasing anything else contained in the regexp structure.
+C<regexp> structure. This is only responsible for freeing private data;
+Perl will handle releasing anything else contained in the C<regexp> structure.
=head2 Numbered capture callbacks
@@ -250,11 +318,22 @@
equivalents, ${^PREMATCH}, ${^POSTMATCH} and $^{MATCH}, as well as the
numbered capture groups (C<$1>, C<$2>, ...).
-The C<paren> parameter will be C<-2> for C<$`>, C<-1> for C<$'>, C<0>
-for C<$&>, C<1> for C<$1> and so forth.
+The C<paren> parameter will be C<1> for C<$1>, C<2> for C<$2> and so
+forth, and have these symbolic values for the special variables:
+ ${^PREMATCH} RX_BUFF_IDX_CARET_PREMATCH
+ ${^POSTMATCH} RX_BUFF_IDX_CARET_POSTMATCH
+ ${^MATCH} RX_BUFF_IDX_CARET_FULLMATCH
+ $` RX_BUFF_IDX_PREMATCH
+ $' RX_BUFF_IDX_POSTMATCH
+ $& RX_BUFF_IDX_FULLMATCH
+
+Note that in Perl 5.17.3 and earlier, the last three constants were also
+used for the caret variants of the variables.
+
+
The names have been chosen by analogy with L<Tie::Scalar> methods
-names with an additional B<LENGTH> callback for efficiency. However
+names with an additional B<LENGTH> callback for efficiency. However
named capture variables are currently not tied internally but
implemented via magic.
@@ -263,31 +342,33 @@
void numbered_buff_FETCH(pTHX_ REGEXP * const rx, const I32 paren,
SV * const sv);
-Fetch a specified numbered capture. C<sv> should be set to the scalar
+Fetch a specified numbered capture. C<sv> should be set to the scalar
to return, the scalar is passed as an argument rather than being
-returned from the function because when it's called perl already has a
+returned from the function because when it's called Perl already has a
scalar to store the value, creating another one would be
-redundant. The scalar can be set with C<sv_setsv>, C<sv_setpvn> and
+redundant. The scalar can be set with C<sv_setsv>, C<sv_setpvn> and
friends, see L<perlapi>.
-This callback is where perl untaints its own capture variables under
-taint mode (see L<perlsec>). See the C<Perl_reg_numbered_buff_fetch>
+This callback is where Perl untaints its own capture variables under
+taint mode (see L<perlsec>). See the C<Perl_reg_numbered_buff_fetch>
function in F<regcomp.c> for how to untaint capture variables if
that's something you'd like your engine to do as well.
=head3 numbered_buff_STORE
- void (*numbered_buff_STORE) (pTHX_ REGEXP * const rx, const I32 paren,
+ void (*numbered_buff_STORE) (pTHX_
+ REGEXP * const rx,
+ const I32 paren,
SV const * const value);
-Set the value of a numbered capture variable. C<value> is the scalar
-that is to be used as the new value. It's up to the engine to make
+Set the value of a numbered capture variable. C<value> is the scalar
+that is to be used as the new value. It's up to the engine to make
sure this is used as the new value (or reject it).
Example:
if ("ook" =~ /(o*)/) {
- # `paren' will be `1' and `value' will be `ee'
+ # 'paren' will be '1' and 'value' will be 'ee'
$1 =~ tr/o/e/;
}
@@ -296,8 +377,10 @@
(copied from C<Perl_reg_numbered_buff_store>):
void
- Example_reg_numbered_buff_store(pTHX_ REGEXP * const rx, const I32 paren,
- SV const * const value)
+ Example_reg_numbered_buff_store(pTHX_
+ REGEXP * const rx,
+ const I32 paren,
+ SV const * const value)
{
PERL_UNUSED_ARG(rx);
PERL_UNUSED_ARG(paren);
@@ -307,10 +390,10 @@
Perl_croak(aTHX_ PL_no_modify);
}
-Actually perl will not I<always> croak in a statement that looks
-like it would modify a numbered capture variable. This is because the
-STORE callback will not be called if perl can determine that it
-doesn't have to modify the value. This is exactly how tied variables
+Actually Perl will not I<always> croak in a statement that looks
+like it would modify a numbered capture variable. This is because the
+STORE callback will not be called if Perl can determine that it
+doesn't have to modify the value. This is exactly how tied variables
behave in the same situation:
package CaptureVar;
@@ -325,21 +408,23 @@
tie my $sv => "CaptureVar";
$sv =~ y/a/b/;
-Because C<$sv> is C<undef> when the C<y///> operator is applied to it
+Because C<$sv> is C<undef> when the C<y///> operator is applied to it,
the transliteration won't actually execute and the program won't
-C<die>. This is different to how 5.8 and earlier versions behaved
-since the capture variables were READONLY variables then, now they'll
+C<die>. This is different to how 5.8 and earlier versions behaved
+since the capture variables were READONLY variables then; now they'll
just die when assigned to in the default engine.
=head3 numbered_buff_LENGTH
- I32 numbered_buff_LENGTH (pTHX_ REGEXP * const rx, const SV * const sv,
+ I32 numbered_buff_LENGTH (pTHX_
+ REGEXP * const rx,
+ const SV * const sv,
const I32 paren);
-Get the C<length> of a capture variable. There's a special callback
-for this so that perl doesn't have to do a FETCH and run C<length> on
-the result, since the length is (in perl's case) known from an offset
-stored in C<< rx->offs >> this is much more efficient:
+Get the C<length> of a capture variable. There's a special callback
+for this so that Perl doesn't have to do a FETCH and run C<length> on
+the result, since the length is (in Perl's case) known from an offset
+stored in C<< rx->offs >>, this is much more efficient:
I32 s1 = rx->offs[paren].start;
I32 s2 = rx->offs[paren].end;
@@ -351,7 +436,7 @@
=head2 Named capture callbacks
-Called to get/set the value of C<%+> and C<%-> as well as by some
+Called to get/set the value of C<%+> and C<%->, as well as by some
utility functions in L<re>.
There are two callbacks, C<named_buff> is called in all the cases the
@@ -360,7 +445,7 @@
same cases as FIRSTKEY and NEXTKEY.
The C<flags> parameter can be used to determine which of these
-operations the callbacks should respond to, the following flags are
+operations the callbacks should respond to. The following flags are
currently defined:
Which L<Tie::Hash> operation is being performed from the Perl level on
@@ -375,13 +460,13 @@
RXapif_FIRSTKEY
RXapif_NEXTKEY
-Whether C<%+> or C<%-> is being operated on, if any.
+If C<%+> or C<%-> is being operated on, if any.
RXapif_ONE /* %+ */
RXapif_ALL /* %- */
-Whether this is being called as C<re::regname>, C<re::regnames> or
-C<re::regnames_count>, if any. The first two will be combined with
+If this is being called as C<re::regname>, C<re::regnames> or
+C<re::regnames_count>, if any. The first two will be combined with
C<RXapif_ONE> or C<RXapif_ALL>.
RXapif_REGNAME
@@ -389,10 +474,10 @@
RXapif_REGNAMES_COUNT
Internally C<%+> and C<%-> are implemented with a real tied interface
-via L<Tie::Hash::NamedCapture>. The methods in that package will call
-back into these functions. However the usage of
+via L<Tie::Hash::NamedCapture>. The methods in that package will call
+back into these functions. However the usage of
L<Tie::Hash::NamedCapture> for this purpose might change in future
-releases. For instance this might be implemented by magic instead
+releases. For instance this might be implemented by magic instead
(would need an extension to mgvtbl).
=head3 named_buff
@@ -402,7 +487,9 @@
=head3 named_buff_iter
- SV* (*named_buff_iter) (pTHX_ REGEXP * const rx, const SV * const lastkey,
+ SV* (*named_buff_iter) (pTHX_
+ REGEXP * const rx,
+ const SV * const lastkey,
const U32 flags);
=head2 qr_package
@@ -410,12 +497,12 @@
SV* qr_package(pTHX_ REGEXP * const rx);
The package the qr// magic object is blessed into (as seen by C<ref
-qr//>). It is recommended that engines change this to their package
-name for identification regardless of whether they implement methods
+qr//>). It is recommended that engines change this to their package
+name for identification regardless of if they implement methods
on the object.
The package this method returns should also have the internal
-C<Regexp> package in its C<@ISA>. C<< qr//->isa("Regexp") >> should always
+C<Regexp> package in its C<@ISA>. C<< qr//->isa("Regexp") >> should always
be true regardless of what engine is being used.
Example implementation might be:
@@ -447,12 +534,12 @@
void* dupe(pTHX_ REGEXP * const rx, CLONE_PARAMS *param);
On threaded builds a regexp may need to be duplicated so that the pattern
-can be used by multiple threads. This routine is expected to handle the
+can be used by multiple threads. This routine is expected to handle the
duplication of any private data pointed to by the C<pprivate> member of
-the regexp structure. It will be called with the preconstructed new
-regexp structure as an argument, the C<pprivate> member will point at
+the C<regexp> structure. It will be called with the preconstructed new
+C<regexp> structure as an argument, the C<pprivate> member will point at
the B<old> private structure, and it is this routine's responsibility to
-construct a copy and return a pointer to it (which perl will then use to
+construct a copy and return a pointer to it (which Perl will then use to
overwrite the field as passed to this routine.)
This allows the engine to dupe its private data but also if necessary
@@ -460,24 +547,30 @@
On unthreaded builds this field doesn't exist.
+=head2 op_comp
+
+This is private to the Perl core and subject to change. Should be left
+null.
+
=head1 The REGEXP structure
-The REGEXP struct is defined in F<regexp.h>. All regex engines must be able to
+The REGEXP struct is defined in F<regexp.h>.
+All regex engines must be able to
correctly build such a structure in their L</comp> routine.
-The REGEXP structure contains all the data that perl needs to be aware of
-to properly work with the regular expression. It includes data about
-optimisations that perl can use to determine if the regex engine should
+The REGEXP structure contains all the data that Perl needs to be aware of
+to properly work with the regular expression. It includes data about
+optimisations that Perl can use to determine if the regex engine should
really be used, and various other control info that is needed to properly
-execute patterns in various contexts such as is the pattern anchored in
-some way, or what flags were used during the compile, or whether the
-program contains special constructs that perl needs to be aware of.
+execute patterns in various contexts, such as if the pattern anchored in
+some way, or what flags were used during the compile, or if the
+program contains special constructs that Perl needs to be aware of.
In addition it contains two fields that are intended for the private
-use of the regex engine that compiled the pattern. These are the
-C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
-an arbitrary structure whose use and management is the responsibility
-of the compiling engine. perl will never modify either of these
+use of the regex engine that compiled the pattern. These are the
+C<intflags> and C<pprivate> members. C<pprivate> is a void pointer to
+an arbitrary structure, whose use and management is the responsibility
+of the compiling engine. Perl will never modify either of these
values.
typedef struct regexp {
@@ -487,10 +580,12 @@
/* what re is this a lightweight copy of? */
struct regexp* mother_re;
- /* Information about the match that the perl core uses to manage things */
+ /* Information about the match that the Perl core uses to manage
+ * things */
U32 extflags; /* Flags used both externally and internally */
- I32 minlen; /* mininum possible length of string to match */
- I32 minlenret; /* mininum possible length of $& */
+ I32 minlen; /* mininum possible number of chars in */
+ string to match */
+ I32 minlenret; /* mininum possible number of chars in $& */
U32 gofs; /* chars left of pos that we search from */
/* substring data about strings that must appear
@@ -504,15 +599,21 @@
void *pprivate; /* Data private to the regex engine which
created this object. */
- /* Data about the last/current match. These are modified during matching*/
- U32 lastparen; /* last open paren matched */
- U32 lastcloseparen; /* last close paren matched */
+ /* Data about the last/current match. These are modified during
+ * matching*/
+ U32 lastparen; /* highest close paren matched ($+) */
+ U32 lastcloseparen; /* last close paren matched ($^N) */
regexp_paren_pair *swap; /* Swap copy of *offs */
- regexp_paren_pair *offs; /* Array of offsets for (@-) and (@+) */
+ regexp_paren_pair *offs; /* Array of offsets for (@-) and
+ (@+) */
- char *subbeg; /* saved or original string so \digit works forever. */
+ char *subbeg; /* saved or original string so \digit works
+ forever. */
SV_SAVED_COPY /* If non-NULL, SV which is COW from original */
I32 sublen; /* Length of string pointed by subbeg */
+ I32 suboffset; /* byte offset of subbeg from logical start of
+ str */
+ I32 subcoffset; /* suboffset equiv, but in chars (for @-/@+) */
/* Information about the match that isn't often used */
I32 prelen; /* length of precomp */
@@ -521,7 +622,8 @@
char *wrapped; /* wrapped version of the pattern */
I32 wraplen; /* length of wrapped */
- I32 seen_evals; /* number of eval groups in the pattern - for security checks */
+ I32 seen_evals; /* number of eval groups in the pattern - for
+ security checks */
HV *paren_names; /* Optional hash of paren names */
/* Refcount of this regexp */
@@ -532,13 +634,13 @@
=head2 C<engine>
-This field points at a regexp_engine structure which contains pointers
-to the subroutines that are to be used for performing a match. It
+This field points at a C<regexp_engine> structure which contains pointers
+to the subroutines that are to be used for performing a match. It
is the compiling routine's responsibility to populate this field before
returning the regexp object.
Internally this is set to C<NULL> unless a custom engine is specified in
-C<$^H{regcomp}>, perl's own set of callbacks can be accessed in the struct
+C<$^H{regcomp}>, Perl's own set of callbacks can be accessed in the struct
pointed to by C<RE_ENGINE_PTR>.
=head2 C<mother_re>
@@ -547,21 +649,22 @@
=head2 C<extflags>
-This will be used by perl to see what flags the regexp was compiled
+This will be used by Perl to see what flags the regexp was compiled
with, this will normally be set to the value of the flags parameter by
-the L<comp|/comp> callback. See the L<comp|/comp> documentation for
+the L<comp|/comp> callback. See the L<comp|/comp> documentation for
valid flags.
=head2 C<minlen> C<minlenret>
-The minimum string length required for the pattern to match. This is used to
+The minimum string length (in characters) required for the pattern to match.
+This is used to
prune the search space by not bothering to match any closer to the end of a
-string than would allow a match. For instance there is no point in even
+string than would allow a match. For instance there is no point in even
starting the regex engine if the minlen is 10 but the string is only 5
-characters long. There is no way that the pattern can match.
+characters long. There is no way that the pattern can match.
-C<minlenret> is the minimum length of the string that would be found
-in $& after a match.
+C<minlenret> is the minimum length (in characters) of the string that would
+be found in $& after a match.
The difference between C<minlen> and C<minlenret> can be seen in the
following pattern:
@@ -569,10 +672,11 @@
/ns(?=\d)/
where the C<minlen> would be 3 but C<minlenret> would only be 2 as the \d is
-required to match but is not actually included in the matched content. This
+required to match but is not actually
+included in the matched content. This
distinction is particularly important as the substitution logic uses the
-C<minlenret> to tell whether it can do in-place substitution which can result in
-considerable speedup.
+C<minlenret> to tell if it can do in-place substitutions (these can
+result in considerable speed-up).
=head2 C<gofs>
@@ -580,11 +684,11 @@
=head2 C<substrs>
-Substring data about strings that must appear in the final match. This
-is currently only used internally by perl's engine for but might be
+Substring data about strings that must appear in the final match. This
+is currently only used internally by Perl's engine, but might be
used in the future for all engines for optimisations.
-=head2 C<nparens>, C<lasparen>, and C<lastcloseparen>
+=head2 C<nparens>, C<lastparen>, and C<lastcloseparen>
These fields are used to keep track of how many paren groups could be matched
in the pattern, which was the last open paren to be entered, and which was
@@ -597,13 +701,14 @@
=head2 C<pprivate>
-A void* pointing to an engine-defined data structure. The perl engine uses the
+A void* pointing to an engine-defined
+data structure. The Perl engine uses the
C<regexp_internal> structure (see L<perlreguts/Base Structures>) but a custom
engine should use something else.
=head2 C<swap>
-Unused. Left in for compatibility with perl 5.10.0.
+Unused. Left in for compatibility with Perl 5.10.0.
=head2 C<offs>
@@ -617,16 +722,17 @@
} regexp_paren_pair;
If C<< ->offs[num].start >> or C<< ->offs[num].end >> is C<-1> then that
-capture group did not match. C<< ->offs[0].start/end >> represents C<$&> (or
-C<${^MATCH> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
+capture group did not match.
+C<< ->offs[0].start/end >> represents C<$&> (or
+C<${^MATCH}> under C<//p>) and C<< ->offs[paren].end >> matches C<$$paren> where
C<$paren >= 1>.
=head2 C<precomp> C<prelen>
-Used for optimisations. C<precomp> holds a copy of the pattern that
-was compiled and C<prelen> its length. When a new pattern is to be
+Used for optimisations. C<precomp> holds a copy of the pattern that
+was compiled and C<prelen> its length. When a new pattern is to be
compiled (such as inside a loop) the internal C<regcomp> operator
-checks whether the last compiled C<REGEXP>'s C<precomp> and C<prelen>
+checks if the last compiled C<REGEXP>'s C<precomp> and C<prelen>
are equivalent to the new one, and if so uses the old pattern instead
of compiling a new one.
@@ -639,7 +745,7 @@
=head2 C<paren_names>
This is a hash used internally to track named capture groups and their
-offsets. The keys are the names of the buffers the values are dualvars,
+offsets. The keys are the names of the buffers the values are dualvars,
with the IV slot holding the number of buffers with the given name and the
pv being an embedded array of I32. The values may also be contained
independently in the data array in cases where named backreferences are
@@ -649,17 +755,31 @@
Holds information on the longest string that must occur at a fixed
offset from the start of the pattern, and the longest string that must
-occur at a floating offset from the start of the pattern. Used to do
+occur at a floating offset from the start of the pattern. Used to do
Fast-Boyer-Moore searches on the string to find out if its worth using
the regex engine at all, and if so where in the string to search.
-=head2 C<subbeg> C<sublen> C<saved_copy>
+=head2 C<subbeg> C<sublen> C<saved_copy> C<suboffset> C<subcoffset>
-Used during execution phase for managing search and replace patterns.
+Used during the execution phase for managing search and replace patterns,
+and for providing the text for C<$&>, C<$1> etc. C<subbeg> points to a
+buffer (either the original string, or a copy in the case of
+C<RX_MATCH_COPIED(rx)>), and C<sublen> is the length of the buffer. The
+C<RX_OFFS> start and end indices index into this buffer.
+In the presence of the C<REXEC_COPY_STR> flag, but with the addition of
+the C<REXEC_COPY_SKIP_PRE> or C<REXEC_COPY_SKIP_POST> flags, an engine
+can choose not to copy the full buffer (although it must still do so in
+the presence of C<RXf_PMf_KEEPCOPY> or the relevant bits being set in
+C<PL_sawampersand>). In this case, it may set C<suboffset> to indicate the
+number of bytes from the logical start of the buffer to the physical start
+(i.e. C<subbeg>). It should also set C<subcoffset>, the number of
+characters in the offset. The latter is needed to support C<@-> and C<@+>
+which work in characters, not bytes.
+
=head2 C<wrapped> C<wraplen>
-Stores the string C<qr//> stringifies to. The perl engine for example
+Stores the string C<qr//> stringifies to. The Perl engine for example
stores C<(?^:eek)> in the case of C<qr/eek/>.
When using a custom engine that doesn't support the C<(?:)> construct
@@ -676,13 +796,15 @@
=head2 C<seen_evals>
-This stores the number of eval groups in the pattern. This is used for security
+This stores the number of eval groups in
+the pattern. This is used for security
purposes when embedding compiled regexes into larger patterns with C<qr//>.
=head2 C<refcnt>
-The number of times the structure is referenced. When this falls to 0 the
-regexp is automatically freed by a call to pregfree. This should be set to 1 in
+The number of times the structure is referenced. When
+this falls to 0, the regexp is automatically freed
+by a call to pregfree. This should be set to 1 in
each engine's L</comp> routine.
=head1 HISTORY
Property changes on: trunk/contrib/perl/pod/perlreapi.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlrebackslash.pod
===================================================================
--- trunk/contrib/perl/pod/perlrebackslash.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlrebackslash.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -68,7 +68,7 @@
\A Beginning of string. Not in [].
\b Word/non-word boundary. (Backspace in []).
\B Not a word/non-word boundary. Not in [].
- \cX Control-X
+ \cX Control-X.
\C Single octet, even under UTF-8. Not in [].
\d Character class for digits.
\D Character class for non-digits.
@@ -75,7 +75,9 @@
\e Escape character.
\E Turn off \Q, \L and \U processing. Not in [].
\f Form feed.
- \g{}, \g1 Named, absolute or relative backreference. Not in []
+ \F Foldcase till \E. Not in [].
+ \g{}, \g1 Named, absolute or relative backreference.
+ Not in [].
\G Pos assertion. Not in [].
\h Character class for horizontal whitespace.
\H Character class for non horizontal whitespace.
@@ -84,12 +86,13 @@
\l Lowercase next character. Not in [].
\L Lowercase till \E. Not in [].
\n (Logical) newline character.
- \N Any character but newline. Experimental. Not in [].
+ \N Any character but newline. Not in [].
\N{} Named or numbered (Unicode) character or sequence.
\o{} Octal escape sequence.
\p{}, \pP Character with the given Unicode property.
\P{}, \PP Character without the given Unicode property.
- \Q Quotemeta till \E. Not in [].
+ \Q Quote (disable) pattern metacharacters till \E. Not
+ in [].
\r Return character.
\R Generic new line. Not in [].
\s Character class for whitespace.
@@ -173,8 +176,7 @@
Certain sequences of characters also have names.
To specify by name, the name of the character or character sequence goes
-between the curly braces. In this case, you have to C<use charnames> to
-load the Unicode names of the characters; otherwise Perl will complain.
+between the curly braces.
To specify a character by Unicode code point, use the form C<\N{U+I<code
point>}>, where I<code point> is a number in hexadecimal that gives the
@@ -201,7 +203,6 @@
=head4 Example
- use charnames ':full'; # Loads the Unicode names.
$str =~ /\N{THAI CHARACTER SO SO}/; # Matches the Thai SO SO character
use charnames 'Cyrillic'; # Loads Cyrillic names.
@@ -246,16 +247,17 @@
$str = "Perl";
$str =~ /\o{120}/; # Match, "\120" is "P".
$str =~ /\120/; # Same.
- $str =~ /\o{120}+/; # Match, "\120" is "P", it's repeated at least once
+ $str =~ /\o{120}+/; # Match, "\120" is "P",
+ # it's repeated at least once.
$str =~ /\120+/; # Same.
$str =~ /P\053/; # No match, "\053" is "+" and taken literally.
/\o{23073}/ # Black foreground, white background smiling face.
- /\o{4801234567}/ # Raises a warning, and yields chr(4)
+ /\o{4801234567}/ # Raises a warning, and yields chr(4).
=head4 Disambiguation rules between old-style octal escapes and backreferences
Octal escapes of the C<\000> form outside of bracketed character classes
-potentially clash with old-style backreferences. (see L</Absolute referencing>
+potentially clash with old-style backreferences (see L</Absolute referencing>
below). They both consist of a backslash followed by numbers. So Perl has to
use heuristics to determine whether it is a backreference or an octal escape.
Perl uses the following rules to disambiguate:
@@ -282,7 +284,7 @@
$pat .= ")" x 999;
/^($pat)\1000$/; # Matches 'aa'; there are 1000 capture groups.
/^$pat\1000$/; # Matches 'a at 0'; there are 999 capture groups
- # and \1000 is seen as \100 (a '@') and a '0'
+ # and \1000 is seen as \100 (a '@') and a '0'.
=back
@@ -332,14 +334,21 @@
C<\E>, whichever comes first. They provide functionality similar to what
the functions C<lc> and C<uc> provide.
-C<\Q> is used to escape all characters following, up to the next C<\E>
-or the end of the pattern. C<\Q> adds a backslash to any character that
-isn't a letter, digit, or underscore. This ensures that any character
-between C<\Q> and C<\E> shall be matched literally, not interpreted
-as a metacharacter by the regex engine.
+C<\Q> is used to quote (disable) pattern metacharacters, up to the next
+C<\E> or the end of the pattern. C<\Q> adds a backslash to any character
+that could have special meaning to Perl. In the ASCII range, it quotes
+every character that isn't a letter, digit, or underscore. See
+L<perlfunc/quotemeta> for details on what gets quoted for non-ASCII
+code points. Using this ensures that any character between C<\Q> and
+C<\E> will be matched literally, not interpreted as a metacharacter by
+the regex engine.
-Mnemonic: I<L>owercase, I<U>ppercase, I<Q>uotemeta, I<E>nd.
+C<\F> can be used to casefold all characters following, up to the next C<\E>
+or the end of the pattern. It provides the functionality similar to
+the C<fc> function.
+Mnemonic: I<L>owercase, I<U>ppercase, I<F>old-case, I<Q>uotemeta, I<E>nd.
+
=head4 Examples
$sid = "sid";
@@ -423,7 +432,7 @@
=head4 Examples
/(\w+) \g1/; # Finds a duplicated word, (e.g. "cat cat").
- /(\w+) \1/; # Same thing; written old-style
+ /(\w+) \1/; # Same thing; written old-style.
/(.)(.)\g2\g1/; # Match a four letter palindrome (e.g. "ABBA").
@@ -568,7 +577,7 @@
C<\C> always matches a single octet, even if the source string is encoded
in UTF-8 format, and the character to be matched is a multi-octet character.
-C<\C> was introduced in perl 5.6. This is very dangerous, because it violates
+This is very dangerous, because it violates
the logical character abstraction and can cause UTF-8 sequences to become malformed.
Mnemonic: oI<C>tet.
@@ -584,7 +593,7 @@
=item \N
-This is an experimental feature new to perl 5.12.0. It matches any character
+This feature, available starting in v5.12, matches any character
that is B<not> a newline. It is a short-hand for writing C<[^\n]>, and is
identical to the C<.> metasymbol, except under the C</s> flag, which changes
the meaning of C<.>, but not C<\N>.
@@ -603,11 +612,21 @@
C<\v> (vertical whitespace), and the multi character sequence C<"\x0D\x0A">
(carriage return followed by a line feed, sometimes called the network
newline; it's the end of line sequence used in Microsoft text files opened
-in binary mode). C<\R> is equivalent to C<< (?>\x0D\x0A)|\v) >>. Since
+in binary mode). C<\R> is equivalent to C<< (?>\x0D\x0A|\v) >>. (The
+reason it doesn't backtrack is that the sequence is considered
+inseparable. That means that
+
+ "\x0D\x0A" =~ /^\R\x0A$/ # No match
+
+fails, because the C<\R> matches the entire string, and won't backtrack
+to match just the C<"\x0D">.) Since
C<\R> can match a sequence of more than one character, it cannot be put
inside a bracketed character class; C</[\R]/> is an error; use C<\v>
instead. C<\R> was introduced in perl 5.10.0.
+Note that this does not respect any locale that might be in effect; it
+matches according to the platform's native character set.
+
Mnemonic: none really. C<\R> was picked because PCRE already uses C<\R>,
and more importantly because Unicode recommends such a regular expression
metacharacter, and suggests C<\R> as its notation.
@@ -630,7 +649,8 @@
=head4 Examples
- "\x{256}" =~ /^\C\C$/; # Match as chr (0x256) takes 2 octets in UTF-8.
+ "\x{256}" =~ /^\C\C$/; # Match as chr (0x256) takes
+ # 2 octets in UTF-8.
$str =~ s/foo\Kbar/baz/g; # Change any 'bar' following a 'foo' to 'baz'
$str =~ s/(.)\K\g1//g; # Delete duplicated characters.
Property changes on: trunk/contrib/perl/pod/perlrebackslash.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlrecharclass.pod
===================================================================
--- trunk/contrib/perl/pod/perlrecharclass.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlrecharclass.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -26,10 +26,10 @@
The dot (or period), C<.> is probably the most used, and certainly
the most well-known character class. By default, a dot matches any
-character, except for the newline. The default can be changed to
+character, except for the newline. That default can be changed to
add matching the newline by using the I<single line> modifier: either
for the entire regular expression with the C</s> modifier, or
-locally with C<(?s)>. (The experimental C<\N> backslash sequence, described
+locally with C<(?s)>. (The C<\N> backslash sequence, described
below, matches any character except newline without regard to the
I<single line> modifier.)
@@ -68,14 +68,29 @@
\H Match a character that isn't horizontal whitespace.
\v Match a vertical whitespace character.
\V Match a character that isn't vertical whitespace.
- \N Match a character that isn't a newline. Experimental.
+ \N Match a character that isn't a newline.
\pP, \p{Prop} Match a character that has the given Unicode property.
\PP, \P{Prop} Match a character that doesn't have the Unicode property
+=head3 \N
+
+C<\N>, available starting in v5.12, like the dot, matches any
+character that is not a newline. The difference is that C<\N> is not influenced
+by the I<single line> regular expression modifier (see L</The dot> above). Note
+that the form C<\N{...}> may mean something completely different. When the
+C<{...}> is a L<quantifier|perlre/Quantifiers>, it means to match a non-newline
+character that many times. For example, C<\N{3}> means to match 3
+non-newlines; C<\N{5,}> means to match 5 or more non-newlines. But if C<{...}>
+is not a legal quantifier, it is presumed to be a named character. See
+L<charnames> for those. For example, none of C<\N{COLON}>, C<\N{4F}>, and
+C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose
+names are respectively C<COLON>, C<4F>, and C<F4>.
+
=head3 Digits
C<\d> matches a single character considered to be a decimal I<digit>.
-If the C</a> modifier in effect, it matches [0-9]. Otherwise, it
+If the C</a> regular expression modifier is in effect, it matches [0-9].
+Otherwise, it
matches anything that is matched by C<\p{Digit}>, which includes [0-9].
(An unlikely possible exception is that under locale matching rules, the
current locale might not have [0-9] matched by C<\d>, and/or might match
@@ -94,7 +109,8 @@
is expecting only the ASCII digits might be misled, or if the match is
C<\d+>, the matched string might contain a mixture of digits from
different writing systems that look like they signify a number different
-than they actually do. L<Unicode::UCD/num()> can be used to safely
+than they actually do. L<Unicode::UCD/num()> can
+be used to safely
calculate the value, returning C<undef> if the input string contains
such a mixture.
@@ -114,7 +130,7 @@
to characters that match the other type of "digit",
C<\p{Numeric_Type=Digit}>, and so C<\d> doesn't match them.
-In Unicode 5.2, the Tamil digits (U+0BE6 - U+0BEF) can also legally be
+The Tamil digits (U+0BE6 - U+0BEF) can also legally be
used in old-style Tamil numbers in which they would appear no more than
one in a row, separated by characters that mean "times 10", "times 100",
etc. (See L<http://www.unicode.org/notes/tn21>.)
@@ -124,11 +140,12 @@
=head3 Word characters
A C<\w> matches a single alphanumeric character (an alphabetic character, or a
-decimal digit) or a connecting punctuation character, such as an
-underscore ("_"). It does not match a whole word. To match a whole
-word, use C<\w+>. This isn't the same thing as matching an English word, but
-in the ASCII range it is the same as a string of Perl-identifier
-characters.
+decimal digit); or a connecting punctuation character, such as an
+underscore ("_"); or a "mark" character (like some sort of accent) that
+attaches to one of those. It does not match a whole word. To match a
+whole word, use C<\w+>. This isn't the same thing as matching an
+English word, but in the ASCII range it is the same as a string of
+Perl-identifier characters.
=over
@@ -157,7 +174,7 @@
C<\w> matches the platform's native underscore character plus whatever
the locale considers to be alphanumeric.
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
+=item if Unicode rules are in effect ...
C<\w> matches exactly what C<\p{Word}> matches.
@@ -178,8 +195,9 @@
Also, for a somewhat finer-grained set of characters that are in programming
language identifiers beyond the ASCII range, you may wish to instead use the
-more customized Unicode properties, "ID_Start", ID_Continue", "XID_Start", and
-"XID_Continue". See L<http://unicode.org/reports/tr31>.
+more customized L</Unicode Properties>, C<\p{ID_Start}>,
+C<\p{ID_Continue}>, C<\p{XID_Start}>, and C<\p{XID_Continue}>. See
+L<http://unicode.org/reports/tr31>.
Any character not matched by C<\w> is matched by C<\W>.
@@ -191,9 +209,11 @@
=item If the C</a> modifier is in effect ...
-C<\s> matches the 5 characters [\t\n\f\r ]; that is, the horizontal tab,
-the newline, the form feed, the carriage return, and the space. (Note
-that it doesn't match the vertical tab, C<\cK> on ASCII platforms.)
+In all Perl versions, C<\s> matches the 5 characters [\t\n\f\r ]; that
+is, the horizontal tab,
+the newline, the form feed, the carriage return, and the space.
+Starting in Perl v5.18, experimentally, it also matches the vertical tab, C<\cK>.
+See note C<[1]> below for a discussion of this.
=item otherwise ...
@@ -210,11 +230,9 @@
=item if locale rules are in effect ...
-C<\s> matches whatever the locale considers to be whitespace. Note that
-this is likely to include the vertical space, unlike non-locale C<\s>
-matching.
+C<\s> matches whatever the locale considers to be whitespace.
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
+=item if Unicode rules are in effect ...
C<\s> matches exactly the characters shown with an "s" column in the
table below.
@@ -221,7 +239,9 @@
=item otherwise ...
-C<\s> matches [\t\n\f\r ].
+C<\s> matches [\t\n\f\r\cK ] and, starting, experimentally in Perl
+v5.18, the vertical tab, C<\cK>.
+(See note C<[1]> below for a discussion of this.)
Note that this list doesn't include the non-breaking space.
=back
@@ -235,68 +255,84 @@
Any character not matched by C<\s> is matched by C<\S>.
C<\h> matches any character considered horizontal whitespace;
-this includes the space and tab characters and several others
+this includes the platform's space and tab characters and several others
listed in the table below. C<\H> matches any character
-not considered horizontal whitespace.
+not considered horizontal whitespace. They use the platform's native
+character set, and do not consider any locale that may otherwise be in
+use.
C<\v> matches any character considered vertical whitespace;
-this includes the carriage return and line feed characters (newline)
+this includes the platform's carriage return and line feed characters (newline)
plus several other characters, all listed in the table below.
C<\V> matches any character not considered vertical whitespace.
+They use the platform's native character set, and do not consider any
+locale that may otherwise be in use.
C<\R> matches anything that can be considered a newline under Unicode
rules. It's not a character class, as it can match a multi-character
sequence. Therefore, it cannot be used inside a bracketed character
-class; use C<\v> instead (vertical whitespace).
+class; use C<\v> instead (vertical whitespace). It uses the platform's
+native character set, and does not consider any locale that may
+otherwise be in use.
Details are discussed in L<perlrebackslash>.
Note that unlike C<\s> (and C<\d> and C<\w>), C<\h> and C<\v> always match
-the same characters, without regard to other factors, such as whether the
-source string is in UTF-8 format.
+the same characters, without regard to other factors, such as the active
+locale or whether the source string is in UTF-8 format.
-One might think that C<\s> is equivalent to C<[\h\v]>. This is not true.
-For example, the vertical tab (C<"\x0b">) is not matched by C<\s>, it is
-however considered vertical whitespace.
+One might think that C<\s> is equivalent to C<[\h\v]>. This is indeed true
+starting in Perl v5.18, but prior to that, the sole difference was that the
+vertical tab (C<"\cK">) was not matched by C<\s>.
The following table is a complete listing of characters matched by
C<\s>, C<\h> and C<\v> as of Unicode 6.0.
-The first column gives the code point of the character (in hex format),
+The first column gives the Unicode code point of the character (in hex format),
the second column gives the (Unicode) name. The third column indicates
-by which class(es) the character is matched (assuming no locale or EBCDIC code
-page is in effect that changes the C<\s> matching).
+by which class(es) the character is matched (assuming no locale is in
+effect that changes the C<\s> matching).
- 0x00009 CHARACTER TABULATION h s
- 0x0000a LINE FEED (LF) vs
- 0x0000b LINE TABULATION v
- 0x0000c FORM FEED (FF) vs
- 0x0000d CARRIAGE RETURN (CR) vs
- 0x00020 SPACE h s
- 0x00085 NEXT LINE (NEL) vs [1]
- 0x000a0 NO-BREAK SPACE h s [1]
- 0x01680 OGHAM SPACE MARK h s
- 0x0180e MONGOLIAN VOWEL SEPARATOR h s
- 0x02000 EN QUAD h s
- 0x02001 EM QUAD h s
- 0x02002 EN SPACE h s
- 0x02003 EM SPACE h s
- 0x02004 THREE-PER-EM SPACE h s
- 0x02005 FOUR-PER-EM SPACE h s
- 0x02006 SIX-PER-EM SPACE h s
- 0x02007 FIGURE SPACE h s
- 0x02008 PUNCTUATION SPACE h s
- 0x02009 THIN SPACE h s
- 0x0200a HAIR SPACE h s
- 0x02028 LINE SEPARATOR vs
- 0x02029 PARAGRAPH SEPARATOR vs
- 0x0202f NARROW NO-BREAK SPACE h s
- 0x0205f MEDIUM MATHEMATICAL SPACE h s
- 0x03000 IDEOGRAPHIC SPACE h s
+ 0x0009 CHARACTER TABULATION h s
+ 0x000a LINE FEED (LF) vs
+ 0x000b LINE TABULATION vs [1]
+ 0x000c FORM FEED (FF) vs
+ 0x000d CARRIAGE RETURN (CR) vs
+ 0x0020 SPACE h s
+ 0x0085 NEXT LINE (NEL) vs [2]
+ 0x00a0 NO-BREAK SPACE h s [2]
+ 0x1680 OGHAM SPACE MARK h s
+ 0x180e MONGOLIAN VOWEL SEPARATOR h s
+ 0x2000 EN QUAD h s
+ 0x2001 EM QUAD h s
+ 0x2002 EN SPACE h s
+ 0x2003 EM SPACE h s
+ 0x2004 THREE-PER-EM SPACE h s
+ 0x2005 FOUR-PER-EM SPACE h s
+ 0x2006 SIX-PER-EM SPACE h s
+ 0x2007 FIGURE SPACE h s
+ 0x2008 PUNCTUATION SPACE h s
+ 0x2009 THIN SPACE h s
+ 0x200a HAIR SPACE h s
+ 0x2028 LINE SEPARATOR vs
+ 0x2029 PARAGRAPH SEPARATOR vs
+ 0x202f NARROW NO-BREAK SPACE h s
+ 0x205f MEDIUM MATHEMATICAL SPACE h s
+ 0x3000 IDEOGRAPHIC SPACE h s
=over 4
=item [1]
+Prior to Perl v5.18, C<\s> did not match the vertical tab. The change
+in v5.18 is considered an experiment, which means it could be backed out
+in v5.20 or v5.22 if experience indicates that it breaks too much
+existing code. If this change adversely affects you, send email to
+C<perlbug at perl.org>; if it affects you positively, email
+C<perlthanks at perl.org>. In the meantime, C<[^\S\cK]> (obscurely)
+matches what C<\s> traditionally did.
+
+=item [2]
+
NEXT LINE and NO-BREAK SPACE may or may not match C<\s> depending
on the rules in effect. See
L<the beginning of this section|/Whitespace>.
@@ -303,20 +339,6 @@
=back
-=head3 \N
-
-C<\N> is new in 5.12, and is experimental. It, like the dot, matches any
-character that is not a newline. The difference is that C<\N> is not influenced
-by the I<single line> regular expression modifier (see L</The dot> above). Note
-that the form C<\N{...}> may mean something completely different. When the
-C<{...}> is a L<quantifier|perlre/Quantifiers>, it means to match a non-newline
-character that many times. For example, C<\N{3}> means to match 3
-non-newlines; C<\N{5,}> means to match 5 or more non-newlines. But if C<{...}>
-is not a legal quantifier, it is presumed to be a named character. See
-L<charnames> for those. For example, none of C<\N{COLON}>, C<\N{4F}>, and
-C<\N{F4}> contain legal quantifiers, so Perl will try to find characters whose
-names are respectively C<COLON>, C<4F>, and C<F4>.
-
=head3 Unicode Properties
C<\pP> and C<\p{Prop}> are character classes to match characters that fit given
@@ -329,7 +351,7 @@
For instance, a match for a number can be written as C</\pN/> or as
C</\p{Number}/>, or as C</\p{Number=True}/>.
Lowercase letters are matched by the property I<Lowercase_Letter> which
-has as short form I<Ll>. They need the braces, so are written as C</\p{Ll}/> or
+has the short form I<Ll>. They need the braces, so are written as C</\p{Ll}/> or
C</\p{Lowercase_Letter}/>, or C</\p{General_Category=Lowercase_Letter}/>
(the underscores are optional).
C</\pLl/> is valid, but means something different.
@@ -336,9 +358,9 @@
It matches a two character string: a letter (Unicode property C<\pL>),
followed by a lowercase C<l>.
-If neither the C</a> modifier nor locale rules are in effect, the use of
+If locale rules are not in effect, the use of
a Unicode property will force the regular expression into using Unicode
-rules.
+rules, if it isn't already.
Note that almost all properties are immune to case-insensitive matching.
That is, adding a C</i> regular expression modifier does not change what
@@ -353,11 +375,11 @@
and C<Titlecase>,
all of which match C<Cased> under C</i> matching.
(The difference between these sets is that some things, such as Roman
-Numerals, come in both upper and lower case so they are C<Cased>, but
+numerals, come in both upper and lower case, so they are C<Cased>, but
aren't considered to be letters, so they aren't C<Cased_Letter>s. They're
actually C<Letter_Number>s.)
This set also includes its subsets C<PosixUpper> and C<PosixLower>, both
-of which under C</i> matching match C<PosixAlpha>.
+of which under C</i> match C<PosixAlpha>.
For more details on Unicode properties, see L<perlunicode/Unicode
Character Properties>; for a
@@ -367,6 +389,17 @@
It is also possible to define your own properties. This is discussed in
L<perlunicode/User-Defined Character Properties>.
+Unicode properties are defined (surprise!) only on Unicode code points.
+A warning is raised and all matches fail on non-Unicode code points
+(those above the legal Unicode maximum of 0x10FFFF). This can be
+somewhat surprising,
+
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails.
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Also fails!
+
+Even though these two matches might be thought of as complements, they
+are so only on Unicode code points.
+
=head4 Examples
"a" =~ /\w/ # Match, "a" is a 'word' character.
@@ -419,9 +452,10 @@
-------
-* There is an exception to a bracketed character class matching only a
-single character. When the class is to match caselessely under C</i>
-matching rules, and a character inside the class matches a
+* There is an exception to a bracketed character class matching a
+single character only. When the class is to match caselessly under C</i>
+matching rules, and a character that is explicitly mentioned inside the
+class matches a
multiple-character sequence caselessly under Unicode rules, the class
(when not L<inverted|/Negation>) will also match that sequence. For
example, Unicode says that the letter C<LATIN SMALL LETTER SHARP S>
@@ -430,6 +464,18 @@
'ss' =~ /\A\N{LATIN SMALL LETTER SHARP S}\z/i # Matches
'ss' =~ /\A[aeioust\N{LATIN SMALL LETTER SHARP S}]\z/i # Matches
+For this to happen, the character must be explicitly specified, and not
+be part of a multi-character range (not even as one of its endpoints).
+(L</Character Ranges> will be explained shortly.) Therefore,
+
+ 'ss' =~ /\A[\0-\x{ff}]\z/i # Doesn't match
+ 'ss' =~ /\A[\0-\N{LATIN SMALL LETTER SHARP S}]\z/i # No match
+ 'ss' =~ /\A[\xDF-\xDF]\z/i # Matches on ASCII platforms, since \XDF
+ # is LATIN SMALL LETTER SHARP S, and the
+ # range is just a single element
+
+Note that it isn't a good idea to specify these types of ranges anyway.
+
=head3 Special Characters Inside a Bracketed Character Class
Most characters that are meta characters in regular expressions (that
@@ -488,7 +534,7 @@
Examples:
"+" =~ /[+?*]/ # Match, "+" in a character class is not special.
- "\cH" =~ /[\b]/ # Match, \b inside in a character class
+ "\cH" =~ /[\b]/ # Match, \b inside in a character class.
# is equivalent to a backspace.
"]" =~ /[][]/ # Match, as the character class contains.
# both [ and ].
@@ -503,7 +549,7 @@
If inside a bracketed character class you have two characters separated
by a hyphen, it's treated as if all characters between the two were in
the class. For instance, C<[0-9]> matches any ASCII digit, and C<[a-m]>
-matches any lowercase letter from the first half of the old ASCII alphabet.
+matches any lowercase letter from the first half of the ASCII alphabet.
Note that the two characters on either side of the hyphen are not
necessarily both letters or both digits. Any character is possible,
@@ -537,26 +583,27 @@
It is also possible to instead list the characters you do not want to
match. You can do so by using a caret (C<^>) as the first character in the
character class. For instance, C<[^a-z]> matches any character that is not a
-lowercase ASCII letter, which therefore includes almost a hundred thousand
-Unicode letters. The class is said to be "negated" or "inverted".
+lowercase ASCII letter, which therefore includes more than a million
+Unicode code points. The class is said to be "negated" or "inverted".
This syntax make the caret a special character inside a bracketed character
class, but only if it is the first character of the class. So if you want
the caret as one of the characters to match, either escape the caret or
-else not list it first.
+else don't list it first.
In inverted bracketed character classes, Perl ignores the Unicode rules
-that normally say that a given character matches a sequence of multiple
-characters under caseless C</i> matching, which otherwise could be
-highly confusing:
+that normally say that certain characters should match a sequence of
+multiple characters under caseless C</i> matching. Following those
+rules could lead to highly confusing situations:
- "ss" =~ /^[^\xDF]+$/ui;
+ "ss" =~ /^[^\xDF]+$/ui; # Matches!
This should match any sequences of characters that aren't C<\xDF> nor
what C<\xDF> matches under C</i>. C<"s"> isn't C<\xDF>, but Unicode
says that C<"ss"> is what C<\xDF> matches under C</i>. So which one
"wins"? Do you fail the match because the string has C<ss> or accept it
-because it has an C<s> followed by another C<s>?
+because it has an C<s> followed by another C<s>? Perl has chosen the
+latter.
Examples:
@@ -622,7 +669,7 @@
Perl recognizes the following POSIX character classes:
alpha Any alphabetical character ("[A-Za-z]").
- alnum Any alphanumeric character. ("[A-Za-z0-9]")
+ alnum Any alphanumeric character ("[A-Za-z0-9]").
ascii Any character in the ASCII character set.
blank A GNU extension, equal to a space or a horizontal tab ("\t").
cntrl Any control character. See Note [2] below.
@@ -631,7 +678,8 @@
lower Any lowercase character ("[a-z]").
print Any printable character, including a space. See Note [4] below.
punct Any graphical character excluding "word" characters. Note [5].
- space Any whitespace character. "\s" plus the vertical tab ("\cK").
+ space Any whitespace character. "\s" including the vertical tab
+ ("\cK").
upper Any uppercase character ("[A-Z]").
word A Perl extension ("[A-Za-z0-9_]"), equivalent to "\w".
xdigit Any hexadecimal digit ("[0-9a-fA-F]").
@@ -648,68 +696,9 @@
appropriate characters in the full Unicode character set. For example,
C<\p{Alpha}> matches not just the ASCII alphabetic characters, but any
character in the entire Unicode character set considered alphabetic.
-The column labelled "backslash sequence" is a (short) synonym for
-the Full-range Unicode form.
+An entry in the column labelled "backslash sequence" is a (short)
+equivalent.
-(Each of the counterparts has various synonyms as well.
-L<perluniprops/Properties accessible through \p{} and \P{}> lists all
-synonyms, plus all characters matched by each ASCII-range property.
-For example, C<\p{AHex}> is a synonym for C<\p{ASCII_Hex_Digit}>,
-and any C<\p> property name can be prefixed with "Is" such as C<\p{IsAlpha}>.)
-
-Both the C<\p> counterparts always assume Unicode rules are in effect.
-On ASCII platforms, this means they assume that the code points from 128
-to 255 are Latin-1, and that means that using them under locale rules is
-unwise unless the locale is guaranteed to be Latin-1 or UTF-8. In contrast, the
-POSIX character classes are useful under locale rules. They are
-affected by the actual rules in effect, as follows:
-
-=over
-
-=item If the C</a> modifier, is in effect ...
-
-Each of the POSIX classes matches exactly the same as their ASCII-range
-counterparts.
-
-=item otherwise ...
-
-=over
-
-=item For code points above 255 ...
-
-The POSIX class matches the same as its Full-range counterpart.
-
-=item For code points below 256 ...
-
-=over
-
-=item if locale rules are in effect ...
-
-The POSIX class matches according to the locale.
-
-=item if Unicode rules are in effect or if on an EBCDIC platform ...
-
-The POSIX class matches the same as the Full-range counterpart.
-
-=item otherwise ...
-
-The POSIX class matches the same as the ASCII range counterpart.
-
-=back
-
-=back
-
-=back
-
-Which rules apply are determined as described in
-L<perlre/Which character set modifier is in effect?>.
-
-It is proposed to change this behavior in a future release of Perl so that
-whether or not Unicode rules are in effect would not change the
-behavior: Outside of locale or an EBCDIC code page, the POSIX classes
-would behave like their ASCII-range counterparts. If you wish to
-comment on this proposal, send email to C<perl5-porters at perl.org>.
-
[[:...:]] ASCII-range Full-range backslash Note
Unicode Unicode sequence
-----------------------------------------------------
@@ -743,10 +732,6 @@
In the ASCII range, characters whose code points are between 0 and 31 inclusive,
plus 127 (C<DEL>) are control characters.
-On EBCDIC platforms, it is likely that the code page will define C<[[:cntrl:]]>
-to be the EBCDIC equivalents of the ASCII controls, plus the controls
-that in Unicode have code pointss from 128 through 159.
-
=item [3]
Any character that is I<graphical>, that is, visible. This class consists
@@ -766,11 +751,12 @@
The similarly named property, C<\p{Punct}>, matches a somewhat different
set in the ASCII range, namely
-C<[-!"#%&'()*,./:;?@[\\\]_{}]>. That is, it is missing C<[$+E<lt>=E<gt>^`|~]>.
+C<[-!"#%&'()*,./:;?@[\\\]_{}]>. That is, it is missing the nine
+characters C<[$+E<lt>=E<gt>^`|~]>.
This is because Unicode splits what POSIX considers to be punctuation into two
categories, Punctuation and Symbols.
-C<\p{XPosixPunct}> and (in Unicode mode) C<[[:punct:]]>, match what
+C<\p{XPosixPunct}> and (under Unicode rules) C<[[:punct:]]>, match what
C<\p{PosixPunct}> matches in the ASCII range, plus what C<\p{Punct}>
matches. This is different than strictly matching according to
C<\p{Punct}>. Another way to say it is that
@@ -780,17 +766,74 @@
=item [6]
-C<\p{SpacePerl}> and C<\p{Space}> differ only in that in non-locale
-matching, C<\p{Space}> additionally
-matches the vertical tab, C<\cK>. Same for the two ASCII-only range forms.
+C<\p{SpacePerl}> and C<\p{Space}> match identically starting with Perl
+v5.18. In earlier versions, these differ only in that in non-locale
+matching, C<\p{SpacePerl}> does not match the vertical tab, C<\cK>.
+Same for the two ASCII-only range forms.
=back
-There are various other synonyms that can be used for these besides
-C<\p{HorizSpace}> and \C<\p{XPosixBlank}>. For example,
-C<\p{PosixAlpha}> can be written as C<\p{Alpha}>. All are listed
-in L<perluniprops/Properties accessible through \p{} and \P{}>.
+There are various other synonyms that can be used besides the names
+listed in the table. For example, C<\p{PosixAlpha}> can be written as
+C<\p{Alpha}>. All are listed in
+L<perluniprops/Properties accessible through \p{} and \P{}>,
+plus all characters matched by each ASCII-range property.
+Both the C<\p> counterparts always assume Unicode rules are in effect.
+On ASCII platforms, this means they assume that the code points from 128
+to 255 are Latin-1, and that means that using them under locale rules is
+unwise unless the locale is guaranteed to be Latin-1 or UTF-8. In contrast, the
+POSIX character classes are useful under locale rules. They are
+affected by the actual rules in effect, as follows:
+
+=over
+
+=item If the C</a> modifier, is in effect ...
+
+Each of the POSIX classes matches exactly the same as their ASCII-range
+counterparts.
+
+=item otherwise ...
+
+=over
+
+=item For code points above 255 ...
+
+The POSIX class matches the same as its Full-range counterpart.
+
+=item For code points below 256 ...
+
+=over
+
+=item if locale rules are in effect ...
+
+The POSIX class matches according to the locale, except that
+C<word> uses the platform's native underscore character, no matter what
+the locale is.
+
+=item if Unicode rules are in effect ...
+
+The POSIX class matches the same as the Full-range counterpart.
+
+=item otherwise ...
+
+The POSIX class matches the same as the ASCII range counterpart.
+
+=back
+
+=back
+
+=back
+
+Which rules apply are determined as described in
+L<perlre/Which character set modifier is in effect?>.
+
+It is proposed to change this behavior in a future release of Perl so that
+whether or not Unicode rules are in effect would not change the
+behavior: Outside of locale, the POSIX classes
+would behave like their ASCII-range counterparts. If you wish to
+comment on this proposal, send email to C<perl5-porters at perl.org>.
+
=head4 Negation of POSIX character classes
X<character class, negation>
@@ -821,11 +864,218 @@
/[01[:lower:]]/ # Matches a character that is either a
# lowercase letter, or '0' or '1'.
/[[:digit:][:^xdigit:]]/ # Matches a character that can be anything
- # except the letters 'a' to 'f'. This is
- # because the main character class is composed
- # of two POSIX character classes that are ORed
- # together, one that matches any digit, and
- # the other that matches anything that isn't a
- # hex digit. The result matches all
- # characters except the letters 'a' to 'f' and
- # 'A' to 'F'.
+ # except the letters 'a' to 'f' and 'A' to
+ # 'F'. This is because the main character
+ # class is composed of two POSIX character
+ # classes that are ORed together, one that
+ # matches any digit, and the other that
+ # matches anything that isn't a hex digit.
+ # The OR adds the digits, leaving only the
+ # letters 'a' to 'f' and 'A' to 'F' excluded.
+
+=head3 Extended Bracketed Character Classes
+X<character class>
+X<set operations>
+
+This is a fancy bracketed character class that can be used for more
+readable and less error-prone classes, and to perform set operations,
+such as intersection. An example is
+
+ /(?[ \p{Thai} & \p{Digit} ])/
+
+This will match all the digit characters that are in the Thai script.
+
+This is an experimental feature available starting in 5.18, and is
+subject to change as we gain field experience with it. Any attempt to
+use it will raise a warning, unless disabled via
+
+ no warnings "experimental::regex_sets";
+
+Comments on this feature are welcome; send email to
+C<perl5-porters at perl.org>.
+
+We can extend the example above:
+
+ /(?[ ( \p{Thai} + \p{Lao} ) & \p{Digit} ])/
+
+This matches digits that are in either the Thai or Laotian scripts.
+
+Notice the white space in these examples. This construct always has
+the C<E<sol>x> modifier turned on.
+
+The available binary operators are:
+
+ & intersection
+ + union
+ | another name for '+', hence means union
+ - subtraction (the result matches the set consisting of those
+ code points matched by the first operand, excluding any that
+ are also matched by the second operand)
+ ^ symmetric difference (the union minus the intersection). This
+ is like an exclusive or, in that the result is the set of code
+ points that are matched by either, but not both, of the
+ operands.
+
+There is one unary operator:
+
+ ! complement
+
+All the binary operators left associate, and are of equal precedence.
+The unary operator right associates, and has higher precedence. Use
+parentheses to override the default associations. Some feedback we've
+received indicates a desire for intersection to have higher precedence
+than union. This is something that feedback from the field may cause us
+to change in future releases; you may want to parenthesize copiously to
+avoid such changes affecting your code, until this feature is no longer
+considered experimental.
+
+The main restriction is that everything is a metacharacter. Thus,
+you cannot refer to single characters by doing something like this:
+
+ /(?[ a + b ])/ # Syntax error!
+
+The easiest way to specify an individual typable character is to enclose
+it in brackets:
+
+ /(?[ [a] + [b] ])/
+
+(This is the same thing as C<[ab]>.) You could also have said the
+equivalent:
+
+ /(?[[ a b ]])/
+
+(You can, of course, specify single characters by using, C<\x{ }>,
+C<\N{ }>, etc.)
+
+This last example shows the use of this construct to specify an ordinary
+bracketed character class without additional set operations. Note the
+white space within it; C<E<sol>x> is turned on even within bracketed
+character classes, except you can't have comments inside them. Hence,
+
+ (?[ [#] ])
+
+matches the literal character "#". To specify a literal white space character,
+you can escape it with a backslash, like:
+
+ /(?[ [ a e i o u \ ] ])/
+
+This matches the English vowels plus the SPACE character.
+All the other escapes accepted by normal bracketed character classes are
+accepted here as well; but unrecognized escapes that generate warnings
+in normal classes are fatal errors here.
+
+All warnings from these class elements are fatal, as well as some
+practices that don't currently warn. For example you cannot say
+
+ /(?[ [ \xF ] ])/ # Syntax error!
+
+You have to have two hex digits after a braceless C<\x> (use a leading
+zero to make two). These restrictions are to lower the incidence of
+typos causing the class to not match what you thought it would.
+
+The final difference between regular bracketed character classes and
+these, is that it is not possible to get these to match a
+multi-character fold. Thus,
+
+ /(?[ [\xDF] ])/iu
+
+does not match the string C<ss>.
+
+You don't have to enclose POSIX class names inside double brackets,
+hence both of the following work:
+
+ /(?[ [:word:] - [:lower:] ])/
+ /(?[ [[:word:]] - [[:lower:]] ])/
+
+Any contained POSIX character classes, including things like C<\w> and C<\D>
+respect the C<E<sol>a> (and C<E<sol>aa>) modifiers.
+
+C<< (?[ ]) >> is a regex-compile-time construct. Any attempt to use
+something which isn't knowable at the time the containing regular
+expression is compiled is a fatal error. In practice, this means
+just three limitiations:
+
+=over 4
+
+=item 1
+
+This construct cannot be used within the scope of
+C<use locale> (or the C<E<sol>l> regex modifier).
+
+=item 2
+
+Any
+L<user-defined property|perlunicode/"User-Defined Character Properties">
+used must be already defined by the time the regular expression is
+compiled (but note that this construct can be used instead of such
+properties).
+
+=item 3
+
+A regular expression that otherwise would compile
+using C<E<sol>d> rules, and which uses this construct will instead
+use C<E<sol>u>. Thus this construct tells Perl that you don't want
+C<E<sol>d> rules for the entire regular expression containing it.
+
+=back
+
+The C<E<sol>x> processing within this class is an extended form.
+Besides the characters that are considered white space in normal C</x>
+processing, there are 5 others, recommended by the Unicode standard:
+
+ U+0085 NEXT LINE
+ U+200E LEFT-TO-RIGHT MARK
+ U+200F RIGHT-TO-LEFT MARK
+ U+2028 LINE SEPARATOR
+ U+2029 PARAGRAPH SEPARATOR
+
+Note that skipping white space applies only to the interior of this
+construct. There must not be any space between any of the characters
+that form the initial C<(?[>. Nor may there be space between the
+closing C<])> characters.
+
+Just as in all regular expressions, the pattern can can be built up by
+including variables that are interpolated at regex compilation time.
+Care must be taken to ensure that you are getting what you expect. For
+example:
+
+ my $thai_or_lao = '\p{Thai} + \p{Lao}';
+ ...
+ qr/(?[ \p{Digit} & $thai_or_lao ])/;
+
+compiles to
+
+ qr/(?[ \p{Digit} & \p{Thai} + \p{Lao} ])/;
+
+But this does not have the effect that someone reading the code would
+likely expect, as the intersection applies just to C<\p{Thai}>,
+excluding the Laotian. Pitfalls like this can be avoided by
+parenthesizing the component pieces:
+
+ my $thai_or_lao = '( \p{Thai} + \p{Lao} )';
+
+But any modifiers will still apply to all the components:
+
+ my $lower = '\p{Lower} + \p{Digit}';
+ qr/(?[ \p{Greek} & $lower ])/i;
+
+matches upper case things. You can avoid surprises by making the
+components into instances of this construct by compiling them:
+
+ my $thai_or_lao = qr/(?[ \p{Thai} + \p{Lao} ])/;
+ my $lower = qr/(?[ \p{Lower} + \p{Digit} ])/;
+
+When these are embedded in another pattern, what they match does not
+change, regardless of parenthesization or what modifiers are in effect
+in that outer pattern.
+
+Due to the way that Perl parses things, your parentheses and brackets
+may need to be balanced, even including comments. If you run into any
+examples, please send them to C<perlbug at perl.org>, so that we can have a
+concrete example for this man page.
+
+We may change it so that things that remain legal uses in normal bracketed
+character classes might become illegal within this experimental
+construct. One proposal, for example, is to forbid adjacent uses of the
+same character, as in C<(?[ [aa] ])>. The motivation for such a change
+is that this usage is likely a typo, as the second "a" adds nothing.
Property changes on: trunk/contrib/perl/pod/perlrecharclass.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlref.pod
===================================================================
--- trunk/contrib/perl/pod/perlref.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlref.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -24,7 +24,7 @@
automatically freeing the thing referred to when its reference count goes
to zero. (Reference counts for values in self-referential or
cyclic data structures may not go to zero without a little help; see
-L<perlobj/"Two-Phased Garbage Collection"> for a detailed explanation.)
+L</"Circular References"> for a detailed explanation.)
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
@@ -46,11 +46,18 @@
X<reference, hard> X<hard reference>
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 simple scalar. It
-doesn't magically start being an array or hash or subroutine; you have to
+principle: in general, Perl does no implicit referencing or dereferencing.
+When a scalar is holding a reference, it always behaves as a simple scalar.
+It doesn't magically start being an array or hash or subroutine; you have to
tell it explicitly to do so, by dereferencing it.
+That said, be aware that Perl version 5.14 introduces an exception
+to the rule, for syntactic convenience. Experimental array and hash container
+function behavior allows array and hash references to be handled by Perl as
+if they had been explicitly syntactically dereferenced. See
+L<perl5140delta/"Syntactical Enhancements">
+and L<perlfunc> for details.
+
=head2 Making References
X<reference, creation> X<referencing>
@@ -255,8 +262,11 @@
$ioref = *STDIN{IO};
$globref = *foo{GLOB};
$formatref = *foo{FORMAT};
+ $globname = *foo{NAME}; # "foo"
+ $pkgname = *foo{PACKAGE}; # "main"
-All of these are self-explanatory except for C<*foo{IO}>. It returns
+Most of these are self-explanatory, but C<*foo{IO}>
+deserves special attention. It returns
the IO handle, used for file handles (L<perlfunc/open>), sockets
(L<perlfunc/socket> and L<perlfunc/socketpair>), and directory
handles (L<perlfunc/opendir>). For compatibility with previous
@@ -269,6 +279,13 @@
anonymous scalar if $foo hasn't been used yet. This might change in a
future release.
+C<*foo{NAME}> and C<*foo{PACKAGE}> are the exception, in that they return
+strings, rather than references. These return the package and name of the
+typeglob itself, rather than one that has been assigned to it. So, after
+C<*foo=*Foo::bar>, C<*foo> will become "*Foo::bar" when used as a string,
+but C<*foo{PACKAGE}> and C<*foo{NAME}> will continue to produce "main" and
+"foo", respectively.
+
C<*foo{IO}> is an alternative to the C<*HANDLE> mechanism given in
L<perldata/"Typeglobs and Filehandles"> for passing filehandles
into or out of subroutines, or storing into larger data structures.
@@ -458,6 +475,58 @@
print "That yields ${\($n + 5)} widgets\n";
+=head2 Circular References
+X<circular reference> X<reference, circular>
+
+It is possible to create a "circular reference" in Perl, which can lead
+to memory leaks. A circular reference occurs when two references
+contain a reference to each other, like this:
+
+ my $foo = {};
+ my $bar = { foo => $foo };
+ $foo->{bar} = $bar;
+
+You can also create a circular reference with a single variable:
+
+ my $foo;
+ $foo = \$foo;
+
+In this case, the reference count for the variables will never reach 0,
+and the references will never be garbage-collected. This can lead to
+memory leaks.
+
+Because objects in Perl are implemented as references, it's possible to
+have circular references with objects as well. Imagine a TreeNode class
+where each node references its parent and child nodes. Any node with a
+parent will be part of a circular reference.
+
+You can break circular references by creating a "weak reference". A
+weak reference does not increment the reference count for a variable,
+which means that the object can go out of scope and be destroyed. You
+can weaken a reference with the C<weaken> function exported by the
+L<Scalar::Util> module.
+
+Here's how we can make the first example safer:
+
+ use Scalar::Util 'weaken';
+
+ my $foo = {};
+ my $bar = { foo => $foo };
+ $foo->{bar} = $bar;
+
+ weaken $foo->{bar};
+
+The reference from C<$foo> to C<$bar> has been weakened. When the
+C<$bar> variable goes out of scope, it will be garbage-collected. The
+next time you look at the value of the C<< $foo->{bar} >> key, it will
+be C<undef>.
+
+This action at a distance can be confusing, so you should be careful
+with your use of weaken. You should weaken the reference in the
+variable that will go out of scope I<first>. That way, the longer-lived
+variable will contain the expected reference until it goes out of
+scope.
+
=head2 Symbolic references
X<reference, symbolic> X<reference, soft>
X<symbolic reference> X<soft reference>
@@ -478,7 +547,7 @@
${$name x 2} = 3; # Sets $foofoo
$name->[0] = 4; # Sets $foo[0]
@$name = (); # Clears @foo
- &$name(); # Calls &foo() (as in Perl 4)
+ &$name(); # Calls &foo()
$pack = "THAT";
${"${pack}::$name"} = 5; # Sets $THAT::foo without eval
@@ -510,16 +579,16 @@
=head2 Not-so-symbolic references
-A new feature contributing to readability in perl version 5.001 is that the
-brackets around a symbolic reference behave more like quotes, just as they
-always have within a string. That is,
+Brackets around a symbolic reference can simply
+serve to isolate an identifier or variable name from the rest of an
+expression, just as they always have within a string. For example,
$push = "pop on ";
print "${push}over";
has always meant to print "pop on over", even though push is
-a reserved word. This has been generalized to work the same outside
-of quotes, so that
+a reserved word. This is generalized to work the same
+without the enclosing double quotes, so that
print ${push} . "over";
@@ -527,8 +596,7 @@
print ${ push } . "over";
-will have the same effect. (This would have been a syntax error in
-Perl 5.000, though Perl 4 allowed it in the spaceless form.) This
+will have the same effect. This
construct is I<not> considered to be a symbolic reference when you're
using strict refs:
@@ -536,9 +604,9 @@
${ 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
+Similarly, because of all the subscripting that is done using single words,
+the same rule applies to any bareword that is used for subscripting a hash.
+So now, instead of writing
$array{ "aaa" }{ "bbb" }{ "ccc" }
@@ -682,5 +750,5 @@
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<perltoot>, L<perlobj>, and L<perlbot>
+complex data structures, and L<perlootut> and L<perlobj>
for how to use them to create objects.
Property changes on: trunk/contrib/perl/pod/perlref.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlreftut.pod
===================================================================
--- trunk/contrib/perl/pod/perlreftut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlreftut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -7,7 +7,7 @@
One of the most important new features in Perl 5 was the capability to
manage complicated data structures like multidimensional arrays and
nested hashes. To enable these, Perl 5 introduced a feature called
-`references', and using references is the key to managing complicated,
+'references', and using references is the key to managing complicated,
structured data in Perl. Unfortunately, there's a lot of funny syntax
to learn, and the main manual page can be hard to follow. The manual
is quite complete, and sometimes people find that a problem, because
@@ -18,9 +18,9 @@
=head1 Who Needs Complicated Data Structures?
-One problem that came up all the time in Perl 4 was how to represent a
-hash whose values were lists. Perl 4 had hashes, of course, but the
-values had to be scalars; they couldn't be lists.
+One problem that comes up all the time is needing a hash whose values are
+lists. Perl has hashes, of course, but the values have to be scalars;
+they can't be lists.
Why would you want a hash of lists? Let's take a simple example: You
have a file of city and country names, like this:
@@ -47,8 +47,7 @@
the input, iterate over the hash as usual, sorting each list of cities
before you print it out.
-If hash values can't be lists, you lose. In Perl 4, hash values can't
-be lists; they can only be strings. You lose. You'd probably have to
+If hash values couldn't be lists, you lose. You'd probably have to
combine all the cities into a single string somehow, and then when
time came to write the output, you'd have to break the string into a
list, sort the list, and turn it back into a string. This is messy
@@ -402,8 +401,8 @@
to push C<Athens> onto an array that doesn't exist, so it helpfully
makes a new, empty, anonymous array for you, installs it into
C<%table>, and then pushes C<Athens> onto it. This is called
-`autovivification'--bringing things to life automatically. Perl saw
-that they key wasn't in the hash, so it created a new hash entry
+'autovivification'--bringing things to life automatically. Perl saw
+that the key wasn't in the hash, so it created a new hash entry
automatically. Perl saw that you wanted to use the hash value as an
array, so it created a new empty array and installed a reference to it
in the hash automatically. And as usual, Perl made the array one
Property changes on: trunk/contrib/perl/pod/perlreftut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlreguts.pod
===================================================================
--- trunk/contrib/perl/pod/perlreguts.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlreguts.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -182,9 +182,9 @@
additional 4-byte (32-bit) bitmap indicating which POSIX char classes
have been included.
- regnode_charclass_class U32 arg1;
- char bitmap[ANYOF_BITMAP_SIZE];
- char classflags[ANYOF_CLASSBITMAP_SIZE];
+ regnode_charclass_class U32 arg1;
+ char bitmap[ANYOF_BITMAP_SIZE];
+ char classflags[ANYOF_CLASSBITMAP_SIZE];
=back
@@ -354,20 +354,23 @@
The call graph looks like this:
- reg() # parse a top level regex, or inside of parens
- regbranch() # parse a single branch of an alternation
- regpiece() # parse a pattern followed by a quantifier
- regatom() # parse a simple pattern
- regclass() # used to handle a class
- reg() # used to handle a parenthesised subpattern
- ....
- ...
- regtail() # finish off the branch
- ...
- regtail() # finish off the branch sequence. Tie each
- # branch's tail to the tail of the sequence
- # (NEW) In Debug mode this is
- # regtail_study().
+ reg() # parse a top level regex, or inside of
+ # parens
+ regbranch() # parse a single branch of an alternation
+ regpiece() # parse a pattern followed by a quantifier
+ regatom() # parse a simple pattern
+ regclass() # used to handle a class
+ reg() # used to handle a parenthesised
+ # subpattern
+ ....
+ ...
+ regtail() # finish off the branch
+ ...
+ regtail() # finish off the branch sequence. Tie each
+ # branch's tail to the tail of the
+ # sequence
+ # (NEW) In Debug mode this is
+ # regtail_study().
A grammar form might be something like this:
@@ -383,6 +386,52 @@
piece : _piece
| _piece quant
+=head3 Parsing complications
+
+The implication of the above description is that a pattern containing nested
+parentheses will result in a call graph which cycles through C<reg()>,
+C<regbranch()>, C<regpiece()>, C<regatom()>, C<reg()>, C<regbranch()> I<etc>
+multiple times, until the deepest level of nesting is reached. All the above
+routines return a pointer to a C<regnode>, which is usually the last regnode
+added to the program. However, one complication is that reg() returns NULL
+for parsing C<(?:)> syntax for embedded modifiers, setting the flag
+C<TRYAGAIN>. The C<TRYAGAIN> propagates upwards until it is captured, in
+some cases by by C<regatom()>, but otherwise unconditionally by
+C<regbranch()>. Hence it will never be returned by C<regbranch()> to
+C<reg()>. This flag permits patterns such as C<(?i)+> to be detected as
+errors (I<Quantifier follows nothing in regex; marked by <-- HERE in m/(?i)+
+<-- HERE />).
+
+Another complication is that the representation used for the program differs
+if it needs to store Unicode, but it's not always possible to know for sure
+whether it does until midway through parsing. The Unicode representation for
+the program is larger, and cannot be matched as efficiently. (See L</Unicode
+and Localisation Support> below for more details as to why.) If the pattern
+contains literal Unicode, it's obvious that the program needs to store
+Unicode. Otherwise, the parser optimistically assumes that the more
+efficient representation can be used, and starts sizing on this basis.
+However, if it then encounters something in the pattern which must be stored
+as Unicode, such as an C<\x{...}> escape sequence representing a character
+literal, then this means that all previously calculated sizes need to be
+redone, using values appropriate for the Unicode representation. Currently,
+all regular expression constructions which can trigger this are parsed by code
+in C<regatom()>.
+
+To avoid wasted work when a restart is needed, the sizing pass is abandoned
+- C<regatom()> immediately returns NULL, setting the flag C<RESTART_UTF8>.
+(This action is encapsulated using the macro C<REQUIRE_UTF8>.) This restart
+request is propagated up the call chain in a similar fashion, until it is
+"caught" in C<Perl_re_op_compile()>, which marks the pattern as containing
+Unicode, and restarts the sizing pass. It is also possible for constructions
+within run-time code blocks to turn out to need Unicode representation.,
+which is signalled by C<S_compile_runtime_code()> returning false to
+C<Perl_re_op_compile()>.
+
+The restart was previously implemented using a C<longjmp> in C<regatom()>
+back to a C<setjmp> in C<Perl_re_op_compile()>, but this proved to be
+problematic as the latter is a large function containing many automatic
+variables, which interact badly with the emergent control flow of C<setjmp>.
+
=head3 Debug Output
In the 5.9.x development version of perl you can C<< use re Debug => 'PARSE' >>
@@ -489,11 +538,11 @@
atom
>)$< 34 tail~ BRANCH (28)
36 tsdy~ BRANCH (END) (31)
- ~ attach to CLOSE1 (34) offset to 3
+ ~ attach to CLOSE1 (34) offset to 3
tsdy~ EXACT <foo> (EXACT) (29)
- ~ attach to CLOSE1 (34) offset to 5
+ ~ attach to CLOSE1 (34) offset to 5
tsdy~ EXACT <bar> (EXACT) (32)
- ~ attach to CLOSE1 (34) offset to 2
+ ~ attach to CLOSE1 (34) offset to 2
>$< tail~ BRANCH (3)
~ BRANCH (9)
~ TAIL (25)
@@ -765,7 +814,7 @@
The other structure is pointed to be the C<regexp> struct's
C<pprivate> and is in addition to C<intflags> in the same struct
considered to be the property of the regex engine which compiled the
-regular expression;
+regular expression;
The regexp structure contains all the data that perl needs to be aware of
to properly work with the regular expression. It includes data about
@@ -792,31 +841,24 @@
regex engine. Since it is specific to perl it is only of curiosity
value to other engine implementations.
- typedef struct regexp_internal {
- regexp_paren_ofs *swap; /* Swap copy of *startp / *endp */
- U32 *offsets; /* offset annotations 20001228 MJD
- data about mapping the program to the
- string*/
- regnode *regstclass; /* Optional startclass as identified or constructed
- by the optimiser */
- struct reg_data *data; /* Additional miscellaneous data used by the program.
- Used to make it easier to clone and free arbitrary
- data that the regops need. Often the ARG field of
- a regop is an index into this structure */
- regnode program[1]; /* Unwarranted chumminess with compiler. */
- } regexp_internal;
+ typedef struct regexp_internal {
+ U32 *offsets; /* offset annotations 20001228 MJD
+ * data about mapping the program to
+ * the string*/
+ regnode *regstclass; /* Optional startclass as identified or
+ * constructed by the optimiser */
+ struct reg_data *data; /* Additional miscellaneous data used
+ * by the program. Used to make it
+ * easier to clone and free arbitrary
+ * data that the regops need. Often the
+ * ARG field of a regop is an index
+ * into this structure */
+ regnode program[1]; /* Unwarranted chumminess with
+ * compiler. */
+ } regexp_internal;
=over 5
-=item C<swap>
-
-C<swap> formerly was an extra set of startp/endp stored in a
-C<regexp_paren_ofs> struct. This was used when the last successful match
-was from the same pattern as the current pattern, so that a partial
-match didn't overwrite the previous match's results, but it caused a
-problem with re-entrant code such as trying to build the UTF-8 swashes.
-Currently unused and left for backward compatibility with 5.10.0.
-
=item C<offsets>
Offsets holds a mapping of offset in the C<program>
Property changes on: trunk/contrib/perl/pod/perlreguts.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perlrepository.pod (from rev 6437, vendor/perl/5.18.1/pod/perlrepository.pod)
===================================================================
--- trunk/contrib/perl/pod/perlrepository.pod (rev 0)
+++ trunk/contrib/perl/pod/perlrepository.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,689 @@
+=for comment
+Consistent formatting of this file is achieved with:
+ perl ./Porting/podtidy pod/perlrepository.pod
+
+=head1 NAME
+
+perlrepository - Using the Perl source repository
+
+=head1 SYNOPSIS
+
+All of Perl's source code is kept centrally in a Git repository at
+I<perl5.git.perl.org>. The repository contains many Perl revisions from
+Perl 1 onwards and all the revisions from Perforce, the version control
+system we were using previously. This repository is accessible in
+different ways.
+
+The full repository takes up about 80MB of disk space. A check out of
+the blead branch (that is, the main development branch, which contains
+bleadperl, the development version of perl 5) takes up about 160MB of
+disk space (including the repository). A build of bleadperl takes up
+about 200MB (including the repository and the check out).
+
+=head1 GETTING ACCESS TO THE REPOSITORY
+
+=head2 READ ACCESS VIA THE WEB
+
+You may access the repository over the web. This allows you to browse
+the tree, see recent commits, subscribe to RSS feeds for the changes,
+search for particular commits and more. You may access it at:
+
+ http://perl5.git.perl.org/perl.git
+
+A mirror of the repository is found at:
+
+ http://github.com/github/perl
+
+=head2 READ ACCESS VIA GIT
+
+You will need a copy of Git for your computer. You can fetch a copy of
+the repository using the Git protocol (which uses port 9418):
+
+ git clone git://perl5.git.perl.org/perl.git perl-git
+
+This clones the repository and makes a local copy in the F<perl-git>
+directory.
+
+If your local network does not allow you to use port 9418, then you can
+fetch a copy of the repository over HTTP (this is slower):
+
+ git clone http://perl5.git.perl.org/perl.git perl-http
+
+This clones the repository and makes a local copy in the F<perl-http>
+directory.
+
+=head2 WRITE ACCESS TO THE REPOSITORY
+
+If you are a committer, then you can fetch a copy of the repository
+that you can push back on with:
+
+ git clone ssh://perl5.git.perl.org/gitroot/perl.git perl-ssh
+
+This clones the repository and makes a local copy in the F<perl-ssh>
+directory.
+
+If you cloned using the git protocol, which is faster than ssh, then
+you will need to modify your config in order to enable pushing. Edit
+F<.git/config> where you will see something like:
+
+ [remote "origin"]
+ url = git://perl5.git.perl.org/perl.git
+
+change that to something like this:
+
+ [remote "origin"]
+ url = ssh://perl5.git.perl.org/gitroot/perl.git
+
+NOTE: there are symlinks set up so that the /gitroot is optional and
+since SSH is the default protocol you can actually shorten the "url" to
+C<perl5.git.perl.org:/perl.git>.
+
+You can also set up your user name and e-mail address. For example
+
+ % git config user.name "Leon Brocard"
+ % git config user.email acme at astray.com
+
+It is also possible to keep C<origin> as a git remote, and add a new
+remote for ssh access:
+
+ % git remote add camel perl5.git.perl.org:/perl.git
+
+This allows you to update your local repository by pulling from
+C<origin>, which is faster and doesn't require you to authenticate, and
+to push your changes back with the C<camel> remote:
+
+ % git fetch camel
+ % git push camel
+
+The C<fetch> command just updates the C<camel> refs, as the objects
+themselves should have been fetched when pulling from C<origin>.
+
+The committers have access to 2 servers that serve perl5.git.perl.org.
+One is camel.booking.com, which is the 'master' repository. The
+perl5.git.perl.org IP address also lives on this machine. The second
+one is dromedary.booking.com, which can be used for general testing and
+development. Dromedary syncs the git tree from camel every few minutes,
+you should not push there. Both machines also have a full CPAN mirror.
+To share files with the general public, dromedary serves your
+~/public_html/ as http://users.perl5.git.perl.org/~yourlogin/
+
+=head1 OVERVIEW OF THE REPOSITORY
+
+Once you have changed into the repository directory, you can inspect
+it.
+
+After a clone the repository will contain a single local branch, which
+will be the current branch as well, as indicated by the asterisk.
+
+ % git branch
+ * blead
+
+Using the -a switch to C<branch> will also show the remote tracking
+branches in the repository:
+
+ % git branch -a
+ * blead
+ origin/HEAD
+ origin/blead
+ ...
+
+The branches that begin with "origin" correspond to the "git remote"
+that you cloned from (which is named "origin"). Each branch on the
+remote will be exactly tracked by theses branches. You should NEVER do
+work on these remote tracking branches. You only ever do work in a
+local branch. Local branches can be configured to automerge (on pull)
+from a designated remote tracking branch. This is the case with the
+default branch C<blead> which will be configured to merge from the
+remote tracking branch C<origin/blead>.
+
+You can see recent commits:
+
+ % git log
+
+And pull new changes from the repository, and update your local
+repository (must be clean first)
+
+ % git pull
+
+Assuming we are on the branch C<blead> immediately after a pull, this
+command would be more or less equivalent to:
+
+ % git fetch
+ % git merge origin/blead
+
+In fact if you want to update your local repository without touching
+your working directory you do:
+
+ % git fetch
+
+And if you want to update your remote-tracking branches for all defined
+remotes simultaneously you can do
+
+ % git remote update
+
+Neither of these last two commands will update your working directory,
+however both will update the remote-tracking branches in your
+repository.
+
+To switch to another branch:
+
+ % git checkout origin/maint-5.8-dor
+
+To make a local branch of a remote branch:
+
+ % git checkout -b maint-5.10 origin/maint-5.10
+
+To switch back to blead:
+
+ % git checkout blead
+
+=head2 FINDING OUT YOUR STATUS
+
+The most common git command you will use will probably be
+
+ % git status
+
+This command will produce as output a description of the current state
+of the repository, including modified files and unignored untracked
+files, and in addition it will show things like what files have been
+staged for the next commit, and usually some useful information about
+how to change things. For instance the following:
+
+ $ git status
+ # On branch blead
+ # Your branch is ahead of 'origin/blead' by 1 commit.
+ #
+ # Changes to be committed:
+ # (use "git reset HEAD <file>..." to unstage)
+ #
+ # modified: pod/perlrepository.pod
+ #
+ # Changed but not updated:
+ # (use "git add <file>..." to update what will be committed)
+ #
+ # modified: pod/perlrepository.pod
+ #
+ # Untracked files:
+ # (use "git add <file>..." to include in what will be committed)
+ #
+ # deliberate.untracked
+
+This shows that there were changes to this document staged for commit,
+and that there were further changes in the working directory not yet
+staged. It also shows that there was an untracked file in the working
+directory, and as you can see shows how to change all of this. It also
+shows that there is one commit on the working branch C<blead> which has
+not been pushed to the C<origin> remote yet. B<NOTE>: that this output
+is also what you see as a template if you do not provide a message to
+C<git commit>.
+
+Assuming we commit all the mentioned changes above:
+
+ % git commit -a -m'explain git status and stuff about remotes'
+ Created commit daf8e63: explain git status and stuff about remotes
+ 1 files changed, 83 insertions(+), 3 deletions(-)
+
+We can re-run git status and see something like this:
+
+ % git status
+ # On branch blead
+ # Your branch is ahead of 'origin/blead' by 2 commits.
+ #
+ # Untracked files:
+ # (use "git add <file>..." to include in what will be committed)
+ #
+ # deliberate.untracked
+ nothing added to commit but untracked files present (use "git add" to track)
+
+
+When in doubt, before you do anything else, check your status and read
+it carefully, many questions are answered directly by the git status
+output.
+
+=head1 SUBMITTING A PATCH
+
+If you have a patch in mind for Perl, you should first get a copy of
+the repository:
+
+ % git clone git://perl5.git.perl.org/perl.git perl-git
+
+Then change into the directory:
+
+ % cd perl-git
+
+Alternatively, if you already have a Perl repository, you should ensure
+that you're on the I<blead> branch, and your repository is up to date:
+
+ % git checkout blead
+ % git pull
+
+It's preferable to patch against the latest blead version, since this
+is where new development occurs for all changes other than critical bug
+fixes. Critical bug fix patches should be made against the relevant
+maint branches, or should be submitted with a note indicating all the
+branches where the fix should be applied.
+
+Now that we have everything up to date, we need to create a temporary
+new branch for these changes and switch into it:
+
+ % git checkout -b orange
+
+which is the short form of
+
+ % git branch orange
+ % git checkout orange
+
+Then make your changes. For example, if Leon Brocard changes his name
+to Orange Brocard, we should change his name in the AUTHORS file:
+
+ % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
+
+You can see what files are changed:
+
+ % git status
+ # On branch orange
+ # Changes to be committed:
+ # (use "git reset HEAD <file>..." to unstage)
+ #
+ # modified: AUTHORS
+ #
+
+And you can see the changes:
+
+ % git diff
+ diff --git a/AUTHORS b/AUTHORS
+ index 293dd70..722c93e 100644
+ --- a/AUTHORS
+ +++ b/AUTHORS
+ @@ -541,7 +541,7 @@ Lars Hecking <lhecking at nmrc.ucc.ie>
+ Laszlo Molnar <laszlo.molnar at eth.ericsson.se>
+ Leif Huhn <leif at hale.dkstat.com>
+ Len Johnson <lenjay at ibm.net>
+ -Leon Brocard <acme at astray.com>
+ +Orange Brocard <acme at astray.com>
+ Les Peters <lpeters at aol.net>
+ Lesley Binks <lesley.binks at gmail.com>
+ Lincoln D. Stein <lstein at cshl.org>
+
+Now commit your change locally:
+
+ % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
+ Created commit 6196c1d: Rename Leon Brocard to Orange Brocard
+ 1 files changed, 1 insertions(+), 1 deletions(-)
+
+You can examine your last commit with:
+
+ % git show HEAD
+
+and if you are not happy with either the description or the patch
+itself you can fix it up by editing the files once more and then issue:
+
+ % git commit -a --amend
+
+Now you should create a patch file for all your local changes:
+
+ % git format-patch origin
+ 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
+
+You should now send an email to perl5-porters at perl.org with a
+description of your changes, and include this patch file as an
+attachment.
+
+If you want to delete your temporary branch, you may do so with:
+
+ % git checkout blead
+ % git branch -d orange
+ error: The branch 'orange' is not an ancestor of your current HEAD.
+ If you are sure you want to delete it, run 'git branch -D orange'.
+ % git branch -D orange
+ Deleted branch orange.
+
+=head2 A note on derived files
+
+Be aware that many files in the distribution are derivative--avoid
+patching them, because git won't see the changes to them, and the build
+process will overwrite them. Patch the originals instead. Most
+utilities (like perldoc) are in this category, i.e. patch
+utils/perldoc.PL rather than utils/perldoc. Similarly, don't create
+patches for files under $src_root/ext from their copies found in
+$install_root/lib. If you are unsure about the proper location of a
+file that may have gotten copied while building the source
+distribution, consult the C<MANIFEST>.
+
+=head2 A note on binary files
+
+Since the patch(1) utility cannot deal with binary files, it's
+important that you either avoid the use of binary files in your patch,
+generate the files dynamically, or that you encode any binary files
+using the F<uupacktool.pl> utility.
+
+Assuming you needed to include a gzip-encoded file for a module's test
+suite, you might do this as follows using the F<uupacktool.pl> utility:
+
+ $ perl uupacktool.pl -v -p -D lib/Some/Module/t/src/t.gz
+ Writing lib/Some/Module/t/src/t.gz into lib/Some/Module/t/src/t.gz.packed
+
+This will replace the C<t.gz> file with an encoded counterpart. During
+C<make test>, before any tests are run, perl's Makefile will restore
+all the C<.packed> files mentioned in the MANIFEST to their original
+name. This means that the test suite does not need to be aware of this
+packing scheme and will not need to be altered.
+
+=head2 Getting your patch accepted
+
+The first thing you should include with your patch is a description of
+the problem that the patch corrects. If it is a code patch (rather
+than a documentation patch) you should also include a small test case
+that illustrates the bug (a patch to an existing test file is
+preferred).
+
+If you are submitting a code patch there are several other things that
+you need to do.
+
+=over 4
+
+=item Comments, Comments, Comments
+
+Be sure to adequately comment your code. While commenting every line
+is unnecessary, anything that takes advantage of side effects of
+operators, that creates changes that will be felt outside of the
+function being patched, or that others may find confusing should be
+documented. If you are going to err, it is better to err on the side
+of adding too many comments than too few.
+
+=item Style
+
+In general, please follow the particular style of the code you are
+patching.
+
+In particular, follow these general guidelines for patching Perl
+sources:
+
+ 8-wide tabs (no exceptions!)
+ 4-wide indents for code, 2-wide indents for nested CPP #defines
+ try hard not to exceed 79-columns
+ ANSI C prototypes
+ uncuddled elses and "K&R" style for indenting control constructs
+ no C++ style (//) comments
+ mark places that need to be revisited with XXX (and revisit often!)
+ opening brace lines up with "if" when conditional spans multiple
+ lines; should be at end-of-line otherwise
+ in function definitions, name starts in column 0 (return value is on
+ previous line)
+ single space after keywords that are followed by parens, no space
+ between function name and following paren
+ avoid assignments in conditionals, but if they're unavoidable, use
+ extra paren, e.g. "if (a && (b = c)) ..."
+ "return foo;" rather than "return(foo);"
+ "if (!foo) ..." rather than "if (foo == FALSE) ..." etc.
+
+=item Testsuite
+
+When submitting a patch you should make every effort to also include an
+addition to perl's regression tests to properly exercise your patch.
+Your testsuite additions should generally follow these guidelines
+(courtesy of Gurusamy Sarathy <gsar at activestate.com>):
+
+ Know what you're testing. Read the docs, and the source.
+ Tend to fail, not succeed.
+ Interpret results strictly.
+ Use unrelated features (this will flush out bizarre interactions).
+ Use non-standard idioms (otherwise you are not testing TIMTOWTDI).
+ Avoid using hardcoded test numbers whenever possible (the
+ EXPECTED/GOT found in t/op/tie.t is much more maintainable,
+ and gives better failure reports).
+ Give meaningful error messages when a test fails.
+ Avoid using qx// and system() unless you are testing for them. If you
+ do use them, make sure that you cover _all_ perl platforms.
+ Unlink any temporary files you create.
+ Promote unforeseen warnings to errors with $SIG{__WARN__}.
+ Be sure to use the libraries and modules shipped with the version
+ being tested, not those that were already installed.
+ Add comments to the code explaining what you are testing for.
+ Make updating the '1..42' string unnecessary. Or make sure that
+ you update it.
+ Test _all_ behaviors of a given operator, library, or function:
+ - All optional arguments
+ - Return values in various contexts (boolean, scalar, list, lvalue)
+ - Use both global and lexical variables
+ - Don't forget the exceptional, pathological cases.
+
+=back
+
+=head1 ACCEPTING A PATCH
+
+If you have received a patch file generated using the above section,
+you should try out the patch.
+
+First we need to create a temporary new branch for these changes and
+switch into it:
+
+ % git checkout -b experimental
+
+Patches that were formatted by C<git format-patch> are applied with
+C<git am>:
+
+ % git am 0001-Rename-Leon-Brocard-to-Orange-Brocard.patch
+ Applying Rename Leon Brocard to Orange Brocard
+
+If just a raw diff is provided, it is also possible use this two-step
+process:
+
+ % git apply bugfix.diff
+ % git commit -a -m "Some fixing" --author="That Guy <that.guy at internets.com>"
+
+Now we can inspect the change:
+
+ % git show HEAD
+ commit b1b3dab48344cff6de4087efca3dbd63548ab5e2
+ Author: Leon Brocard <acme at astray.com>
+ Date: Fri Dec 19 17:02:59 2008 +0000
+
+ Rename Leon Brocard to Orange Brocard
+
+ diff --git a/AUTHORS b/AUTHORS
+ index 293dd70..722c93e 100644
+ --- a/AUTHORS
+ +++ b/AUTHORS
+ @@ -541,7 +541,7 @@ Lars Hecking <lhecking at nmrc.ucc.ie>
+ Laszlo Molnar <laszlo.molnar at eth.ericsson.se>
+ Leif Huhn <leif at hale.dkstat.com>
+ Len Johnson <lenjay at ibm.net>
+ -Leon Brocard <acme at astray.com>
+ +Orange Brocard <acme at astray.com>
+ Les Peters <lpeters at aol.net>
+ Lesley Binks <lesley.binks at gmail.com>
+ Lincoln D. Stein <lstein at cshl.org>
+
+If you are a committer to Perl and you think the patch is good, you can
+then merge it into blead then push it out to the main repository:
+
+ % git checkout blead
+ % git merge experimental
+ % git push
+
+If you want to delete your temporary branch, you may do so with:
+
+ % git checkout blead
+ % git branch -d experimental
+ error: The branch 'experimental' is not an ancestor of your current HEAD.
+ If you are sure you want to delete it, run 'git branch -D experimental'.
+ % git branch -D experimental
+ Deleted branch experimental.
+
+=head1 CLEANING A WORKING DIRECTORY
+
+The command C<git clean> can with varying arguments be used as a
+replacement for C<make clean>.
+
+To reset your working directory to a pristine condition you can do:
+
+ git clean -dxf
+
+However, be aware this will delete ALL untracked content. You can use
+
+ git clean -Xf
+
+to remove all ignored untracked files, such as build and test
+byproduct, but leave any manually created files alone.
+
+If you only want to cancel some uncommitted edits, you can use C<git
+checkout> and give it a list of files to be reverted, or C<git checkout
+-f> to revert them all.
+
+If you want to cancel one or several commits, you can use C<git reset>.
+
+=head1 BISECTING
+
+C<git> provides a built-in way to determine, with a binary search in
+the history, which commit should be blamed for introducing a given bug.
+
+Suppose that we have a script F<~/testcase.pl> that exits with C<0>
+when some behaviour is correct, and with C<1> when it's faulty. We need
+an helper script that automates building C<perl> and running the
+testcase:
+
+ % cat ~/run
+ #!/bin/sh
+ git clean -dxf
+ # If you can use ccache, add -Dcc=ccache\ gcc -Dld=gcc to the Configure line
+ sh Configure -des -Dusedevel -Doptimize="-g"
+ test -f config.sh || exit 125
+ # Correct makefile for newer GNU gcc
+ perl -ni -we 'print unless /<(?:built-in|command)/' makefile x2p/makefile
+ # if you just need miniperl, replace test_prep with miniperl
+ make -j4 test_prep
+ -x ./perl || exit 125
+ ./perl -Ilib ~/testcase.pl
+ ret=$?
+ git clean -dxf
+ exit $ret
+
+This script may return C<125> to indicate that the corresponding commit
+should be skipped. Otherwise, it returns the status of
+F<~/testcase.pl>.
+
+We first enter in bisect mode with:
+
+ % git bisect start
+
+For example, if the bug is present on C<HEAD> but wasn't in 5.10.0,
+C<git> will learn about this when you enter:
+
+ % git bisect bad
+ % git bisect good perl-5.10.0
+ Bisecting: 853 revisions left to test after this
+
+This results in checking out the median commit between C<HEAD> and
+C<perl-5.10.0>. We can then run the bisecting process with:
+
+ % git bisect run ~/run
+
+When the first bad commit is isolated, C<git bisect> will tell you so:
+
+ ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5 is first bad commit
+ commit ca4cfd28534303b82a216cfe83a1c80cbc3b9dc5
+ Author: Dave Mitchell <davem at fdisolutions.com>
+ Date: Sat Feb 9 14:56:23 2008 +0000
+
+ [perl #49472] Attributes + Unknown Error
+ ...
+
+ bisect run success
+
+You can peek into the bisecting process with C<git bisect log> and
+C<git bisect visualize>. C<git bisect reset> will get you out of bisect
+mode.
+
+Please note that the first C<good> state must be an ancestor of the
+first C<bad> state. If you want to search for the commit that I<solved>
+some bug, you have to negate your test case (i.e. exit with C<1> if OK
+and C<0> if not) and still mark the lower bound as C<good> and the
+upper as C<bad>. The "first bad commit" has then to be understood as
+the "first commit where the bug is solved".
+
+C<git help bisect> has much more information on how you can tweak your
+binary searches.
+
+=head1 SUBMITTING A PATCH VIA GITHUB
+
+GitHub is a website that makes it easy to fork and publish projects
+with Git. First you should set up a GitHub account and log in.
+
+Perl's git repository is mirrored on GitHub at this page:
+
+ http://github.com/github/perl/tree/blead
+
+Visit the page and click the "fork" button. This clones the Perl git
+repository for you and provides you with "Your Clone URL" from which
+you should clone:
+
+ % git clone git at github.com:USERNAME/perl.git perl-github
+
+We shall make the same patch as above, creating a new branch:
+
+ % cd perl-github
+ % git remote add upstream git://github.com/github/perl.git
+ % git pull upstream blead
+ % git checkout -b orange
+ % perl -pi -e 's{Leon Brocard}{Orange Brocard}' AUTHORS
+ % git commit -a -m 'Rename Leon Brocard to Orange Brocard'
+ % git push origin orange
+
+The orange branch has been pushed to GitHub, so you should now send an
+email to perl5-porters at perl.org with a description of your changes and
+the following information:
+
+ http://github.com/USERNAME/perl/tree/orange
+ git at github.com:USERNAME/perl.git branch orange
+
+=head1 MERGING FROM A BRANCH VIA GITHUB
+
+If someone has provided a branch via GitHub and you are a committer,
+you should use the following in your perl-ssh directory:
+
+ % git remote add dandv git://github.com/dandv/perl.git
+ % git fetch
+
+Now you can see the differences between the branch and blead:
+
+ % git diff dandv/blead
+
+And you can see the commits:
+
+ % git log dandv/blead
+
+If you approve of a specific commit, you can cherry pick it:
+
+ % git cherry-pick 3adac458cb1c1d41af47fc66e67b49c8dec2323f
+
+Or you could just merge the whole branch if you like it all:
+
+ % git merge dandv/blead
+
+And then push back to the repository:
+
+ % git push
+
+=head1 COMMITTING TO MAINTENANCE VERSIONS
+
+Maintenance versions should only be altered to add critical bug fixes.
+
+To commit to a maintenance version of perl, you need to create a local
+tracking branch:
+
+ % git checkout --track -b maint-5.005 origin/maint-5.005
+
+This creates a local branch named C<maint-5.005>, which tracks the
+remote branch C<origin/maint-5.005>. Then you can pull, commit, merge
+and push as before.
+
+You can also cherry-pick commits from blead and another branch, by
+using the C<git cherry-pick> command. It is recommended to use the
+B<-x> option to C<git cherry-pick> in order to record the SHA1 of the
+original commit in the new commit message.
+
+=head1 SEE ALSO
+
+The git documentation, accessible via C<git help command>.
+
Modified: trunk/contrib/perl/pod/perlrequick.pod
===================================================================
--- trunk/contrib/perl/pod/perlrequick.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlrequick.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -162,8 +162,9 @@
/[a^]at/; # matches 'aat' or '^at'; here '^' is ordinary
Perl has several abbreviations for common character classes. (These
-definitions are those that Perl uses in ASCII mode with the C</a> modifier.
-See L<perlrecharclass/Backslash sequences> for details.)
+definitions are those that Perl uses in ASCII-safe mode with the C</a> modifier.
+Otherwise they could match many more non-ASCII Unicode characters as
+well. See L<perlrecharclass/Backslash sequences> for details.)
=over 4
Property changes on: trunk/contrib/perl/pod/perlrequick.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlreref.pod
===================================================================
--- trunk/contrib/perl/pod/perlreref.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlreref.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -107,6 +107,7 @@
\u Titlecase next character
\L Lowercase until \E
\U Uppercase until \E
+ \F Foldcase until \E
\Q Disable pattern metacharacters until \E
\E End modification
@@ -135,7 +136,7 @@
\S A non-whitespace character
\h An horizontal whitespace
\H A non horizontal whitespace
- \N A non newline (when not followed by '{NAME}'; experimental;
+ \N A non newline (when not followed by '{NAME}';;
not valid in a character class; equivalent to [^\n]; it's
like '.' without /s modifier)
\v A vertical whitespace
@@ -176,7 +177,7 @@
space PosixSpace XPosixSpace [\s\cK]
PerlSpace XPerlSpace \s Perl's whitespace def'n
upper PosixUpper XPosixUpper Uppercase characters
- word PerlWord XPosixWord \w Alnum + Unicode marks +
+ word PosixWord XPosixWord \w Alnum + Unicode marks +
connectors, like '_'
(Perl extension)
xdigit ASCII_Hex_Digit XPosixDigit Hexadecimal digit,
@@ -299,6 +300,7 @@
lcfirst Lowercase first char of a string
uc Uppercase a string
ucfirst Titlecase first char of a string
+ fc Foldcase a string
pos Return or set current match position
quotemeta Quote metacharacters
@@ -307,8 +309,9 @@
split Use a regex to split a string into parts
-The first four of these are like the escape sequences C<\L>, C<\l>,
-C<\U>, and C<\u>. For Titlecase, see L</Titlecase>.
+The first five of these are like the escape sequences C<\L>, C<\l>,
+C<\U>, C<\u>, and C<\F>. For Titlecase, see L</Titlecase>; For
+Foldcase, see L</Foldcase>.
=head2 TERMINOLOGY
@@ -317,6 +320,12 @@
Unicode concept which most often is equal to uppercase, but for
certain characters like the German "sharp s" there is a difference.
+=head3 Foldcase
+
+Unicode form that is useful when comparing strings regardless of case,
+as certain characters have compex one-to-many case mappings. Primarily a
+variant of lowercase.
+
=head1 AUTHOR
Iain Truskett. Updated by the Perl 5 Porters.
Property changes on: trunk/contrib/perl/pod/perlreref.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlretut.pod
===================================================================
--- trunk/contrib/perl/pod/perlretut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlretut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -781,7 +781,7 @@
=head2 Relative backreferences
Counting the opening parentheses to get the correct number for a
-backreference is errorprone as soon as there is more than one
+backreference is error-prone as soon as there is more than one
capturing group. A more convenient technique became available
with Perl 5.10: relative backreferences. To refer to the immediately
preceding capture group one now may write C<\g{-1}>, the next but
@@ -869,7 +869,7 @@
=head2 Position information
-In addition to what was matched, Perl (since 5.6.0) also provides the
+In addition to what was matched, Perl also provides the
positions of what was matched as contents of the C<@-> and C<@+>
arrays. C<$-[0]> is the position of the start of the entire match and
C<$+[0]> is the position of the end. Similarly, C<$-[n]> is the
@@ -1537,7 +1537,7 @@
=head3 Global matching
-The final two modifiers we will disccuss here,
+The final two modifiers we will discuss here,
C<//g> and C<//c>, concern multiple matches.
The modifier C<//g> stands for global matching and allows the
matching operator to match within a string as many times as possible.
@@ -1583,9 +1583,9 @@
we wanted just the words, we could use
@words = ($x =~ /(\w+)/g); # matches,
- # $word[0] = 'cat'
- # $word[1] = 'dog'
- # $word[2] = 'house'
+ # $words[0] = 'cat'
+ # $words[1] = 'dog'
+ # $words[2] = 'house'
Closely associated with the C<//g> modifier is the C<\G> anchor. The
C<\G> anchor matches at the point where the previous C<//g> match left
@@ -1654,7 +1654,7 @@
desired.
(There are other regexp modifiers that are available, such as
-C<//o>, C<//d>, and C<//l>, but their specialized uses are beyond the
+C<//o>, but their specialized uses are beyond the
scope of this introduction. )
=head3 Search and replace
@@ -1870,12 +1870,12 @@
C<\Q>, C<\L>, C<\l>, C<\U>, C<\u> and C<\E> are actually part of
double-quotish syntax, and not part of regexp syntax proper. They will
-work if they appear in a regular expression embeddded directly in a
+work if they appear in a regular expression embedded directly in a
program, but not when contained in a string that is interpolated in a
pattern.
-With the advent of 5.6.0, Perl regexps can handle more than just the
-standard ASCII character set. Perl now supports I<Unicode>, a standard
+Perl regexps can handle more than just the
+standard ASCII character set. Perl supports I<Unicode>, a standard
for representing the alphabets from virtually all of the world's written
languages, and a host of symbols. Perl's text strings are Unicode strings, so
they can contain characters with a value (codepoint or character number) higher
@@ -1907,32 +1907,32 @@
represent or match the astrological sign for the planet Mercury, we
could use
- use charnames ":full"; # use named chars with Unicode full names
$x = "abc\N{MERCURY}def";
$x =~ /\N{MERCURY}/; # matches
-One can also use short names or restrict names to a certain alphabet:
+One can also use "short" names:
- use charnames ':full';
print "\N{GREEK SMALL LETTER SIGMA} is called sigma.\n";
-
- use charnames ":short";
print "\N{greek:Sigma} is an upper-case sigma.\n";
+You can also restrict names to a certain alphabet by specifying the
+L<charnames> pragma:
+
use charnames qw(greek);
print "\N{sigma} is Greek sigma\n";
-A list of full names can be found in F<NamesList.txt> in the Unicode standard
-(available at L<http://www.unicode.org/Public/UNIDATA/>).
+An index of character names is available on-line from the Unicode
+Consortium, L<http://www.unicode.org/charts/charindex.html>; explanatory
+material with links to other resources at
+L<http://www.unicode.org/standard/where>.
-The answer to requirement 2), as of 5.6.0, is that a regexp (mostly)
-uses Unicode characters. (For messy backward compatibility reasons,
-most but not all semantics of a match will assume Unicode, unless,
-starting in Perl 5.14, you tell it to use full Unicode. You can do this
-explicitly by using the C<//u> modifier, or you can ask Perl to use the
-modifier implicitly for all regexes in a scope by using C<use 5.012> (or
-higher) or C<use feature 'unicode_strings'>.) If you want to handle
-Unicode properly, you should ensure that one of these is the case.)
+The answer to requirement 2) is that a regexp (mostly)
+uses Unicode characters. The "mostly" is for messy backward
+compatibility reasons, but starting in Perl 5.14, any regex compiled in
+the scope of a C<use feature 'unicode_strings'> (which is automatically
+turned on within the scope of a C<use 5.012> or higher) will turn that
+"mostly" into "always". If you want to handle Unicode properly, you
+should ensure that C<'unicode_strings'> is turned on.
Internally, this is encoded to bytes using either UTF-8 or a native 8
bit encoding, depending on the history of the string, but conceptually
it is a sequence of characters, not bytes. See L<perlunitut> for a
@@ -1944,7 +1944,6 @@
character class, which is the negation of the C<\p{name}> class. For
example, to match lower and uppercase characters,
- use charnames ":full"; # use named chars with Unicode full names
$x = "BOB";
$x =~ /^\p{IsUpper}/; # matches, uppercase char class
$x =~ /^\P{IsUpper}/; # doesn't match, char class sans uppercase
@@ -2619,23 +2618,23 @@
code expression, we don't need the extra parentheses around the
conditional.
-If you try to use code expressions with interpolating variables, Perl
-may surprise you:
+If you try to use code expressions where the code text is contained within
+an interpolated variable, rather than appearing literally in the pattern,
+Perl may surprise you:
$bar = 5;
$pat = '(?{ 1 })';
/foo(?{ $bar })bar/; # compiles ok, $bar not interpolated
- /foo(?{ 1 })$bar/; # compile error!
+ /foo(?{ 1 })$bar/; # compiles ok, $bar interpolated
/foo${pat}bar/; # compile error!
$pat = qr/(?{ $foo = 1 })/; # precompile code regexp
/foo${pat}bar/; # compiles ok
-If a regexp has (1) code expressions and interpolating variables, or
-(2) a variable that interpolates a code expression, Perl treats the
-regexp as an error. If the code expression is precompiled into a
-variable, however, interpolating is ok. The question is, why is this
-an error?
+If a regexp has a variable that interpolates a code expression, Perl
+treats the regexp as an error. If the code expression is precompiled into
+a variable, however, interpolating is ok. The question is, why is this an
+error?
The reason is that variable interpolation and code expressions
together pose a security risk. The combination is dangerous because
@@ -2658,7 +2657,6 @@
use re 'eval'; # throw caution out the door
$bar = 5;
$pat = '(?{ 1 })';
- /foo(?{ 1 })$bar/; # compiles ok
/foo${pat}bar/; # compiles ok
Another form of code expression is the I<pattern code expression>.
@@ -2699,8 +2697,9 @@
Note that the variables C<$z0> and C<$z1> are not substituted when the
regexp is compiled, as happens for ordinary variables outside a code
-expression. Rather, the code expressions are evaluated when Perl
-encounters them during the search for a match.
+expression. Rather, the whole code block is parsed as perl code at the
+same time as perl is compiling the code containing the literal regexp
+pattern.
The regexp without the C<//x> modifier is
@@ -2732,7 +2731,7 @@
combination with embedded code.
%count = ();
- "supercalifragilisticexpialidoceous" =~
+ "supercalifragilisticexpialidocious" =~
/([aeiou])(?{ $count{$1}++; })(*FAIL)/i;
printf "%3d '%s'\n", $count{$_}, $_ for (sort keys %count);
@@ -2745,7 +2744,7 @@
regexp engine proceeds until the entire string has been inspected.
(It's remarkable that an alternative solution using something like
- $count{lc($_)}++ for split('', "supercalifragilisticexpialidoceous");
+ $count{lc($_)}++ for split('', "supercalifragilisticexpialidocious");
printf "%3d '%s'\n", $count2{$_}, $_ for ( qw{ a e i o u } );
is considerably slower.)
@@ -2776,7 +2775,8 @@
The C<re '/flags'> pragma (introduced in Perl
5.14) turns on the given regular expression flags
-until the end of the lexical scope. See C<re/"'/flags' mode"> for more
+until the end of the lexical scope. See
+L<re/"'E<sol>flags' mode"> for more
detail.
use re 'debug';
@@ -2792,7 +2792,7 @@
termcap color sequences. Here is example output:
% perl -e 'use re "debug"; "abc" =~ /a*b+c/;'
- Compiling REx `a*b+c'
+ Compiling REx 'a*b+c'
size 9 first at 1
1: STAR(4)
2: EXACT <a>(0)
@@ -2800,11 +2800,11 @@
5: EXACT <b>(0)
7: EXACT <c>(9)
9: END(0)
- floating `bc' at 0..2147483647 (checking floating) minlen 2
- Guessing start of match, REx `a*b+c' against `abc'...
- Found floating substr `bc' at offset 1...
+ floating 'bc' at 0..2147483647 (checking floating) minlen 2
+ Guessing start of match, REx 'a*b+c' against 'abc'...
+ Found floating substr 'bc' at offset 1...
Guessed: match at offset 0
- Matching REx `a*b+c' against `abc'
+ Matching REx 'a*b+c' against 'abc'
Setting an EVAL scope, savestack=3
0 <> <abc> | 1: STAR
EXACT <a> can match 1 times out of 32767...
@@ -2815,13 +2815,13 @@
2 <ab> <c> | 7: EXACT <c>
3 <abc> <> | 9: END
Match successful!
- Freeing REx: `a*b+c'
+ Freeing REx: 'a*b+c'
If you have gotten this far into the tutorial, you can probably guess
what the different parts of the debugging output tell you. The first
part
- Compiling REx `a*b+c'
+ Compiling REx 'a*b+c'
size 9 first at 1
1: STAR(4)
2: EXACT <a>(0)
@@ -2835,15 +2835,15 @@
i.e., C<PLUS(7)>. The middle lines describe some heuristics and
optimizations performed before a match:
- floating `bc' at 0..2147483647 (checking floating) minlen 2
- Guessing start of match, REx `a*b+c' against `abc'...
- Found floating substr `bc' at offset 1...
+ floating 'bc' at 0..2147483647 (checking floating) minlen 2
+ Guessing start of match, REx 'a*b+c' against 'abc'...
+ Found floating substr 'bc' at offset 1...
Guessed: match at offset 0
Then the match is executed and the remaining lines describe the
process:
- Matching REx `a*b+c' against `abc'
+ Matching REx 'a*b+c' against 'abc'
Setting an EVAL scope, savestack=3
0 <> <abc> | 1: STAR
EXACT <a> can match 1 times out of 32767...
@@ -2854,7 +2854,7 @@
2 <ab> <c> | 7: EXACT <c>
3 <abc> <> | 9: END
Match successful!
- Freeing REx: `a*b+c'
+ Freeing REx: 'a*b+c'
Each step is of the form S<C<< n <x> <y> >>>, with C<< <x> >> the
part of the string matched and C<< <y> >> the part not yet
Property changes on: trunk/contrib/perl/pod/perlretut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlrun.pod
===================================================================
--- trunk/contrib/perl/pod/perlrun.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlrun.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -90,14 +90,15 @@
The examples above use a relative path to the perl interpreter,
getting whatever version is first in the user's path. If you want
-a specific version of Perl, say, perl5.005_57, you should place
+a specific version of Perl, say, perl5.14.1, you should place
that directly in the C<#!> line's path.
-If the C<#!> line does not contain the word "perl", the program named after
-the C<#!> is executed instead of the Perl interpreter. This is slightly
-bizarre, but it helps people on machines that don't do C<#!>, because they
-can tell a program that their SHELL is F</usr/bin/perl>, and Perl will then
-dispatch the program to the correct interpreter for them.
+If the C<#!> line does not contain the word "perl" nor the word "indir"
+the program named after the C<#!> is executed instead of the Perl
+interpreter. This is slightly bizarre, but it helps people on machines
+that don't do C<#!>, because they can tell a program that their SHELL is
+F</usr/bin/perl>, and Perl will then dispatch the program to the correct
+interpreter for them.
After locating your program, Perl compiles the entire program to an
internal form. If there are any compilation errors, execution of the
@@ -143,8 +144,8 @@
Put
- $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
- $ exit++ + ++$status != 0 and $exit = $status = undef;
+ $ perl -mysw 'f$env("procedure")' 'p1' 'p2' 'p3' 'p4' 'p5' 'p6' 'p7' 'p8' !
+ $ exit++ + ++$status != 0 and $exit = $status = undef;
at the top of your program, where B<-mysw> are any command line switches you
want to pass to Perl. You can now invoke the program directly, by saying
@@ -160,7 +161,7 @@
on quoting than Unix shells. You'll need to learn the special
characters in your command-interpreter (C<*>, C<\> and C<"> are
common) and how to protect whitespace and these characters to run
-one-liners (see B<-e> below).
+one-liners (see L<-e|/-e commandline> below).
On some systems, you may have to change single-quotes to double ones,
which you must I<not> do on Unix or Plan 9 systems. You might also
@@ -204,12 +205,12 @@
will stand in for whatever method works on your system. You are
advised to use a specific path if you care about a specific version.
- #!/usr/local/bin/perl5.00554
+ #!/usr/local/bin/perl5.14
or if you just want to be running at least version, place a statement
like this at the top of your program:
- use 5.005_54;
+ use 5.014;
=head2 Command Switches
X<perl, command switches> X<command switches>
@@ -282,13 +283,13 @@
D 24 i + o
A 32 the @ARGV elements are expected to be strings encoded
in UTF-8
- L 64 normally the "IOEioA" are unconditional,
- the L makes them conditional on the locale environment
- variables (the LC_ALL, LC_TYPE, and LANG, in the order
- of decreasing precedence) -- if the variables indicate
+ L 64 normally the "IOEioA" are unconditional, the L makes
+ them conditional on the locale environment variables
+ (the LC_ALL, LC_TYPE, and LANG, in the order of
+ decreasing precedence) -- if the variables indicate
UTF-8, then the selected "IOEioA" are in effect
- a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching code in
- debugging mode.
+ a 256 Set ${^UTF8CACHE} to -1, to run the UTF-8 caching
+ code in debugging mode.
=for documenting_the_underdocumented
perl.h gives W/128 as PERL_UNICODE_WIDESYSCALLS "/* for Sarathy */"
@@ -314,6 +315,7 @@
the default C<open()> layer are UTF-8-fied I<but> only if the locale
environment variables indicate a UTF-8 locale. This behaviour follows
the I<implicit> (and problematic) UTF-8 behaviour of Perl 5.8.0.
+(See L<perl581delta/UTF-8 no longer default under UTF-8 locales>.)
You can use B<-C0> (or C<"0"> for C<PERL_UNICODE>) to explicitly
disable all the above Unicode features.
@@ -393,19 +395,25 @@
512 r Regular expression parsing and execution
1024 x Syntax tree dump
2048 u Tainting checks
- 4096 U Unofficial, User hacking (reserved for private, unreleased use)
+ 4096 U Unofficial, User hacking (reserved for private,
+ unreleased use)
8192 H Hash dump -- usurps values()
16384 X Scratchpad allocation
32768 D Cleaning up
+ 65536 S Op slab allocation
131072 T Tokenizing
- 262144 R Include reference counts of dumped variables (eg when using -Ds)
- 524288 J show s,t,P-debug (don't Jump over) on opcodes within package DB
+ 262144 R Include reference counts of dumped variables (eg when
+ using -Ds)
+ 524288 J show s,t,P-debug (don't Jump over) on opcodes within
+ package DB
1048576 v Verbose: use in conjunction with other flags
2097152 C Copy On Write
4194304 A Consistency checks on internal structures
- 8388608 q quiet - currently only suppresses the "EXECUTING" message
+ 8388608 q quiet - currently only suppresses the "EXECUTING"
+ message
16777216 M trace smart match resolution
- 33554432 B dump suBroutine definitions, including special Blocks like BEGIN
+ 33554432 B dump suBroutine definitions, including special Blocks
+ like BEGIN
All these flags require B<-DDEBUGGING> when you compile the Perl
executable (but see C<:opd> in L<Devel::Peek> or L<re/'debug' mode>
@@ -498,8 +506,10 @@
modify the name of the old file to make a backup copy, following these
rules:
-If no extension is supplied, no backup is made and the current file is
-overwritten.
+If no extension is supplied, and your system supports it, the original
+I<file> is kept open without a name while the output is redirected to
+a new file with the original I<filename>. When perl exits, cleanly or not,
+the original I<file> is unlinked.
If the extension doesn't contain a C<*>, then it is appended to the
end of the current filename as a suffix. If the extension does
@@ -512,20 +522,22 @@
This allows you to add a prefix to the backup file, instead of (or in
addition to) a suffix:
- $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to 'orig_fileA'
+ $ perl -pi'orig_*' -e 's/bar/baz/' fileA # backup to
+ # 'orig_fileA'
Or even to place backup copies of the original files into another
directory (provided the directory already exists):
- $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to 'old/fileA.orig'
+ $ perl -pi'old/*.orig' -e 's/bar/baz/' fileA # backup to
+ # 'old/fileA.orig'
These sets of one-liners are equivalent:
- $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
+ $ perl -pi -e 's/bar/baz/' fileA # overwrite current file
+ $ perl -pi'*' -e 's/bar/baz/' fileA # overwrite current file
- $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
- $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
+ $ perl -pi'*.orig' -e 's/bar/baz/' fileA # backup to 'fileA.orig'
From the shell, saying
@@ -669,7 +681,7 @@
... # your program goes here
}
-Note that the lines are not printed by default. See B<-p> to have
+Note that the lines are not printed by default. See L</-p> to have
lines printed. If a file named by an argument cannot be opened for
some reason, Perl warns you about it and moves on to the next file.
@@ -967,9 +979,13 @@
A list of directories in which to look for Perl library
files before looking in the standard library and the current
-directory. Any architecture-specific directories under the specified
-locations are automatically included if they exist, with this lookup
-done at interpreter startup time.
+directory. Any architecture-specific and version-specific directories,
+such as F<version/archname/>, F<version/>, or F<archname/> under the
+specified locations are automatically included if they exist, with this
+lookup done at interpreter startup time. In addition, any directories
+matching the entries in C<$Config{inc_version_list}> are added.
+(These typically would be for older compatible perl versions installed
+in the same directory tree.)
If PERL5LIB is not defined, PERLLIB is used. Directories are separated
(like in PATH) by a colon on Unixish platforms and by a semicolon on
@@ -990,7 +1006,7 @@
switches are allowed. When running taint checks (either because the
program was running setuid or setgid, or because the B<-T> or B<-t>
switch was used), this variable is ignored. If PERL5OPT begins with
-B<- T>, tainting will be enabled and subsequent options ignored. If
+B<-T>, tainting will be enabled and subsequent options ignored. If
PERL5OPT begins with B<-t>, tainting will be enabled, a writable dot
removed from @INC, and subsequent options honored.
@@ -1002,7 +1018,7 @@
It is conventional to start layer names with a colon (for example, C<:perlio>) to
emphasize their similarity to variable "attributes". But the code that parses
-layer specification strings, which is also used to decode the PERLIO
+layer specification strings, which is also used to decode the PERLIO
environment variable, treats the colon as a separator.
An unset or empty PERLIO is equivalent to the default set of layers for
@@ -1011,7 +1027,7 @@
The list becomes the default for I<all> Perl's IO. Consequently only built-in
layers can appear in this list, as external layers (such as C<:encoding()>) need
-IO in order to load them!. See L<"open pragma"|open> for how to add external
+IO in order to load them! See L<"open pragma"|open> for how to add external
encodings as defaults.
Layers it makes sense to include in the PERLIO environment
@@ -1124,7 +1140,7 @@
X<PERLIO_DEBUG>
If set to the name of a file or device, certain operations of PerlIO
-subsystem will be logged to that file, which is opened in append mode
+subsystem will be logged to that file, which is opened in append mode.
Typical uses are in Unix:
% env PERLIO_DEBUG=/dev/tty perl script ...
@@ -1235,46 +1251,71 @@
=item PERL_HASH_SEED
X<PERL_HASH_SEED>
-(Since Perl 5.8.1.) Used to randomize Perl's internal hash function.
-To emulate the pre-5.8.1 behaviour, set to an integer; C<"0"> means
-exactly the same order as in 5.8.0. "Pre-5.8.1" means, among other
-things, that hash keys will always have the same ordering between
-different runs of Perl.
+(Since Perl 5.8.1, new semantics in Perl 5.18.0) Used to override
+the randomization of Perl's internal hash function. The value is expressed
+in hexadecimal, and may include a leading 0x. Truncated patterns
+are treated as though they are suffixed with sufficient 0's as required.
-Most hashes by default return elements in the same order as in Perl 5.8.0.
-On a hash by hash basis, if pathological data is detected during a hash
-key insertion, then that hash will switch to an alternative random hash
-seed.
+If the option is provided, and C<PERL_PERTURB_KEYS> is NOT set, then
+a value of '0' implies C<PERL_PERTURB_KEYS=0> and any other value
+implies C<PERL_PERTURB_KEYS=2>.
-The default behaviour is to randomize unless the PERL_HASH_SEED is set.
-If Perl has been compiled with B<-DUSE_HASH_SEED_EXPLICIT>, the default
-behaviour is I<not> to randomize unless the PERL_HASH_SEED is set.
-
-If PERL_HASH_SEED is unset or set to a non-numeric string, Perl uses
-the pseudorandom seed supplied by the operating system and libraries.
-
B<PLEASE NOTE: The hash seed is sensitive information>. Hashes are
randomized to protect against local and remote attacks against Perl
code. By manually setting a seed, this protection may be partially or
completely lost.
-See L<perlsec/"Algorithmic Complexity Attacks"> and
+See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_PERTURB_KEYS>
L</PERL_HASH_SEED_DEBUG> for more information.
+=item PERL_PERTURB_KEYS
+X<PERL_PERTURB_KEYS>
+
+(Since Perl 5.18.0) Set to C<"0"> or C<"NO"> then traversing keys
+will be repeatable from run to run for the same PERL_HASH_SEED.
+Insertion into a hash will not change the order, except to provide
+for more space in the hash. When combined with setting PERL_HASH_SEED
+this mode is as close to pre 5.18 behavior as you can get.
+
+When set to C<"1"> or C<"RANDOM"> then traversing keys will be randomized.
+Every time a hash is inserted into the key order will change in a random
+fashion. The order may not be repeatable in a following program run
+even if the PERL_HASH_SEED has been specified. This is the default
+mode for perl.
+
+When set to C<"2"> or C<"DETERMINISTIC"> then inserting keys into a hash
+will cause the key order to change, but in a way that is repeatable
+from program run to program run.
+
+B<NOTE:> Use of this option is considered insecure, and is intended only
+for debugging non-deterministic behavior in Perl's hash function. Do
+not use it in production.
+
+See L<perlsec/"Algorithmic Complexity Attacks"> and L</PERL_HASH_SEED>
+and L</PERL_HASH_SEED_DEBUG> for more information. You can get and set the
+key traversal mask for a specific hash by using the C<hash_traversal_mask()>
+function from L<Hash::Util>.
+
=item PERL_HASH_SEED_DEBUG
X<PERL_HASH_SEED_DEBUG>
-(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) the value of
-the hash seed at the beginning of execution. This, combined with
-L</PERL_HASH_SEED> is intended to aid in debugging nondeterministic
-behaviour caused by hash randomization.
+(Since Perl 5.8.1.) Set to C<"1"> to display (to STDERR) information
+about the hash function, seed, and what type of key traversal
+randomization is in effect at the beginning of execution. This, combined
+with L</PERL_HASH_SEED> and L</PERL_PERTURB_KEYS> is intended to aid in
+debugging nondeterministic behaviour caused by hash randomization.
-B<Note that the hash seed is sensitive information>: by knowing it, one
-can craft a denial-of-service attack against Perl code, even remotely;
-see L<perlsec/"Algorithmic Complexity Attacks"> for more information.
-B<Do not disclose the hash seed> to people who don't need to know it.
-See also hash_seed() in L<Hash::Util>.
+B<Note> that any information about the hash function, especially the hash
+seed is B<sensitive information>: by knowing it, one can craft a denial-of-service
+attack against Perl code, even remotely; see L<perlsec/"Algorithmic Complexity Attacks">
+for more information. B<Do not disclose the hash seed> to people who
+don't need to know it. See also C<hash_seed()> and
+C<key_traversal_mask()> in L<Hash::Util>.
+An example output might be:
+
+ HASH_FUNCTION = ONE_AT_A_TIME_HARD HASH_SEED = 0x652e9b9349a7a032 PERTURB_KEYS = 1 (RANDOM)
+
=item PERL_MEM_LOG
X<PERL_MEM_LOG>
Property changes on: trunk/contrib/perl/pod/perlrun.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.4
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlsec.pod
===================================================================
--- trunk/contrib/perl/pod/perlsec.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlsec.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -93,7 +93,7 @@
For example:
$arg = shift; # $arg is tainted
- $hid = $arg, 'bar'; # $hid is also tainted
+ $hid = $arg . 'bar'; # $hid is also tainted
$line = <>; # Tainted
$line = <STDIN>; # Also tainted
open FOO, "/home/me/bar" or die $!;
@@ -134,10 +134,8 @@
@files = <*.c>; # insecure (uses readdir() or similar)
@files = glob('*.c'); # insecure (uses readdir() or similar)
- # In Perl releases older than 5.6.0 the <*.c> and glob('*.c') would
- # have used an external program to do the filename expansion; but in
- # either case the result is tainted since the list of filenames comes
- # from outside of the program.
+ # In either case, the results of glob are tainted, since the list of
+ # filenames comes from outside of the program.
$bad = ($arg, 23); # $bad will be tainted
$arg, `true`; # Insecure (although it isn't really)
@@ -170,6 +168,7 @@
Or you may be able to use the following C<is_tainted()> function.
sub is_tainted {
+ local $@; # Don't pollute caller's value.
return ! eval { eval("#" . substr(join("", @_), 0, 0)); 1 };
}
@@ -455,41 +454,84 @@
=item *
-Hash Function - the algorithm used to "order" hash elements has been
-changed several times during the development of Perl, mainly to be
-reasonably fast. In Perl 5.8.1 also the security aspect was taken
-into account.
+Hash Algorithm - Hash algorithms like the one used in Perl are well
+known to be vulnerable to collision attacks on their hash function.
+Such attacks involve constructing a set of keys which collide into
+the same bucket producing inefficient behavior. Such attacks often
+depend on discovering the seed of the hash function used to map the
+keys to buckets. That seed is then used to brute-force a key set which
+can be used to mount a denial of service attack. In Perl 5.8.1 changes
+were introduced to harden Perl to such attacks, and then later in
+Perl 5.18.0 these features were enhanced and additional protections
+added.
-In Perls before 5.8.1 one could rather easily generate data that as
-hash keys would cause Perl to consume large amounts of time because
-internal structure of hashes would badly degenerate. In Perl 5.8.1
-the hash function is randomly perturbed by a pseudorandom seed which
-makes generating such naughty hash keys harder.
-See L<perlrun/PERL_HASH_SEED> for more information.
+At the time of this writing, Perl 5.18.0 is considered to be
+well-hardened against algorithmic complexity attacks on its hash
+implementation. This is largely owed to the following measures
+mitigate attacks:
-In Perl 5.8.1 the random perturbation was done by default, but as of
-5.8.2 it is only used on individual hashes if the internals detect the
-insertion of pathological data. If one wants for some reason emulate the
-old behaviour (and expose oneself to DoS attacks) one can set the
-environment variable PERL_HASH_SEED to zero to disable the protection
-(or any other integer to force a known perturbation, rather than random).
-One possible reason for wanting to emulate the old behaviour is that in the
-new behaviour consecutive runs of Perl will order hash keys differently,
-which may confuse some applications (like Data::Dumper: the outputs of two
-different runs are no longer identical).
+=over 4
-B<Perl has never guaranteed any ordering of the hash keys>, and the
-ordering has already changed several times during the lifetime of
-Perl 5. Also, the ordering of hash keys has always been, and
-continues to be, affected by the insertion order.
+=item Hash Seed Randomization
+In order to make it impossible to know what seed to generate an attack
+key set for, this seed is randomly initialized at process start. This
+may be overridden by using the PERL_HASH_SEED environment variable, see
+L<perlrun/PERL_HASH_SEED>. This environment variable controls how
+items are actually stored, not how they are presented via
+C<keys>, C<values> and C<each>.
+
+=item Hash Traversal Randomization
+
+Independent of which seed is used in the hash function, C<keys>,
+C<values>, and C<each> return items in a per-hash randomized order.
+Modifying a hash by insertion will change the iteration order of that hash.
+This behavior can be overridden by using C<hash_traversal_mask()> from
+L<Hash::Util> or by using the PERL_PERTURB_KEYS environment variable,
+see L<perlrun/PERL_PERTURB_KEYS>. Note that this feature controls the
+"visible" order of the keys, and not the actual order they are stored in.
+
+=item Bucket Order Perturbance
+
+When items collide into a given hash bucket the order they are stored in
+the chain is no longer predictable in Perl 5.18. This has the intention
+to make it harder to observe a collisions. This behavior can be overridden by using
+the PERL_PERTURB_KEYS environment variable, see L<perlrun/PERL_PERTURB_KEYS>.
+
+=item New Default Hash Function
+
+The default hash function has been modified with the intention of making
+it harder to infer the hash seed.
+
+=item Alternative Hash Functions
+
+The source code includes multiple hash algorithms to choose from. While we
+believe that the default perl hash is robust to attack, we have included the
+hash function Siphash as a fall-back option. At the time of release of
+Perl 5.18.0 Siphash is believed to be of cryptographic strength. This is
+not the default as it is much slower than the default hash.
+
+=back
+
+Without compiling a special Perl, there is no way to get the exact same
+behavior of any versions prior to Perl 5.18.0. The closest one can get
+is by setting PERL_PERTURB_KEYS to 0 and setting the PERL_HASH_SEED
+to a known value. We do not advise those settings for production use
+due to the above security considerations.
+
+B<Perl has never guaranteed any ordering of the hash keys>, and
+the ordering has already changed several times during the lifetime of
+Perl 5. Also, the ordering of hash keys has always been, and continues
+to be, affected by the insertion order and the history of changes made
+to the hash over its lifetime.
+
Also note that while the order of the hash elements might be
-randomised, this "pseudoordering" should B<not> be used for
-applications like shuffling a list randomly (use List::Util::shuffle()
+randomized, this "pseudo-ordering" should B<not> be used for
+applications like shuffling a list randomly (use C<List::Util::shuffle()>
for that, see L<List::Util>, a standard core module since Perl 5.8.0;
-or the CPAN module Algorithm::Numerical::Shuffle), or for generating
-permutations (use e.g. the CPAN modules Algorithm::Permute or
-Algorithm::FastPermute), or for any cryptographic applications.
+or the CPAN module C<Algorithm::Numerical::Shuffle>), or for generating
+permutations (use e.g. the CPAN modules C<Algorithm::Permute> or
+C<Algorithm::FastPermute>), or for any cryptographic applications.
=item *
Property changes on: trunk/contrib/perl/pod/perlsec.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlsource.pod
===================================================================
--- trunk/contrib/perl/pod/perlsource.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlsource.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -10,18 +10,21 @@
=head1 DESCRIPTION
-This document describes the layout of the Perl source tree. If you're hacking
-on the Perl core, this will help you find what you're looking for.
+This document describes the layout of the Perl source tree. If you're
+hacking on the Perl core, this will help you find what you're looking
+for.
=head1 FINDING YOUR WAY AROUND
-The Perl source tree is big. Here's some of the thing you'll find in it:
+The Perl source tree is big. Here's some of the thing you'll find in
+it:
=head2 C code
-The C source code and header files mostly live in the root of the source
-tree. There are a few platform-specific directories which contain C code. In
-addition, some of the modules shipped with Perl include C or XS code.
+The C source code and header files mostly live in the root of the
+source tree. There are a few platform-specific directories which
+contain C code. In addition, some of the modules shipped with Perl
+include C or XS code.
See L<perlinterp> for more details on the files that make up the Perl
interpreter, as well as details on how it works.
@@ -28,57 +31,58 @@
=head2 Core modules
-Modules shipped as part of the Perl core live in four subdirectories. Two of
-these directories contain modules that live in the core, and two contain
-modules that can also be released separately on CPAN. Modules which can be
-released on cpan are known as "dual-life" modules.
+Modules shipped as part of the Perl core live in four subdirectories.
+Two of these directories contain modules that live in the core, and two
+contain modules that can also be released separately on CPAN. Modules
+which can be released on cpan are known as "dual-life" modules.
=over 4
=item * F<lib/>
-This directory contains pure-Perl modules which are only released as part of
-the core. This directory contains I<all> of the modules and their tests,
-unlike other core modules.
+This directory contains pure-Perl modules which are only released as
+part of the core. This directory contains I<all> of the modules and
+their tests, unlike other core modules.
=item * F<ext/>
-This directory contains XS-using modules which are only released as part of
-the core. These modules generally have their F<Makefile.PL> and are laid out
-more like a typical CPAN module.
+This directory contains XS-using modules which are only released as
+part of the core. These modules generally have their F<Makefile.PL> and
+are laid out more like a typical CPAN module.
=item * F<dist/>
This directory is for dual-life modules where the blead source is
-canonical. Note that some modules in this directory may not yet have been
-released separately on CPAN.
+canonical. Note that some modules in this directory may not yet have
+been released separately on CPAN.
=item * F<cpan/>
This directory contains dual-life modules where the CPAN module is
-canonical. Do not patch these modules directly! Changes to these modules
-should be submitted to the maintainer of the CPAN module. Once those changes
-are applied and released, the new version of the module will be incorporated
-into the core.
+canonical. Do not patch these modules directly! Changes to these
+modules should be submitted to the maintainer of the CPAN module. Once
+those changes are applied and released, the new version of the module
+will be incorporated into the core.
=back
-For some dual-life modules, it has not yet been determined if the CPAN version
-or the blead source is canonical. Until that is done, those modules should be
-in F<cpan/>.
+For some dual-life modules, it has not yet been determined if the CPAN
+version or the blead source is canonical. Until that is done, those
+modules should be in F<cpan/>.
=head2 Tests
The Perl core has an extensive test suite. If you add new tests (or new
-modules with tests), you may need to update the F<t/TEST> file so that the
-tests are run.
+modules with tests), you may need to update the F<t/TEST> file so that
+the tests are run.
=over 4
=item * Module tests
-Tests for core modules in the F<lib/> directory are right next to the module
-itself. For example, we have F<lib/strict.pm> and F<lib/strict.t>.
+Tests for core modules in the F<lib/> directory are right next to the
+module itself. For example, we have F<lib/strict.pm> and
+F<lib/strict.t>.
Tests for modules in F<ext/> and the dual-life modules are in F<t/>
subdirectories for each module, like a standard CPAN distribution.
@@ -85,14 +89,15 @@
=item * F<t/base/>
-Tests for the absolute basic functionality of Perl. This includes C<if>, basic
-file reads and writes, simple regexes, etc. These are run first in the test
-suite and if any of them fail, something is I<really> broken.
+Tests for the absolute basic functionality of Perl. This includes
+C<if>, basic file reads and writes, simple regexes, etc. These are run
+first in the test suite and if any of them fail, something is I<really>
+broken.
=item * F<t/cmd/>
-Tests for basic control structures, C<if/else>, C<while>,
-subroutines, etc.
+Tests for basic control structures, C<if/else>, C<while>, subroutines,
+etc.
=item * F<t/comp/>
@@ -111,6 +116,13 @@
Tests for perl's built in functions that don't fit into any of the
other directories.
+=item * F<t/opbasic/>
+
+Tests for perl's built in functions which, like those in F<t/op/>, do not fit
+into any of the other directories, but which, in addition, cannot use
+F<t/test.pl>,as that program depends on functionality which the
+test file itself is testing.
+
=item * F<t/re/>
Tests for regex related functions or behaviour. (These used to live in
@@ -131,9 +143,9 @@
=item * F<t/porting/>
-Tests the state of the source tree for various common errors. For example, it
-tests that everyone who is listed in the git log has a corresponding entry in
-the F<AUTHORS> file.
+Tests the state of the source tree for various common errors. For
+example, it tests that everyone who is listed in the git log has a
+corresponding entry in the F<AUTHORS> file.
=item * F<t/lib/>
@@ -149,15 +161,15 @@
=head2 Documentation
-All of the core documentation intended for end users lives in
-F<pod/>. Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/>
-usually have their own documentation, either in the F<Module.pm> file or an
+All of the core documentation intended for end users lives in F<pod/>.
+Individual modules in F<lib/>, F<ext/>, F<dist/>, and F<cpan/> usually
+have their own documentation, either in the F<Module.pm> file or an
accompanying F<Module.pod> file.
Finally, documentation intended for core Perl developers lives in the
F<Porting/> directory.
-=head2 Hacking toolks and documentation
+=head2 Hacking tools and documentation
The F<Porting> directory contains a grab bag of code and documentation
intended to help porters work on Perl. Some of the highlights include:
@@ -166,18 +178,19 @@
=item * F<check*>
-These are scripts which will check the source things like ANSI C violations,
-POD encoding issues, etc.
+These are scripts which will check the source things like ANSI C
+violations, POD encoding issues, etc.
=item * F<Maintainers>, F<Maintainers.pl>, and F<Maintainers.pm>
-These files contain information on who maintains which modules. Run C<perl
-Porting/Maintainers -M Module::Name> to find out more information about a
-dual-life module.
+These files contain information on who maintains which modules. Run
+C<perl Porting/Maintainers -M Module::Name> to find out more
+information about a dual-life module.
=item * F<podtidy>
-Tidies a pod file. It's a good idea to run this on a pod file you've patched.
+Tidies a pod file. It's a good idea to run this on a pod file you've
+patched.
=back
@@ -186,8 +199,8 @@
The Perl build system starts with the F<Configure> script in the root
directory.
-Platform-specific pieces of the build system also live in platform-specific
-directories like F<win32/>, F<vms/>, etc.
+Platform-specific pieces of the build system also live in
+platform-specific directories like F<win32/>, F<vms/>, etc.
The F<Configure> script is ultimately responsible for generating a
F<Makefile>.
@@ -195,21 +208,22 @@
The build system that Perl uses is called metaconfig. This system is
maintained separately from the Perl core.
-The metaconfig system has its own git repository. Please see its README file
-in L<http://perl5.git.perl.org/metaconfig.git/> for more details.
+The metaconfig system has its own git repository. Please see its README
+file in L<http://perl5.git.perl.org/metaconfig.git/> for more details.
-The F<Cross> directory contains various files related to cross-compiling
-Perl. See F<Cross/README> for more details.
+The F<Cross> directory contains various files related to
+cross-compiling Perl. See F<Cross/README> for more details.
=head2 F<AUTHORS>
-This file everyone who's contributed to Perl. If you submit a patch, you
-should add your name to this file as part of the patch.
+This file lists everyone who's contributed to Perl. If you submit a
+patch, you should add your name to this file as part of the patch.
=head2 F<MANIFEST>
-The F<MANIFEST> file in the root of the source tree contains a list of every
-file in the Perl core, as well as a brief description of each file.
+The F<MANIFEST> file in the root of the source tree contains a list of
+every file in the Perl core, as well as a brief description of each
+file.
You can get an overview of all the files with this command:
Property changes on: trunk/contrib/perl/pod/perlsource.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlstyle.pod
===================================================================
--- trunk/contrib/perl/pod/perlstyle.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlstyle.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlstyle.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlsub.pod
===================================================================
--- trunk/contrib/perl/pod/perlsub.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlsub.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -217,9 +217,24 @@
Not only does the C<&> form make the argument list optional, it also
disables any prototype checking on arguments you do provide. This
is partly for historical reasons, and partly for having a convenient way
-to cheat if you know what you're doing. See L<Prototypes> below.
+to cheat if you know what you're doing. See L</Prototypes> below.
X<&>
+Since Perl 5.16.0, the C<__SUB__> token is available under C<use feature
+'current_sub'> and C<use 5.16.0>. It will evaluate to a reference to the
+currently-running sub, which allows for recursive calls without knowing
+your subroutine's name.
+
+ use 5.16.0;
+ my $factorial = sub {
+ my ($x) = @_;
+ return 1 if $x == 1;
+ return($x * __SUB__->( $x - 1 ) );
+ };
+
+The behaviour of C<__SUB__> within a regex code block (such as C</(?{...})/>)
+is subject to change.
+
Subroutines whose names are in all upper case are reserved to the Perl
core, as are modules whose names are in all lower case. A subroutine in
all capitals is a loosely-held convention meaning it will be called
@@ -439,11 +454,21 @@
=head3 Persistent variables via state()
-Beginning with perl 5.9.4, you can declare variables with the C<state>
-keyword in place of C<my>. For that to work, though, you must have
+Beginning with Perl 5.10.0, you can declare variables with the C<state>
+keyword in place of C<my>. For that to work, though, you must have
enabled that feature beforehand, either by using the C<feature> pragma, or
-by using C<-E> on one-liners. (see L<feature>)
+by using C<-E> on one-liners (see L<feature>). Beginning with Perl 5.16,
+the C<CORE::state> form does not require the
+C<feature> pragma.
+The C<state> keyword creates a lexical variable (following the same scoping
+rules as C<my>) that persists from one subroutine call to the next. If a
+state variable resides inside an anonymous subroutine, then each copy of
+the subroutine has its own copy of the state variable. However, the value
+of the state variable will still persist between calls to the same copy of
+the anonymous subroutine. (Don't forget that C<sub { ... }> creates a new
+subroutine each time it is executed.)
+
For example, the following code maintains a private counter, incremented
each time the gimme_another() function is called:
@@ -450,6 +475,13 @@
use feature 'state';
sub gimme_another { state $x; return ++$x }
+And this example uses anonymous subroutines to create separate counters:
+
+ use feature 'state';
+ sub create_counter {
+ return sub { state $x; return ++$x }
+ }
+
Also, since C<$x> is lexical, it can't be reached or modified by any Perl
code outside.
@@ -554,7 +586,7 @@
a local variable. This is known as dynamic scoping. Lexical scoping
is done with C<my>, which works more like C's auto declarations.
-Some types of lvalues can be localized as well : hash and array elements
+Some types of lvalues can be localized as well: hash and array elements
and slices, conditionals (provided that their result is always
localizable), and symbolic references. As for simple variables, this
creates new, dynamically scoped values.
@@ -602,7 +634,7 @@
{ local $/ = undef; $slurp = <FILE>; }
Note, however, that this restricts localization of some values ; for
-example, the following statement dies, as of perl 5.9.0, with an error
+example, the following statement dies, as of perl 5.10.0, with an error
I<Modification of a read-only value attempted>, because the $1 variable is
magical and read-only :
@@ -740,8 +772,7 @@
my $val;
sub canmod : lvalue {
- # return $val; this doesn't work, don't say "return"
- $val;
+ $val; # or: return $val;
}
sub nomod {
$val;
@@ -770,14 +801,9 @@
=item Lvalue subroutines are EXPERIMENTAL
-They appear to be convenient, but there are several reasons to be
+They appear to be convenient, but there is at least one reason to be
circumspect.
-You can't use the return keyword, you must pass out the value before
-falling out of subroutine scope. (see comment in example above). This
-is usually not a problem, but it disallows an explicit return out of a
-deeply nested loop, which is sometimes a nice way out.
-
They violate encapsulation. A normal mutator can check the supplied
argument before setting the attribute it is protecting, an lvalue
subroutine never gets that chance. Consider;
@@ -799,6 +825,107 @@
=back
+=head2 Lexical Subroutines
+X<my sub> X<state sub> X<our sub> X<subroutine, lexical>
+
+B<WARNING>: Lexical subroutines are still experimental. The feature may be
+modified or removed in future versions of Perl.
+
+Lexical subroutines are only available under the C<use feature
+'lexical_subs'> pragma, which produces a warning unless the
+"experimental::lexical_subs" warnings category is disabled.
+
+Beginning with Perl 5.18, you can declare a private subroutine with C<my>
+or C<state>. As with state variables, the C<state> keyword is only
+available under C<use feature 'state'> or C<use 5.010> or higher.
+
+These subroutines are only visible within the block in which they are
+declared, and only after that declaration:
+
+ no warnings "experimental::lexical_subs";
+ use feature 'lexical_subs';
+
+ foo(); # calls the package/global subroutine
+ state sub foo {
+ foo(); # also calls the package subroutine
+ }
+ foo(); # calls "state" sub
+ my $ref = \&foo; # take a reference to "state" sub
+
+ my sub bar { ... }
+ bar(); # calls "my" sub
+
+To use a lexical subroutine from inside the subroutine itself, you must
+predeclare it. The C<sub foo {...}> subroutine definition syntax respects
+any previous C<my sub;> or C<state sub;> declaration.
+
+ my sub baz; # predeclaration
+ sub baz { # define the "my" sub
+ baz(); # recursive call
+ }
+
+=head3 C<state sub> vs C<my sub>
+
+What is the difference between "state" subs and "my" subs? Each time that
+execution enters a block when "my" subs are declared, a new copy of each
+sub is created. "State" subroutines persist from one execution of the
+containing block to the next.
+
+So, in general, "state" subroutines are faster. But "my" subs are
+necessary if you want to create closures:
+
+ no warnings "experimental::lexical_subs";
+ use feature 'lexical_subs';
+
+ sub whatever {
+ my $x = shift;
+ my sub inner {
+ ... do something with $x ...
+ }
+ inner();
+ }
+
+In this example, a new C<$x> is created when C<whatever> is called, and
+also a new C<inner>, which can see the new C<$x>. A "state" sub will only
+see the C<$x> from the first call to C<whatever>.
+
+=head3 C<our> subroutines
+
+Like C<our $variable>, C<our sub> creates a lexical alias to the package
+subroutine of the same name.
+
+The two main uses for this are to switch back to using the package sub
+inside an inner scope:
+
+ no warnings "experimental::lexical_subs";
+ use feature 'lexical_subs';
+
+ sub foo { ... }
+
+ sub bar {
+ my sub foo { ... }
+ {
+ # need to use the outer foo here
+ our sub foo;
+ foo();
+ }
+ }
+
+and to make a subroutine visible to other packages in the same scope:
+
+ package MySneakyModule;
+
+ no warnings "experimental::lexical_subs";
+ use feature 'lexical_subs';
+
+ our sub do_something { ... }
+
+ sub do_something_with_caller {
+ package DB;
+ () = caller 1; # sets @DB::args
+ do_something(@args); # uses MySneakyModule::do_something
+ }
+
=head2 Passing Symbol Table Entries (typeglobs)
X<typeglob> X<*>
@@ -893,7 +1020,7 @@
a local alias.
{
- local *grow = \&shrink; # only until this block exists
+ local *grow = \&shrink; # only until this block exits
grow(); # really calls shrink()
move(); # if move() grow()s, it shrink()s too
}
@@ -915,8 +1042,7 @@
}
# interruptibility automatically restored here
-But it also works on lexically declared aggregates. Prior to 5.005,
-this operation could on occasion misbehave.
+But it also works on lexically declared aggregates.
=back
@@ -1081,8 +1207,8 @@
Any backslashed prototype character represents an actual argument
that must start with that character (optionally preceded by C<my>,
-C<our> or C<local>), with the exception of C<$>, which will accept a
-hash or array element even without a dollar sign, such as
+C<our> or C<local>), with the exception of C<$>, which will
+accept any scalar lvalue expression, such as C<$foo = 7> or
C<< my_function()->[0] >>. The value passed as part of C<@_> will be a
reference to the actual argument given in the subroutine call,
obtained by applying C<\> to that argument.
@@ -1140,9 +1266,9 @@
A semicolon (C<;>) separates mandatory arguments from optional arguments.
It is redundant before C<@> or C<%>, which gobble up everything else.
-As the last character of a prototype, or just before a semicolon, you can
-use C<_> in place of C<$>: if this argument is not provided, C<$_> will be
-used instead.
+As the last character of a prototype, or just before a semicolon, a C<@>
+or a C<%>, you can use C<_> in place of C<$>: if this argument is not
+provided, C<$_> will be used instead.
Note how the last three examples in the table above are treated
specially by the parser. C<mygrep()> is parsed as a true list
@@ -1153,8 +1279,12 @@
mytime +2;
you'll get C<mytime() + 2>, not C<mytime(2)>, which is how it would be parsed
-without a prototype.
+without a prototype. If you want to force a unary function to have the
+same precedence as a list operator, add C<;> to the end of the prototype:
+ sub mygetprotobynumber($;);
+ mygetprotobynumber $a > $b; # parsed as mygetprotobynumber($a > $b)
+
The interesting thing about C<&> is that you can generate new syntax with it,
provided it's in the initial position:
X<&>
@@ -1278,9 +1408,10 @@
}
If you redefine a subroutine that was eligible for inlining, you'll get
-a mandatory warning. (You can use this warning to tell whether or not a
+a warning by default. (You can use this warning to tell whether or not a
particular subroutine is considered constant.) The warning is
-considered severe enough not to be optional because previously compiled
+considered severe enough not to be affected by the B<-w>
+switch (or its absence) because previously compiled
invocations of the function will still be using the old value of the
function. If you need to be able to redefine the subroutine, you need to
ensure that it isn't inlined, either by dropping the C<()> prototype
@@ -1313,8 +1444,10 @@
saying C<CORE::open()> always refers to the built-in C<open()>, even
if the current package has imported some other subroutine called
C<&open()> from elsewhere. Even though it looks like a regular
-function call, it isn't: you can't take a reference to it, such as
-the incorrect C<\&CORE::open> might appear to produce.
+function call, it isn't: the CORE:: prefix in that case is part of Perl's
+syntax, and works for any keyword, regardless of what is in the CORE
+package. Taking a reference to it, that is, C<\&CORE::open>, only works
+for some keywords. See L<CORE>.
Library modules should not in general export built-in names like C<open>
or C<chdir> as part of their default C<@EXPORT> list, because these may
@@ -1430,9 +1563,8 @@
is not passed as an ordinary argument because, er, well, just
because, that's why. (As an exception, a method call to a nonexistent
C<import> or C<unimport> method is just skipped instead. Also, if
-the AUTOLOAD subroutine is an XSUB, C<$AUTOLOAD> is not populated;
-instead, you should call L<< C<SvPVX>E<sol>C<SvCUR>|perlapi >> on the
-C<CV> for C<AUTOLOAD> to retrieve the method name.)
+the AUTOLOAD subroutine is an XSUB, there are other ways to retrieve the
+subroutine name. See L<perlguts/Autoloading with XSUBs> for details.)
Many C<AUTOLOAD> routines load in a definition for the requested
@@ -1461,7 +1593,7 @@
who "am", "i";
ls '-l';
-A more complete example of this is the standard Shell module, which
+A more complete example of this is the Shell module on CPAN, which
can treat undefined subroutine calls as calls to external programs.
Mechanisms are available to help modules writers split their modules
@@ -1518,4 +1650,4 @@
See L<perlembed> if you'd like to learn about calling Perl subroutines from C.
See L<perlmod> to learn about bundling up your functions in separate files.
See L<perlmodlib> to learn what library modules come standard on your system.
-See L<perltoot> to learn how to make object method calls.
+See L<perlootut> to learn how to make object method calls.
Property changes on: trunk/contrib/perl/pod/perlsub.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlsyn.pod
===================================================================
--- trunk/contrib/perl/pod/perlsyn.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlsyn.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -6,12 +6,13 @@
=head1 DESCRIPTION
A Perl program consists of a sequence of declarations and statements
-which run from the top to the bottom. Loops, subroutines and other
+which run from the top to the bottom. Loops, subroutines, and other
control structures allow you to jump around within the code.
-Perl is a B<free-form> language, you can format and indent it however
-you like. Whitespace mostly serves to separate tokens, unlike
-languages like Python where it is an important part of the syntax.
+Perl is a B<free-form> language: you can format and indent it however
+you like. Whitespace serves mostly to separate tokens, unlike
+languages like Python where it is an important part of the syntax,
+or Fortran where it is immaterial.
Many of Perl's syntactic elements are B<optional>. Rather than
requiring you to put parentheses around every function call and
@@ -31,7 +32,7 @@
X<declaration> X<undef> X<undefined> X<uninitialized>
The only things you need to declare in Perl are report formats and
-subroutines (and sometimes not even subroutines). A variable holds
+subroutines (and sometimes not even subroutines). A scalar variable holds
the undefined value (C<undef>) until it has been assigned a defined
value, which is anything other than C<undef>. When used as a number,
C<undef> is treated as C<0>; when used as a string, it is treated as
@@ -41,24 +42,23 @@
C<undef> as a string or a number. Well, usually. Boolean contexts,
such as:
- my $a;
if ($a) {}
are exempt from warnings (because they care about truth rather than
definedness). Operators such as C<++>, C<-->, C<+=>,
-C<-=>, and C<.=>, that operate on undefined left values such as:
+C<-=>, and C<.=>, that operate on undefined variables such as:
- my $a;
+ undef $a;
$a++;
are also always exempt from such warnings.
A declaration can be put anywhere a statement can, but has no effect on
-the execution of the primary sequence of statements--declarations all
-take effect at compile time. Typically all the declarations are put at
+the execution of the primary sequence of statements: declarations all
+take effect at compile time. All declarations are typically put at
the beginning or the end of the script. However, if you're using
-lexically-scoped private variables created with C<my()>, you'll
-have to make sure
+lexically-scoped private variables created with C<my()>,
+C<state()>, or C<our()>, you'll have to make sure
your format or subroutine definition is within the same block scope
as the my if you expect to be able to access those private variables.
@@ -70,12 +70,22 @@
sub myname;
$me = myname $0 or die "can't get myname";
-Note that myname() functions as a list operator, not as a unary operator;
-so be careful to use C<or> instead of C<||> in this case. However, if
-you were to declare the subroutine as C<sub myname ($)>, then
-C<myname> would function as a unary operator, so either C<or> or
-C<||> would work.
+A bare declaration like that declares the function to be a list operator,
+not a unary operator, so you have to be careful to use parentheses (or
+C<or> instead of C<||>.) The C<||> operator binds too tightly to use after
+list operators; it becomes part of the last element. You can always use
+parentheses around the list operators arguments to turn the list operator
+back into something that behaves more like a function call. Alternatively,
+you can use the prototype C<($)> to turn the subroutine into a unary
+operator:
+ sub myname ($);
+ $me = myname $0 || die "can't get myname";
+
+That now parses as you'd expect, but you still ought to get in the habit of
+using parentheses in that situation. For more on prototypes, see
+L<perlsub>
+
Subroutines declarations can also be loaded up with the C<require> statement
or both loaded and imported into your namespace with a C<use> statement.
See L<perlmod> for details on this.
@@ -97,23 +107,24 @@
X<statement> X<semicolon> X<expression> X<;>
The only kind of simple statement is an expression evaluated for its
-side effects. Every simple statement must be terminated with a
+side-effects. Every simple statement must be terminated with a
semicolon, unless it is the final statement in a block, in which case
-the semicolon is optional. (A semicolon is still encouraged if the
+the semicolon is optional. But put the semicolon in anyway if the
block takes up more than one line, because you may eventually add
-another line.) Note that there are some operators like C<eval {}> and
-C<do {}> that look like compound statements, but aren't (they're just
-TERMs in an expression), and thus need an explicit termination if used
+another line. Note that there are operators like C<eval {}>, C<sub {}>, and
+C<do {}> that I<look> like compound statements, but aren't--they're just
+TERMs in an expression--and thus need an explicit termination when used
as the last item in a statement.
=head2 Truth and Falsehood
X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
-The number 0, the strings C<'0'> and C<''>, the empty list C<()>, and
-C<undef> are all false in a boolean context. All other values are true.
+The number 0, the strings C<'0'> and C<"">, the empty list C<()>, and
+C<undef> are all false in a boolean context. All other values are true.
Negation of a true value by C<!> or C<not> returns a special false value.
-When evaluated as a string it is treated as C<''>, but as a number, it
-is treated as 0.
+When evaluated as a string it is treated as C<"">, but as a number, it
+is treated as 0. Most Perl operators
+that return true or false behave this way.
=head2 Statement Modifiers
X<statement modifier> X<modifier> X<if> X<unless> X<while>
@@ -127,9 +138,9 @@
unless EXPR
while EXPR
until EXPR
- when EXPR
for LIST
foreach LIST
+ when EXPR
The C<EXPR> following the modifier is referred to as the "condition".
Its truth or falsehood determines how the modifier will behave.
@@ -136,31 +147,15 @@
C<if> executes the statement once I<if> and only if the condition is
true. C<unless> is the opposite, it executes the statement I<unless>
-the condition is true (i.e., if the condition is false).
+the condition is true (that is, if the condition is false).
print "Basset hounds got long ears" if length $ear >= 10;
go_outside() and play() unless $is_raining;
-C<when> executes the statement I<when> C<$_> smart matches C<EXPR>, and
-then either C<break>s out if it's enclosed in a C<given> scope or skips
-to the C<next> element when it lies directly inside a C<for> loop.
-See also L</"Switch statements">.
-
- given ($something) {
- $abc = 1 when /^abc/;
- $just_a = 1 when /^a/;
- $other = 1;
- }
-
- for (@names) {
- admin($_) when [ qw/Alice Bob/ ];
- regular($_) when [ qw/Chris David Ellen/ ];
- }
-
-The C<foreach> modifier is an iterator: it executes the statement once
+The C<for(each)> modifier is an iterator: it executes the statement once
for each item in the LIST (with C<$_> aliased to each item in turn).
- print "Hello $_!\n" foreach qw(world Dolly nurse);
+ print "Hello $_!\n" for qw(world Dolly nurse);
C<while> repeats the statement I<while> the condition is true.
C<until> does the opposite, it repeats the statement I<until> the
@@ -172,14 +167,16 @@
The C<while> and C<until> modifiers have the usual "C<while> loop"
semantics (conditional evaluated first), except when applied to a
-C<do>-BLOCK (or to the deprecated C<do>-SUBROUTINE statement), in
+C<do>-BLOCK (or to the Perl4 C<do>-SUBROUTINE statement), in
which case the block executes once before the conditional is
-evaluated. This is so that you can write loops like:
+evaluated.
+This is so that you can write loops like:
+
do {
$line = <STDIN>;
...
- } until $line eq ".\n";
+ } until !defined($line) || $line eq ".\n"
See L<perlfunc/do>. Note also that the loop control statements described
later will I<NOT> work in this construct, because modifiers don't take
@@ -203,8 +200,9 @@
} while $x++ <= $z;
}
-B<NOTE:> The behaviour of a C<my> statement modified with a statement
-modifier conditional or loop construct (e.g. C<my $x if ...>) is
+B<NOTE:> The behaviour of a C<my>, C<state>, or
+C<our> modified with a statement modifier conditional
+or loop construct (for example, C<my $x if ...>) is
B<undefined>. The value of the C<my> variable may be C<undef>, any
previously assigned value, or possibly anything else. Don't rely on
it. Future versions of perl might do something different from the
@@ -211,9 +209,22 @@
version of perl you try it out on. Here be dragons.
X<my>
+The C<when> modifier is an experimental feature that first appeared in Perl
+5.14. To use it, you should include a C<use v5.14> declaration.
+(Technically, it requires only the C<switch> feature, but that aspect of it
+was not available before 5.14.) Operative only from within a C<foreach>
+loop or a C<given> block, it executes the statement only if the smartmatch
+C<< $_ ~~ I<EXPR> >> is true. If the statement executes, it is followed by
+a C<next> from inside a C<foreach> and C<break> from inside a C<given>.
+
+Under the current implementation, the C<foreach> loop can be
+anywhere within the C<when> modifier's dynamic scope, but must be
+within the C<given> block's lexical scope. This restricted may
+be relaxed in a future release. See L<"Switch Statements"> below.
+
=head2 Compound Statements
X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
-X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue>
+X<{> X<}> X<if> X<unless> X<given> X<while> X<until> X<foreach> X<for> X<continue>
In Perl, a sequence of statements that defines a scope is called a block.
Sometimes a block is delimited by the file containing it (in the case
@@ -227,36 +238,55 @@
if (EXPR) BLOCK
if (EXPR) BLOCK else BLOCK
+ if (EXPR) BLOCK elsif (EXPR) BLOCK ...
if (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+
unless (EXPR) BLOCK
unless (EXPR) BLOCK else BLOCK
+ unless (EXPR) BLOCK elsif (EXPR) BLOCK ...
unless (EXPR) BLOCK elsif (EXPR) BLOCK ... else BLOCK
+
+ given (EXPR) BLOCK
+
LABEL while (EXPR) BLOCK
LABEL while (EXPR) BLOCK continue BLOCK
+
LABEL until (EXPR) BLOCK
LABEL until (EXPR) BLOCK continue BLOCK
+
LABEL for (EXPR; EXPR; EXPR) BLOCK
+ LABEL for VAR (LIST) BLOCK
+ LABEL for VAR (LIST) BLOCK continue BLOCK
+
+ LABEL foreach (EXPR; EXPR; EXPR) BLOCK
LABEL foreach VAR (LIST) BLOCK
LABEL foreach VAR (LIST) BLOCK continue BLOCK
+
+ LABEL BLOCK
LABEL BLOCK continue BLOCK
-Note that, unlike C and Pascal, these are defined in terms of BLOCKs,
+ PHASE BLOCK
+
+The experimental C<given> statement is I<not automatically enabled>; see
+L</"Switch Statements"> below for how to do so, and the attendant caveats.
+
+Unlike in C and Pascal, in Perl these are all defined in terms of BLOCKs,
not statements. This means that the curly brackets are I<required>--no
dangling statements allowed. If you want to write conditionals without
-curly brackets there are several other ways to do it. The following
+curly brackets, there are several other ways to do it. The following
all do the same thing:
- if (!open(FOO)) { die "Can't open $FOO: $!"; }
+ if (!open(FOO)) { die "Can't open $FOO: $!" }
die "Can't open $FOO: $!" unless open(FOO);
- open(FOO) or die "Can't open $FOO: $!"; # FOO or bust!
- open(FOO) ? 'hi mom' : die "Can't open $FOO: $!";
+ open(FOO) || die "Can't open $FOO: $!";
+ open(FOO) ? () : die "Can't open $FOO: $!";
# a bit exotic, that last one
The C<if> statement is straightforward. Because BLOCKs are always
bounded by curly brackets, there is never any ambiguity about which
C<if> an C<else> goes with. If you use C<unless> in place of C<if>,
-the sense of the test is reversed. Like C<if>, C<unless> can be followed
-by C<else>. C<unless> can even be followed by one or more C<elsif>
+the sense of the test is reversed. Like C<if>, C<unless> can be followed
+by C<else>. C<unless> can even be followed by one or more C<elsif>
statements, though you may want to think twice before using that particular
language construct, as everyone reading your code will have to think at least
twice before they can understand what's going on.
@@ -279,8 +309,12 @@
increment a loop variable, even when the loop has been continued via
the C<next> statement.
+When a block is preceding by a compilation phase keyword such as C<BEGIN>,
+C<END>, C<INIT>, C<CHECK>, or C<UNITCHECK>, then the block will run only
+during the corresponding phase of execution. See L<perlmod> for more details.
+
Extension modules can also hook into the Perl parser to define new
-kinds of compound statement. These are introduced by a keyword which
+kinds of compound statements. These are introduced by a keyword which
the extension recognizes, and the syntax following the keyword is
defined entirely by the extension. If you are an implementor, see
L<perlapi/PL_keyword_plugin> for the mechanism. If you are using such
@@ -323,7 +357,7 @@
# now process $_
}
-which is Perl short-hand for the more explicitly written version:
+which is Perl shorthand for the more explicitly written version:
LINE: while (defined($line = <ARGV>)) {
chomp($line);
@@ -336,7 +370,7 @@
Note that if there were a C<continue> block on the above code, it would
get executed only on lines discarded by the regex (since redo skips the
-continue block). A continue block is often used to reset line counters
+continue block). A continue block is often used to reset line counters
or C<m?pat?> one-time matches:
# inspired by :1,$g/fred/s//WILMA/
@@ -354,12 +388,13 @@
test is reversed, but the conditional is still tested before the first
iteration.
-The loop control statements don't work in an C<if> or C<unless>, since
+Loop control statements don't work in an C<if> or C<unless>, since
they aren't loops. You can double the braces to make them such, though.
if (/pattern/) {{
last if /fred/;
- next if /barney/; # same effect as "last", but doesn't document as well
+ next if /barney/; # same effect as "last",
+ # but doesn't document as well
# do something here
}}
@@ -431,9 +466,7 @@
X<my> X<local>
The C<foreach> keyword is actually a synonym for the C<for> keyword, so
-you can use C<foreach> for readability or C<for> for brevity. (Or because
-the Bourne shell is more familiar to you than I<csh>, so writing C<for>
-comes more naturally.) If VAR is omitted, C<$_> is set to each value.
+you can use either. If VAR is omitted, C<$_> is set to each value.
X<$_>
If any element of LIST is an lvalue, you can modify it by modifying
@@ -459,8 +492,9 @@
$elem *= 2;
}
- for $count (10,9,8,7,6,5,4,3,2,1,'BOOM') {
- print $count, "\n"; sleep(1);
+ for $count (reverse(1..10), "BOOM") {
+ print $count, "\n";
+ sleep(1);
}
for (1..15) { print "Merry Christmas\n"; }
@@ -518,34 +552,349 @@
$nothing = 1;
}
-Such constructs are quite frequently used, because older versions
-of Perl had no official C<switch> statement.
+You'll also find that C<foreach> loop used to create a topicalizer
+and a switch:
-=head2 Switch statements
+ SWITCH:
+ for ($var) {
+ if (/^abc/) { $abc = 1; last SWITCH; }
+ if (/^def/) { $def = 1; last SWITCH; }
+ if (/^xyz/) { $xyz = 1; last SWITCH; }
+ $nothing = 1;
+ }
+
+Such constructs are quite frequently used, both because older versions of
+Perl had no official C<switch> statement, and also because the new version
+described immediately below remains experimental and can sometimes be confusing.
+
+=head2 Switch Statements
+
X<switch> X<case> X<given> X<when> X<default>
-Starting from Perl 5.10, you can say
+Starting from Perl 5.10.1 (well, 5.10.0, but it didn't work
+right), you can say
use feature "switch";
-which enables a switch feature that is closely based on the
-Perl 6 proposal.
+to enable an experimental switch feature. This is loosely based on an
+old version of a Perl 6 proposal, but it no longer resembles the Perl 6
+construct. You also get the switch feature whenever you declare that your
+code prefers to run under a version of Perl that is 5.10 or later. For
+example:
-The keywords C<given> and C<when> are analogous
-to C<switch> and C<case> in other languages, so the code
-above could be written as
+ use v5.14;
- given($_) {
- when (/^abc/) { $abc = 1; }
- when (/^def/) { $def = 1; }
- when (/^xyz/) { $xyz = 1; }
- default { $nothing = 1; }
+Under the "switch" feature, Perl gains the experimental keywords
+C<given>, C<when>, C<default>, C<continue>, and C<break>.
+Starting from Perl 5.16, one can prefix the switch
+keywords with C<CORE::> to access the feature without a C<use feature>
+statement. The keywords C<given> and
+C<when> are analogous to C<switch> and
+C<case> in other languages, so the code in the previous section could be
+rewritten as
+
+ use v5.10.1;
+ for ($var) {
+ when (/^abc/) { $abc = 1 }
+ when (/^def/) { $def = 1 }
+ when (/^xyz/) { $xyz = 1 }
+ default { $nothing = 1 }
}
-This construct is very flexible and powerful. For example:
+The C<foreach> is the non-experimental way to set a topicalizer.
+If you wish to use the highly experimental C<given>, that could be
+written like this:
+ use v5.10.1;
+ given ($var) {
+ when (/^abc/) { $abc = 1 }
+ when (/^def/) { $def = 1 }
+ when (/^xyz/) { $xyz = 1 }
+ default { $nothing = 1 }
+ }
+
+As of 5.14, that can also be written this way:
+
+ use v5.14;
+ for ($var) {
+ $abc = 1 when /^abc/;
+ $def = 1 when /^def/;
+ $xyz = 1 when /^xyz/;
+ default { $nothing = 1 }
+ }
+
+Or if you don't care to play it safe, like this:
+
+ use v5.14;
+ given ($var) {
+ $abc = 1 when /^abc/;
+ $def = 1 when /^def/;
+ $xyz = 1 when /^xyz/;
+ default { $nothing = 1 }
+ }
+
+The arguments to C<given> and C<when> are in scalar context,
+and C<given> assigns the C<$_> variable its topic value.
+
+Exactly what the I<EXPR> argument to C<when> does is hard to describe
+precisely, but in general, it tries to guess what you want done. Sometimes
+it is interpreted as C<< $_ ~~ I<EXPR> >>, and sometimes it is not. It
+also behaves differently when lexically enclosed by a C<given> block than
+it does when dynamically enclosed by a C<foreach> loop. The rules are far
+too difficult to understand to be described here. See L</"Experimental Details
+on given and when"> later on.
+
+Due to an unfortunate bug in how C<given> was implemented between Perl 5.10
+and 5.16, under those implementations the version of C<$_> governed by
+C<given> is merely a lexically scoped copy of the original, not a
+dynamically scoped alias to the original, as it would be if it were a
+C<foreach> or under both the original and the current Perl 6 language
+specification. This bug was fixed in Perl
+5.18. If you really want a lexical C<$_>,
+specify that explicitly, but note that C<my $_>
+is now deprecated and will warn unless warnings
+have been disabled:
+
+ given(my $_ = EXPR) { ... }
+
+If your code still needs to run on older versions,
+stick to C<foreach> for your topicalizer and
+you will be less unhappy.
+
+=head2 Goto
+X<goto>
+
+Although not for the faint of heart, Perl does support a C<goto>
+statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
+C<goto>-&NAME. A loop's LABEL is not actually a valid target for
+a C<goto>; it's just the name of the loop.
+
+The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
+execution there. It may not be used to go into any construct that
+requires initialization, such as a subroutine or a C<foreach> loop. It
+also can't be used to go into a construct that is optimized away. It
+can be used to go almost anywhere else within the dynamic scope,
+including out of subroutines, but it's usually better to use some other
+construct such as C<last> or C<die>. The author of Perl has never felt the
+need to use this form of C<goto> (in Perl, that is--C is another matter).
+
+The C<goto>-EXPR form expects a label name, whose scope will be resolved
+dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
+necessarily recommended if you're optimizing for maintainability:
+
+ goto(("FOO", "BAR", "GLARCH")[$i]);
+
+The C<goto>-&NAME form is highly magical, and substitutes a call to the
+named subroutine for the currently running subroutine. This is used by
+C<AUTOLOAD()> subroutines that wish to load another subroutine and then
+pretend that the other subroutine had been called in the first place
+(except that any modifications to C<@_> in the current subroutine are
+propagated to the other subroutine.) After the C<goto>, not even C<caller()>
+will be able to tell that this routine was called first.
+
+In almost all cases like this, it's usually a far, far better idea to use the
+structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
+resorting to a C<goto>. For certain applications, the catch and throw pair of
+C<eval{}> and die() for exception processing can also be a prudent approach.
+
+=head2 The Ellipsis Statement
+X<...>
+X<... statement>
+X<ellipsis operator>
+X<elliptical statement>
+X<unimplemented statement>
+X<unimplemented operator>
+X<yada-yada>
+X<yada-yada operator>
+X<... operator>
+X<whatever operator>
+X<triple-dot operator>
+
+Beginning in Perl 5.12, Perl accepts an ellipsis, "C<...>", as a
+placeholder for code that you haven't implemented yet. This form of
+ellipsis, the unimplemented statement, should not be confused with the
+binary flip-flop C<...> operator. One is a statement and the other an
+operator. (Perl doesn't usually confuse them because usually Perl can tell
+whether it wants an operator or a statement, but see below for exceptions.)
+
+When Perl 5.12 or later encounters an ellipsis statement, it parses this
+without error, but if and when you should actually try to execute it, Perl
+throws an exception with the text C<Unimplemented>:
+
+ use v5.12;
+ sub unimplemented { ... }
+ eval { unimplemented() };
+ if ($@ =~ /^Unimplemented at /) {
+ say "I found an ellipsis!";
+ }
+
+You can only use the elliptical statement to stand in for a
+complete statement. These examples of how the ellipsis works:
+
+ use v5.12;
+ { ... }
+ sub foo { ... }
+ ...;
+ eval { ... };
+ sub somemeth {
+ my $self = shift;
+ ...;
+ }
+ $x = do {
+ my $n;
+ ...;
+ say "Hurrah!";
+ $n;
+ };
+
+The elliptical statement cannot stand in for an expression that
+is part of a larger statement, since the C<...> is also the three-dot
+version of the flip-flop operator (see L<perlop/"Range Operators">).
+
+These examples of attempts to use an ellipsis are syntax errors:
+
+ use v5.12;
+
+ print ...;
+ open(my $fh, ">", "/dev/passwd") or ...;
+ if ($condition && ... ) { say "Howdy" };
+
+There are some cases where Perl can't immediately tell the difference
+between an expression and a statement. For instance, the syntax for a
+block and an anonymous hash reference constructor look the same unless
+there's something in the braces to give Perl a hint. The ellipsis is a
+syntax error if Perl doesn't guess that the C<{ ... }> is a block. In that
+case, it doesn't think the C<...> is an ellipsis because it's expecting an
+expression instead of a statement:
+
+ @transformed = map { ... } @input; # syntax error
+
+You can use a C<;> inside your block to denote that the C<{ ... }> is a
+block and not a hash reference constructor. Now the ellipsis works:
+
+ @transformed = map {; ... } @input; # ; disambiguates
+
+ @transformed = map { ...; } @input; # ; disambiguates
+
+Note: Some folks colloquially refer to this bit of punctuation as a
+"yada-yada" or "triple-dot", but its true name
+is actually an ellipsis. Perl does not yet
+accept the Unicode version, U+2026 HORIZONTAL ELLIPSIS, as an alias for
+C<...>, but someday it may.
+
+=head2 PODs: Embedded Documentation
+X<POD> X<documentation>
+
+Perl has a mechanism for intermixing documentation with source code.
+While it's expecting the beginning of a new statement, if the compiler
+encounters a line that begins with an equal sign and a word, like this
+
+ =head1 Here There Be Pods!
+
+Then that text and all remaining text up through and including a line
+beginning with C<=cut> will be ignored. The format of the intervening
+text is described in L<perlpod>.
+
+This allows you to intermix your source code
+and your documentation text freely, as in
+
+ =item snazzle($)
+
+ The snazzle() function will behave in the most spectacular
+ form that you can possibly imagine, not even excepting
+ cybernetic pyrotechnics.
+
+ =cut back to the compiler, nuff of this pod stuff!
+
+ sub snazzle($) {
+ my $thingie = shift;
+ .........
+ }
+
+Note that pod translators should look at only paragraphs beginning
+with a pod directive (it makes parsing easier), whereas the compiler
+actually knows to look for pod escapes even in the middle of a
+paragraph. This means that the following secret stuff will be
+ignored by both the compiler and the translators.
+
+ $a=3;
+ =secret stuff
+ warn "Neither POD nor CODE!?"
+ =cut back
+ print "got $a\n";
+
+You probably shouldn't rely upon the C<warn()> being podded out forever.
+Not all pod translators are well-behaved in this regard, and perhaps
+the compiler will become pickier.
+
+One may also use pod directives to quickly comment out a section
+of code.
+
+=head2 Plain Old Comments (Not!)
+X<comment> X<line> X<#> X<preprocessor> X<eval>
+
+Perl can process line directives, much like the C preprocessor. Using
+this, one can control Perl's idea of filenames and line numbers in
+error or warning messages (especially for strings that are processed
+with C<eval()>). The syntax for this mechanism is almost the same as for
+most C preprocessors: it matches the regular expression
+
+ # example: '# line 42 "new_filename.plx"'
+ /^\# \s*
+ line \s+ (\d+) \s*
+ (?:\s("?)([^"]+)\g2)? \s*
+ $/x
+
+with C<$1> being the line number for the next line, and C<$3> being
+the optional filename (specified with or without quotes). Note that
+no whitespace may precede the C<< # >>, unlike modern C preprocessors.
+
+There is a fairly obvious gotcha included with the line directive:
+Debuggers and profilers will only show the last source line to appear
+at a particular line number in a given file. Care should be taken not
+to cause line number collisions in code you'd like to debug later.
+
+Here are some examples that you should be able to type into your command
+shell:
+
+ % perl
+ # line 200 "bzzzt"
+ # the '#' on the previous line must be the first char on line
+ die 'foo';
+ __END__
+ foo at bzzzt line 201.
+
+ % perl
+ # line 200 "bzzzt"
+ eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
+ __END__
+ foo at - line 2001.
+
+ % perl
+ eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
+ __END__
+ foo at foo bar line 200.
+
+ % perl
+ # line 345 "goop"
+ eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
+ print $@;
+ __END__
+ foo at goop line 345.
+
+=head2 Experimental Details on given and when
+
+As previously mentioned, the "switch" feature is considered highly
+experimental; it is subject to change with little notice. In particular,
+C<when> has tricky behaviours that are expected to change to become less
+tricky in the future. Do not rely upon its current (mis)implementation.
+Before Perl 5.18, C<given> also had tricky behaviours that you should still
+beware of if your code must run on older versions of Perl.
+
+Here is a longer example of C<given>:
+
use feature ":5.10";
- given($foo) {
+ given ($foo) {
when (undef) {
say '$foo is undefined';
}
@@ -567,102 +916,122 @@
}
}
-C<given(EXPR)> will assign the value of EXPR to C<$_>
-within the lexical scope of the block, so it's similar to
+Before Perl 5.18, C<given(EXPR)> assigned the value of I<EXPR> to
+merely a lexically scoped I<B<copy>> (!) of C<$_>, not a dynamically
+scoped alias the way C<foreach> does. That made it similar to
do { my $_ = EXPR; ... }
-except that the block is automatically broken out of by a
-successful C<when> or an explicit C<break>.
+except that the block was automatically broken out of by a successful
+C<when> or an explicit C<break>. Because it was only a copy, and because
+it was only lexically scoped, not dynamically scoped, you could not do the
+things with it that you are used to in a C<foreach> loop. In particular,
+it did not work for arbitrary function calls if those functions might try
+to access $_. Best stick to C<foreach> for that.
-Most of the power comes from implicit smart matching:
+Most of the power comes from the implicit smartmatching that can
+sometimes apply. Most of the time, C<when(EXPR)> is treated as an
+implicit smartmatch of C<$_>, that is, C<$_ ~~ EXPR>. (See
+L<perlop/"Smartmatch Operator"> for more information on smartmatching.)
+But when I<EXPR> is one of the 10 exceptional cases (or things like them)
+listed below, it is used directly as a boolean.
- when($foo)
+=over 4
-is exactly equivalent to
+=item 1.
- when($_ ~~ $foo)
+A user-defined subroutine call or a method invocation.
-Most of the time, C<when(EXPR)> is treated as an implicit smart match of
-C<$_>, i.e. C<$_ ~~ EXPR>. (See L</"Smart matching in detail"> for more
-information on smart matching.) But when EXPR is one of the below
-exceptional cases, it is used directly as a boolean:
+=item 2.
-=over 4
+A regular expression match in the form of C</REGEX/>, C<$foo =~ /REGEX/>,
+or C<$foo =~ EXPR>. Also, a negated regular expression match in
+the form C<!/REGEX/>, C<$foo !~ /REGEX/>, or C<$foo !~ EXPR>.
-=item *
+=item 3.
-a subroutine or method call
+A smart match that uses an explicit C<~~> operator, such as C<EXPR ~~ EXPR>.
-=item *
+=item 4.
-a regular expression match, i.e. C</REGEX/> or C<$foo =~ /REGEX/>,
-or a negated regular expression match (C<!/REGEX/> or C<$foo !~ /REGEX/>).
+A boolean comparison operator such as C<$_ E<lt> 10> or C<$x eq "abc">. The
+relational operators that this applies to are the six numeric comparisons
+(C<< < >>, C<< > >>, C<< <= >>, C<< >= >>, C<< == >>, and C<< != >>), and
+the six string comparisons (C<lt>, C<gt>, C<le>, C<ge>, C<eq>, and C<ne>).
-=item *
+B<NOTE:> You will often have to use C<$c ~~ $_> because
+the default case uses C<$_ ~~ $c> , which is frequently
+the opposite of what you want.
-a comparison such as C<$_ E<lt> 10> or C<$x eq "abc">
-(or of course C<$_ ~~ $c>)
+=item 5.
-=item *
+At least the three builtin functions C<defined(...)>, C<exists(...)>, and
+C<eof(...)>. We might someday add more of these later if we think of them.
-C<defined(...)>, C<exists(...)>, or C<eof(...)>
+=item 6.
-=item *
+A negated expression, whether C<!(EXPR)> or C<not(EXPR)>, or a logical
+exclusive-or, C<(EXPR1) xor (EXPR2)>. The bitwise versions (C<~> and C<^>)
+are not included.
-a negated expression C<!(...)> or C<not (...)>, or a logical
-exclusive-or C<(...) xor (...)>.
+=item 7.
-=item *
+A filetest operator, with exactly 4 exceptions: C<-s>, C<-M>, C<-A>, and
+C<-C>, as these return numerical values, not boolean ones. The C<-z>
+filetest operator is not included in the exception list.
-a filetest operator, with the exception of C<-s>, C<-M>, C<-A>, and C<-C>,
-that return numerical values, not boolean ones.
+=item 8.
-=item *
+The C<..> and C<...> flip-flop operators. Note that the C<...> flip-flop
+operator is completely different from the C<...> elliptical statement
+just described.
-the C<..> and C<...> flip-flop operators.
-
=back
-In those cases the value of EXPR is used directly as a boolean.
+In those 8 cases above, the value of EXPR is used directly as a boolean, so
+no smartmatching is done. You may think of C<when> as a smartsmartmatch.
-Furthermore, Perl inspects the operands of the binary boolean operators to
-decide whether to use smart matching for each one by applying the above test to
-the operands:
+Furthermore, Perl inspects the operands of logical operators to
+decide whether to use smartmatching for each one by applying the
+above test to the operands:
=over 4
-=item *
+=item 9.
-If EXPR is C<... && ...> or C<... and ...>, the test
-is applied recursively to both operands. If I<both>
-operands pass the test, then the expression is treated
-as boolean; otherwise, smart matching is used.
+If EXPR is C<EXPR1 && EXPR2> or C<EXPR1 and EXPR2>, the test is applied
+I<recursively> to both EXPR1 and EXPR2.
+Only if I<both> operands also pass the
+test, I<recursively>, will the expression be treated as boolean. Otherwise,
+smartmatching is used.
-=item *
+=item 10.
-If EXPR is C<... || ...>, C<... // ...> or C<... or ...>, the test
-is applied recursively to the first operand (which may be a
-higher-precedence AND operator, for example). If the first operand
-is to use smart matching, then both operands will do so; if it is
-not, then the second argument will not be either.
+If EXPR is C<EXPR1 || EXPR2>, C<EXPR1 // EXPR2>, or C<EXPR1 or EXPR2>, the
+test is applied I<recursively> to EXPR1 only (which might itself be a
+higher-precedence AND operator, for example, and thus subject to the
+previous rule), not to EXPR2. If EXPR1 is to use smartmatching, then EXPR2
+also does so, no matter what EXPR2 contains. But if EXPR2 does not get to
+use smartmatching, then the second argument will not be either. This is
+quite different from the C<&&> case just described, so be careful.
=back
-These rules look complicated, but usually they will do what
-you want. For example:
+These rules are complicated, but the goal is for them to do what you want
+(even if you don't quite understand why they are doing it). For example:
when (/^\d+$/ && $_ < 75) { ... }
-will be treated as a boolean match because the rules say both a regex match and
-an explicit test on $_ will be treated as boolean.
+will be treated as a boolean match because the rules say both
+a regex match and an explicit test on C<$_> will be treated
+as boolean.
Also:
when ([qw(foo bar)] && /baz/) { ... }
-will use smart matching because only I<one> of the operands is a boolean; the
-other uses smart matching, and that wins.
+will use smartmatching because only I<one> of the operands is a boolean:
+the other uses smartmatching, and that wins.
Further:
@@ -672,29 +1041,31 @@
when (/^baz/ || [qw(foo bar)]) { ... }
-will test only the regex, which causes both operands to be treated as boolean.
-Watch out for this one, then, because an arrayref is always a true value, which
-makes it effectively redundant.
+will test only the regex, which causes both operands to be
+treated as boolean. Watch out for this one, then, because an
+arrayref is always a true value, which makes it effectively
+redundant. Not a good idea.
-Tautologous boolean operators are still going to be optimized away. Don't be
-tempted to write
+Tautologous boolean operators are still going to be optimized
+away. Don't be tempted to write
- when ('foo' or 'bar') { ... }
+ when ("foo" or "bar") { ... }
-This will optimize down to C<'foo'>, so C<'bar'> will never be considered (even
-though the rules say to use a smart match on C<'foo'>). For an alternation like
-this, an array ref will work, because this will instigate smart matching:
+This will optimize down to C<"foo">, so C<"bar"> will never be considered (even
+though the rules say to use a smartmatch
+on C<"foo">). For an alternation like
+this, an array ref will work, because this will instigate smartmatching:
when ([qw(foo bar)] { ... }
This is somewhat equivalent to the C-style switch statement's fallthrough
-functionality (not to be confused with I<Perl's> fallthrough functionality - see
-below), wherein the same block is used for several C<case> statements.
+functionality (not to be confused with I<Perl's> fallthrough
+functionality--see below), wherein the same block is used for several
+C<case> statements.
-Another useful shortcut is that, if you use a literal array
-or hash as the argument to C<given>, it is turned into a
-reference. So C<given(@foo)> is the same as C<given(\@foo)>,
-for example.
+Another useful shortcut is that, if you use a literal array or hash as the
+argument to C<given>, it is turned into a reference. So C<given(@foo)> is
+the same as C<given(\@foo)>, for example.
C<default> behaves exactly like C<when(1 == 1)>, which is
to say that it always matches.
@@ -712,29 +1083,29 @@
given($foo) {
when (/x/) { say '$foo contains an x'; continue }
- when (/y/) { say '$foo contains a y' }
- default { say '$foo does not contain a y' }
+ when (/y/) { say '$foo contains a y' }
+ default { say '$foo does not contain a y' }
}
=head3 Return value
-When a C<given> statement is also a valid expression (e.g.
-when it's the last statement of a block), it evaluates to :
+When a C<given> statement is also a valid expression (for example,
+when it's the last statement of a block), it evaluates to:
=over 4
=item *
-an empty list as soon as an explicit C<break> is encountered.
+An empty list as soon as an explicit C<break> is encountered.
=item *
-the value of the last evaluated expression of the successful
-C<when>/C<default> clause, if there's one.
+The value of the last evaluated expression of the successful
+C<when>/C<default> clause, if there happens to be one.
=item *
-the value of the last evaluated expression of the C<given> block if no
+The value of the last evaluated expression of the C<given> block if no
condition is true.
=back
@@ -745,15 +1116,18 @@
Note that, unlike C<if> and C<unless>, failed C<when> statements always
evaluate to an empty list.
- my $price = do { given ($item) {
- when ([ 'pear', 'apple' ]) { 1 }
- break when 'vote'; # My vote cannot be bought
- 1e10 when /Mona Lisa/;
- 'unknown';
- } };
+ my $price = do {
+ given ($item) {
+ when (["pear", "apple"]) { 1 }
+ break when "vote"; # My vote cannot be bought
+ 1e10 when /Mona Lisa/;
+ "unknown";
+ }
+ };
-Currently, C<given> blocks can't always be used as proper expressions. This
-may be addressed in a future version of perl.
+Currently, C<given> blocks can't always
+be used as proper expressions. This
+may be addressed in a future version of Perl.
=head3 Switching in a loop
@@ -761,6 +1135,7 @@
For example, here's one way to count how many times a particular
string occurs in an array:
+ use v5.10.1;
my $count = 0;
for (@array) {
when ("foo") { ++$count }
@@ -767,250 +1142,76 @@
}
print "\@array contains $count copies of 'foo'\n";
-At the end of all C<when> blocks, there is an implicit C<next>.
-You can override that with an explicit C<last> if you're only
-interested in the first match.
+Or in a more recent version:
-This doesn't work if you explicitly specify a loop variable,
-as in C<for $item (@array)>. You have to use the default
-variable C<$_>. (You can use C<for my $_ (@array)>.)
+ use v5.14;
+ my $count = 0;
+ for (@array) {
+ ++$count when "foo";
+ }
+ print "\@array contains $count copies of 'foo'\n";
-=head3 Smart matching in detail
+At the end of all C<when> blocks, there is an implicit C<next>.
+You can override that with an explicit C<last> if you're
+interested in only the first match alone.
-The behaviour of a smart match depends on what type of thing its arguments
-are. The behaviour is determined by the following table: the first row
-that applies determines the match behaviour (which is thus mostly
-determined by the type of the right operand). Note that the smart match
-implicitly dereferences any non-blessed hash or array ref, so the "Hash"
-and "Array" entries apply in those cases. (For blessed references, the
-"Object" entries apply.)
+This doesn't work if you explicitly specify a loop variable, as
+in C<for $item (@array)>. You have to use the default variable C<$_>.
-Note that the "Matching Code" column is not always an exact rendition. For
-example, the smart match operator short-circuits whenever possible, but
-C<grep> does not.
-
- $a $b Type of Match Implied Matching Code
- ====== ===== ===================== =============
- Any undef undefined !defined $a
-
- Any Object invokes ~~ overloading on $object, or dies
-
- Hash CodeRef sub truth for each key[1] !grep { !$b->($_) } keys %$a
- Array CodeRef sub truth for each elt[1] !grep { !$b->($_) } @$a
- Any CodeRef scalar sub truth $b->($a)
-
- Hash Hash hash keys identical (every key is found in both hashes)
- Array Hash hash keys intersection grep { exists $b->{$_} } @$a
- Regex Hash hash key grep grep /$a/, keys %$b
- undef Hash always false (undef can't be a key)
- Any Hash hash entry existence exists $b->{$a}
-
- Hash Array hash keys intersection grep { exists $a->{$_} } @$b
- Array Array arrays are comparable[2]
- Regex Array array grep grep /$a/, @$b
- undef Array array contains undef grep !defined, @$b
- Any Array match against an array element[3]
- grep $a ~~ $_, @$b
-
- Hash Regex hash key grep grep /$b/, keys %$a
- Array Regex array grep grep /$b/, @$a
- Any Regex pattern match $a =~ /$b/
-
- Object Any invokes ~~ overloading on $object, or falls back:
- Any Num numeric equality $a == $b
- Num numish[4] numeric equality $a == $b
- undef Any undefined !defined($b)
- Any Any string equality $a eq $b
-
- 1 - empty hashes or arrays will match.
- 2 - that is, each element smart-matches the element of same index in the
- other array. [3]
- 3 - If a circular reference is found, we fall back to referential equality.
- 4 - either a real number, or a string that looks like a number
-
-=head3 Custom matching via overloading
-
-You can change the way that an object is matched by overloading
-the C<~~> operator. This may alter the usual smart match semantics.
-
-It should be noted that C<~~> will refuse to work on objects that
-don't overload it (in order to avoid relying on the object's
-underlying structure).
-
-Note also that smart match's matching rules take precedence over
-overloading, so if C<$obj> has smart match overloading, then
-
- $obj ~~ X
-
-will not automatically invoke the overload method with X as an argument;
-instead the table above is consulted as normal, and based in the type of X,
-overloading may or may not be invoked.
-
-See L<overload>.
-
=head3 Differences from Perl 6
-The Perl 5 smart match and C<given>/C<when> constructs are not
-absolutely identical to their Perl 6 analogues. The most visible
-difference is that, in Perl 5, parentheses are required around
-the argument to C<given()> and C<when()> (except when this last
-one is used as a statement modifier). Parentheses in Perl 6
-are always optional in a control construct such as C<if()>,
-C<while()>, or C<when()>; they can't be made optional in Perl
-5 without a great deal of potential confusion, because Perl 5
-would parse the expression
+The Perl 5 smartmatch and C<given>/C<when> constructs are not compatible
+with their Perl 6 analogues. The most visible difference and least
+important difference is that, in Perl 5, parentheses are required around
+the argument to C<given()> and C<when()> (except when this last one is used
+as a statement modifier). Parentheses in Perl 6 are always optional in a
+control construct such as C<if()>, C<while()>, or C<when()>; they can't be
+made optional in Perl 5 without a great deal of potential confusion,
+because Perl 5 would parse the expression
- given $foo {
- ...
- }
+ given $foo {
+ ...
+ }
as though the argument to C<given> were an element of the hash
C<%foo>, interpreting the braces as hash-element syntax.
-The table of smart matches is not identical to that proposed by the
-Perl 6 specification, mainly due to the differences between Perl 6's
-and Perl 5's data models.
+However, their are many, many other differences. For example,
+this works in Perl 5:
-In Perl 6, C<when()> will always do an implicit smart match
-with its argument, whilst it is convenient in Perl 5 to
-suppress this implicit smart match in certain situations,
-as documented above. (The difference is largely because Perl 5
-does not, even internally, have a boolean type.)
+ use v5.12;
+ my @primary = ("red", "blue", "green");
-=head2 Goto
-X<goto>
+ if (@primary ~~ "red") {
+ say "primary smartmatches red";
+ }
-Although not for the faint of heart, Perl does support a C<goto>
-statement. There are three forms: C<goto>-LABEL, C<goto>-EXPR, and
-C<goto>-&NAME. A loop's LABEL is not actually a valid target for
-a C<goto>; it's just the name of the loop.
-
-The C<goto>-LABEL form finds the statement labeled with LABEL and resumes
-execution there. It may not be used to go into any construct that
-requires initialization, such as a subroutine or a C<foreach> loop. It
-also can't be used to go into a construct that is optimized away. It
-can be used to go almost anywhere else within the dynamic scope,
-including out of subroutines, but it's usually better to use some other
-construct such as C<last> or C<die>. The author of Perl has never felt the
-need to use this form of C<goto> (in Perl, that is--C is another matter).
-
-The C<goto>-EXPR form expects a label name, whose scope will be resolved
-dynamically. This allows for computed C<goto>s per FORTRAN, but isn't
-necessarily recommended if you're optimizing for maintainability:
-
- goto(("FOO", "BAR", "GLARCH")[$i]);
-
-The C<goto>-&NAME form is highly magical, and substitutes a call to the
-named subroutine for the currently running subroutine. This is used by
-C<AUTOLOAD()> subroutines that wish to load another subroutine and then
-pretend that the other subroutine had been called in the first place
-(except that any modifications to C<@_> in the current subroutine are
-propagated to the other subroutine.) After the C<goto>, not even C<caller()>
-will be able to tell that this routine was called first.
-
-In almost all cases like this, it's usually a far, far better idea to use the
-structured control flow mechanisms of C<next>, C<last>, or C<redo> instead of
-resorting to a C<goto>. For certain applications, the catch and throw pair of
-C<eval{}> and die() for exception processing can also be a prudent approach.
-
-=head2 PODs: Embedded Documentation
-X<POD> X<documentation>
-
-Perl has a mechanism for intermixing documentation with source code.
-While it's expecting the beginning of a new statement, if the compiler
-encounters a line that begins with an equal sign and a word, like this
-
- =head1 Here There Be Pods!
-
-Then that text and all remaining text up through and including a line
-beginning with C<=cut> will be ignored. The format of the intervening
-text is described in L<perlpod>.
-
-This allows you to intermix your source code
-and your documentation text freely, as in
-
- =item snazzle($)
-
- The snazzle() function will behave in the most spectacular
- form that you can possibly imagine, not even excepting
- cybernetic pyrotechnics.
-
- =cut back to the compiler, nuff of this pod stuff!
-
- sub snazzle($) {
- my $thingie = shift;
- .........
+ if ("red" ~~ @primary) {
+ say "red smartmatches primary";
}
-Note that pod translators should look at only paragraphs beginning
-with a pod directive (it makes parsing easier), whereas the compiler
-actually knows to look for pod escapes even in the middle of a
-paragraph. This means that the following secret stuff will be
-ignored by both the compiler and the translators.
+ say "that's all, folks!";
- $a=3;
- =secret stuff
- warn "Neither POD nor CODE!?"
- =cut back
- print "got $a\n";
+But it doesn't work at all in Perl 6. Instead, you should
+use the (parallelizable) C<any> operator instead:
-You probably shouldn't rely upon the C<warn()> being podded out forever.
-Not all pod translators are well-behaved in this regard, and perhaps
-the compiler will become pickier.
+ if any(@primary) eq "red" {
+ say "primary smartmatches red";
+ }
-One may also use pod directives to quickly comment out a section
-of code.
+ if "red" eq any(@primary) {
+ say "red smartmatches primary";
+ }
-=head2 Plain Old Comments (Not!)
-X<comment> X<line> X<#> X<preprocessor> X<eval>
+The table of smartmatches in L<perlop/"Smartmatch Operator"> is not
+identical to that proposed by the Perl 6 specification, mainly due to
+differences between Perl 6's and Perl 5's data models, but also because
+the Perl 6 spec has changed since Perl 5 rushed into early adoption.
-Perl can process line directives, much like the C preprocessor. Using
-this, one can control Perl's idea of filenames and line numbers in
-error or warning messages (especially for strings that are processed
-with C<eval()>). The syntax for this mechanism is almost the same as for
-most C preprocessors: it matches the regular expression
+In Perl 6, C<when()> will always do an implicit smartmatch with its
+argument, while in Perl 5 it is convenient (albeit potentially confusing) to
+suppress this implicit smartmatch in various rather loosely-defined
+situations, as roughly outlined above. (The difference is largely because
+Perl 5 does not have, even internally, a boolean type.)
- # example: '# line 42 "new_filename.plx"'
- /^\# \s*
- line \s+ (\d+) \s*
- (?:\s("?)([^"]+)\g2)? \s*
- $/x
-
-with C<$1> being the line number for the next line, and C<$3> being
-the optional filename (specified with or without quotes). Note that
-no whitespace may precede the C<< # >>, unlike modern C preprocessors.
-
-There is a fairly obvious gotcha included with the line directive:
-Debuggers and profilers will only show the last source line to appear
-at a particular line number in a given file. Care should be taken not
-to cause line number collisions in code you'd like to debug later.
-
-Here are some examples that you should be able to type into your command
-shell:
-
- % perl
- # line 200 "bzzzt"
- # the `#' on the previous line must be the first char on line
- die 'foo';
- __END__
- foo at bzzzt line 201.
-
- % perl
- # line 200 "bzzzt"
- eval qq[\n#line 2001 ""\ndie 'foo']; print $@;
- __END__
- foo at - line 2001.
-
- % perl
- eval qq[\n#line 200 "foo bar"\ndie 'foo']; print $@;
- __END__
- foo at foo bar line 200.
-
- % perl
- # line 345 "goop"
- eval "\n#line " . __LINE__ . ' "' . __FILE__ ."\"\ndie 'foo'";
- print $@;
- __END__
- foo at goop line 345.
-
=cut
Property changes on: trunk/contrib/perl/pod/perlsyn.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlthrtut.pod
===================================================================
--- trunk/contrib/perl/pod/perlthrtut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlthrtut.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -7,13 +7,13 @@
=head1 DESCRIPTION
This tutorial describes the use of Perl interpreter threads (sometimes
-referred to as I<ithreads>) that was first introduced in Perl 5.6.0. In this
+referred to as I<ithreads>). In this
model, each thread runs in its own Perl interpreter, and any data sharing
between threads must be explicit. The user-level interface for I<ithreads>
uses the L<threads> class.
B<NOTE>: There was another older Perl threading flavor called the 5.005 model
-that used the L<Threads> class. This old model was known to have problems, is
+that used the L<threads> class. This old model was known to have problems, is
deprecated, and was removed for release 5.10. You are
strongly encouraged to migrate any existing 5.005 threads code to the new
model as soon as possible.
@@ -1043,7 +1043,7 @@
guarantee that a signal sent to a multi-threaded Perl application
will get intercepted by any particular thread. (However, a recently
added feature does provide the capability to send signals between
-threads. See L<threads/"THREAD SIGNALLING> for more details.)
+threads. See L<threads/THREAD SIGNALLING> for more details.)
=head1 Thread-Safety of System Libraries
@@ -1090,7 +1090,7 @@
L<http://search.cpan.org/search?module=threads%3A%3Ashared>
Perl threads mailing list:
-L<http://lists.cpan.org/showlist.cgi?name=iThreads>
+L<http://lists.perl.org/list/ithreads.html>
=head1 Bibliography
Property changes on: trunk/contrib/perl/pod/perlthrtut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perltie.pod
===================================================================
--- trunk/contrib/perl/pod/perltie.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perltie.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -870,11 +870,10 @@
in some special way. See nvi and the Apache module for examples.
When tying a handle, the first argument to C<tie> should begin with an
-asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have assigned
-it to a scalar variable, say C<$handle>, use C<*$handle>. C<tie $handle>
-works, too, but that is considered a bug and will be fixed in Perl 5.16. It
-is supposed to tie the scalar C<$handle>, not the handle inside it.
-C<tie $handle> emits a deprecation warning as of Perl 5.14.
+asterisk. So, if you are tying STDOUT, use C<*STDOUT>. If you have
+assigned it to a scalar variable, say C<$handle>, use C<*$handle>.
+C<tie $handle> ties the scalar variable C<$handle>, not the handle inside
+it.
In our example we're going to create a shouting handle.
Property changes on: trunk/contrib/perl/pod/perltie.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/perltoc.pod (from rev 6437, vendor/perl/5.18.1/pod/perltoc.pod)
===================================================================
--- trunk/contrib/perl/pod/perltoc.pod (rev 0)
+++ trunk/contrib/perl/pod/perltoc.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,33219 @@
+
+# !!!!!!! DO NOT EDIT THIS FILE !!!!!!!
+# This file is autogenerated by buildtoc from all the other pods.
+# Edit those files and run buildtoc --build-toc to effect changes.
+
+=head1 NAME
+
+perltoc - perl documentation table of contents
+
+=head1 DESCRIPTION
+
+This page provides a brief table of contents for the rest of the Perl
+documentation set. It is meant to be scanned quickly or grepped
+through to locate the proper section you're looking for.
+
+=head1 BASIC DOCUMENTATION
+
+=head2 perl - Practical Extraction and Report Language
+
+=over 4
+
+=item SYNOPSIS
+
+=over 4
+
+=item Overview
+
+=item Tutorials
+
+=item Reference Manual
+
+=item Internals and C Language Interface
+
+=item Miscellaneous
+
+=item Language-Specific
+
+=item Platform-Specific
+
+=back
+
+=item DESCRIPTION
+
+=item AVAILABILITY
+
+=item ENVIRONMENT
+
+=item AUTHOR
+
+=item FILES
+
+=item SEE ALSO
+
+=item DIAGNOSTICS
+
+=item BUGS
+
+=item NOTES
+
+=back
+
+=head2 perlintro -- a brief introduction and overview of Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item What is Perl?
+
+=item Running Perl programs
+
+=item Safety net
+
+=item Basic syntax overview
+
+=item Perl variable types
+
+Scalars, Arrays, Hashes
+
+=item Variable scoping
+
+=item Conditional and looping constructs
+
+if, while, for, foreach
+
+=item Builtin operators and functions
+
+Arithmetic, Numeric comparison, String comparison, Boolean logic,
+Miscellaneous
+
+=item Files and I/O
+
+=item Regular expressions
+
+Simple matching, Simple substitution, More complex regular expressions,
+Parentheses for capturing, Other regexp features
+
+=item Writing subroutines
+
+=item OO Perl
+
+=item Using Perl modules
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlreftut - Mark's very short tutorial about references
+
+=over 4
+
+=item DESCRIPTION
+
+=item Who Needs Complicated Data Structures?
+
+=item The Solution
+
+=item Syntax
+
+=over 4
+
+=item Making References
+
+=item Using References
+
+=item An Example
+
+=item Arrow Rule
+
+=back
+
+=item Solution
+
+=item The Rest
+
+=item Summary
+
+=item Credits
+
+=over 4
+
+=item Distribution Conditions
+
+=back
+
+=back
+
+=head2 perldsc - Perl Data Structures Cookbook
+
+=over 4
+
+=item DESCRIPTION
+
+arrays of arrays, hashes of arrays, arrays of hashes, hashes of hashes,
+more elaborate constructs
+
+=item REFERENCES
+X<reference> X<dereference> X<dereferencing> X<pointer>
+
+=item COMMON MISTAKES
+
+=item CAVEAT ON PRECEDENCE
+X<dereference, precedence> X<dereferencing, precedence>
+
+=item WHY YOU SHOULD ALWAYS C<use strict>
+
+=item DEBUGGING
+X<data structure, debugging> X<complex data structure, debugging>
+X<AoA, debugging> X<HoA, debugging> X<AoH, debugging> X<HoH, debugging>
+X<array of arrays, debugging> X<hash of arrays, debugging>
+X<array of hashes, debugging> X<hash of hashes, debugging>
+
+=item CODE EXAMPLES
+
+=item ARRAYS OF ARRAYS
+X<array of arrays> X<AoA>
+
+=over 4
+
+=item Declaration of an ARRAY OF ARRAYS
+
+=item Generation of an ARRAY OF ARRAYS
+
+=item Access and Printing of an ARRAY OF ARRAYS
+
+=back
+
+=item HASHES OF ARRAYS
+X<hash of arrays> X<HoA>
+
+=over 4
+
+=item Declaration of a HASH OF ARRAYS
+
+=item Generation of a HASH OF ARRAYS
+
+=item Access and Printing of a HASH OF ARRAYS
+
+=back
+
+=item ARRAYS OF HASHES
+X<array of hashes> X<AoH>
+
+=over 4
+
+=item Declaration of an ARRAY OF HASHES
+
+=item Generation of an ARRAY OF HASHES
+
+=item Access and Printing of an ARRAY OF HASHES
+
+=back
+
+=item HASHES OF HASHES
+X<hass of hashes> X<HoH>
+
+=over 4
+
+=item Declaration of a HASH OF HASHES
+
+=item Generation of a HASH OF HASHES
+
+=item Access and Printing of a HASH OF HASHES
+
+=back
+
+=item MORE ELABORATE RECORDS
+X<record> X<structure> X<struct>
+
+=over 4
+
+=item Declaration of MORE ELABORATE RECORDS
+
+=item Declaration of a HASH OF COMPLEX RECORDS
+
+=item Generation of a HASH OF COMPLEX RECORDS
+
+=back
+
+=item Database Ties
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perllol - Manipulating Arrays of Arrays in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Declaration and Access of Arrays of Arrays
+
+=item Growing Your Own
+
+=item Access and Printing
+
+=item Slices
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perlrequick - Perl regular expressions quick start
+
+=over 4
+
+=item DESCRIPTION
+
+=item The Guide
+
+=over 4
+
+=item Simple word matching
+
+=item Using character classes
+
+=item Matching this or that
+
+=item Grouping things and hierarchical matching
+
+=item Extracting matches
+
+=item Matching repetitions
+
+=item More matching
+
+=item Search and replace
+
+=item The split operator
+
+=back
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHOR AND COPYRIGHT
+
+=over 4
+
+=item Acknowledgments
+
+=back
+
+=back
+
+=head2 perlretut - Perl regular expressions tutorial
+
+=over 4
+
+=item DESCRIPTION
+
+=item Part 1: The basics
+
+=over 4
+
+=item Simple word matching
+
+=item Using character classes
+
+=item Matching this or that
+
+=item Grouping things and hierarchical matching
+
+=item Extracting matches
+
+=item Backreferences
+
+=item Relative backreferences
+
+=item Named backreferences
+
+=item Alternative capture group numbering
+
+=item Position information
+
+=item Non-capturing groupings
+
+=item Matching repetitions
+
+=item Possessive quantifiers
+
+=item Building a regexp
+
+=item Using regular expressions in Perl
+
+=back
+
+=item Part 2: Power tools
+
+=over 4
+
+=item More on characters, strings, and character classes
+
+=item Compiling and saving regular expressions
+
+=item Composing regular expressions at runtime
+
+=item Embedding comments and modifiers in a regular expression
+
+=item Looking ahead and looking behind
+
+=item Using independent subexpressions to prevent backtracking
+
+=item Conditional expressions
+
+=item Defining named patterns
+
+=item Recursive patterns
+
+=item A bit of magic: executing Perl code in a regular expression
+
+=item Backtracking control verbs
+
+=item Pragmas and debugging
+
+=back
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHOR AND COPYRIGHT
+
+=over 4
+
+=item Acknowledgments
+
+=back
+
+=back
+
+=head2 perlboot - Beginner's Object-Oriented Tutorial
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item If we could talk to the animals...
+
+=item Introducing the method invocation arrow
+
+=item Invoking a barnyard
+
+=item The extra parameter of method invocation
+
+=item Calling a second method to simplify things
+
+=item Inheriting the windpipes
+
+=item A few notes about @ISA
+
+=item Overriding the methods
+
+=item Starting the search from a different place
+
+=item The SUPER way of doing things
+
+=item Where we're at so far...
+
+=item A horse is a horse, of course of course -- or is it?
+
+=item Invoking an instance method
+
+=item Accessing the instance data
+
+=item How to build a horse
+
+=item Inheriting the constructor
+
+=item Making a method work with either classes or instances
+
+=item Adding parameters to a method
+
+=item More interesting instances
+
+=item A horse of a different color
+
+=item Summary
+
+=back
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
+=head2 perltoot - Tom's object-oriented tutorial for perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item Creating a Class
+
+=over 4
+
+=item Object Representation
+
+=item Class Interface
+
+=item Constructors and Instance Methods
+
+=item Planning for the Future: Better Constructors
+
+=item Destructors
+
+=item Other Object Methods
+
+=back
+
+=item Class Data
+
+=over 4
+
+=item Accessing Class Data
+
+=item Debugging Methods
+
+=item Class Destructors
+
+=item Documenting the Interface
+
+=back
+
+=item Aggregation
+
+=item Inheritance
+
+=over 4
+
+=item Overridden Methods
+
+=item Multiple Inheritance
+
+=item UNIVERSAL: The Root of All Objects
+
+=item Deeper UNIVERSAL details
+
+=back
+
+=item Alternate Object Representations
+
+=over 4
+
+=item Arrays as Objects
+
+=item Closures as Objects
+
+=back
+
+=item AUTOLOAD: Proxy Methods
+
+=over 4
+
+=item Autoloaded Data Methods
+
+=item Inherited Autoloaded Data Methods
+
+=back
+
+=item Metaclassical Tools
+
+=over 4
+
+=item Class::Struct
+
+=item Data Members as Variables
+
+=back
+
+=item NOTES
+
+=over 4
+
+=item Object Terminology
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR AND COPYRIGHT
+
+=item COPYRIGHT
+
+=over 4
+
+=item Acknowledgments
+
+=back
+
+=back
+
+=head2 perltooc - Tom's OO Tutorial for Class Data in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item Class Data in a Can
+
+=item Class Data as Package Variables
+
+=over 4
+
+=item Putting All Your Eggs in One Basket
+
+=item Inheritance Concerns
+
+=item The Eponymous Meta-Object
+
+=item Indirect References to Class Data
+
+=item Monadic Classes
+
+=item Translucent Attributes
+
+=back
+
+=item Class Data as Lexical Variables
+
+=over 4
+
+=item Privacy and Responsibility
+
+=item File-Scoped Lexicals
+
+=item More Inheritance Concerns
+
+=item Locking the Door and Throwing Away the Key
+
+=item Translucency Revisited
+
+=back
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR AND COPYRIGHT
+
+=item ACKNOWLEDGEMENTS
+
+=item HISTORY
+
+=back
+
+=head2 perlbot - Bag'o Object Tricks (the BOT)
+
+=over 4
+
+=item DESCRIPTION
+
+=item OO SCALING TIPS
+
+=item INSTANCE VARIABLES
+
+=item SCALAR INSTANCE VARIABLES
+
+=item INSTANCE VARIABLE INHERITANCE
+
+=item OBJECT RELATIONSHIPS
+
+=item OVERRIDING SUPERCLASS METHODS
+
+=item USING RELATIONSHIP WITH SDBM
+
+=item THINKING OF CODE REUSE
+
+=item CLASS CONTEXT AND THE OBJECT
+
+=item INHERITING A CONSTRUCTOR
+
+=item DELEGATION
+
+=item SEE ALSO
+
+=back
+
+=head2 perlstyle - Perl style guide
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 perlcheat - Perl 5 Cheat Sheet
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item The sheet
+
+=back
+
+=item ACKNOWLEDGEMENTS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perltrap - Perl traps for the unwary
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Awk Traps
+
+=item C/C++ Traps
+
+=item Sed Traps
+
+=item Shell Traps
+
+=item Perl Traps
+
+=item Perl4 to Perl5 Traps
+
+Discontinuance, Deprecation, and BugFix traps, Parsing Traps, Numerical
+Traps, General data type traps, Context Traps - scalar, list contexts,
+Precedence Traps, General Regular Expression Traps using s///, etc,
+Subroutine, Signal, Sorting Traps, OS Traps, DBM Traps, Unclassified Traps
+
+=item Discontinuance, Deprecation, and BugFix traps
+
+Symbols starting with "_" no longer forced into main, Double-colon valid
+package separator in variable name, 2nd and 3rd args to C<splice()> are now
+in scalar context, Can't do C<goto> into a block that is optimized away,
+Can't use whitespace as variable name or quote delimiter, C<while/if BLOCK
+BLOCK> gone, C<**> binds tighter than unary minus, C<foreach> changed when
+iterating over a list, C<split> with no args behavior changed, B<-e>
+behavior fixed, C<push> returns number of elements in resulting list, Some
+error messages differ, C<split()> honors subroutine args, Bugs removed
+
+=item Parsing Traps
+
+Space between . and = triggers syntax error, Better parsing in perl 5,
+Function parsing, String interpolation of C<$#array> differs, Perl guesses
+on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
+
+=item Numerical Traps
+
+Formatted output and significant digits, Auto-increment operator over
+signed int limit deleted, Assignment of return values from numeric equality
+tests doesn't work, Bitwise string ops
+
+=item General data type traps
+
+Negative array subscripts now count from the end of array, Setting
+C<$#array> lower now discards array elements, Hashes get defined before
+use, Glob assignment from localized variable to variable, Assigning
+C<undef> to glob, Changes in unary negation (of strings), Modifying of
+constants prohibited, C<defined $var> behavior changed, Variable Suicide
+
+=item Context Traps - scalar, list contexts
+
+Elements of argument lists for formats evaluated in list context,
+C<caller()> returns false value in scalar context if no caller present,
+Comma operator in scalar context gives scalar context to args, C<sprintf()>
+prototyped as C<($;@)>
+
+=item Precedence Traps
+
+LHS vs. RHS of any assignment operator, Semantic errors introduced due to
+precedence, Precedence of assignment operators same as the precedence of
+assignment, C<open> requires parentheses around filehandle, C<$:>
+precedence over C<$::> gone, Precedence of file test operators documented,
+C<keys>, C<each>, C<values> are regular named unary operators
+
+=item General Regular Expression Traps using s///, etc.
+
+C<s'$lhs'$rhs'> interpolates on either side, C<m//g> attaches its state to
+the searched string, C<m//o> used within an anonymous sub, C<$+> isn't set
+to whole match, Substitution now returns null string if it fails,
+C<s`lhs`rhs`> is now a normal substitution, Stricter parsing of variables
+in regular expressions, C<m?x?> matches only once, Failed matches don't
+reset the match variables
+
+=item Subroutine, Signal, Sorting Traps
+
+Barewords that used to look like strings look like subroutine calls,
+Reverse is no longer allowed as the name of a sort subroutine, C<warn()>
+won't let you specify a filehandle
+
+=item OS Traps
+
+SysV resets signal handler correctly, SysV C<seek()> appends correctly
+
+=item Interpolation Traps
+
+C<@> always interpolates an array in double-quotish strings, Double-quoted
+strings may no longer end with an unescaped $, Arbitrary expressions are
+evaluated inside braces within double quotes, C<$$x> now tries to
+dereference $x, Creation of hashes on the fly with C<eval "EXPR"> requires
+protection, Bugs in earlier perl versions, Array and hash brackets during
+interpolation, Interpolation of C<\$$foo{bar}>, C<qq()> string passed to
+C<eval> will not find string terminator
+
+=item DBM Traps
+
+Perl5 must have been linked with same dbm/ndbm as the default for
+C<dbmopen()>, DBM exceeding limit on the key/value size will cause perl5 to
+exit immediately
+
+=item Unclassified Traps
+
+C<require>/C<do> trap using returned value, C<split> on empty string with
+LIMIT specified
+
+=back
+
+=back
+
+=head2 perldebtut - Perl debugging tutorial
+
+=over 4
+
+=item DESCRIPTION
+
+=item use strict
+
+=item Looking at data and -w and v
+
+=item help
+
+=item Stepping through code
+
+=item Placeholder for a, w, t, T
+
+=item REGULAR EXPRESSIONS
+
+=item OUTPUT TIPS
+
+=item CGI
+
+=item GUIs
+
+=item SUMMARY
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item CONTRIBUTORS
+
+=back
+
+=head2 perlfaq - frequently asked questions about Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Where to get the perlfaq
+
+=item How to contribute to the perlfaq
+
+=item What will happen if you mail your Perl programming problems to the
+authors?
+
+=back
+
+=item CREDITS
+
+=item AUTHOR AND COPYRIGHT
+
+=item Table of Contents
+
+perlfaq - this document, perlfaq1 - General Questions About Perl, perlfaq2
+- Obtaining and Learning about Perl, perlfaq3 - Programming Tools, perlfaq4
+- Data Manipulation, perlfaq5 - Files and Formats, perlfaq6 - Regular
+Expressions, perlfaq7 - General Perl Language Issues, perlfaq8 - System
+Interaction, perlfaq9 - Networking
+
+=item The Questions
+
+=over 4
+
+=item L<perlfaq1>: General Questions About Perl
+
+=item L<perlfaq2>: Obtaining and Learning about Perl
+
+=item L<perlfaq3>: Programming Tools
+
+=item L<perlfaq4>: Data Manipulation
+
+=item L<perlfaq5>: Files and Formats
+
+=item L<perlfaq6>: Regular Expressions
+
+=item L<perlfaq7>: General Perl Language Issues
+
+=item L<perlfaq8>: System Interaction
+
+=item L<perlfaq9>: Networking
+
+=back
+
+=back
+
+=head2 perlfaq1 - General Questions About Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item What is Perl?
+
+=item Who supports Perl? Who develops it? Why is it free?
+
+=item Which version of Perl should I use?
+
+=item What are Perl 4, Perl 5, or Perl 6?
+
+=item What was Ponie?
+
+=item What is Perl 6?
+
+=item How stable is Perl?
+
+=item Is Perl difficult to learn?
+
+=item How does Perl compare with other languages like Java, Python, REXX,
+Scheme, or Tcl?
+
+=item Can I do [task] in Perl?
+
+=item When shouldn't I program in Perl?
+
+=item What's the difference between "perl" and "Perl"?
+
+=item Is it a Perl program or a Perl script?
+
+=item What is a JAPH?
+
+=item Where can I get a list of Larry Wall witticisms?
+
+=item How can I convince others to use Perl?
+
+http://perltraining.com.au/whyperl.html,
+http://www.perl.org/advocacy/whyperl.html
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq2 - Obtaining and Learning about Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item What machines support perl? Where do I get it?
+
+=item How can I get a binary version of perl?
+
+=item I don't have a C compiler. How can I build my own Perl interpreter?
+
+=item I copied the perl binary from one machine to another, but scripts
+don't work.
+
+=item I grabbed the sources and tried to compile but gdbm/dynamic
+loading/malloc/linking/... failed. How do I make it work?
+
+=item What modules and extensions are available for Perl? What is CPAN?
+What does CPAN/src/... mean?
+
+=item Is there an ISO or ANSI certified version of Perl?
+
+=item Where can I get information on Perl?
+
+=item What are the Perl newsgroups on Usenet? Where do I post questions?
+
+=item Where should I post source code?
+
+=item Perl Books
+
+References, Tutorials, Task-Oriented, Special Topics
+
+=item Which magazines have Perl content?
+
+=item What mailing lists are there for Perl?
+
+=item Where are the archives for comp.lang.perl.misc?
+
+=item Where can I buy a commercial version of perl?
+
+=item Where do I send bug reports?
+
+=item What is perl.com? Perl Mongers? pm.org? perl.org? cpan.org?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq3 - Programming Tools
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item How do I do (anything)?
+
+=item How can I use Perl interactively?
+
+=item Is there a Perl shell?
+
+=item How do I find which modules are installed on my system?
+
+=item How do I debug my Perl programs?
+
+=item How do I profile my Perl programs?
+
+=item How do I cross-reference my Perl programs?
+
+=item Is there a pretty-printer (formatter) for Perl?
+
+=item Is there a ctags for Perl?
+
+=item Is there an IDE or Windows Perl Editor?
+
+Eclipse, Enginsite, Komodo, Open Perl IDE, OptiPerl, PerlBuilder,
+visiPerl+, Visual Perl, Zeus, GNU Emacs, MicroEMACS, XEmacs, Jed, Elvis,
+Vile, Vim, Codewright, MultiEdit, SlickEdit, Bash, Ksh, Tcsh, Zsh, Affrus,
+Alpha, BBEdit and BBEdit Lite
+
+=item Where can I get Perl macros for vi?
+
+=item Where can I get perl-mode for emacs?
+
+=item How can I use curses with Perl?
+
+=item How can I write a GUI (X, Tk, Gtk, etc.) in Perl?
+X<GUI> X<Tk> X<Wx> X<WxWidgets> X<Gtk> X<Gtk2> X<CamelBones> X<Qt>
+
+Tk, Wx, Gtk and Gtk2, Win32::GUI, CamelBones, Qt, Athena
+
+=item How can I make my Perl program run faster?
+
+=item How can I make my Perl program take less memory?
+
+Don't slurp!, Use map and grep selectively, Avoid unnecessary quotes and
+stringification, Pass by reference, Tie large variables to disk
+
+=item Is it safe to return a reference to local or lexical data?
+
+=item How can I free an array or hash so my program shrinks?
+
+=item How can I make my CGI script more efficient?
+
+=item How can I hide the source for my Perl program?
+
+=item How can I compile my Perl program into byte code or C?
+
+=item How can I get C<#!perl> to work on [MS-DOS,NT,...]?
+
+=item Can I write useful Perl programs on the command line?
+
+=item Why don't Perl one-liners work on my DOS/Mac/VMS system?
+
+=item Where can I learn about CGI or Web programming in Perl?
+
+=item Where can I learn about object-oriented Perl programming?
+
+=item Where can I learn about linking C with Perl?
+
+=item I've read perlembed, perlguts, etc., but I can't embed perl in my C
+program; what am I doing wrong?
+
+=item When I tried to run my script, I got this message. What does it mean?
+
+=item What's MakeMaker?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq4 - Data Manipulation
+
+=over 4
+
+=item DESCRIPTION
+
+=item Data: Numbers
+
+=over 4
+
+=item Why am I getting long decimals (eg, 19.9499999999999) instead of the
+numbers I should be getting (eg, 19.95)?
+
+=item Why is int() broken?
+
+=item Why isn't my octal data interpreted correctly?
+
+=item Does Perl have a round() function? What about ceil() and floor()?
+Trig functions?
+
+=item How do I convert between numeric representations/bases/radixes?
+
+How do I convert hexadecimal into decimal, How do I convert from decimal to
+hexadecimal, How do I convert from octal to decimal, How do I convert from
+decimal to octal, How do I convert from binary to decimal, How do I convert
+from decimal to binary
+
+=item Why doesn't & work the way I want it to?
+
+=item How do I multiply matrices?
+
+=item How do I perform an operation on a series of integers?
+
+=item How can I output Roman numerals?
+
+=item Why aren't my random numbers random?
+
+=item How do I get a random number between X and Y?
+
+=back
+
+=item Data: Dates
+
+=over 4
+
+=item How do I find the day or week of the year?
+
+=item How do I find the current century or millennium?
+
+=item How can I compare two dates and find the difference?
+
+=item How can I take a string and turn it into epoch seconds?
+
+=item How can I find the Julian Day?
+
+=item How do I find yesterday's date?
+
+=item Does Perl have a Year 2000 problem? Is Perl Y2K compliant?
+
+=back
+
+=item Data: Strings
+
+=over 4
+
+=item How do I validate input?
+
+=item How do I unescape a string?
+
+=item How do I remove consecutive pairs of characters?
+
+=item How do I expand function calls in a string?
+
+=item How do I find matching/nesting anything?
+
+=item How do I reverse a string?
+
+=item How do I expand tabs in a string?
+
+=item How do I reformat a paragraph?
+
+=item How can I access or change N characters of a string?
+
+=item How do I change the Nth occurrence of something?
+
+=item How can I count the number of occurrences of a substring within a
+string?
+
+=item How do I capitalize all the words on one line?
+
+=item How can I split a [character] delimited string except when inside
+[character]?
+
+=item How do I strip blank space from the beginning/end of a string?
+
+=item How do I pad a string with blanks or pad a number with zeroes?
+
+=item How do I extract selected columns from a string?
+
+=item How do I find the soundex value of a string?
+
+=item How can I expand variables in text strings?
+
+=item What's wrong with always quoting "$vars"?
+
+=item Why don't my E<lt>E<lt>HERE documents work?
+
+There must be no space after the E<lt>E<lt> part, There (probably) should
+be a semicolon at the end, You can't (easily) have any space in front of
+the tag
+
+=back
+
+=item Data: Arrays
+
+=over 4
+
+=item What is the difference between a list and an array?
+
+=item What is the difference between $array[1] and @array[1]?
+
+=item How can I remove duplicate elements from a list or array?
+
+=item How can I tell whether a certain element is contained in a list or
+array?
+
+=item How do I compute the difference of two arrays? How do I compute the
+intersection of two arrays?
+
+=item How do I test whether two arrays or hashes are equal?
+
+=item How do I find the first array element for which a condition is true?
+
+=item How do I handle linked lists?
+
+=item How do I handle circular lists?
+
+=item How do I shuffle an array randomly?
+
+=item How do I process/modify each element of an array?
+
+=item How do I select a random element from an array?
+
+=item How do I permute N elements of a list?
+X<List::Permuter> X<permute> X<Algorithm::Loops> X<Knuth>
+X<The Art of Computer Programming> X<Fischer-Krause>
+
+=item How do I sort an array by (anything)?
+
+=item How do I manipulate arrays of bits?
+
+=item Why does defined() return true on empty arrays and hashes?
+
+=back
+
+=item Data: Hashes (Associative Arrays)
+
+=over 4
+
+=item How do I process an entire hash?
+
+=item What happens if I add or remove keys from a hash while iterating over
+it?
+
+=item How do I look up a hash element by value?
+
+=item How can I know how many entries are in a hash?
+
+=item How do I sort a hash (optionally by value instead of key)?
+
+=item How can I always keep my hash sorted?
+X<hash tie sort DB_File Tie::IxHash>
+
+=item What's the difference between "delete" and "undef" with hashes?
+
+=item Why don't my tied hashes make the defined/exists distinction?
+
+=item How do I reset an each() operation part-way through?
+
+=item How can I get the unique keys from two hashes?
+
+=item How can I store a multidimensional array in a DBM file?
+
+=item How can I make my hash remember the order I put elements into it?
+
+=item Why does passing a subroutine an undefined element in a hash create
+it?
+
+=item How can I make the Perl equivalent of a C structure/C++ class/hash or
+array of hashes or arrays?
+
+=item How can I use a reference as a hash key?
+
+=back
+
+=item Data: Misc
+
+=over 4
+
+=item How do I handle binary data correctly?
+
+=item How do I determine whether a scalar is a number/whole/integer/float?
+
+=item How do I keep persistent data across program calls?
+
+=item How do I print out or copy a recursive data structure?
+
+=item How do I define methods for every class/object?
+
+=item How do I verify a credit card checksum?
+
+=item How do I pack arrays of doubles or floats for XS code?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq5 - Files and Formats
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item How do I flush/unbuffer an output filehandle? Why must I do this?
+X<flush> X<buffer> X<unbuffer> X<autoflush>
+
+=item How do I count the number of lines in a file?
+X<file, counting lines> X<lines> X<line>
+
+=item How can I use Perl's C<-i> option from within a program?
+X<-i> X<in-place>
+
+=item How can I copy a file?
+X<copy> X<file, copy>
+
+=item How do I make a temporary file name?
+X<file, temporary>
+
+=item How can I manipulate fixed-record-length files?
+X<fixed-length> X<file, fixed-length records>
+
+=item How can I make a filehandle local to a subroutine? How do I pass
+filehandles between subroutines? How do I make an array of filehandles?
+X<filehandle, local> X<filehandle, passing> X<filehandle, reference>
+
+=item How can I use a filehandle indirectly?
+X<filehandle, indirect>
+
+=item How can I set up a footer format to be used with write()?
+X<footer>
+
+=item How can I write() into a string?
+X<write, into a string>
+
+=item How can I open a filehandle to a string?
+X<string>, X<open>, X<IO::Scalar>, X<filehandle>
+
+=item How can I translate tildes (~) in a filename?
+X<tilde> X<tilde expansion>
+
+=item How come when I open a file read-write it wipes it out?
+X<clobber> X<read-write> X<clobbering> X<truncate> X<truncating>
+
+=item Why do I sometimes get an "Argument list too long" when I use
+E<lt>*E<gt>?
+X<argument list too long>
+
+=item Is there a leak/bug in glob()?
+X<glob>
+
+=item How can I open a file with a leading ">" or trailing blanks?
+X<filename, special characters>
+
+=item How can I reliably rename a file?
+X<rename> X<mv> X<move> X<file, rename> X<ren>
+
+=item How can I lock a file?
+X<lock> X<file, lock> X<flock>
+
+=item Why can't I just open(FH, "E<gt>file.lock")?
+X<lock, lockfile race condition>
+
+=item I still don't get locking. I just want to increment the number in
+the file. How can I do this?
+X<counter> X<file, counter>
+
+=item All I want to do is append a small amount of text to the end of a
+file. Do I still have to use locking?
+X<append> X<file, append>
+
+=item How do I randomly update a binary file?
+X<file, binary patch>
+
+=item How do I get a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
+
+=item How do I set a file's timestamp in perl?
+X<timestamp> X<file, timestamp>
+
+=item How do I print to more than one file at once?
+X<print, to multiple files>
+
+=item How can I read in an entire file all at once?
+X<slurp> X<file, slurping>
+
+=item How can I read in a file by paragraphs?
+X<file, reading by paragraphs>
+
+=item How can I read a single character from a file? From the keyboard?
+X<getc> X<file, reading one character at a time>
+
+=item How can I tell whether there's a character waiting on a filehandle?
+
+=item How do I do a C<tail -f> in perl?
+X<tail> X<IO::Handle> X<File::Tail> X<clearerr>
+
+=item How do I dup() a filehandle in Perl?
+X<dup>
+
+=item How do I close a file descriptor by number?
+X<file, closing file descriptors> X<POSIX> X<close>
+
+=item Why can't I use "C:\temp\foo" in DOS paths? Why doesn't
+`C:\temp\foo.exe` work?
+X<filename, DOS issues>
+
+=item Why doesn't glob("*.*") get all the files?
+X<glob>
+
+=item Why does Perl let me delete read-only files? Why does C<-i> clobber
+protected files? Isn't this a bug in Perl?
+
+=item How do I select a random line from a file?
+X<file, selecting a random line>
+
+=item Why do I get weird spaces when I print an array of lines?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq6 - Regular Expressions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item How can I hope to use regular expressions without creating illegible
+and unmaintainable code?
+X<regex, legibility> X<regexp, legibility>
+X<regular expression, legibility> X</x>
+
+Comments Outside the Regex, Comments Inside the Regex, Different Delimiters
+
+=item I'm having trouble matching over more than one line. What's wrong?
+X<regex, multiline> X<regexp, multiline> X<regular expression, multiline>
+
+=item How can I pull out lines between two patterns that are themselves on
+different lines?
+X<..>
+
+=item I put a regular expression into $/ but it didn't work. What's wrong?
+X<$/, regexes in> X<$INPUT_RECORD_SEPARATOR, regexes in>
+X<$RS, regexes in>
+
+=item How do I substitute case insensitively on the LHS while preserving
+case on the RHS?
+X<replace, case preserving> X<substitute, case preserving>
+X<substitution, case preserving> X<s, case preserving>
+
+=item How can I make C<\w> match national character sets?
+X<\w>
+
+=item How can I match a locale-smart version of C</[a-zA-Z]/>?
+X<alpha>
+
+=item How can I quote a variable to use in a regex?
+X<regex, escaping> X<regexp, escaping> X<regular expression, escaping>
+
+=item What is C</o> really for?
+X</o, regular expressions> X<compile, regular expressions>
+
+=item How do I use a regular expression to strip C style comments from a
+file?
+
+=item Can I use Perl regular expressions to match balanced text?
+X<regex, matching balanced test> X<regexp, matching balanced test>
+X<regular expression, matching balanced test>
+
+=item What does it mean that regexes are greedy? How can I get around it?
+X<greedy> X<greediness>
+
+=item How do I process each word on each line?
+X<word>
+
+=item How can I print out a word-frequency or line-frequency summary?
+
+=item How can I do approximate matching?
+X<match, approximate> X<matching, approximate>
+
+=item How do I efficiently match many regular expressions at once?
+X<regex, efficiency> X<regexp, efficiency>
+X<regular expression, efficiency>
+
+=item Why don't word-boundary searches with C<\b> work for me?
+X<\b>
+
+=item Why does using $&, $`, or $' slow my program down?
+X<$MATCH> X<$&> X<$POSTMATCH> X<$'> X<$PREMATCH> X<$`>
+
+=item What good is C<\G> in a regular expression?
+X<\G>
+
+=item Are Perl regexes DFAs or NFAs? Are they POSIX compliant?
+X<DFA> X<NFA> X<POSIX>
+
+=item What's wrong with using grep in a void context?
+X<grep>
+
+=item How can I match strings with multibyte characters?
+X<regex, and multibyte characters> X<regexp, and multibyte characters>
+X<regular expression, and multibyte characters> X<martian> X<encoding,
+Martian>
+
+=item How do I match a regular expression that's in a variable?
+X<regex, in variable> X<eval> X<regex> X<quotemeta> X<\Q, regex>
+X<\E, regex>, X<qr//>
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq7 - General Perl Language Issues
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Can I get a BNF/yacc/RE for the Perl language?
+
+=item What are all these $@%&* punctuation signs, and how do I know when to
+use them?
+
+=item Do I always/never have to quote my strings or use semicolons and
+commas?
+
+=item How do I skip some return values?
+
+=item How do I temporarily block warnings?
+
+=item What's an extension?
+
+=item Why do Perl operators have different precedence than C operators?
+
+=item How do I declare/create a structure?
+
+=item How do I create a module?
+
+=item How do I adopt or take over a module already on CPAN?
+
+=item How do I create a class?
+
+=item How can I tell if a variable is tainted?
+
+=item What's a closure?
+
+=item What is variable suicide and how can I prevent it?
+
+=item How can I pass/return a {Function, FileHandle, Array, Hash, Method,
+Regex}?
+
+Passing Variables and Functions, Passing Filehandles, Passing Regexes,
+Passing Methods
+
+=item How do I create a static variable?
+
+=item What's the difference between dynamic and lexical (static) scoping?
+Between local() and my()?
+
+=item How can I access a dynamic variable while a similarly named lexical
+is in scope?
+
+=item What's the difference between deep and shallow binding?
+
+=item Why doesn't "my($foo) = E<lt>FILEE<gt>;" work right?
+
+=item How do I redefine a builtin function, operator, or method?
+
+=item What's the difference between calling a function as &foo and foo()?
+
+=item How do I create a switch or case statement?
+
+=item How can I catch accesses to undefined variables, functions, or
+methods?
+
+=item Why can't a method included in this same file be found?
+
+=item How can I find out my current package?
+
+=item How can I comment out a large block of perl code?
+
+=item How do I clear a package?
+
+=item How can I use a variable as a variable name?
+
+=item What does "bad interpreter" mean?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq8 - System Interaction
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item How do I find out which operating system I'm running under?
+
+=item How come exec() doesn't return?
+
+=item How do I do fancy stuff with the keyboard/screen/mouse?
+
+Keyboard, Screen, Mouse
+
+=item How do I print something out in color?
+
+=item How do I read just one key without waiting for a return key?
+
+=item How do I check whether input is ready on the keyboard?
+
+=item How do I clear the screen?
+
+=item How do I get the screen size?
+
+=item How do I ask the user for a password?
+
+=item How do I read and write the serial port?
+
+lockfiles, open mode, end of line, flushing output, non-blocking input
+
+=item How do I decode encrypted password files?
+
+=item How do I start a process in the background?
+
+STDIN, STDOUT, and STDERR are shared, Signals, Zombies
+
+=item How do I trap control characters/signals?
+
+=item How do I modify the shadow password file on a Unix system?
+
+=item How do I set the time and date?
+
+=item How can I sleep() or alarm() for under a second?
+X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
+
+=item How can I measure time under a second?
+X<Time::HiRes> X<BSD::Itimer> X<sleep> X<select>
+
+=item How can I do an atexit() or setjmp()/longjmp()? (Exception handling)
+
+=item Why doesn't my sockets program work under System V (Solaris)? What
+does the error message "Protocol not supported" mean?
+
+=item How can I call my system's unique C functions from Perl?
+
+=item Where do I get the include files to do ioctl() or syscall()?
+
+=item Why do setuid perl scripts complain about kernel problems?
+
+=item How can I open a pipe both to and from a command?
+
+=item Why can't I get the output of a command with system()?
+
+=item How can I capture STDERR from an external command?
+
+=item Why doesn't open() return an error when a pipe open fails?
+
+=item What's wrong with using backticks in a void context?
+
+=item How can I call backticks without shell processing?
+
+=item Why can't my script read from STDIN after I gave it EOF (^D on Unix,
+^Z on MS-DOS)?
+
+=item How can I convert my shell script to perl?
+
+=item Can I use perl to run a telnet or ftp session?
+
+=item How can I write expect in Perl?
+
+=item Is there a way to hide perl's command line from programs such as
+"ps"?
+
+=item I {changed directory, modified my environment} in a perl script. How
+come the change disappeared when I exited the script? How do I get my
+changes to be visible?
+
+Unix
+
+=item How do I close a process's filehandle without waiting for it to
+complete?
+
+=item How do I fork a daemon process?
+
+=item How do I find out if I'm running interactively or not?
+
+=item How do I timeout a slow event?
+
+=item How do I set CPU limits?
+X<BSD::Resource> X<limit> X<CPU>
+
+=item How do I avoid zombies on a Unix system?
+
+=item How do I use an SQL database?
+
+=item How do I make a system() exit on control-C?
+
+=item How do I open a file without blocking?
+
+=item How do I tell the difference between errors from the shell and perl?
+
+=item How do I install a module from CPAN?
+
+=item What's the difference between require and use?
+
+=item How do I keep my own module/library directory?
+
+=item How do I add the directory my program lives in to the module/library
+search path?
+
+=item How do I add a directory to my include path (@INC) at runtime?
+
+the PERLLIB environment variable, the PERL5LIB environment variable, the
+perl -Idir command line flag, the use lib pragma:
+
+=item What is socket.ph and where do I get it?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlfaq9 - Networking
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item What is the correct form of response from a CGI script?
+
+=item My CGI script runs from the command line but not the browser. (500
+Server Error)
+
+=item How can I get better error messages from a CGI program?
+
+=item How do I remove HTML from a string?
+
+=item How do I extract URLs?
+
+=item How do I download a file from the user's machine? How do I open a
+file on another machine?
+
+=item How do I make an HTML pop-up menu with Perl?
+
+=item How do I fetch an HTML file?
+
+=item How do I automate an HTML form submission?
+
+=item How do I decode or create those %-encodings on the web?
+
+=item How do I redirect to another page?
+
+=item How do I put a password on my web pages?
+
+=item How do I edit my .htpasswd and .htgroup files with Perl?
+
+=item How do I make sure users can't enter values into a form that cause my
+CGI script to do bad things?
+
+=item How do I parse a mail header?
+
+=item How do I decode a CGI form?
+
+=item How do I check a valid mail address?
+
+=item How do I decode a MIME/BASE64 string?
+
+=item How do I return the user's mail address?
+
+=item How do I send mail?
+
+=item How do I use MIME to make an attachment to a mail message?
+
+=item How do I read mail?
+
+=item How do I find out my hostname, domainname, or IP address?
+X<hostname, domainname, IP address, host, domain, hostfqdn, inet_ntoa,
+gethostbyname, Socket, Net::Domain, Sys::Hostname>
+
+=item How do I fetch a news article or the active newsgroups?
+
+=item How do I fetch/put an FTP file?
+
+=item How can I do RPC in Perl?
+
+=back
+
+=item REVISION
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlsyn - Perl syntax
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Declarations
+X<declaration> X<undef> X<undefined> X<uninitialized>
+
+=item Comments
+X<comment> X<#>
+
+=item Simple Statements
+X<statement> X<semicolon> X<expression> X<;>
+
+=item Truth and Falsehood
+X<truth> X<falsehood> X<true> X<false> X<!> X<not> X<negation> X<0>
+
+=item Statement Modifiers
+X<statement modifier> X<modifier> X<if> X<unless> X<while>
+X<until> X<foreach> X<for>
+
+=item Compound Statements
+X<statement, compound> X<block> X<bracket, curly> X<curly bracket> X<brace>
+X<{> X<}> X<if> X<unless> X<while> X<until> X<foreach> X<for> X<continue>
+
+=item Loop Control
+X<loop control> X<loop, control> X<next> X<last> X<redo> X<continue>
+
+=item For Loops
+X<for> X<foreach>
+
+=item Foreach Loops
+X<for> X<foreach>
+
+=item Basic BLOCKs
+X<block>
+
+=item Switch statements
+X<switch> X<case> X<given> X<when> X<default>
+
+o, o, o, o, o, o, o
+
+=item Goto
+X<goto>
+
+=item PODs: Embedded Documentation
+X<POD> X<documentation>
+
+=item Plain Old Comments (Not!)
+X<comment> X<line> X<#> X<preprocessor> X<eval>
+
+=back
+
+=back
+
+=head2 perldata - Perl data types
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Variable names
+X<variable, name> X<variable name> X<data type> X<type>
+
+=item Context
+X<context> X<scalar context> X<list context>
+
+=item Scalar values
+X<scalar> X<number> X<string> X<reference>
+
+=item Scalar value constructors
+X<scalar, literal> X<scalar, constant>
+
+=item List value constructors
+X<list>
+
+=item Subscripts
+
+=item Slices
+X<slice> X<array, slice> X<hash, slice>
+
+=item Typeglobs and Filehandles
+X<typeglob> X<filehandle> X<*>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlop - Perl operators and precedence
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Operator Precedence and Associativity
+X<operator, precedence> X<precedence> X<associativity>
+
+=item Terms and List Operators (Leftward)
+X<list operator> X<operator, list> X<term>
+
+=item The Arrow Operator
+X<arrow> X<dereference> X<< -> >>
+
+=item Auto-increment and Auto-decrement
+X<increment> X<auto-increment> X<++> X<decrement> X<auto-decrement> X<-->
+
+=item Exponentiation
+X<**> X<exponentiation> X<power>
+
+=item Symbolic Unary Operators
+X<unary operator> X<operator, unary>
+
+=item Binding Operators
+X<binding> X<operator, binding> X<=~> X<!~>
+
+=item Multiplicative Operators
+X<operator, multiplicative>
+
+=item Additive Operators
+X<operator, additive>
+
+=item Shift Operators
+X<shift operator> X<operator, shift> X<<< << >>>
+X<<< >> >>> X<right shift> X<left shift> X<bitwise shift>
+X<shl> X<shr> X<shift, right> X<shift, left>
+
+=item Named Unary Operators
+X<operator, named unary>
+
+=item Relational Operators
+X<relational operator> X<operator, relational>
+
+=item Equality Operators
+X<equality> X<equal> X<equals> X<operator, equality>
+
+=item Bitwise And
+X<operator, bitwise, and> X<bitwise and> X<&>
+
+=item Bitwise Or and Exclusive Or
+X<operator, bitwise, or> X<bitwise or> X<|> X<operator, bitwise, xor>
+X<bitwise xor> X<^>
+
+=item C-style Logical And
+X<&&> X<logical and> X<operator, logical, and>
+
+=item C-style Logical Or
+X<||> X<operator, logical, or>
+
+=item C-style Logical Defined-Or
+X<//> X<operator, logical, defined-or>
+
+=item Range Operators
+X<operator, range> X<range> X<..> X<...>
+
+=item Conditional Operator
+X<operator, conditional> X<operator, ternary> X<ternary> X<?:>
+
+=item Assignment Operators
+X<assignment> X<operator, assignment> X<=> X<**=> X<+=> X<*=> X<&=>
+X<<< <<= >>> X<&&=> X<-=> X</=> X<|=> X<<< >>= >>> X<||=> X<//=> X<.=>
+X<%=> X<^=> X<x=>
+
+=item Comma Operator
+X<comma> X<operator, comma> X<,>
+
+=item List Operators (Rightward)
+X<operator, list, rightward> X<list operator>
+
+=item Logical Not
+X<operator, logical, not> X<not>
+
+=item Logical And
+X<operator, logical, and> X<and>
+
+=item Logical or, Defined or, and Exclusive Or
+X<operator, logical, or> X<operator, logical, xor>
+X<operator, logical, defined or> X<operator, logical, exclusive or>
+X<or> X<xor>
+
+=item C Operators Missing From Perl
+X<operator, missing from perl> X<&> X<*>
+X<typecasting> X<(TYPE)>
+
+unary &, unary *, (TYPE)
+
+=item Quote and Quote-like Operators
+X<operator, quote> X<operator, quote-like> X<q> X<qq> X<qx> X<qw> X<m>
+X<qr> X<s> X<tr> X<'> X<''> X<"> X<""> X<//> X<`> X<``> X<<< << >>>
+X<escape sequence> X<escape>
+
+=item Regexp Quote-Like Operators
+X<operator, regexp>
+
+qr/STRING/msixpo X<qr> X</i> X</m> X</o> X</s> X</x> X</p>,
+m/PATTERN/msixpogc X<m> X<operator, match> X<regexp, options> X<regexp>
+X<regex, options> X<regex> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c>,
+/PATTERN/msixpogc, ?PATTERN? X<?>, s/PATTERN/REPLACEMENT/msixpogce
+X<substitute> X<substitution> X<replace> X<regexp, replace> X<regexp,
+substitute> X</m> X</s> X</i> X</x> X</p> X</o> X</g> X</c> X</e>
+
+=item Quote-Like Operators
+X<operator, quote-like>
+
+q/STRING/ X<q> X<quote, single> X<'> X<''>, 'STRING', qq/STRING/ X<qq>
+X<quote, double> X<"> X<"">, "STRING", qx/STRING/ X<qx> X<`> X<``>
+X<backtick>, `STRING`, qw/STRING/ X<qw> X<quote, list> X<quote, words>,
+tr/SEARCHLIST/REPLACEMENTLIST/cds X<tr> X<y> X<transliterate> X</c> X</d>
+X</s>, y/SEARCHLIST/REPLACEMENTLIST/cds, <<EOF X<here-doc> X<heredoc>
+X<here-document> X<<< << >>>, Double Quotes, Single Quotes, Backticks
+
+=item Gory details of parsing quoted constructs
+X<quote, gory details>
+
+Finding the end, Interpolation X<interpolation>, C<<<'EOF'>, C<m''>, the
+pattern of C<s'''>, C<''>, C<q//>, C<tr'''>, C<y'''>, the replacement of
+C<s'''>, C<tr///>, C<y///>, C<"">, C<``>, C<qq//>, C<qx//>, C<< <file*glob>
+>>, C<<<"EOF">, the replacement of C<s///>, C<RE> in C<?RE?>, C</RE/>,
+C<m/RE/>, C<s/RE/foo/>,, parsing regular expressions X<regexp, parse>,
+Optimization of regular expressions X<regexp, optimization>
+
+=item I/O Operators
+X<operator, i/o> X<operator, io> X<io> X<while> X<filehandle>
+X<< <> >> X<@ARGV>
+
+=item Constant Folding
+X<constant folding> X<folding>
+
+=item No-ops
+X<no-op> X<nop>
+
+=item Bitwise String Operators
+X<operator, bitwise, string>
+
+=item Integer Arithmetic
+X<integer>
+
+=item Floating-point Arithmetic
+X<floating-point> X<floating point> X<float> X<real>
+
+=item Bigger Numbers
+X<number, arbitrary precision>
+
+=back
+
+=back
+
+=head2 perlsub - Perl subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Private Variables via my()
+X<my> X<variable, lexical> X<lexical> X<lexical variable> X<scope, lexical>
+X<lexical scope> X<attributes, my>
+
+=item Persistent Private Variables
+X<state> X<state variable> X<static> X<variable, persistent> X<variable,
+static> X<closure>
+
+=item Temporary Values via local()
+X<local> X<scope, dynamic> X<dynamic scope> X<variable, local>
+X<variable, temporary>
+
+=item Lvalue subroutines
+X<lvalue> X<subroutine, lvalue>
+
+Lvalue subroutines are EXPERIMENTAL
+
+=item Passing Symbol Table Entries (typeglobs)
+X<typeglob> X<*>
+
+=item When to Still Use local()
+X<local> X<variable, local>
+
+=item Pass by Reference
+X<pass by reference> X<pass-by-reference> X<reference>
+
+=item Prototypes
+X<prototype> X<subroutine, prototype>
+
+=item Constant Functions
+X<constant>
+
+=item Overriding Built-in Functions
+X<built-in> X<override> X<CORE> X<CORE::GLOBAL>
+
+=item Autoloading
+X<autoloading> X<AUTOLOAD>
+
+=item Subroutine Attributes
+X<attribute> X<subroutine, attribute> X<attrs>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlfunc - Perl builtin functions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Perl Functions by Category
+X<function>
+
+Functions for SCALARs or strings X<scalar> X<string> X<character>, Regular
+expressions and pattern matching X<regular expression> X<regex> X<regexp>,
+Numeric functions X<numeric> X<number> X<trigonometric> X<trigonometry>,
+Functions for real @ARRAYs X<array>, Functions for list data X<list>,
+Functions for real %HASHes X<hash>, Input and output functions X<I/O>
+X<input> X<output> X<dbm>, Functions for fixed length data or records,
+Functions for filehandles, files, or directories X<file> X<filehandle>
+X<directory> X<pipe> X<link> X<symlink>, Keywords related to the control
+flow of your Perl program X<control flow>, Keywords related to switch,
+Keywords related to scoping, Miscellaneous functions, Functions for
+processes and process groups X<process> X<pid> X<process id>, Keywords
+related to perl modules X<module>, Keywords related to classes and
+object-orientation X<object> X<class> X<package>, Low-level socket
+functions X<socket> X<sock>, System V interprocess communication functions
+X<IPC> X<System V> X<semaphore> X<shared memory> X<memory> X<message>,
+Fetching user and group info X<user> X<group> X<password> X<uid> X<gid>
+X<passwd> X</etc/passwd>, Fetching network info X<network> X<protocol>
+X<host> X<hostname> X<IP> X<address> X<service>, Time-related functions
+X<time> X<date>, Functions new in perl5 X<perl5>, Functions obsoleted in
+perl5
+
+=item Portability
+X<portability> X<Unix> X<portable>
+
+=item Alphabetical Listing of Perl Functions
+
+-I<X> FILEHANDLE
+X<-r>X<-w>X<-x>X<-o>X<-R>X<-W>X<-X>X<-O>X<-e>X<-z>X<-s>X<-f>X<-d>X<-l>X<-p>
+X<-S>X<-b>X<-c>X<-t>X<-u>X<-g>X<-k>X<-T>X<-B>X<-M>X<-A>X<-C>, -I<X> EXPR,
+-I<X> DIRHANDLE, -I<X>, abs VALUE X<abs> X<absolute>, abs, accept
+NEWSOCKET,GENERICSOCKET X<accept>, alarm SECONDS X<alarm> X<SIGALRM>
+X<timer>, alarm, atan2 Y,X X<atan2> X<arctangent> X<tan> X<tangent>, bind
+SOCKET,NAME X<bind>, binmode FILEHANDLE, LAYER X<binmode> X<binary> X<text>
+X<DOS> X<Windows>, binmode FILEHANDLE, bless REF,CLASSNAME X<bless>, bless
+REF, break, caller EXPR X<caller> X<call stack> X<stack> X<stack trace>,
+caller, chdir EXPR X<chdir> X<cd> X<directory, change>, chdir FILEHANDLE,
+chdir DIRHANDLE, chdir, chmod LIST X<chmod> X<permission> X<mode>, chomp
+VARIABLE X<chomp> X<INPUT_RECORD_SEPARATOR> X<$/> X<newline> X<eol>, chomp(
+LIST ), chomp, chop VARIABLE X<chop>, chop( LIST ), chop, chown LIST
+X<chown> X<owner> X<user> X<group>, chr NUMBER X<chr> X<character> X<ASCII>
+X<Unicode>, chr, chroot FILENAME X<chroot> X<root>, chroot, close
+FILEHANDLE X<close>, close, closedir DIRHANDLE X<closedir>, connect
+SOCKET,NAME X<connect>, continue BLOCK X<continue>, continue, cos EXPR
+X<cos> X<cosine> X<acos> X<arccosine>, cos, crypt PLAINTEXT,SALT X<crypt>
+X<digest> X<hash> X<salt> X<plaintext> X<password> X<decrypt>
+X<cryptography> X<passwd> X<encrypt>, dbmclose HASH X<dbmclose>, dbmopen
+HASH,DBNAME,MASK X<dbmopen> X<dbm> X<ndbm> X<sdbm> X<gdbm>, defined EXPR
+X<defined> X<undef> X<undefined>, defined, delete EXPR X<delete>, die LIST
+X<die> X<throw> X<exception> X<raise> X<$@> X<abort>, do BLOCK X<do>
+X<block>, do SUBROUTINE(LIST) X<do>, do EXPR X<do>, dump LABEL X<dump>
+X<core> X<undump>, dump, each HASH X<each> X<hash, iterator>, eof
+FILEHANDLE X<eof> X<end of file> X<end-of-file>, eof (), eof, eval EXPR
+X<eval> X<try> X<catch> X<evaluate> X<parse> X<execute> X<error, handling>
+X<exception, handling>, eval BLOCK, eval, exec LIST X<exec> X<execute>,
+exec PROGRAM LIST, exists EXPR X<exists> X<autovivification>, exit EXPR
+X<exit> X<terminate> X<abort>, exit, exp EXPR X<exp> X<exponential>
+X<antilog> X<antilogarithm> X<e>, exp, fcntl FILEHANDLE,FUNCTION,SCALAR
+X<fcntl>, fileno FILEHANDLE X<fileno>, flock FILEHANDLE,OPERATION X<flock>
+X<lock> X<locking>, fork X<fork> X<child> X<parent>, format X<format>,
+formline PICTURE,LIST X<formline>, getc FILEHANDLE X<getc> X<getchar>
+X<character> X<file, read>, getc, getlogin X<getlogin> X<login>,
+getpeername SOCKET X<getpeername> X<peer>, getpgrp PID X<getpgrp> X<group>,
+getppid X<getppid> X<parent> X<pid>, getpriority WHICH,WHO X<getpriority>
+X<priority> X<nice>, getpwnam NAME X<getpwnam> X<getgrnam> X<gethostbyname>
+X<getnetbyname> X<getprotobyname> X<getpwuid> X<getgrgid> X<getservbyname>
+X<gethostbyaddr> X<getnetbyaddr> X<getprotobynumber> X<getservbyport>
+X<getpwent> X<getgrent> X<gethostent> X<getnetent> X<getprotoent>
+X<getservent> X<setpwent> X<setgrent> X<sethostent> X<setnetent>
+X<setprotoent> X<setservent> X<endpwent> X<endgrent> X<endhostent>
+X<endnetent> X<endprotoent> X<endservent>, getgrnam NAME, gethostbyname
+NAME, getnetbyname NAME, getprotobyname NAME, getpwuid UID, getgrgid GID,
+getservbyname NAME,PROTO, gethostbyaddr ADDR,ADDRTYPE, getnetbyaddr
+ADDR,ADDRTYPE, getprotobynumber NUMBER, getservbyport PORT,PROTO, getpwent,
+getgrent, gethostent, getnetent, getprotoent, getservent, setpwent,
+setgrent, sethostent STAYOPEN, setnetent STAYOPEN, setprotoent STAYOPEN,
+setservent STAYOPEN, endpwent, endgrent, endhostent, endnetent,
+endprotoent, endservent, getsockname SOCKET X<getsockname>, getsockopt
+SOCKET,LEVEL,OPTNAME X<getsockopt>, glob EXPR X<glob> X<wildcard>
+X<filename, expansion> X<expand>, glob, gmtime EXPR X<gmtime> X<UTC>
+X<Greenwich>, gmtime, goto LABEL X<goto> X<jump> X<jmp>, goto EXPR, goto
+&NAME, grep BLOCK LIST X<grep>, grep EXPR,LIST, hex EXPR X<hex>
+X<hexadecimal>, hex, import LIST X<import>, index STR,SUBSTR,POSITION
+X<index> X<indexOf> X<InStr>, index STR,SUBSTR, int EXPR X<int> X<integer>
+X<truncate> X<trunc> X<floor>, int, ioctl FILEHANDLE,FUNCTION,SCALAR
+X<ioctl>, join EXPR,LIST X<join>, keys HASH X<keys> X<key>, kill SIGNAL,
+LIST X<kill> X<signal>, last LABEL X<last> X<break>, last, lc EXPR X<lc>
+X<lowercase>, lc, lcfirst EXPR X<lcfirst> X<lowercase>, lcfirst, length
+EXPR X<length> X<size>, length, link OLDFILE,NEWFILE X<link>, listen
+SOCKET,QUEUESIZE X<listen>, local EXPR X<local>, localtime EXPR
+X<localtime> X<ctime>, localtime, lock THING X<lock>, log EXPR X<log>
+X<logarithm> X<e> X<ln> X<base>, log, lstat EXPR X<lstat>, lstat, m//, map
+BLOCK LIST X<map>, map EXPR,LIST, mkdir FILENAME,MASK X<mkdir> X<md>
+X<directory, create>, mkdir FILENAME, mkdir, msgctl ID,CMD,ARG X<msgctl>,
+msgget KEY,FLAGS X<msgget>, msgrcv ID,VAR,SIZE,TYPE,FLAGS X<msgrcv>, msgsnd
+ID,MSG,FLAGS X<msgsnd>, my EXPR X<my>, my TYPE EXPR, my EXPR : ATTRS, my
+TYPE EXPR : ATTRS, next LABEL X<next> X<continue>, next, no Module VERSION
+LIST X<no>, no Module VERSION, no Module LIST, no Module, no VERSION, oct
+EXPR X<oct> X<octal> X<hex> X<hexadecimal> X<binary> X<bin>, oct, open
+FILEHANDLE,EXPR X<open> X<pipe> X<file, open> X<fopen>, open
+FILEHANDLE,MODE,EXPR, open FILEHANDLE,MODE,EXPR,LIST, open
+FILEHANDLE,MODE,REFERENCE, open FILEHANDLE, opendir DIRHANDLE,EXPR
+X<opendir>, ord EXPR X<ord> X<encoding>, ord, our EXPR X<our> X<global>,
+our TYPE EXPR, our EXPR : ATTRS, our TYPE EXPR : ATTRS, pack TEMPLATE,LIST
+X<pack>, package NAMESPACE X<package> X<module> X<namespace>, package, pipe
+READHANDLE,WRITEHANDLE X<pipe>, pop ARRAY X<pop> X<stack>, pop, pos SCALAR
+X<pos> X<match, position>, pos, print FILEHANDLE LIST X<print>, print LIST,
+print, printf FILEHANDLE FORMAT, LIST X<printf>, printf FORMAT, LIST,
+prototype FUNCTION X<prototype>, push ARRAY,LIST X<push> X<stack>,
+q/STRING/, qq/STRING/, qr/STRING/, qx/STRING/, qw/STRING/, quotemeta EXPR
+X<quotemeta> X<metacharacter>, quotemeta, rand EXPR X<rand> X<random>,
+rand, read FILEHANDLE,SCALAR,LENGTH,OFFSET X<read> X<file, read>, read
+FILEHANDLE,SCALAR,LENGTH, readdir DIRHANDLE X<readdir>, readline EXPR,
+readline X<readline> X<gets> X<fgets>, readlink EXPR X<readlink>, readlink,
+readpipe EXPR, readpipe X<readpipe>, recv SOCKET,SCALAR,LENGTH,FLAGS
+X<recv>, redo LABEL X<redo>, redo, ref EXPR X<ref> X<reference>, ref,
+rename OLDNAME,NEWNAME X<rename> X<move> X<mv> X<ren>, require VERSION
+X<require>, require EXPR, require, reset EXPR X<reset>, reset, return EXPR
+X<return>, return, reverse LIST X<reverse> X<rev> X<invert>, rewinddir
+DIRHANDLE X<rewinddir>, rindex STR,SUBSTR,POSITION X<rindex>, rindex
+STR,SUBSTR, rmdir FILENAME X<rmdir> X<rd> X<directory, remove>, rmdir,
+s///, say FILEHANDLE LIST X<say>, say LIST, say, scalar EXPR X<scalar>
+X<context>, seek FILEHANDLE,POSITION,WHENCE X<seek> X<fseek> X<filehandle,
+position>, seekdir DIRHANDLE,POS X<seekdir>, select FILEHANDLE X<select>
+X<filehandle, default>, select, select RBITS,WBITS,EBITS,TIMEOUT X<select>,
+semctl ID,SEMNUM,CMD,ARG X<semctl>, semget KEY,NSEMS,FLAGS X<semget>, semop
+KEY,OPSTRING X<semop>, send SOCKET,MSG,FLAGS,TO X<send>, send
+SOCKET,MSG,FLAGS, setpgrp PID,PGRP X<setpgrp> X<group>, setpriority
+WHICH,WHO,PRIORITY X<setpriority> X<priority> X<nice> X<renice>, setsockopt
+SOCKET,LEVEL,OPTNAME,OPTVAL X<setsockopt>, shift ARRAY X<shift>, shift,
+shmctl ID,CMD,ARG X<shmctl>, shmget KEY,SIZE,FLAGS X<shmget>, shmread
+ID,VAR,POS,SIZE X<shmread> X<shmwrite>, shmwrite ID,STRING,POS,SIZE,
+shutdown SOCKET,HOW X<shutdown>, sin EXPR X<sin> X<sine> X<asin>
+X<arcsine>, sin, sleep EXPR X<sleep> X<pause>, sleep, socket
+SOCKET,DOMAIN,TYPE,PROTOCOL X<socket>, socketpair
+SOCKET1,SOCKET2,DOMAIN,TYPE,PROTOCOL X<socketpair>, sort SUBNAME LIST
+X<sort> X<qsort> X<quicksort> X<mergesort>, sort BLOCK LIST, sort LIST,
+splice ARRAY,OFFSET,LENGTH,LIST X<splice>, splice ARRAY,OFFSET,LENGTH,
+splice ARRAY,OFFSET, splice ARRAY, split /PATTERN/,EXPR,LIMIT X<split>,
+split /PATTERN/,EXPR, split /PATTERN/, split, sprintf FORMAT, LIST
+X<sprintf>, format parameter index, flags, vector flag, (minimum) width,
+precision, or maximum width X<precision>, size, order of arguments, sqrt
+EXPR X<sqrt> X<root> X<square root>, sqrt, srand EXPR X<srand> X<seed>
+X<randseed>, srand, stat FILEHANDLE X<stat> X<file, status> X<ctime>, stat
+EXPR, stat DIRHANDLE, stat, state EXPR X<state>, state TYPE EXPR, state
+EXPR : ATTRS, state TYPE EXPR : ATTRS, study SCALAR X<study>, study, sub
+NAME BLOCK X<sub>, sub NAME (PROTO) BLOCK, sub NAME : ATTRS BLOCK, sub NAME
+(PROTO) : ATTRS BLOCK, substr EXPR,OFFSET,LENGTH,REPLACEMENT X<substr>
+X<substring> X<mid> X<left> X<right>, substr EXPR,OFFSET,LENGTH, substr
+EXPR,OFFSET, symlink OLDFILE,NEWFILE X<symlink> X<link> X<symbolic link>
+X<link, symbolic>, syscall NUMBER, LIST X<syscall> X<system call>, sysopen
+FILEHANDLE,FILENAME,MODE X<sysopen>, sysopen
+FILEHANDLE,FILENAME,MODE,PERMS, sysread FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<sysread>, sysread FILEHANDLE,SCALAR,LENGTH, sysseek
+FILEHANDLE,POSITION,WHENCE X<sysseek> X<lseek>, system LIST X<system>
+X<shell>, system PROGRAM LIST, syswrite FILEHANDLE,SCALAR,LENGTH,OFFSET
+X<syswrite>, syswrite FILEHANDLE,SCALAR,LENGTH, syswrite FILEHANDLE,SCALAR,
+tell FILEHANDLE X<tell>, tell, telldir DIRHANDLE X<telldir>, tie
+VARIABLE,CLASSNAME,LIST X<tie>, tied VARIABLE X<tied>, time X<time>
+X<epoch>, times X<times>, tr///, truncate FILEHANDLE,LENGTH X<truncate>,
+truncate EXPR,LENGTH, uc EXPR X<uc> X<uppercase> X<toupper>, uc, ucfirst
+EXPR X<ucfirst> X<uppercase>, ucfirst, umask EXPR X<umask>, umask, undef
+EXPR X<undef> X<undefine>, undef, unlink LIST X<unlink> X<delete> X<remove>
+X<rm> X<del>, unlink, unpack TEMPLATE,EXPR X<unpack>, unpack TEMPLATE,
+untie VARIABLE X<untie>, unshift ARRAY,LIST X<unshift>, use Module VERSION
+LIST X<use> X<module> X<import>, use Module VERSION, use Module LIST, use
+Module, use VERSION, utime LIST X<utime>, values HASH X<values>, vec
+EXPR,OFFSET,BITS X<vec> X<bit> X<bit vector>, wait X<wait>, waitpid
+PID,FLAGS X<waitpid>, wantarray X<wantarray> X<context>, warn LIST X<warn>
+X<warning> X<STDERR>, write FILEHANDLE X<write>, write EXPR, write, y///
+
+=back
+
+=back
+
+=head2 perlopentut - tutorial on opening things in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item Open E<agrave> la shell
+
+=over 4
+
+=item Simple Opens
+
+=item Indirect Filehandles
+
+=item Pipe Opens
+
+=item The Minus File
+
+=item Mixing Reads and Writes
+
+=item Filters
+
+=back
+
+=item Open E<agrave> la C
+
+=over 4
+
+=item Permissions E<agrave> la mode
+
+=back
+
+=item Obscure Open Tricks
+
+=over 4
+
+=item Re-Opening Files (dups)
+
+=item Dispelling the Dweomer
+
+=item Paths as Opens
+
+=item Single Argument Open
+
+=item Playing with STDIN and STDOUT
+
+=back
+
+=item Other I/O Issues
+
+=over 4
+
+=item Opening Non-File Files
+
+=item Opening Named Pipes
+
+=item Opening Sockets
+
+=item Binary Files
+
+=item File Locking
+
+=item IO Layers
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR and COPYRIGHT
+
+=item HISTORY
+
+=back
+
+=head2 perlpacktut - tutorial on C<pack> and C<unpack>
+
+=over 4
+
+=item DESCRIPTION
+
+=item The Basic Principle
+
+=item Packing Text
+
+=item Packing Numbers
+
+=over 4
+
+=item Integers
+
+=item Unpacking a Stack Frame
+
+=item How to Eat an Egg on a Net
+
+=item Byte-order modifiers
+
+=item Floating point Numbers
+
+=back
+
+=item Exotic Templates
+
+=over 4
+
+=item Bit Strings
+
+=item Uuencoding
+
+=item Doing Sums
+
+=item Unicode
+
+=item Another Portable Binary Encoding
+
+=back
+
+=item Template Grouping
+
+=item Lengths and Widths
+
+=over 4
+
+=item String Lengths
+
+=item Dynamic Templates
+
+=item Counting Repetitions
+
+=back
+
+=item Packing and Unpacking C Structures
+
+=over 4
+
+=item The Alignment Pit
+
+=item Dealing with Endian-ness
+
+=item Alignment, Take 2
+
+=item Alignment, Take 3
+
+=item Pointers for How to Use Them
+
+=back
+
+=item Pack Recipes
+
+=item Funnies Section
+
+=item Authors
+
+=back
+
+=head2 perlpod - the Plain Old Documentation format
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Ordinary Paragraph
+X<POD, ordinary paragraph>
+
+=item Verbatim Paragraph
+X<POD, verbatim paragraph> X<verbatim>
+
+=item Command Paragraph
+X<POD, command>
+
+C<=head1 I<Heading Text>> X<=head1> X<=head2> X<=head3> X<=head4> X<head1>
+X<head2> X<head3> X<head4>, C<=head2 I<Heading Text>>, C<=head3 I<Heading
+Text>>, C<=head4 I<Heading Text>>, C<=over I<indentlevel>> X<=over>
+X<=item> X<=back> X<over> X<item> X<back>, C<=item I<stuff...>>, C<=back>,
+C<=cut> X<=cut> X<cut>, C<=pod> X<=pod> X<pod>, C<=begin I<formatname>>
+X<=begin> X<=end> X<=for> X<begin> X<end> X<for>, C<=end I<formatname>>,
+C<=for I<formatname> I<text...>>, C<=encoding I<encodingname>> X<=encoding>
+X<encoding>
+
+=item Formatting Codes
+X<POD, formatting code> X<formatting code>
+X<POD, interior sequence> X<interior sequence>
+
+C<IE<lt>textE<gt>> -- italic text X<I> X<< IZ<><> >> X<POD, formatting
+code, italic> X<italic>, C<BE<lt>textE<gt>> -- bold text X<B> X<< BZ<><> >>
+X<POD, formatting code, bold> X<bold>, C<CE<lt>codeE<gt>> -- code text X<C>
+X<< CZ<><> >> X<POD, formatting code, code> X<code>, C<LE<lt>nameE<gt>> --
+a hyperlink X<L> X<< LZ<><> >> X<POD, formatting code, hyperlink>
+X<hyperlink>, C<EE<lt>escapeE<gt>> -- a character escape X<E> X<< EZ<><> >>
+X<POD, formatting code, escape> X<escape>, C<FE<lt>filenameE<gt>> -- used
+for filenames X<F> X<< FZ<><> >> X<POD, formatting code, filename>
+X<filename>, C<SE<lt>textE<gt>> -- text contains non-breaking spaces X<S>
+X<< SZ<><> >> X<POD, formatting code, non-breaking space> X<non-breaking
+space>, C<XE<lt>topic nameE<gt>> -- an index entry X<X> X<< XZ<><> >>
+X<POD, formatting code, index entry> X<index entry>, C<ZE<lt>E<gt>> -- a
+null (zero-effect) formatting code X<Z> X<< ZZ<><> >> X<POD, formatting
+code, null> X<null>
+
+=item The Intent
+X<POD, intent of>
+
+=item Embedding Pods in Perl Modules
+X<POD, embedding>
+
+=item Hints for Writing Pod
+
+X<podchecker> X<POD, validating>
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perlpodspec - Plain Old Documentation: format specification and
+notes
+
+=over 4
+
+=item DESCRIPTION
+
+=item Pod Definitions
+
+=item Pod Commands
+
+"=head1", "=head2", "=head3", "=head4", "=pod", "=cut", "=over", "=item",
+"=back", "=begin formatname", "=end formatname", "=for formatname text...",
+"=encoding encodingname"
+
+=item Pod Formatting Codes
+
+C<IE<lt>textE<gt>> -- italic text, C<BE<lt>textE<gt>> -- bold text,
+C<CE<lt>codeE<gt>> -- code text, C<FE<lt>filenameE<gt>> -- style for
+filenames, C<XE<lt>topic nameE<gt>> -- an index entry, C<ZE<lt>E<gt>> -- a
+null (zero-effect) formatting code, C<LE<lt>nameE<gt>> -- a hyperlink,
+C<EE<lt>escapeE<gt>> -- a character escape, C<SE<lt>textE<gt>> -- text
+contains non-breaking spaces
+
+=item Notes on Implementing Pod Processors
+
+=item About LE<lt>...E<gt> Codes
+
+First:, Second:, Third:, Fourth:, Fifth:, Sixth:
+
+=item About =over...=back Regions
+
+=item About Data Paragraphs and "=begin/=end" Regions
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perlrun - how to execute the Perl interpreter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item #! and quoting on non-Unix systems
+X<hashbang> X<#!>
+
+OS/2, MS-DOS, Win95/NT, Macintosh, VMS
+
+=item Location of Perl
+X<perl, location of interpreter>
+
+=item Command Switches
+X<perl, command switches> X<command switches>
+
+B<-0>[I<octal/hexadecimal>] X<-0> X<$/>, B<-a> X<-a> X<autosplit>, B<-C
+[I<number/list>]> X<-C>, B<-c> X<-c>, B<-d> X<-d> X<-dt>, B<-dt>,
+B<-d:>I<foo[=bar,baz]> X<-d> X<-dt>, B<-dt:>I<foo[=bar,baz]>,
+B<-D>I<letters> X<-D> X<DEBUGGING> X<-DDEBUGGING>, B<-D>I<number>, B<-e>
+I<commandline> X<-e>, B<-E> I<commandline> X<-E>, B<-f> X<-f>,
+B<-F>I<pattern> X<-F>, B<-h> X<-h>, B<-i>[I<extension>] X<-i> X<in-place>,
+B<-I>I<directory> X<-I> X<@INC>, B<-l>[I<octnum>] X<-l> X<$/> X<$\>,
+B<-m>[B<->]I<module> X<-m> X<-M>, B<-M>[B<->]I<module>,
+B<-M>[B<->]I<'module ...'>, B<-[mM]>[B<->]I<module=arg[,arg]...>, B<-n>
+X<-n>, B<-p> X<-p>, B<-P> X<-P>, B<-s> X<-s>, B<-S> X<-S>, B<-t> X<-t>,
+B<-T> X<-T>, B<-u> X<-u>, B<-U> X<-U>, B<-v> X<-v>, B<-V> X<-V>,
+B<-V:>I<configvar>, B<-w> X<-w>, B<-W> X<-W>, B<-X> X<-X>, B<-x> X<-x>,
+B<-x>I<directory>
+
+=back
+
+=item ENVIRONMENT
+X<perl, environment variables>
+
+HOME X<HOME>, LOGDIR X<LOGDIR>, PATH X<PATH>, PERL5LIB X<PERL5LIB>,
+PERL5OPT X<PERL5OPT>, PERLIO X<PERLIO>, :bytes X<:bytes>, :crlf X<:crlf>,
+:mmap X<:mmap>, :perlio X<:perlio>, :pop X<:pop>, :raw X<:raw>, :stdio
+X<:stdio>, :unix X<:unix>, :utf8 X<:utf8>, :win32 X<:win32>, PERLIO_DEBUG
+X<PERLIO_DEBUG>, PERLLIB X<PERLLIB>, PERL5DB X<PERL5DB>, PERL5DB_THREADED
+X<PERL5DB_THREADED>, PERL5SHELL (specific to the Win32 port) X<PERL5SHELL>,
+PERL_ALLOW_NON_IFS_LSP (specific to the Win32 port)
+X<PERL_ALLOW_NON_IFS_LSP>, PERL_DEBUG_MSTATS X<PERL_DEBUG_MSTATS>,
+PERL_DESTRUCT_LEVEL X<PERL_DESTRUCT_LEVEL>, PERL_DL_NONLAZY
+X<PERL_DL_NONLAZY>, PERL_ENCODING X<PERL_ENCODING>, PERL_HASH_SEED
+X<PERL_HASH_SEED>, PERL_HASH_SEED_DEBUG X<PERL_HASH_SEED_DEBUG>, PERL_ROOT
+(specific to the VMS port) X<PERL_ROOT>, PERL_SIGNALS X<PERL_SIGNALS>,
+PERL_UNICODE X<PERL_UNICODE>, SYS$LOGIN (specific to the VMS port)
+X<SYS$LOGIN>
+
+=back
+
+=head2 perldiag - various Perl diagnostics
+
+=over 4
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 perllexwarn - Perl Lexical Warnings
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Default Warnings and Optional Warnings
+
+=item What's wrong with B<-w> and C<$^W>
+
+=item Controlling Warnings from the Command Line
+
+B<-w> X<-w>, B<-W> X<-W>, B<-X> X<-X>
+
+=item Backward Compatibility
+
+=item Category Hierarchy
+X<warning, categories>
+
+=item Fatal Warnings
+X<warning, fatal>
+
+=item Reporting Warnings from a Module
+X<warning, reporting> X<warning, registering>
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perldebug - Perl debugging
+
+=over 4
+
+=item DESCRIPTION
+
+=item The Perl Debugger
+
+=over 4
+
+=item Calling the debugger
+
+perl -d program_name, perl -d -e 0, perl -d:Ptkdb program_name, perl -dt
+threaded_program_name
+
+=item Debugger Commands
+
+h X<debugger command, h>, h [command], h h, p expr X<debugger command, p>,
+x [maxdepth] expr X<debugger command, x>, V [pkg [vars]] X<debugger
+command, V>, X [vars] X<debugger command, X>, y [level [vars]] X<debugger
+command, y>, T X<debugger command, T> X<backtrace> X<stack, backtrace>, s
+[expr] X<debugger command, s> X<step>, n [expr] X<debugger command, n>, r
+X<debugger command, r>, <CR>, c [line|sub] X<debugger command, c>, l
+X<debugger command, l>, l min+incr, l min-max, l line, l subname, -
+X<debugger command, ->, v [line] X<debugger command, v>, . X<debugger
+command, .>, f filename X<debugger command, f>, /pattern/, ?pattern?, L
+[abw] X<debugger command, L>, S [[!]regex] X<debugger command, S>, t
+X<debugger command, t>, t expr X<debugger command, t>, b X<breakpoint>
+X<debugger command, b>, b [line] [condition] X<breakpoint> X<debugger
+command, b>, b subname [condition] X<breakpoint> X<debugger command, b>, b
+postpone subname [condition] X<breakpoint> X<debugger command, b>, b load
+filename X<breakpoint> X<debugger command, b>, b compile subname
+X<breakpoint> X<debugger command, b>, B line X<breakpoint> X<debugger
+command, B>, B * X<breakpoint> X<debugger command, B>, a [line] command
+X<debugger command, a>, A line X<debugger command, A>, A * X<debugger
+command, A>, w expr X<debugger command, w>, W expr X<debugger command, W>,
+W * X<debugger command, W>, o X<debugger command, o>, o booloption ...
+X<debugger command, o>, o anyoption? ... X<debugger command, o>, o
+option=value ... X<debugger command, o>, < ? X<< debugger command, < >>, <
+[ command ] X<< debugger command, < >>, < * X<< debugger command, < >>, <<
+command X<< debugger command, << >>, > ? X<< debugger command, > >>, >
+command X<< debugger command, > >>, > * X<< debugger command, > >>, >>
+command X<<< debugger command, >> >>>, { ? X<debugger command, {>, { [
+command ], { * X<debugger command, {>, {{ command X<debugger command, {{>,
+! number X<debugger command, !>, ! -number X<debugger command, !>, !
+pattern X<debugger command, !>, !! cmd X<debugger command, !!>, source file
+X<debugger command, source>, H -number X<debugger command, H>, q or ^D
+X<debugger command, q> X<debugger command, ^D>, R X<debugger command, R>,
+|dbcmd X<debugger command, |>, ||dbcmd X<debugger command, ||>, command, m
+expr X<debugger command, m>, M X<debugger command, M>, man [manpage]
+X<debugger command, man>
+
+=item Configurable Options
+
+C<recallCommand>, C<ShellBang> X<debugger option, recallCommand> X<debugger
+option, ShellBang>, C<pager> X<debugger option, pager>, C<tkRunning>
+X<debugger option, tkRunning>, C<signalLevel>, C<warnLevel>, C<dieLevel>
+X<debugger option, signalLevel> X<debugger option, warnLevel> X<debugger
+option, dieLevel>, C<AutoTrace> X<debugger option, AutoTrace>, C<LineInfo>
+X<debugger option, LineInfo>, C<inhibit_exit> X<debugger option,
+inhibit_exit>, C<PrintRet> X<debugger option, PrintRet>, C<ornaments>
+X<debugger option, ornaments>, C<frame> X<debugger option, frame>,
+C<maxTraceLen> X<debugger option, maxTraceLen>, C<windowSize> X<debugger
+option, windowSize>, C<arrayDepth>, C<hashDepth> X<debugger option,
+arrayDepth> X<debugger option, hashDepth>, C<dumpDepth> X<debugger option,
+dumpDepth>, C<compactDump>, C<veryCompact> X<debugger option, compactDump>
+X<debugger option, veryCompact>, C<globPrint> X<debugger option,
+globPrint>, C<DumpDBFiles> X<debugger option, DumpDBFiles>, C<DumpPackages>
+X<debugger option, DumpPackages>, C<DumpReused> X<debugger option,
+DumpReused>, C<quote>, C<HighBit>, C<undefPrint> X<debugger option, quote>
+X<debugger option, HighBit> X<debugger option, undefPrint>, C<UsageOnly>
+X<debugger option, UsageOnly>, C<TTY> X<debugger option, TTY>, C<noTTY>
+X<debugger option, noTTY>, C<ReadLine> X<debugger option, ReadLine>,
+C<NonStop> X<debugger option, NonStop>
+
+=item Debugger input/output
+
+Prompt, Multiline commands, Stack backtrace X<backtrace> X<stack,
+backtrace>, Line Listing Format, Frame listing
+
+=item Debugging compile-time statements
+
+=item Debugger Customization
+
+=item Readline Support
+
+=item Editor Support for Debugging
+
+=item The Perl Profiler
+X<profile> X<profiling> X<profiler>
+
+=back
+
+=item Debugging regular expressions
+X<regular expression, debugging>
+X<regex, debugging> X<regexp, debugging>
+
+=item Debugging memory usage
+X<memory usage>
+
+=item SEE ALSO
+
+=item BUGS
+
+=back
+
+=head2 perlvar - Perl predefined variables
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Predefined Names
+
+$ARG, $_ X<$_> X<$ARG>, $a, $b X<$a> X<$b>, $<I<digits>> X<$1> X<$2> X<$3>,
+$MATCH, $& X<$&> X<$MATCH>, ${^MATCH} X<${^MATCH}>, $PREMATCH, $` X<$`>
+X<$PREMATCH>, ${^PREMATCH} X<${^PREMATCH}>, $POSTMATCH, $' X<$'>
+X<$POSTMATCH>, ${^POSTMATCH} X<${^POSTMATCH}>, $LAST_PAREN_MATCH, $+ X<$+>
+X<$LAST_PAREN_MATCH>, $LAST_SUBMATCH_RESULT, $^N X<$^N>, @LAST_MATCH_END,
+ at + X<@+> X<@LAST_MATCH_END>, %+ X<%+>, HANDLE->input_line_number(EXPR),
+$INPUT_LINE_NUMBER, $NR, $. X<$.> X<$NR> X<$INPUT_LINE_NUMBER> X<line
+number>, IO::Handle->input_record_separator(EXPR), $INPUT_RECORD_SEPARATOR,
+$RS, $/ X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>, HANDLE->autoflush(EXPR),
+$OUTPUT_AUTOFLUSH, $| X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>,
+IO::Handle->output_field_separator EXPR, $OUTPUT_FIELD_SEPARATOR, $OFS, $,
+X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>,
+IO::Handle->output_record_separator EXPR, $OUTPUT_RECORD_SEPARATOR, $ORS,
+$\ X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>, $LIST_SEPARATOR, $" X<$">
+X<$LIST_SEPARATOR>, $SUBSCRIPT_SEPARATOR, $SUBSEP, $; X<$;> X<$SUBSEP>
+X<SUBSCRIPT_SEPARATOR>, HANDLE->format_page_number(EXPR),
+$FORMAT_PAGE_NUMBER, $% X<$%> X<$FORMAT_PAGE_NUMBER>,
+HANDLE->format_lines_per_page(EXPR), $FORMAT_LINES_PER_PAGE, $= X<$=>
+X<$FORMAT_LINES_PER_PAGE>, HANDLE->format_lines_left(EXPR),
+$FORMAT_LINES_LEFT, $- X<$-> X<$FORMAT_LINES_LEFT>, @LAST_MATCH_START, @-
+X<@-> X<@LAST_MATCH_START>, C<$`> is the same as C<substr($var, 0, $-[0])>,
+C<$&> is the same as C<substr($var, $-[0], $+[0] - $-[0])>, C<$'> is the
+same as C<substr($var, $+[0])>, C<$1> is the same as C<substr($var, $-[1],
+$+[1] - $-[1])>, C<$2> is the same as C<substr($var, $-[2], $+[2] -
+$-[2])>, C<$3> is the same as C<substr($var, $-[3], $+[3] - $-[3])>, %-
+X<%->, HANDLE->format_name(EXPR), $FORMAT_NAME, $~ X<$~> X<$FORMAT_NAME>,
+HANDLE->format_top_name(EXPR), $FORMAT_TOP_NAME, $^ X<$^>
+X<$FORMAT_TOP_NAME>, IO::Handle->format_line_break_characters EXPR,
+$FORMAT_LINE_BREAK_CHARACTERS, $: X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>,
+IO::Handle->format_formfeed EXPR, $FORMAT_FORMFEED, $^L X<$^L>
+X<$FORMAT_FORMFEED>, $ACCUMULATOR, $^A X<$^A> X<$ACCUMULATOR>,
+$CHILD_ERROR, $? X<$?> X<$CHILD_ERROR>, ${^CHILD_ERROR_NATIVE}
+X<$^CHILD_ERROR_NATIVE>, ${^ENCODING} X<$^ENCODING>, $OS_ERROR, $ERRNO, $!
+X<$!> X<$ERRNO> X<$OS_ERROR>, %OS_ERROR, %ERRNO, %! X<%!>,
+$EXTENDED_OS_ERROR, $^E X<$^E> X<$EXTENDED_OS_ERROR>, $EVAL_ERROR, $@ X<$@>
+X<$EVAL_ERROR>, $PROCESS_ID, $PID, $$ X<$$> X<$PID> X<$PROCESS_ID>,
+$REAL_USER_ID, $UID, $< X<< $< >> X<$UID> X<$REAL_USER_ID>,
+$EFFECTIVE_USER_ID, $EUID, $> X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>,
+$REAL_GROUP_ID, $GID, $( X<$(> X<$GID> X<$REAL_GROUP_ID>,
+$EFFECTIVE_GROUP_ID, $EGID, $) X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>,
+$PROGRAM_NAME, $0 X<$0> X<$PROGRAM_NAME>, $[ X<$[>, $] X<$]>, $COMPILING,
+$^C X<$^C> X<$COMPILING>, $DEBUGGING, $^D X<$^D> X<$DEBUGGING>,
+${^RE_DEBUG_FLAGS}, ${^RE_TRIE_MAXBUF}, $SYSTEM_FD_MAX, $^F X<$^F>
+X<$SYSTEM_FD_MAX>, $^H, %^H, $INPLACE_EDIT, $^I X<$^I> X<$INPLACE_EDIT>,
+$^M X<$^M>, $OSNAME, $^O X<$^O> X<$OSNAME>, ${^OPEN}, $PERLDB, $^P X<$^P>
+X<$PERLDB>, 0x01, 0x02, 0x04, 0x08, 0x10, 0x20, 0x40, 0x80, 0x100, 0x200,
+0x400, $LAST_REGEXP_CODE_RESULT, $^R X<$^R> X<$LAST_REGEXP_CODE_RESULT>,
+$EXCEPTIONS_BEING_CAUGHT, $^S X<$^S> X<$EXCEPTIONS_BEING_CAUGHT>,
+$BASETIME, $^T X<$^T> X<$BASETIME>, ${^TAINT}, ${^UNICODE}, ${^UTF8CACHE},
+${^UTF8LOCALE}, $PERL_VERSION, $^V X<$^V> X<$PERL_VERSION>, $WARNING, $^W
+X<$^W> X<$WARNING>, ${^WARNING_BITS}, ${^WIN32_SLOPPY_STAT},
+$EXECUTABLE_NAME, $^X X<$^X> X<$EXECUTABLE_NAME>, ARGV X<ARGV>, $ARGV
+X<$ARGV>, @ARGV X<@ARGV>, ARGVOUT X<ARGVOUT>, @F X<@F>, @INC X<@INC>, @ARG,
+ at _ X<@_> X<@ARG>, %INC X<%INC>, %ENV, $ENV{expr} X<%ENV>, %SIG, $SIG{expr}
+X<%SIG>
+
+=item Error Indicators
+X<error> X<exception>
+
+=item Technical Note on the Syntax of Variable Names
+
+=back
+
+=item BUGS
+
+=back
+
+=head2 perlre - Perl regular expressions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Modifiers
+
+m X</m> X<regex, multiline> X<regexp, multiline> X<regular expression,
+multiline>, s X</s> X<regex, single-line> X<regexp, single-line> X<regular
+expression, single-line>, i X</i> X<regex, case-insensitive> X<regexp,
+case-insensitive> X<regular expression, case-insensitive>, x X</x>, p X</p>
+X<regex, preserve> X<regexp, preserve>, g and c X</g> X</c>
+
+=item Regular Expressions
+
+[1], [2], [3], cntrl X<cntrl>, graph X<graph>, print X<print>, punct
+X<punct>, xdigit X<xdigit>
+
+=item Extended Patterns
+
+C<(?#text)> X<(?#)>, C<(?pimsx-imsx)> X<(?)>, C<(?:pattern)> X<(?:)>,
+C<(?imsx-imsx:pattern)>, C<(?|pattern)> X<(?|)> X<Branch reset>,
+Look-Around Assertions X<look-around assertion> X<lookaround assertion>
+X<look-around> X<lookaround>, C<(?=pattern)> X<(?=)> X<look-ahead,
+positive> X<lookahead, positive>, C<(?!pattern)> X<(?!)> X<look-ahead,
+negative> X<lookahead, negative>, C<(?<=pattern)> C<\K> X<(?<=)>
+X<look-behind, positive> X<lookbehind, positive> X<\K>, C<(?<!pattern)>
+X<(?<!)> X<look-behind, negative> X<lookbehind, negative>,
+C<(?'NAME'pattern)>, C<< (?<NAME>pattern) >> X<< (?<NAME>) >> X<(?'NAME')>
+X<named capture> X<capture>, C<< \k<NAME> >>, C<< \k'NAME' >>, C<(?{ code
+})> X<(?{})> X<regex, code in> X<regexp, code in> X<regular expression,
+code in>, C<(??{ code })> X<(??{})> X<regex, postponed> X<regexp,
+postponed> X<regular expression, postponed>, C<(?PARNO)> C<(?-PARNO)>
+C<(?+PARNO)> C<(?R)> C<(?0)> X<(?PARNO)> X<(?1)> X<(?R)> X<(?0)> X<(?-1)>
+X<(?+1)> X<(?-PARNO)> X<(?+PARNO)> X<regex, recursive> X<regexp, recursive>
+X<regular expression, recursive> X<regex, relative recursion>, C<(?&NAME)>
+X<(?&NAME)>, C<(?(condition)yes-pattern|no-pattern)> X<(?()>,
+C<(?(condition)yes-pattern)>, (1) (2) .., (<NAME>) ('NAME'), (?{ CODE }),
+(R), (R1) (R2) .., (R&NAME), (DEFINE), C<< (?>pattern) >> X<backtrack>
+X<backtracking> X<atomic> X<possessive>
+
+=item Special Backtracking Control Verbs
+
+Verbs that take an argument, C<(*PRUNE)> C<(*PRUNE:NAME)> X<(*PRUNE)>
+X<(*PRUNE:NAME)>, C<(*SKIP)> C<(*SKIP:NAME)> X<(*SKIP)>, C<(*MARK:NAME)>
+C<(*:NAME)> X<(*MARK)> C<(*MARK:NAME)> C<(*:NAME)>, C<(*THEN)>
+C<(*THEN:NAME)>, C<(*COMMIT)> X<(*COMMIT)>, Verbs without an argument,
+C<(*FAIL)> C<(*F)> X<(*FAIL)> X<(*F)>, C<(*ACCEPT)> X<(*ACCEPT)>
+
+=item Backtracking
+X<backtrack> X<backtracking>
+
+=item Version 8 Regular Expressions
+X<regular expression, version 8> X<regex, version 8> X<regexp, version 8>
+
+=item Warning on \1 Instead of $1
+
+=item Repeated Patterns Matching a Zero-length Substring
+
+=item Combining RE Pieces
+
+C<ST>, C<S|T>, C<S{REPEAT_COUNT}>, C<S{min,max}>, C<S{min,max}?>, C<S?>,
+C<S*>, C<S+>, C<S??>, C<S*?>, C<S+?>, C<< (?>S) >>, C<(?=S)>, C<(?<=S)>,
+C<(?!S)>, C<(?<!S)>, C<(??{ EXPR })>, C<(?PARNO)>,
+C<(?(condition)yes-pattern|no-pattern)>
+
+=item Creating Custom RE Engines
+
+=back
+
+=item PCRE/Python Support
+
+C<< (?PE<lt>NAMEE<gt>pattern) >>, C<< (?P=NAME) >>, C<< (?P>NAME) >>
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 perlrebackslash - Perl Regular Expression Backslash Sequences and
+Escapes
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item The backslash
+
+[1]
+
+=item All the sequences and escapes
+
+=item Character Escapes
+
+[1], [2]
+
+=item Modifiers
+
+=item Character classes
+
+=item Referencing
+
+=item Assertions
+
+\A, \z, \Z, \G, \b, \B
+
+=item Misc
+
+\C, \K, \R, \X
+
+=back
+
+=back
+
+=head2 perlrecharclass - Perl Regular Expression Character Classes
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item The dot
+
+=item Backslashed sequences
+
+[1]
+
+=item Bracketed Character Classes
+
+cntrl, graph, print, punct
+
+=item Locale, Unicode and UTF-8
+
+=back
+
+=back
+
+=head2 perlreref - Perl Regular Expressions Reference
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item OPERATORS
+
+=item SYNTAX
+
+=item ESCAPE SEQUENCES
+
+=item CHARACTER CLASSES
+
+=item ANCHORS
+
+=item QUANTIFIERS
+
+=item EXTENDED CONSTRUCTS
+
+=item VARIABLES
+
+=item FUNCTIONS
+
+=item TERMINOLOGY
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=item THANKS
+
+=back
+
+=head2 perlref - Perl references and nested data structures
+
+=over 4
+
+=item NOTE
+
+=item DESCRIPTION
+
+=over 4
+
+=item Making References
+X<reference, creation> X<referencing>
+
+1. X<\> X<backslash>, 2. X<array, anonymous> X<[> X<[]> X<square bracket>
+X<bracket, square> X<arrayref> X<array reference> X<reference, array>, 3.
+X<hash, anonymous> X<{> X<{}> X<curly bracket> X<bracket, curly> X<brace>
+X<hashref> X<hash reference> X<reference, hash>, 4. X<subroutine,
+anonymous> X<subroutine, reference> X<reference, subroutine> X<scope,
+lexical> X<closure> X<lexical> X<lexical scope>, 5. X<constructor> X<new>,
+6. X<autovivification>, 7. X<*foo{THING}> X<*>
+
+=item Using References
+X<reference, use> X<dereferencing> X<dereference>
+
+=item Symbolic references
+X<reference, symbolic> X<reference, soft>
+X<symbolic reference> X<soft reference>
+
+=item Not-so-symbolic references
+
+=item Pseudo-hashes: Using an array as a hash
+X<pseudo-hash> X<pseudo hash> X<pseudohash>
+
+=item Function Templates
+X<scope, lexical> X<closure> X<lexical> X<lexical scope>
+X<subroutine, nested> X<sub, nested> X<subroutine, local> X<sub, local>
+
+=back
+
+=item WARNING
+X<reference, string context> X<reference, use as hash key>
+
+=item SEE ALSO
+
+=back
+
+=head2 perlform - Perl formats
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Text Fields
+X<format, text field>
+
+=item Numeric Fields
+X<#> X<format, numeric field>
+
+=item The Field @* for Variable Width Multi-Line Text
+X<@*>
+
+=item The Field ^* for Variable Width One-line-at-a-time Text
+X<^*>
+
+=item Specifying Values
+X<format, specifying values>
+
+=item Using Fill Mode
+X<format, fill mode>
+
+=item Suppressing Lines Where All Fields Are Void
+X<format, suppressing lines>
+
+=item Repeating Format Lines
+X<format, repeating lines>
+
+=item Top of Form Processing
+X<format, top of form> X<top> X<header>
+
+=item Format Variables
+X<format variables>
+X<format, variables>
+
+=back
+
+=item NOTES
+
+=over 4
+
+=item Footers
+X<format, footer> X<footer>
+
+=item Accessing Formatting Internals
+X<format, internals>
+
+=back
+
+=item WARNINGS
+
+=back
+
+=head2 perlobj - Perl objects
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item An Object is Simply a Reference
+X<object> X<bless> X<constructor> X<new>
+
+=item A Class is Simply a Package
+X<class> X<package> X<@ISA> X<inheritance>
+
+=item A Method is Simply a Subroutine
+X<method>
+
+=item Method Invocation
+X<invocation> X<method> X<arrow> X<< -> >>
+
+=item Indirect Object Syntax
+X<indirect object syntax> X<invocation, indirect> X<indirect>
+
+=item Default UNIVERSAL methods
+X<UNIVERSAL>
+
+isa(CLASS) X<isa>, can(METHOD) X<can>, VERSION( [NEED] ) X<VERSION>
+
+=item Destructors
+X<destructor> X<DESTROY>
+
+=item Summary
+
+=item Two-Phased Garbage Collection
+X<garbage collection> X<GC> X<circular reference>
+X<reference, circular> X<DESTROY> X<destructor>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perltie - how to hide an object class in a simple variable
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Tying Scalars
+X<scalar, tying>
+
+TIESCALAR classname, LIST X<TIESCALAR>, FETCH this X<FETCH>, STORE this,
+value X<STORE>, UNTIE this X<UNTIE>, DESTROY this X<DESTROY>
+
+=item Tying Arrays
+X<array, tying>
+
+TIEARRAY classname, LIST X<TIEARRAY>, FETCH this, index X<FETCH>, STORE
+this, index, value X<STORE>, FETCHSIZE this X<FETCHSIZE>, STORESIZE this,
+count X<STORESIZE>, EXTEND this, count X<EXTEND>, EXISTS this, key
+X<EXISTS>, DELETE this, key X<DELETE>, CLEAR this X<CLEAR>, PUSH this, LIST
+ X<PUSH>, POP this X<POP>, SHIFT this X<SHIFT>, UNSHIFT this, LIST
+X<UNSHIFT>, SPLICE this, offset, length, LIST X<SPLICE>, UNTIE this
+X<UNTIE>, DESTROY this X<DESTROY>
+
+=item Tying Hashes
+X<hash, tying>
+
+USER, HOME, CLOBBER, LIST, TIEHASH classname, LIST X<TIEHASH>, FETCH this,
+key X<FETCH>, STORE this, key, value X<STORE>, DELETE this, key X<DELETE>,
+CLEAR this X<CLEAR>, EXISTS this, key X<EXISTS>, FIRSTKEY this X<FIRSTKEY>,
+NEXTKEY this, lastkey X<NEXTKEY>, SCALAR this X<SCALAR>, UNTIE this
+X<UNTIE>, DESTROY this X<DESTROY>
+
+=item Tying FileHandles
+X<filehandle, tying>
+
+TIEHANDLE classname, LIST X<TIEHANDLE>, WRITE this, LIST X<WRITE>, PRINT
+this, LIST X<PRINT>, PRINTF this, LIST X<PRINTF>, READ this, LIST X<READ>,
+READLINE this X<READLINE>, GETC this X<GETC>, CLOSE this X<CLOSE>, UNTIE
+this X<UNTIE>, DESTROY this X<DESTROY>
+
+=item UNTIE this
+X<UNTIE>
+
+=item The C<untie> Gotcha
+X<untie>
+
+=back
+
+=item SEE ALSO
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 perldbmfilter - Perl DBM Filters
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>,
+B<filter_fetch_value>
+
+=over 4
+
+=item The Filter
+
+=item An Example -- the NULL termination problem.
+
+=item Another Example -- Key is a C int.
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 perlipc - Perl interprocess communication (signals, fifos, pipes,
+safe subprocesses, sockets, and semaphores)
+
+=over 4
+
+=item DESCRIPTION
+
+=item Signals
+
+=over 4
+
+=item Handling the SIGHUP Signal in Daemons
+
+=back
+
+=item Named Pipes
+
+=over 4
+
+=item Deferred Signals (Safe Signals)
+
+Long-running opcodes, Interrupting IO, Restartable system calls, Signals as
+"faults", Signals triggered by operating system state
+
+=back
+
+=item Using open() for IPC
+
+=over 4
+
+=item Filehandles
+
+=item Background Processes
+
+=item Complete Dissociation of Child from Parent
+
+=item Safe Pipe Opens
+
+=item Bidirectional Communication with Another Process
+
+=item Bidirectional Communication with Yourself
+
+=back
+
+=item Sockets: Client/Server Communication
+
+=over 4
+
+=item Internet Line Terminators
+
+=item Internet TCP Clients and Servers
+
+=item Unix-Domain TCP Clients and Servers
+
+=back
+
+=item TCP Clients with IO::Socket
+
+=over 4
+
+=item A Simple Client
+
+C<Proto>, C<PeerAddr>, C<PeerPort>
+
+=item A Webget Client
+
+=item Interactive Client with IO::Socket
+
+=back
+
+=item TCP Servers with IO::Socket
+
+Proto, LocalPort, Listen, Reuse
+
+=item UDP: Message Passing
+
+=item SysV IPC
+
+=item NOTES
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlfork - Perl's fork() emulation
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Behavior of other Perl features in forked pseudo-processes
+
+$$ or $PROCESS_ID, %ENV, chdir() and all other builtins that accept
+filenames, wait() and waitpid(), kill(), exec(), exit(), Open handles to
+files, directories and network sockets
+
+=item Resource limits
+
+=item Killing the parent process
+
+=item Lifetime of the parent process and pseudo-processes
+
+=item CAVEATS AND LIMITATIONS
+
+BEGIN blocks, Open filehandles, Forking pipe open() not yet implemented,
+Global state maintained by XSUBs, Interpreter embedded in larger
+application, Thread-safety of extensions
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlnumber - semantics of numbers and numeric operations in Perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Storing numbers
+
+=item Numeric operators and numeric conversions
+
+=item Flavors of Perl numeric operations
+
+Arithmetic operators, ++, Arithmetic operators during C<use integer>, Other
+mathematical operators, Bitwise operators, Bitwise operators during C<use
+integer>, Operators which expect an integer, Operators which expect a
+string
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlthrtut - Tutorial on threads in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item What Is A Thread Anyway?
+
+=item Threaded Program Models
+
+=over 4
+
+=item Boss/Worker
+
+=item Work Crew
+
+=item Pipeline
+
+=back
+
+=item What kind of threads are Perl threads?
+
+=item Thread-Safe Modules
+
+=item Thread Basics
+
+=over 4
+
+=item Basic Thread Support
+
+=item A Note about the Examples
+
+=item Creating Threads
+
+=item Waiting For A Thread To Exit
+
+=item Ignoring A Thread
+
+=item Process and Thread Termination
+
+=back
+
+=item Threads And Data
+
+=over 4
+
+=item Shared And Unshared Data
+
+=item Thread Pitfalls: Races
+
+=back
+
+=item Synchronization and control
+
+=over 4
+
+=item Controlling access: lock()
+
+=item A Thread Pitfall: Deadlocks
+
+=item Queues: Passing Data Around
+
+=item Semaphores: Synchronizing Data Access
+
+=item Basic semaphores
+
+=item Advanced Semaphores
+
+=item Waiting for a Condition
+
+=item Giving up control
+
+=back
+
+=item General Thread Utility Routines
+
+=over 4
+
+=item What Thread Am I In?
+
+=item Thread IDs
+
+=item Are These Threads The Same?
+
+=item What Threads Are Running?
+
+=back
+
+=item A Complete Example
+
+=item Different implementations of threads
+
+=item Performance considerations
+
+=item Process-scope Changes
+
+=item Thread-Safety of System Libraries
+
+=item Conclusion
+
+=item SEE ALSO
+
+=item Bibliography
+
+=over 4
+
+=item Introductory Texts
+
+=item OS-Related References
+
+=item Other References
+
+=back
+
+=item Acknowledgements
+
+=item AUTHOR
+
+=item Copyrights
+
+=back
+
+=head2 perlothrtut - old tutorial on threads in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item What Is A Thread Anyway?
+
+=item Threaded Program Models
+
+=over 4
+
+=item Boss/Worker
+
+=item Work Crew
+
+=item Pipeline
+
+=back
+
+=item Native threads
+
+=item What kind of threads are perl threads?
+
+=item Threadsafe Modules
+
+=item Thread Basics
+
+=over 4
+
+=item Basic Thread Support
+
+=item Creating Threads
+
+=item Giving up control
+
+=item Waiting For A Thread To Exit
+
+=item Errors In Threads
+
+=item Ignoring A Thread
+
+=back
+
+=item Threads And Data
+
+=over 4
+
+=item Shared And Unshared Data
+
+=item Thread Pitfall: Races
+
+=item Controlling access: lock()
+
+=item Thread Pitfall: Deadlocks
+
+=item Queues: Passing Data Around
+
+=back
+
+=item Threads And Code
+
+=over 4
+
+=item Semaphores: Synchronizing Data Access
+
+Basic semaphores, Advanced Semaphores
+
+=item Attributes: Restricting Access To Subroutines
+
+=item Subroutine Locks
+
+=item Methods
+
+=item Locking A Subroutine
+
+=back
+
+=item General Thread Utility Routines
+
+=over 4
+
+=item What Thread Am I In?
+
+=item Thread IDs
+
+=item Are These Threads The Same?
+
+=item What Threads Are Running?
+
+=back
+
+=item A Complete Example
+
+=item Conclusion
+
+=item Bibliography
+
+=over 4
+
+=item Introductory Texts
+
+=item OS-Related References
+
+=item Other References
+
+=back
+
+=item Acknowledgements
+
+=item AUTHOR
+
+=item Copyrights
+
+=back
+
+=head2 perlport - Writing portable Perl
+
+=over 4
+
+=item DESCRIPTION
+
+Not all Perl programs have to be portable, Nearly all of Perl already I<is>
+portable
+
+=item ISSUES
+
+=over 4
+
+=item Newlines
+
+=item Numbers endianness and Width
+
+=item Files and Filesystems
+
+=item System Interaction
+
+=item Command names versus file pathnames
+
+=item Networking
+
+=item Interprocess Communication (IPC)
+
+=item External Subroutines (XS)
+
+=item Standard Modules
+
+=item Time and Date
+
+=item Character sets and character encoding
+
+=item Internationalisation
+
+=item System Resources
+
+=item Security
+
+=item Style
+
+=back
+
+=item CPAN Testers
+
+=item PLATFORMS
+
+=over 4
+
+=item Unix
+
+=item DOS and Derivatives
+
+=item S<Mac OS>
+
+=item VMS
+
+=item VOS
+
+=item EBCDIC Platforms
+
+=item Acorn RISC OS
+
+=item Other perls
+
+=back
+
+=item FUNCTION IMPLEMENTATIONS
+
+=over 4
+
+=item Alphabetical Listing of Perl Functions
+
+-I<X>, atan2, binmode, chmod, chown, chroot, crypt, dbmclose, dbmopen,
+dump, exec, exit, fcntl, flock, fork, getlogin, getpgrp, getppid,
+getpriority, getpwnam, getgrnam, getnetbyname, getpwuid, getgrgid,
+getnetbyaddr, getprotobynumber, getservbyport, getpwent, getgrent,
+gethostbyname, gethostent, getnetent, getprotoent, getservent, sethostent,
+setnetent, setprotoent, setservent, endpwent, endgrent, endhostent,
+endnetent, endprotoent, endservent, getsockopt SOCKET,LEVEL,OPTNAME, glob,
+gmtime, ioctl FILEHANDLE,FUNCTION,SCALAR, kill, link, localtime, lstat,
+msgctl, msgget, msgsnd, msgrcv, open, pipe, readlink, rename, select,
+semctl, semget, semop, setgrent, setpgrp, setpriority, setpwent,
+setsockopt, shmctl, shmget, shmread, shmwrite, sockatmark, socketpair,
+stat, symlink, syscall, sysopen, system, times, truncate, umask, utime,
+wait, waitpid
+
+=back
+
+=item Supported Platforms
+
+=item SEE ALSO
+
+=item AUTHORS / CONTRIBUTORS
+
+=back
+
+=head2 perllocale - Perl locale handling (internationalization and
+localization)
+
+=over 4
+
+=item DESCRIPTION
+
+=item PREPARING TO USE LOCALES
+
+=item USING LOCALES
+
+=over 4
+
+=item The use locale pragma
+
+=item The setlocale function
+
+=item Finding locales
+
+=item LOCALE PROBLEMS
+
+=item Temporarily fixing locale problems
+
+=item Permanently fixing locale problems
+
+=item Permanently fixing your system's locale configuration
+
+=item Fixing system locale configuration
+
+=item The localeconv function
+
+=item I18N::Langinfo
+
+=back
+
+=item LOCALE CATEGORIES
+
+=over 4
+
+=item Category LC_COLLATE: Collation
+
+=item Category LC_CTYPE: Character Types
+
+=item Category LC_NUMERIC: Numeric Formatting
+
+=item Category LC_MONETARY: Formatting of monetary amounts
+
+=item LC_TIME
+
+=item Other categories
+
+=back
+
+=item SECURITY
+
+=item ENVIRONMENT
+
+PERL_BADLANG, LC_ALL, LANGUAGE, LC_CTYPE, LC_COLLATE, LC_MONETARY,
+LC_NUMERIC, LC_TIME, LANG
+
+=over 4
+
+=item Examples
+
+=back
+
+=item NOTES
+
+=over 4
+
+=item Backward compatibility
+
+=item I18N:Collate obsolete
+
+=item Sort speed and memory use impacts
+
+=item write() and LC_NUMERIC
+
+=item Freely available locale definitions
+
+=item I18n and l10n
+
+=item An imperfect standard
+
+=back
+
+=item Unicode and UTF-8
+
+=item BUGS
+
+=over 4
+
+=item Broken systems
+
+=back
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perluniintro - Perl Unicode introduction
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Unicode
+
+=item Perl's Unicode Support
+
+=item Perl's Unicode Model
+
+=item Unicode and EBCDIC
+
+=item Creating Unicode
+
+=item Handling Unicode
+
+=item Legacy Encodings
+
+=item Unicode I/O
+
+=item Displaying Unicode As Text
+
+=item Special Cases
+
+=item Advanced Topics
+
+=item Miscellaneous
+
+=item Questions With Answers
+
+=item Hexadecimal Notation
+
+=item Further Resources
+
+=back
+
+=item UNICODE IN OLDER PERLS
+
+=item SEE ALSO
+
+=item ACKNOWLEDGMENTS
+
+=item AUTHOR, COPYRIGHT, AND LICENSE
+
+=back
+
+=head2 perlunicode - Unicode support in Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Important Caveats
+
+Input and Output Layers, Regular Expressions, C<use utf8> still needed to
+enable UTF-8/UTF-EBCDIC in scripts, BOM-marked scripts and UTF-16 scripts
+autodetected, C<use encoding> needed to upgrade non-Latin-1 byte strings
+
+=item Byte and Character Semantics
+
+=item Effects of Character Semantics
+
+=item Unicode Character Properties
+
+General Category, Bidirectional Character Types, Scripts, Extended property
+classes, Use of "Is" Prefix, Blocks
+
+=item User-Defined Character Properties
+
+=item User-Defined Case Mappings
+
+=item Character Encodings for Input and Output
+
+=item Unicode Regular Expression Support Level
+
+=item Unicode Encodings
+
+=item Security Implications of Unicode
+
+=item Unicode in Perl on EBCDIC
+
+=item Locales
+
+=item When Unicode Does Not Happen
+
+=item Forcing Unicode in Perl (Or Unforcing Unicode in Perl)
+
+=item Using Unicode in XS
+
+=back
+
+=item BUGS
+
+=over 4
+
+=item Interaction with Locales
+
+=item Interaction with Extensions
+
+=item Speed
+
+=item Porting code from perl-5.6.X
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlunifaq - Perl Unicode FAQ
+
+=over 4
+
+=item Q and A
+
+=over 4
+
+=item perlunitut isn't really a Unicode tutorial, is it?
+
+=item What character encodings does Perl support?
+
+=item Which version of perl should I use?
+
+=item What about binary data, like images?
+
+=item When should I decode or encode?
+
+=item What if I don't decode?
+
+=item What if I don't encode?
+
+=item Is there a way to automatically decode or encode?
+
+=item What if I don't know which encoding was used?
+
+=item Can I use Unicode in my Perl sources?
+
+=item Data::Dumper doesn't restore the UTF8 flag; is it broken?
+
+=item Why do regex character classes sometimes match only in the ASCII
+range?
+
+=item Why do some characters not uppercase or lowercase correctly?
+
+=item How can I determine if a string is a text string or a binary string?
+
+=item How do I convert from encoding FOO to encoding BAR?
+
+=item What are C<decode_utf8> and C<encode_utf8>?
+
+=item What is a "wide character"?
+
+=back
+
+=item INTERNALS
+
+=over 4
+
+=item What is "the UTF8 flag"?
+
+=item What about the C<use bytes> pragma?
+
+=item What about the C<use encoding> pragma?
+
+=item What is the difference between C<:encoding> and C<:utf8>?
+
+=item What's the difference between C<UTF-8> and C<utf8>?
+
+=item I lost track; what encoding is the internal format really?
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlunitut - Perl Unicode Tutorial
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Definitions
+
+=item Your new toolkit
+
+=item I/O flow (the actual 5 minute tutorial)
+
+=back
+
+=item SUMMARY
+
+=item Q and A (or FAQ)
+
+=item ACKNOWLEDGEMENTS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlebcdic - Considerations for running Perl on EBCDIC platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item COMMON CHARACTER CODE SETS
+
+=over 4
+
+=item ASCII
+
+=item ISO 8859
+
+=item Latin 1 (ISO 8859-1)
+
+=item EBCDIC
+
+=item 13 variant characters
+
+=item 0037
+
+=item 1047
+
+=item POSIX-BC
+
+=item Unicode code points versus EBCDIC code points
+
+=item Remaining Perl Unicode problems in EBCDIC
+
+=item Unicode and UTF
+
+=item Using Encode
+
+=back
+
+=item SINGLE OCTET TABLES
+
+recipe 0, recipe 1, recipe 2, recipe 3, recipe 4, recipe 5, recipe 6
+
+=item IDENTIFYING CHARACTER CODE SETS
+
+=item CONVERSIONS
+
+=over 4
+
+=item tr///
+
+=item iconv
+
+=item C RTL
+
+=back
+
+=item OPERATOR DIFFERENCES
+
+=item FUNCTION DIFFERENCES
+
+chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack()
+
+=item REGULAR EXPRESSION DIFFERENCES
+
+=item SOCKETS
+
+=item SORTING
+
+=over 4
+
+=item Ignore ASCII vs. EBCDIC sort differences.
+
+=item MONO CASE then sort data.
+
+=item Convert, sort data, then re convert.
+
+=item Perform sorting on one type of machine only.
+
+=back
+
+=item TRANSFORMATION FORMATS
+
+=over 4
+
+=item URL decoding and encoding
+
+=item uu encoding and decoding
+
+=item Quoted-Printable encoding and decoding
+
+=item Caesarian ciphers
+
+=back
+
+=item Hashing order and checksums
+
+=item I18N AND L10N
+
+=item MULTI OCTET CHARACTER SETS
+
+=item OS ISSUES
+
+=over 4
+
+=item OS/400
+
+PASE, IFS access
+
+=item OS/390, z/OS
+
+chcp, dataset access, OS/390, z/OS iconv, locales
+
+=item VM/ESA?
+
+=item POSIX-BC?
+
+=back
+
+=item BUGS
+
+=item SEE ALSO
+
+=item REFERENCES
+
+=item HISTORY
+
+=item AUTHOR
+
+=back
+
+=head2 perlsec - Perl security
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Laundering and Detecting Tainted Data
+
+=item Switches On the "#!" Line
+
+=item Taint mode and @INC
+
+=item Cleaning Up Your Path
+
+=item Security Bugs
+
+=item Protecting Your Programs
+
+=item Unicode
+
+=item Algorithmic Complexity Attacks
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlmod - Perl modules (packages and symbol tables)
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Packages
+X<package> X<namespace> X<variable, global> X<global variable> X<global>
+
+=item Symbol Tables
+X<symbol table> X<stash> X<%::> X<%main::> X<typeglob> X<glob> X<alias>
+
+=item BEGIN, UNITCHECK, CHECK, INIT and END
+X<BEGIN> X<UNITCHECK> X<CHECK> X<INIT> X<END>
+
+=item Perl Classes
+X<class> X<@ISA>
+
+=item Perl Modules
+X<module>
+
+=item Making your module threadsafe
+X<threadsafe> X<thread safe>
+X<module, threadsafe> X<module, thread safe>
+X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlmodlib - constructing new Perl modules and finding existing ones
+
+=over 4
+
+=item THE PERL MODULE LIBRARY
+
+=over 4
+
+=item Pragmatic Modules
+
+attributes, attrs, autouse, base, bigint, bignum, bigrat, blib, bytes,
+charnames, constant, diagnostics, encoding, encoding::warnings, feature,
+fields, filetest, if, integer, less, lib, locale, mro, open, ops, overload,
+re, sigtrap, sort, strict, subs, threads, threads::shared, utf8, vars,
+version, vmsish, warnings, warnings::register
+
+=item Standard Modules
+
+AnyDBM_File, Archive::Extract, Archive::Tar, Archive::Tar::File,
+Attribute::Handlers, AutoLoader, AutoSplit, B, B::Concise, B::Debug,
+B::Deparse, B::Lint, B::Showlex, B::Terse, B::Xref, Benchmark, CGI,
+CGI::Apache, CGI::Carp, CGI::Cookie, CGI::Fast, CGI::Pretty, CGI::Push,
+CGI::Switch, CGI::Util, CORE, CPAN, CPAN::API::HOWTO, CPAN::FirstTime,
+CPAN::Kwalify, CPAN::Nox, CPAN::Version, CPANPLUS, CPANPLUS::Dist::Base,
+CPANPLUS::Dist::Sample, CPANPLUS::Shell::Classic,
+CPANPLUS::Shell::Default::Plugins::HOWTO, Carp, Carp::Heavy, Class::ISA,
+Class::Struct, Compress::Raw::Zlib, Compress::Zlib, Config, Cwd, DB,
+DBM_Filter, DBM_Filter::compress, DBM_Filter::encode, DBM_Filter::int32,
+DBM_Filter::null, DBM_Filter::utf8, DB_File, Data::Dumper, Devel::DProf,
+Devel::InnerPackage, Devel::Peek, Devel::SelfStubber, Digest, Digest::MD5,
+Digest::SHA, Digest::base, Digest::file, DirHandle, Dumpvalue, DynaLoader,
+Encode, Encode::Alias, Encode::Byte, Encode::CJKConstants, Encode::CN,
+Encode::CN::HZ, Encode::Config, Encode::EBCDIC, Encode::Encoder,
+Encode::Encoding, Encode::GSM0338, Encode::Guess, Encode::JP,
+Encode::JP::H2Z, Encode::JP::JIS7, Encode::KR, Encode::KR::2022_KR,
+Encode::MIME::Header, Encode::MIME::Name, Encode::PerlIO,
+Encode::Supported, Encode::Symbol, Encode::TW, Encode::Unicode,
+Encode::Unicode::UTF7, English, Env, Errno, Exporter, Exporter::Heavy,
+ExtUtils::CBuilder, ExtUtils::CBuilder::Platform::Windows,
+ExtUtils::Command, ExtUtils::Command::MM, ExtUtils::Constant,
+ExtUtils::Constant::Base, ExtUtils::Constant::Utils,
+ExtUtils::Constant::XS, ExtUtils::Embed, ExtUtils::Install,
+ExtUtils::Installed, ExtUtils::Liblist, ExtUtils::MM, ExtUtils::MM_AIX,
+ExtUtils::MM_Any, ExtUtils::MM_BeOS, ExtUtils::MM_Cygwin, ExtUtils::MM_DOS,
+ExtUtils::MM_MacOS, ExtUtils::MM_NW5, ExtUtils::MM_OS2, ExtUtils::MM_QNX,
+ExtUtils::MM_UWIN, ExtUtils::MM_Unix, ExtUtils::MM_VMS, ExtUtils::MM_VOS,
+ExtUtils::MM_Win32, ExtUtils::MM_Win95, ExtUtils::MY, ExtUtils::MakeMaker,
+ExtUtils::MakeMaker::Config, ExtUtils::MakeMaker::FAQ,
+ExtUtils::MakeMaker::Tutorial, ExtUtils::MakeMaker::bytes,
+ExtUtils::MakeMaker::vmsish, ExtUtils::Manifest, ExtUtils::Mkbootstrap,
+ExtUtils::Mksymlists, ExtUtils::Packlist, ExtUtils::ParseXS,
+ExtUtils::testlib, Fatal, Fcntl, File::Basename, File::CheckTree,
+File::Compare, File::Copy, File::DosGlob, File::Fetch, File::Find,
+File::Glob, File::GlobMapper, File::Path, File::Spec, File::Spec::Cygwin,
+File::Spec::Epoc, File::Spec::Functions, File::Spec::Mac, File::Spec::OS2,
+File::Spec::Unix, File::Spec::VMS, File::Spec::Win32, File::Temp,
+File::stat, FileCache, FileHandle, Filter::Simple, Filter::Util::Call,
+FindBin, GDBM_File, Getopt::Long, Getopt::Std, Hash::Util,
+Hash::Util::FieldHash, I18N::Collate, I18N::LangTags,
+I18N::LangTags::Detect, I18N::LangTags::List, I18N::Langinfo, IO,
+IO::Compress::Base, IO::Compress::Deflate, IO::Compress::Gzip,
+IO::Compress::RawDeflate, IO::Compress::Zip, IO::Dir, IO::File, IO::Handle,
+IO::Pipe, IO::Poll, IO::Seekable, IO::Select, IO::Socket, IO::Socket::INET,
+IO::Socket::UNIX, IO::Uncompress::AnyInflate,
+IO::Uncompress::AnyUncompress, IO::Uncompress::Base,
+IO::Uncompress::Gunzip, IO::Uncompress::Inflate,
+IO::Uncompress::RawInflate, IO::Uncompress::Unzip, IO::Zlib, IPC::Cmd,
+IPC::Open2, IPC::Open3, IPC::SysV, IPC::SysV::Msg, IPC::SysV::Semaphore,
+List::Util, Locale::Constants, Locale::Country, Locale::Currency,
+Locale::Language, Locale::Maketext, Locale::Maketext::Simple,
+Locale::Maketext::TPJ13, Locale::Script, Log::Message,
+Log::Message::Config, Log::Message::Handlers, Log::Message::Item,
+MIME::Base64, MIME::QuotedPrint, Math::BigFloat, Math::BigInt,
+Math::BigInt::Calc, Math::BigInt::CalcEmu, Math::BigInt::FastCalc,
+Math::BigRat, Math::Complex, Math::Trig, Memoize, Memoize::AnyDBM_File,
+Memoize::Expire, Memoize::ExpireFile, Memoize::ExpireTest,
+Memoize::NDBM_File, Memoize::SDBM_File, Memoize::Storable, Module::Build,
+Module::Build::API, Module::Build::Authoring, Module::Build::Base,
+Module::Build::Compat, Module::Build::ConfigData, Module::Build::Cookbook,
+Module::Build::ModuleInfo, Module::Build::Notes, Module::Build::PPMMaker,
+Module::Build::Platform::Amiga, Module::Build::Platform::Default,
+Module::Build::Platform::EBCDIC, Module::Build::Platform::MPEiX,
+Module::Build::Platform::MacOS, Module::Build::Platform::RiscOS,
+Module::Build::Platform::Unix, Module::Build::Platform::VMS,
+Module::Build::Platform::VOS, Module::Build::Platform::Windows,
+Module::Build::Platform::aix, Module::Build::Platform::cygwin,
+Module::Build::Platform::darwin, Module::Build::Platform::os2,
+Module::Build::YAML, Module::CoreList, Module::Load,
+Module::Load::Conditional, Module::Loaded, Module::Pluggable,
+Module::Pluggable::Object, NDBM_File, NEXT, Net::Cmd, Net::Config,
+Net::Domain, Net::FTP, Net::NNTP, Net::Netrc, Net::POP3, Net::Ping,
+Net::SMTP, Net::Time, Net::hostent, Net::libnetFAQ, Net::netent,
+Net::protoent, Net::servent, O, ODBM_File, Opcode, POSIX,
+Package::Constants, Params::Check, PerlIO, PerlIO::encoding,
+PerlIO::scalar, PerlIO::via, PerlIO::via::QuotedPrint, Pod::Checker,
+Pod::Escapes, Pod::Find, Pod::Functions, Pod::Html, Pod::InputObjects,
+Pod::LaTeX, Pod::Man, Pod::ParseLink, Pod::ParseUtils, Pod::Parser,
+Pod::Perldoc::ToChecker, Pod::Perldoc::ToMan, Pod::Perldoc::ToNroff,
+Pod::Perldoc::ToPod, Pod::Perldoc::ToRtf, Pod::Perldoc::ToText,
+Pod::Perldoc::ToTk, Pod::Perldoc::ToXml, Pod::PlainText, Pod::Plainer,
+Pod::Select, Pod::Simple, Pod::Simple::Checker, Pod::Simple::Debug,
+Pod::Simple::DumpAsText, Pod::Simple::DumpAsXML, Pod::Simple::HTML,
+Pod::Simple::HTMLBatch, Pod::Simple::LinkSection, Pod::Simple::Methody,
+Pod::Simple::PullParser, Pod::Simple::PullParserEndToken,
+Pod::Simple::PullParserStartToken, Pod::Simple::PullParserTextToken,
+Pod::Simple::PullParserToken, Pod::Simple::RTF, Pod::Simple::Search,
+Pod::Simple::SimpleTree, Pod::Simple::Subclassing, Pod::Simple::Text,
+Pod::Simple::TextContent, Pod::Simple::XMLOutStream, Pod::Text,
+Pod::Text::Color, Pod::Text::Overstrike, Pod::Text::Termcap, Pod::Usage,
+SDBM_File, Safe, Scalar::Util, Search::Dict, SelectSaver, SelfLoader,
+Shell, Socket, Storable, Switch, Symbol, Sys::Hostname, Sys::Syslog,
+Sys::Syslog::win32::Win32, Term::ANSIColor, Term::Cap, Term::Complete,
+Term::ReadLine, Term::UI, Test, Test::Builder, Test::Builder::Module,
+Test::Builder::Tester, Test::Builder::Tester::Color, Test::Harness,
+Test::Harness::Assert, Test::Harness::Iterator, Test::Harness::Point,
+Test::Harness::Results, Test::Harness::Straps, Test::Harness::TAP,
+Test::Harness::Util, Test::More, Test::Simple, Test::Tutorial,
+Text::Abbrev, Text::Balanced, Text::ParseWords, Text::Soundex, Text::Tabs,
+Text::Wrap, Thread, Thread::Queue, Thread::Semaphore, Tie::Array,
+Tie::File, Tie::Handle, Tie::Hash, Tie::Hash::NamedCapture, Tie::Memoize,
+Tie::RefHash, Tie::Scalar, Tie::SubstrHash, Time::HiRes, Time::Local,
+Time::Piece, Time::Piece::Seconds, Time::gmtime, Time::localtime, Time::tm,
+UNIVERSAL, Unicode::Collate, Unicode::Normalize, Unicode::UCD, User::grent,
+User::pwent, Win32, Win32API::File, Win32CORE, XS::APItest, XS::Typemap,
+XSLoader
+
+=item Extension Modules
+
+=back
+
+=item CPAN
+
+=over 4
+
+=item Africa
+
+South Africa
+
+=item Asia
+
+China, Indonesia, Israel, Japan, Malaysia, Russian Federation, Saudi
+Arabia, Singapore, South Korea, Taiwan, Thailand
+
+=item Central America
+
+Costa Rica
+
+=item Europe
+
+Austria, Belgium, Bosnia and Herzegovina, Bulgaria, Croatia, Czech
+Republic, Denmark, Estonia, Finland, France, Germany, Greece, Hungary,
+Iceland, Ireland, Italy, Latvia, Lithuania, Netherlands, Norway, Poland,
+Portugal, Romania, Russia, Slovakia, Slovenia, Spain, Sweden, Switzerland,
+Turkey, Ukraine, United Kingdom
+
+=item North America
+
+Canada, Alberta, Manitoba, Nova Scotia, Ontario, Mexico, United States,
+Alabama, California, Colorado, Delaware, District of Columbia, Florida,
+Indiana, Kentucky, Massachusetts, Michigan, Nevada, New Jersey, New York,
+North Carolina, Oklahoma, Oregon, Pennsylvania, Tennessee, Texas, Utah,
+Virginia, Washington, Wisconsin
+
+=item Oceania
+
+Australia, New Zealand, United States
+
+=item South America
+
+Argentina, Brazil, Chile
+
+=item RSYNC Mirrors
+
+=back
+
+=item Modules: Creation, Use, and Abuse
+
+=over 4
+
+=item Guidelines for Module Creation
+
+=item Guidelines for Converting Perl 4 Library Scripts into Modules
+
+=item Guidelines for Reusing Application Code
+
+=back
+
+=item NOTE
+
+=back
+
+=head2 perlmodstyle - Perl module style guide
+
+=over 4
+
+=item INTRODUCTION
+
+=item QUICK CHECKLIST
+
+=over 4
+
+=item Before you start
+
+=item The API
+
+=item Stability
+
+=item Documentation
+
+=item Release considerations
+
+=back
+
+=item BEFORE YOU START WRITING A MODULE
+
+=over 4
+
+=item Has it been done before?
+
+=item Do one thing and do it well
+
+=item What's in a name?
+
+=back
+
+=item DESIGNING AND WRITING YOUR MODULE
+
+=over 4
+
+=item To OO or not to OO?
+
+=item Designing your API
+
+Write simple routines to do simple things, Separate functionality from
+output, Provide sensible shortcuts and defaults, Naming conventions,
+Parameter passing
+
+=item Strictness and warnings
+
+=item Backwards compatibility
+
+=item Error handling and messages
+
+=back
+
+=item DOCUMENTING YOUR MODULE
+
+=over 4
+
+=item POD
+
+=item README, INSTALL, release notes, changelogs
+
+perl Makefile.PL, make, make test, make install, perl Build.PL, perl Build,
+perl Build test, perl Build install
+
+=back
+
+=item RELEASE CONSIDERATIONS
+
+=over 4
+
+=item Version numbering
+
+=item Pre-requisites
+
+=item Testing
+
+=item Packaging
+
+=item Licensing
+
+=back
+
+=item COMMON PITFALLS
+
+=over 4
+
+=item Reinventing the wheel
+
+=item Trying to do too much
+
+=item Inappropriate documentation
+
+=back
+
+=item SEE ALSO
+
+L<perlstyle>, L<perlnewmod>, L<perlpod>, L<podchecker>, Packaging Tools,
+Testing tools, http://pause.perl.org/, Any good book on software
+engineering
+
+=item AUTHOR
+
+=back
+
+=head2 perlmodinstall - Installing CPAN Modules
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item PREAMBLE
+
+B<DECOMPRESS> the file, B<UNPACK> the file into a directory, B<BUILD> the
+module (sometimes unnecessary), B<INSTALL> the module
+
+=back
+
+=item PORTABILITY
+
+=item HEY
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 perlnewmod - preparing a new module for distribution
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Warning
+
+=item What should I make into a module?
+
+=item Step-by-step: Preparing the ground
+
+Look around, Check it's new, Discuss the need, Choose a name, Check again
+
+=item Step-by-step: Making the module
+
+Start with F<module-starter> or F<h2xs>, Use L<strict|strict> and
+L<warnings|warnings>, Use L<Carp|Carp>, Use L<Exporter|Exporter> - wisely!,
+Use L<plain old documentation|perlpod>, Write tests, Write the README
+
+=item Step-by-step: Distributing your module
+
+Get a CPAN user ID, C<perl Makefile.PL; make test; make dist>, Upload the
+tarball, Announce to the modules list, Announce to clpa, Fix bugs!
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlpragma - how to write a user pragma
+
+=over 4
+
+=item DESCRIPTION
+
+=item A basic example
+
+=item Implementation details
+
+=back
+
+=head2 perlutil - utilities packaged with the Perl distribution
+
+=over 4
+
+=item DESCRIPTION
+
+=item LIST OF UTILITIES
+
+=over 4
+
+=item Documentation
+
+L<perldoc|perldoc>, L<pod2man|pod2man> and L<pod2text|pod2text>,
+L<pod2html|pod2html> and L<pod2latex|pod2latex>, L<pod2usage|pod2usage>,
+L<podselect|podselect>, L<podchecker|podchecker>, L<splain|splain>,
+L<roffitall|roffitall>
+
+=item Convertors
+
+L<a2p|a2p>, L<s2p|s2p> and L<psed>, L<find2perl|find2perl>
+
+=item Administration
+
+L<config_data|config_data>, L<libnetcfg|libnetcfg>, L<perlivp>
+
+=item Development
+
+L<perlbug|perlbug>, L<h2ph|h2ph>, L<c2ph|c2ph> and L<pstruct|pstruct>,
+L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>, L<dprofpp|dprofpp>, L<prove>,
+L<corelist>
+
+=item General tools
+
+L<piconv>, L<ptar>, L<ptardiff>, L<shasum>
+
+=item Installation
+
+L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlcompile - Introduction to the Perl Compiler-Translator
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Layout
+
+B::Lint, B::Deparse, B::Xref
+
+=back
+
+=item Using The Back Ends
+
+=over 4
+
+=item The Cross Referencing Back End
+
+i, &, s, r
+
+=item The Decompiling Back End
+
+=item The Lint Back End
+
+=back
+
+=item Module List for the Compiler Suite
+
+B, O, B::Concise, B::Debug, B::Deparse, B::Lint, B::Showlex, B::Terse,
+B::Xref
+
+=item KNOWN PROBLEMS
+
+=item AUTHOR
+
+=back
+
+=head2 perlfilter - Source Filters
+
+=over 4
+
+=item DESCRIPTION
+
+=item CONCEPTS
+
+=item USING FILTERS
+
+=item WRITING A SOURCE FILTER
+
+=item WRITING A SOURCE FILTER IN C
+
+B<Decryption Filters>
+
+=item CREATING A SOURCE FILTER AS A SEPARATE EXECUTABLE
+
+=item WRITING A SOURCE FILTER IN PERL
+
+=item USING CONTEXT: THE DEBUG FILTER
+
+=item CONCLUSION
+
+=item THINGS TO LOOK OUT FOR
+
+Some Filters Clobber the C<DATA> Handle
+
+=item REQUIREMENTS
+
+=item AUTHOR
+
+=item Copyrights
+
+=back
+
+=head2 perlglossary - Perl Glossary
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item A
+
+accessor methods, actual arguments, address operator, algorithm, alias,
+alternatives, anonymous, architecture, argument, ARGV, arithmetical
+operator, array, array context, ASCII, assertion, assignment, assignment
+operator, associative array, associativity, asynchronous, atom, atomic
+operation, attribute, autogeneration, autoincrement, autoload, autosplit,
+autovivification, AV, awk
+
+=item B
+
+backreference, backtracking, backward compatibility, bareword, base class,
+big-endian, binary, binary operator, bind, bit, bit shift, bit string,
+bless, block, BLOCK, block buffering, Boolean, Boolean context, breakpoint,
+broadcast, BSD, bucket, buffer, built-in, bundle, byte, bytecode
+
+=item C
+
+C, C preprocessor, call by reference, call by value, callback, canonical,
+capturing, character, character class, character property, circumfix
+operator, class, class method, client, cloister, closure, cluster, CODE,
+code generator, code subpattern, collating sequence, command, command
+buffering, command name, command-line arguments, comment, compilation unit,
+compile phase, compile time, compiler, composer, concatenation,
+conditional, connection, construct, constructor, context, continuation,
+core dump, CPAN, cracker, current package, current working directory,
+currently selected output channel, CV
+
+=item D
+
+dangling statement, data structure, data type, datagram, DBM, declaration,
+decrement, default, defined, delimiter, deprecated modules and features,
+dereference, derived class, descriptor, destroy, destructor, device,
+directive, directory, directory handle, dispatch, distribution, (to be)
+dropped modules, dweomer, dwimmer, dynamic scoping
+
+=item E
+
+eclectic, element, embedding, empty subclass test, en passant,
+encapsulation, endian, environment, environment variable, EOF, errno,
+error, escape sequence, exception, exception handling, exec, executable
+file, execute, execute bit, exit status, export, expression, extension
+
+=item F
+
+false, FAQ, fatal error, field, FIFO, file, file descriptor, file test
+operator, fileglob, filehandle, filename, filesystem, filter, flag,
+floating point, flush, FMTEYEWTK, fork, formal arguments, format, freely
+available, freely redistributable, freeware, function, funny character,
+garbage collection
+
+=item G
+
+GID, glob, global, global destruction, glue language, granularity, greedy,
+grep, group, GV
+
+=item H
+
+hacker, handler, hard reference, hash, hash table, header file, here
+document, hexadecimal, home directory, host, hubris, HV
+
+=item I
+
+identifier, impatience, implementation, import, increment, indexing,
+indirect filehandle, indirect object, indirect object slot, indirection,
+infix, inheritance, instance, instance variable, integer, interface,
+interpolation, interpreter, invocant, invocation, I/O, IO, IP, IPC, is-a,
+iteration, iterator, IV
+
+=item J
+
+JAPH
+
+=item K
+
+key, keyword
+
+=item L
+
+label, laziness, left shift, leftmost longest, lexeme, lexer, lexical
+analysis, lexical scoping, lexical variable, library, LIFO, line, line
+buffering, line number, link, LIST, list, list context, list operator, list
+value, literal, little-endian, local, logical operator, lookahead,
+lookbehind, loop, loop control statement, loop label, lvaluable, lvalue,
+lvalue modifier
+
+=item M
+
+magic, magical increment, magical variables, Makefile, man, manpage,
+matching, member data, memory, metacharacter, metasymbol, method,
+minimalism, mode, modifier, module, modulus, monger, mortal,
+multidimensional array, multiple inheritance
+
+=item N
+
+named pipe, namespace, network address, newline, NFS, null character, null
+list, null string, numeric context, NV, nybble
+
+=item O
+
+object, octal, offset, one-liner, open source software, operand, operating
+system, operator, operator overloading, options, overloading, overriding,
+owner
+
+=item P
+
+package, pad, parameter, parent class, parse tree, parsing, patch, PATH,
+pathname, pattern, pattern matching, permission bits, Pern, pipe, pipeline,
+platform, pod, pointer, polymorphism, port, portable, porter, POSIX,
+postfix, pp, pragma, precedence, prefix, preprocessing, procedure, process,
+program generator, progressive matching, property, protocol, prototype,
+pseudofunction, pseudohash, pseudoliteral, public domain, pumpkin,
+pumpking, PV
+
+=item Q
+
+qualified, quantifier
+
+=item R
+
+readable, reaping, record, recursion, reference, referent, regex, regular
+expression, regular expression modifier, regular file, relational operator,
+reserved words, return value, RFC, right shift, root, RTFM, run phase, run
+time, run-time pattern, RV, rvalue
+
+=item S
+
+scalar, scalar context, scalar literal, scalar value, scalar variable,
+scope, scratchpad, script, script kiddie, sed, semaphore, separator,
+serialization, server, service, setgid, setuid, shared memory, shebang,
+shell, side effects, signal, signal handler, single inheritance, slice,
+slurp, socket, soft reference, source filter, stack, standard, standard
+error, standard I/O, standard input, standard output, stat structure,
+statement, statement modifier, static, static method, static scoping,
+static variable, status, STDERR, STDIN, STDIO, STDOUT, stream, string,
+string context, stringification, struct, structure, subclass, subpattern,
+subroutine, subscript, substitution, substring, superclass, superuser, SV,
+switch, switch cluster, switch statement, symbol, symbol table, symbolic
+debugger, symbolic link, symbolic reference, synchronous, syntactic sugar,
+syntax, syntax tree, syscall
+
+=item T
+
+tainted, TCP, term, terminator, ternary, text, thread, tie, TMTOWTDI,
+token, tokener, tokenizing, toolbox approach, transliterate, trigger,
+trinary, troff, true, truncating, type, type casting, typed lexical,
+typedef, typeglob, typemap
+
+=item U
+
+UDP, UID, umask, unary operator, Unicode, Unix
+
+=item V
+
+value, variable, variable interpolation, variadic, vector, virtual, void
+context, v-string
+
+=item W
+
+warning, watch expression, whitespace, word, working directory, wrapper,
+WYSIWYG
+
+=item X
+
+XS, XSUB
+
+=item Y
+
+yacc
+
+=item Z
+
+zero width, zombie
+
+=back
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 perlembed - how to embed perl in your C program
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item PREAMBLE
+
+B<Use C from Perl?>, B<Use a Unix program from Perl?>, B<Use Perl from
+Perl?>, B<Use C from C?>, B<Use Perl from C?>
+
+=item ROADMAP
+
+=item Compiling your C program
+
+=item Adding a Perl interpreter to your C program
+
+=item Calling a Perl subroutine from your C program
+
+=item Evaluating a Perl statement from your C program
+
+=item Performing Perl pattern matches and substitutions from your C program
+
+=item Fiddling with the Perl stack from your C program
+
+=item Maintaining a persistent interpreter
+
+=item Execution of END blocks
+
+=item $0 assignments
+
+=item Maintaining multiple interpreter instances
+
+=item Using Perl modules, which themselves use C libraries, from your C
+program
+
+=back
+
+=item Embedding Perl under Win32
+
+=item Hiding Perl_
+
+=item MORAL
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 perldebguts - Guts of Perl debugging
+
+=over 4
+
+=item DESCRIPTION
+
+=item Debugger Internals
+
+=over 4
+
+=item Writing Your Own Debugger
+
+=back
+
+=item Frame Listing Output Examples
+
+=item Debugging regular expressions
+
+=over 4
+
+=item Compile-time output
+
+C<anchored> I<STRING> C<at> I<POS>, C<floating> I<STRING> C<at>
+I<POS1..POS2>, C<matching floating/anchored>, C<minlen>, C<stclass>
+I<TYPE>, C<noscan>, C<isall>, C<GPOS>, C<plus>, C<implicit>, C<with eval>,
+C<anchored(TYPE)>
+
+=item Types of nodes
+
+=item Run-time output
+
+=back
+
+=item Debugging Perl memory usage
+
+=over 4
+
+=item Using C<$ENV{PERL_DEBUG_MSTATS}>
+
+C<buckets SMALLEST(APPROX)..GREATEST(APPROX)>, Free/Used, C<Total sbrk():
+SBRKed/SBRKs:CONTINUOUS>, C<pad: 0>, C<heads: 2192>, C<chain: 0>, C<tail:
+6144>
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlxstut, perlXStut - Tutorial for writing XSUBs
+
+=over 4
+
+=item DESCRIPTION
+
+=item SPECIAL NOTES
+
+=over 4
+
+=item make
+
+=item Version caveat
+
+=item Dynamic Loading versus Static Loading
+
+=back
+
+=item TUTORIAL
+
+=over 4
+
+=item EXAMPLE 1
+
+=item EXAMPLE 2
+
+=item What has gone on?
+
+=item Writing good test scripts
+
+=item EXAMPLE 3
+
+=item What's new here?
+
+=item Input and Output Parameters
+
+=item The XSUBPP Program
+
+=item The TYPEMAP file
+
+=item Warning about Output Arguments
+
+=item EXAMPLE 4
+
+=item What has happened here?
+
+=item Anatomy of .xs file
+
+=item Getting the fat out of XSUBs
+
+=item More about XSUB arguments
+
+=item The Argument Stack
+
+=item Extending your Extension
+
+=item Documenting your Extension
+
+=item Installing your Extension
+
+=item EXAMPLE 5
+
+=item New Things in this Example
+
+=item EXAMPLE 6
+
+=item New Things in this Example
+
+=item EXAMPLE 7 (Coming Soon)
+
+=item EXAMPLE 8 (Coming Soon)
+
+=item EXAMPLE 9 Passing open files to XSes
+
+=item Troubleshooting these Examples
+
+=back
+
+=item See also
+
+=item Author
+
+=over 4
+
+=item Last Changed
+
+=back
+
+=back
+
+=head2 perlxs - XS language reference manual
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Introduction
+
+=item On The Road
+
+=item The Anatomy of an XSUB
+
+=item The Argument Stack
+
+=item The RETVAL Variable
+
+=item Returning SVs, AVs and HVs through RETVAL
+
+=item The MODULE Keyword
+
+=item The PACKAGE Keyword
+
+=item The PREFIX Keyword
+
+=item The OUTPUT: Keyword
+
+=item The NO_OUTPUT Keyword
+
+=item The CODE: Keyword
+
+=item The INIT: Keyword
+
+=item The NO_INIT Keyword
+
+=item Initializing Function Parameters
+
+=item Default Parameter Values
+
+=item The PREINIT: Keyword
+
+=item The SCOPE: Keyword
+
+=item The INPUT: Keyword
+
+=item The IN/OUTLIST/IN_OUTLIST/OUT/IN_OUT Keywords
+
+=item The C<length(NAME)> Keyword
+
+=item Variable-length Parameter Lists
+
+=item The C_ARGS: Keyword
+
+=item The PPCODE: Keyword
+
+=item Returning Undef And Empty Lists
+
+=item The REQUIRE: Keyword
+
+=item The CLEANUP: Keyword
+
+=item The POSTCALL: Keyword
+
+=item The BOOT: Keyword
+
+=item The VERSIONCHECK: Keyword
+
+=item The PROTOTYPES: Keyword
+
+=item The PROTOTYPE: Keyword
+
+=item The ALIAS: Keyword
+
+=item The OVERLOAD: Keyword
+
+=item The FALLBACK: Keyword
+
+=item The INTERFACE: Keyword
+
+=item The INTERFACE_MACRO: Keyword
+
+=item The INCLUDE: Keyword
+
+=item The CASE: Keyword
+
+=item The & Unary Operator
+
+=item Inserting POD, Comments and C Preprocessor Directives
+
+=item Using XS With C++
+
+=item Interface Strategy
+
+=item Perl Objects And C Structures
+
+=item The Typemap
+
+=item Safely Storing Static Data in XS
+
+MY_CXT_KEY, typedef my_cxt_t, START_MY_CXT, MY_CXT_INIT, dMY_CXT, MY_CXT,
+aMY_CXT/pMY_CXT, MY_CXT_CLONE, MY_CXT_INIT_INTERP(my_perl),
+dMY_CXT_INTERP(my_perl)
+
+=item Thread-aware system interfaces
+
+=back
+
+=item EXAMPLES
+
+=item XS VERSION
+
+=item AUTHOR
+
+=back
+
+=head2 perlclib - Internal replacements for standard C library functions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Conventions
+
+C<t>, C<p>, C<n>, C<s>
+
+=item File Operations
+
+=item File Input and Output
+
+=item File Positioning
+
+=item Memory Management and String Handling
+
+=item Character Class Tests
+
+=item F<stdlib.h> functions
+
+=item Miscellaneous functions
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 perlguts - Introduction to the Perl API
+
+=over 4
+
+=item DESCRIPTION
+
+=item Variables
+
+=over 4
+
+=item Datatypes
+
+=item What is an "IV"?
+
+=item Working with SVs
+
+=item Offsets
+
+=item What's Really Stored in an SV?
+
+=item Working with AVs
+
+=item Working with HVs
+
+=item Hash API Extensions
+
+=item AVs, HVs and undefined values
+
+=item References
+
+=item Blessed References and Class Objects
+
+=item Creating New Variables
+
+GV_ADDMULTI, GV_ADDWARN
+
+=item Reference Counts and Mortality
+
+=item Stashes and Globs
+
+=item Double-Typed SVs
+
+=item Magic Variables
+
+=item Assigning Magic
+
+=item Magic Virtual Tables
+
+=item Finding Magic
+
+=item Understanding the Magic of Tied Hashes and Arrays
+
+=item Localizing changes
+
+C<SAVEINT(int i)>, C<SAVEIV(IV i)>, C<SAVEI32(I32 i)>, C<SAVELONG(long i)>,
+C<SAVESPTR(s)>, C<SAVEPPTR(p)>, C<SAVEFREESV(SV *sv)>, C<SAVEMORTALIZESV(SV
+*sv)>, C<SAVEFREEOP(OP *op)>, C<SAVEFREEPV(p)>, C<SAVECLEARSV(SV *sv)>,
+C<SAVEDELETE(HV *hv, char *key, I32 length)>,
+C<SAVEDESTRUCTOR(DESTRUCTORFUNC_NOCONTEXT_t f, void *p)>,
+C<SAVEDESTRUCTOR_X(DESTRUCTORFUNC_t f, void *p)>, C<SAVESTACK_POS()>, C<SV*
+save_scalar(GV *gv)>, C<AV* save_ary(GV *gv)>, C<HV* save_hash(GV *gv)>,
+C<void save_item(SV *item)>, C<void save_list(SV **sarg, I32 maxsarg)>,
+C<SV* save_svref(SV **sptr)>, C<void save_aptr(AV **aptr)>, C<void
+save_hptr(HV **hptr)>
+
+=back
+
+=item Subroutines
+
+=over 4
+
+=item XSUBs and the Argument Stack
+
+=item Calling Perl Routines from within C Programs
+
+=item Memory Allocation
+
+=item PerlIO
+
+=item Putting a C value on Perl stack
+
+=item Scratchpads
+
+=item Scratchpads and recursion
+
+=back
+
+=item Compiled code
+
+=over 4
+
+=item Code tree
+
+=item Examining the tree
+
+=item Compile pass 1: check routines
+
+=item Compile pass 1a: constant folding
+
+=item Compile pass 2: context propagation
+
+=item Compile pass 3: peephole optimization
+
+=item Pluggable runops
+
+=back
+
+=item Examining internal data structures with the C<dump> functions
+
+=item How multiple interpreters and concurrency are supported
+
+=over 4
+
+=item Background and PERL_IMPLICIT_CONTEXT
+
+=item So what happened to dTHR?
+
+=item How do I use all this in extensions?
+
+=item Should I do anything special if I call perl from multiple threads?
+
+=item Future Plans and PERL_IMPLICIT_SYS
+
+=back
+
+=item Internal Functions
+
+A, p, d, s, n, r, f, M, o, x, m, X, E, b, others
+
+=over 4
+
+=item Formatted Printing of IVs, UVs, and NVs
+
+=item Pointer-To-Integer and Integer-To-Pointer
+
+=item Exception Handling
+
+=item Source Documentation
+
+=item Backwards compatibility
+
+=back
+
+=item Unicode Support
+
+=over 4
+
+=item What B<is> Unicode, anyway?
+
+=item How can I recognise a UTF-8 string?
+
+=item How does UTF-8 represent Unicode characters?
+
+=item How does Perl store UTF-8 strings?
+
+=item How do I convert a string to UTF-8?
+
+=item Is there anything else I need to know?
+
+=back
+
+=item Custom Operators
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 perlcall - Perl calling conventions from C
+
+=over 4
+
+=item DESCRIPTION
+
+An Error Handler, An Event Driven Program
+
+=item THE CALL_ FUNCTIONS
+
+call_sv, call_pv, call_method, call_argv
+
+=item FLAG VALUES
+
+=over 4
+
+=item G_VOID
+
+=item G_SCALAR
+
+=item G_ARRAY
+
+=item G_DISCARD
+
+=item G_NOARGS
+
+=item G_EVAL
+
+=item G_KEEPERR
+
+=item Determining the Context
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item No Parameters, Nothing returned
+
+=item Passing Parameters
+
+=item Returning a Scalar
+
+=item Returning a list of values
+
+=item Returning a list in a scalar context
+
+=item Returning Data from Perl via the parameter list
+
+=item Using G_EVAL
+
+=item Using G_KEEPERR
+
+=item Using call_sv
+
+=item Using call_argv
+
+=item Using call_method
+
+=item Using GIMME_V
+
+=item Using Perl to dispose of temporaries
+
+=item Strategies for storing Callback Context Information
+
+1. Ignore the problem - Allow only 1 callback, 2. Create a sequence of
+callbacks - hard wired limit, 3. Use a parameter to map to the Perl
+callback
+
+=item Alternate Stack Manipulation
+
+=item Creating and calling an anonymous subroutine in C
+
+=back
+
+=item LIGHTWEIGHT CALLBACKS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlreapi - perl regular expression plugin interface
+
+=over 4
+
+=item DESCRIPTION
+
+=item Callbacks
+
+=over 4
+
+=item comp
+
+C</m> - RXf_PMf_MULTILINE, C</s> - RXf_PMf_SINGLELINE, C</i> -
+RXf_PMf_FOLD, C</x> - RXf_PMf_EXTENDED, C</p> - RXf_PMf_KEEPCOPY,
+RXf_PMf_LOCALE, RXf_UTF8, RXf_SPLIT, RXf_SKIPWHITE, RXf_START_ONLY,
+RXf_WHITE, RXf_NULL
+
+=item exec
+
+=item intuit
+
+=item checkstr
+
+=item free
+
+=item Numbered capture callbacks
+
+=item Named capture callbacks
+
+=item qr_package
+
+=item dupe
+
+=back
+
+=item The REGEXP structure
+
+=over 4
+
+=item C<engine>
+
+=item C<mother_re>
+
+=item C<extflags>
+
+=item C<minlen> C<minlenret>
+
+=item C<gofs>
+
+=item C<substrs>
+
+=item C<nparens>, C<lasparen>, and C<lastcloseparen>
+
+=item C<intflags>
+
+=item C<pprivate>
+
+=item C<swap>
+
+=item C<offs>
+
+=item C<precomp> C<prelen>
+
+=item C<paren_names>
+
+=item C<substrs>
+
+=item C<subbeg> C<sublen> C<saved_copy>
+
+=item C<wrapped> C<wraplen>
+
+=item C<seen_evals>
+
+=item C<refcnt>
+
+=back
+
+=item HISTORY
+
+=item AUTHORS
+
+=item LICENSE
+
+=back
+
+=head2 perlreguts - Description of the Perl regular expression engine.
+
+=over 4
+
+=item DESCRIPTION
+
+=item OVERVIEW
+
+=over 4
+
+=item A quick note on terms
+
+=item What is a regular expression engine?
+
+=item Structure of a Regexp Program
+
+C<regnode_1>, C<regnode_2>, C<regnode_string>, C<regnode_charclass>,
+C<regnode_charclass_class>
+
+=back
+
+=item Process Overview
+
+A. Compilation, 1. Parsing for size, 2. Parsing for construction, 3.
+Peep-hole optimisation and analysis, B. Execution, 4. Start position and
+no-match optimisations, 5. Program execution
+
+=over 4
+
+=item Compilation
+
+anchored fixed strings, floating fixed strings, minimum and maximum length
+requirements, start class, Beginning/End of line positions
+
+=item Execution
+
+=back
+
+=item MISCELLANEOUS
+
+=over 4
+
+=item Unicode and Localisation Support
+
+=item Base Structures
+
+C<swap>, C<offsets>, C<regstclass>, C<data>, C<program>
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item LICENCE
+
+=item REFERENCES
+
+=back
+
+=head2 perlapi - autogenerated documentation for the perl public API
+
+=over 4
+
+=item DESCRIPTION
+X<Perl API> X<API> X<api>
+
+=item "Gimme" Values
+
+GIMME X<GIMME>, GIMME_V X<GIMME_V>, G_ARRAY X<G_ARRAY>, G_DISCARD
+X<G_DISCARD>, G_EVAL X<G_EVAL>, G_NOARGS X<G_NOARGS>, G_SCALAR X<G_SCALAR>,
+G_VOID X<G_VOID>
+
+=item Array Manipulation Functions
+
+AvFILL X<AvFILL>, av_clear X<av_clear>, av_create_and_push
+X<av_create_and_push>, av_create_and_unshift_one
+X<av_create_and_unshift_one>, av_delete X<av_delete>, av_exists
+X<av_exists>, av_extend X<av_extend>, av_fetch X<av_fetch>, av_fill
+X<av_fill>, av_len X<av_len>, av_make X<av_make>, av_pop X<av_pop>, av_push
+X<av_push>, av_shift X<av_shift>, av_store X<av_store>, av_undef
+X<av_undef>, av_unshift X<av_unshift>, get_av X<get_av>, newAV X<newAV>,
+sortsv X<sortsv>, sortsv_flags X<sortsv_flags>
+
+=item Callback Functions
+
+call_argv X<call_argv>, call_method X<call_method>, call_pv X<call_pv>,
+call_sv X<call_sv>, ENTER X<ENTER>, eval_pv X<eval_pv>, eval_sv X<eval_sv>,
+FREETMPS X<FREETMPS>, LEAVE X<LEAVE>, SAVETMPS X<SAVETMPS>
+
+=item Character classes
+
+isALNUM X<isALNUM>, isALPHA X<isALPHA>, isDIGIT X<isDIGIT>, isLOWER
+X<isLOWER>, isSPACE X<isSPACE>, isUPPER X<isUPPER>, toLOWER X<toLOWER>,
+toUPPER X<toUPPER>
+
+=item Cloning an interpreter
+
+perl_clone X<perl_clone>
+
+=item CV Manipulation Functions
+
+CvSTASH X<CvSTASH>, get_cv X<get_cv>, get_cvn_flags X<get_cvn_flags>
+
+=item Embedding Functions
+
+cv_undef X<cv_undef>, load_module X<load_module>, nothreadhook
+X<nothreadhook>, perl_alloc X<perl_alloc>, perl_construct
+X<perl_construct>, perl_destruct X<perl_destruct>, perl_free X<perl_free>,
+perl_parse X<perl_parse>, perl_run X<perl_run>, require_pv X<require_pv>
+
+=item Functions in file dump.c
+
+pv_display X<pv_display>, pv_escape X<pv_escape>, pv_pretty X<pv_pretty>
+
+=item Functions in file mathoms.c
+
+gv_fetchmethod X<gv_fetchmethod>, pack_cat X<pack_cat>, sv_2pvbyte_nolen
+X<sv_2pvbyte_nolen>, sv_2pvutf8_nolen X<sv_2pvutf8_nolen>, sv_2pv_nolen
+X<sv_2pv_nolen>, sv_catpvn_mg X<sv_catpvn_mg>, sv_catsv_mg X<sv_catsv_mg>,
+sv_force_normal X<sv_force_normal>, sv_iv X<sv_iv>, sv_nolocking
+X<sv_nolocking>, sv_nounlocking X<sv_nounlocking>, sv_nv X<sv_nv>, sv_pv
+X<sv_pv>, sv_pvbyte X<sv_pvbyte>, sv_pvbyten X<sv_pvbyten>, sv_pvn
+X<sv_pvn>, sv_pvutf8 X<sv_pvutf8>, sv_pvutf8n X<sv_pvutf8n>, sv_taint
+X<sv_taint>, sv_unref X<sv_unref>, sv_usepvn X<sv_usepvn>, sv_usepvn_mg
+X<sv_usepvn_mg>, sv_uv X<sv_uv>, unpack_str X<unpack_str>
+
+=item Functions in file pp_ctl.c
+
+find_runcv X<find_runcv>
+
+=item Functions in file pp_pack.c
+
+packlist X<packlist>, unpackstring X<unpackstring>
+
+=item GV Functions
+
+GvSV X<GvSV>, gv_const_sv X<gv_const_sv>, gv_fetchmeth X<gv_fetchmeth>,
+gv_fetchmethod_autoload X<gv_fetchmethod_autoload>, gv_fetchmeth_autoload
+X<gv_fetchmeth_autoload>, gv_stashpv X<gv_stashpv>, gv_stashpvn
+X<gv_stashpvn>, gv_stashpvs X<gv_stashpvs>, gv_stashsv X<gv_stashsv>
+
+=item Handy Values
+
+Nullav X<Nullav>, Nullch X<Nullch>, Nullcv X<Nullcv>, Nullhv X<Nullhv>,
+Nullsv X<Nullsv>
+
+=item Hash Manipulation Functions
+
+get_hv X<get_hv>, HEf_SVKEY X<HEf_SVKEY>, HeHASH X<HeHASH>, HeKEY X<HeKEY>,
+HeKLEN X<HeKLEN>, HePV X<HePV>, HeSVKEY X<HeSVKEY>, HeSVKEY_force
+X<HeSVKEY_force>, HeSVKEY_set X<HeSVKEY_set>, HeVAL X<HeVAL>, HvNAME
+X<HvNAME>, hv_assert X<hv_assert>, hv_clear X<hv_clear>,
+hv_clear_placeholders X<hv_clear_placeholders>, hv_delete X<hv_delete>,
+hv_delete_ent X<hv_delete_ent>, hv_exists X<hv_exists>, hv_exists_ent
+X<hv_exists_ent>, hv_fetch X<hv_fetch>, hv_fetchs X<hv_fetchs>,
+hv_fetch_ent X<hv_fetch_ent>, hv_iterinit X<hv_iterinit>, hv_iterkey
+X<hv_iterkey>, hv_iterkeysv X<hv_iterkeysv>, hv_iternext X<hv_iternext>,
+hv_iternextsv X<hv_iternextsv>, hv_iternext_flags X<hv_iternext_flags>,
+hv_iterval X<hv_iterval>, hv_magic X<hv_magic>, hv_scalar X<hv_scalar>,
+hv_store X<hv_store>, hv_stores X<hv_stores>, hv_store_ent X<hv_store_ent>,
+hv_undef X<hv_undef>, newHV X<newHV>
+
+=item Magical Functions
+
+mg_clear X<mg_clear>, mg_copy X<mg_copy>, mg_find X<mg_find>, mg_free
+X<mg_free>, mg_get X<mg_get>, mg_length X<mg_length>, mg_magical
+X<mg_magical>, mg_set X<mg_set>, SvGETMAGIC X<SvGETMAGIC>, SvLOCK
+X<SvLOCK>, SvSETMAGIC X<SvSETMAGIC>, SvSetMagicSV X<SvSetMagicSV>,
+SvSetMagicSV_nosteal X<SvSetMagicSV_nosteal>, SvSetSV X<SvSetSV>,
+SvSetSV_nosteal X<SvSetSV_nosteal>, SvSHARE X<SvSHARE>, SvUNLOCK
+X<SvUNLOCK>
+
+=item Memory Management
+
+Copy X<Copy>, CopyD X<CopyD>, Move X<Move>, MoveD X<MoveD>, Newx X<Newx>,
+Newxc X<Newxc>, Newxz X<Newxz>, Poison X<Poison>, PoisonFree X<PoisonFree>,
+PoisonNew X<PoisonNew>, PoisonWith X<PoisonWith>, Renew X<Renew>, Renewc
+X<Renewc>, Safefree X<Safefree>, savepv X<savepv>, savepvn X<savepvn>,
+savepvs X<savepvs>, savesharedpv X<savesharedpv>, savesharedpvn
+X<savesharedpvn>, savesvpv X<savesvpv>, StructCopy X<StructCopy>, Zero
+X<Zero>, ZeroD X<ZeroD>
+
+=item Miscellaneous Functions
+
+fbm_compile X<fbm_compile>, fbm_instr X<fbm_instr>, form X<form>, getcwd_sv
+X<getcwd_sv>, my_snprintf X<my_snprintf>, my_sprintf X<my_sprintf>,
+my_vsnprintf X<my_vsnprintf>, new_version X<new_version>, scan_version
+X<scan_version>, strEQ X<strEQ>, strGE X<strGE>, strGT X<strGT>, strLE
+X<strLE>, strLT X<strLT>, strNE X<strNE>, strnEQ X<strnEQ>, strnNE
+X<strnNE>, sv_destroyable X<sv_destroyable>, sv_nosharing X<sv_nosharing>,
+upg_version X<upg_version>, vcmp X<vcmp>, vnormal X<vnormal>, vnumify
+X<vnumify>, vstringify X<vstringify>, vverify X<vverify>
+
+=item MRO Functions
+
+mro_get_linear_isa X<mro_get_linear_isa>, mro_method_changed_in
+X<mro_method_changed_in>
+
+=item Multicall Functions
+
+dMULTICALL X<dMULTICALL>, MULTICALL X<MULTICALL>, POP_MULTICALL
+X<POP_MULTICALL>, PUSH_MULTICALL X<PUSH_MULTICALL>
+
+=item Numeric functions
+
+grok_bin X<grok_bin>, grok_hex X<grok_hex>, grok_number X<grok_number>,
+grok_numeric_radix X<grok_numeric_radix>, grok_oct X<grok_oct>,
+Perl_signbit X<Perl_signbit>, scan_bin X<scan_bin>, scan_hex X<scan_hex>,
+scan_oct X<scan_oct>
+
+=item Optree Manipulation Functions
+
+cv_const_sv X<cv_const_sv>, newCONSTSUB X<newCONSTSUB>, newXS X<newXS>
+
+=item Pad Data Structures
+
+pad_sv X<pad_sv>
+
+=item Per-Interpreter Variables
+
+PL_modglobal X<PL_modglobal>, PL_na X<PL_na>, PL_sv_no X<PL_sv_no>,
+PL_sv_undef X<PL_sv_undef>, PL_sv_yes X<PL_sv_yes>
+
+=item REGEXP Functions
+
+SvRX X<SvRX>, SvRXOK X<SvRXOK>
+
+=item Simple Exception Handling Macros
+
+dXCPT X<dXCPT>, XCPT_CATCH X<XCPT_CATCH>, XCPT_RETHROW X<XCPT_RETHROW>,
+XCPT_TRY_END X<XCPT_TRY_END>, XCPT_TRY_START X<XCPT_TRY_START>
+
+=item Stack Manipulation Macros
+
+dMARK X<dMARK>, dORIGMARK X<dORIGMARK>, dSP X<dSP>, EXTEND X<EXTEND>, MARK
+X<MARK>, mPUSHi X<mPUSHi>, mPUSHn X<mPUSHn>, mPUSHp X<mPUSHp>, mPUSHu
+X<mPUSHu>, mXPUSHi X<mXPUSHi>, mXPUSHn X<mXPUSHn>, mXPUSHp X<mXPUSHp>,
+mXPUSHu X<mXPUSHu>, ORIGMARK X<ORIGMARK>, POPi X<POPi>, POPl X<POPl>, POPn
+X<POPn>, POPp X<POPp>, POPpbytex X<POPpbytex>, POPpx X<POPpx>, POPs
+X<POPs>, PUSHi X<PUSHi>, PUSHMARK X<PUSHMARK>, PUSHmortal X<PUSHmortal>,
+PUSHn X<PUSHn>, PUSHp X<PUSHp>, PUSHs X<PUSHs>, PUSHu X<PUSHu>, PUTBACK
+X<PUTBACK>, SP X<SP>, SPAGAIN X<SPAGAIN>, XPUSHi X<XPUSHi>, XPUSHmortal
+X<XPUSHmortal>, XPUSHn X<XPUSHn>, XPUSHp X<XPUSHp>, XPUSHs X<XPUSHs>,
+XPUSHu X<XPUSHu>, XSRETURN X<XSRETURN>, XSRETURN_EMPTY X<XSRETURN_EMPTY>,
+XSRETURN_IV X<XSRETURN_IV>, XSRETURN_NO X<XSRETURN_NO>, XSRETURN_NV
+X<XSRETURN_NV>, XSRETURN_PV X<XSRETURN_PV>, XSRETURN_UNDEF
+X<XSRETURN_UNDEF>, XSRETURN_UV X<XSRETURN_UV>, XSRETURN_YES
+X<XSRETURN_YES>, XST_mIV X<XST_mIV>, XST_mNO X<XST_mNO>, XST_mNV
+X<XST_mNV>, XST_mPV X<XST_mPV>, XST_mUNDEF X<XST_mUNDEF>, XST_mYES
+X<XST_mYES>
+
+=item SV Flags
+
+svtype X<svtype>, SVt_IV X<SVt_IV>, SVt_NV X<SVt_NV>, SVt_PV X<SVt_PV>,
+SVt_PVAV X<SVt_PVAV>, SVt_PVCV X<SVt_PVCV>, SVt_PVHV X<SVt_PVHV>, SVt_PVMG
+X<SVt_PVMG>
+
+=item SV Manipulation Functions
+
+get_sv X<get_sv>, newRV_inc X<newRV_inc>, SvCUR X<SvCUR>, SvCUR_set
+X<SvCUR_set>, SvEND X<SvEND>, SvGAMAGIC X<SvGAMAGIC>, SvGROW X<SvGROW>,
+SvIOK X<SvIOK>, SvIOKp X<SvIOKp>, SvIOK_notUV X<SvIOK_notUV>, SvIOK_off
+X<SvIOK_off>, SvIOK_on X<SvIOK_on>, SvIOK_only X<SvIOK_only>, SvIOK_only_UV
+X<SvIOK_only_UV>, SvIOK_UV X<SvIOK_UV>, SvIsCOW X<SvIsCOW>,
+SvIsCOW_shared_hash X<SvIsCOW_shared_hash>, SvIV X<SvIV>, SvIVX X<SvIVX>,
+SvIVx X<SvIVx>, SvIV_nomg X<SvIV_nomg>, SvIV_set X<SvIV_set>, SvLEN
+X<SvLEN>, SvLEN_set X<SvLEN_set>, SvMAGIC_set X<SvMAGIC_set>, SvNIOK
+X<SvNIOK>, SvNIOKp X<SvNIOKp>, SvNIOK_off X<SvNIOK_off>, SvNOK X<SvNOK>,
+SvNOKp X<SvNOKp>, SvNOK_off X<SvNOK_off>, SvNOK_on X<SvNOK_on>, SvNOK_only
+X<SvNOK_only>, SvNV X<SvNV>, SvNVX X<SvNVX>, SvNVx X<SvNVx>, SvNV_set
+X<SvNV_set>, SvOK X<SvOK>, SvOOK X<SvOOK>, SvPOK X<SvPOK>, SvPOKp
+X<SvPOKp>, SvPOK_off X<SvPOK_off>, SvPOK_on X<SvPOK_on>, SvPOK_only
+X<SvPOK_only>, SvPOK_only_UTF8 X<SvPOK_only_UTF8>, SvPV X<SvPV>, SvPVbyte
+X<SvPVbyte>, SvPVbytex X<SvPVbytex>, SvPVbytex_force X<SvPVbytex_force>,
+SvPVbyte_force X<SvPVbyte_force>, SvPVbyte_nolen X<SvPVbyte_nolen>,
+SvPVutf8 X<SvPVutf8>, SvPVutf8x X<SvPVutf8x>, SvPVutf8x_force
+X<SvPVutf8x_force>, SvPVutf8_force X<SvPVutf8_force>, SvPVutf8_nolen
+X<SvPVutf8_nolen>, SvPVX X<SvPVX>, SvPVx X<SvPVx>, SvPV_force
+X<SvPV_force>, SvPV_force_nomg X<SvPV_force_nomg>, SvPV_nolen
+X<SvPV_nolen>, SvPV_nomg X<SvPV_nomg>, SvPV_set X<SvPV_set>, SvREFCNT
+X<SvREFCNT>, SvREFCNT_dec X<SvREFCNT_dec>, SvREFCNT_inc X<SvREFCNT_inc>,
+SvREFCNT_inc_NN X<SvREFCNT_inc_NN>, SvREFCNT_inc_simple
+X<SvREFCNT_inc_simple>, SvREFCNT_inc_simple_NN X<SvREFCNT_inc_simple_NN>,
+SvREFCNT_inc_simple_void X<SvREFCNT_inc_simple_void>,
+SvREFCNT_inc_simple_void_NN X<SvREFCNT_inc_simple_void_NN>,
+SvREFCNT_inc_void X<SvREFCNT_inc_void>, SvREFCNT_inc_void_NN
+X<SvREFCNT_inc_void_NN>, SvROK X<SvROK>, SvROK_off X<SvROK_off>, SvROK_on
+X<SvROK_on>, SvRV X<SvRV>, SvRV_set X<SvRV_set>, SvSTASH X<SvSTASH>,
+SvSTASH_set X<SvSTASH_set>, SvTAINT X<SvTAINT>, SvTAINTED X<SvTAINTED>,
+SvTAINTED_off X<SvTAINTED_off>, SvTAINTED_on X<SvTAINTED_on>, SvTRUE
+X<SvTRUE>, SvTYPE X<SvTYPE>, SvUOK X<SvUOK>, SvUPGRADE X<SvUPGRADE>, SvUTF8
+X<SvUTF8>, SvUTF8_off X<SvUTF8_off>, SvUTF8_on X<SvUTF8_on>, SvUV X<SvUV>,
+SvUVX X<SvUVX>, SvUVx X<SvUVx>, SvUV_nomg X<SvUV_nomg>, SvUV_set
+X<SvUV_set>, SvVOK X<SvVOK>, sv_catpvn_nomg X<sv_catpvn_nomg>,
+sv_catsv_nomg X<sv_catsv_nomg>, sv_derived_from X<sv_derived_from>, sv_does
+X<sv_does>, sv_report_used X<sv_report_used>, sv_setsv_nomg
+X<sv_setsv_nomg>
+
+=item SV-Body Allocation
+
+looks_like_number X<looks_like_number>, newRV_noinc X<newRV_noinc>, newSV
+X<newSV>, newSVhek X<newSVhek>, newSViv X<newSViv>, newSVnv X<newSVnv>,
+newSVpv X<newSVpv>, newSVpvf X<newSVpvf>, newSVpvn X<newSVpvn>,
+newSVpvn_share X<newSVpvn_share>, newSVpvs X<newSVpvs>, newSVpvs_share
+X<newSVpvs_share>, newSVrv X<newSVrv>, newSVsv X<newSVsv>, newSVuv
+X<newSVuv>, newSV_type X<newSV_type>, sv_2bool X<sv_2bool>, sv_2cv
+X<sv_2cv>, sv_2io X<sv_2io>, sv_2iv_flags X<sv_2iv_flags>, sv_2mortal
+X<sv_2mortal>, sv_2nv X<sv_2nv>, sv_2pvbyte X<sv_2pvbyte>, sv_2pvutf8
+X<sv_2pvutf8>, sv_2pv_flags X<sv_2pv_flags>, sv_2uv_flags X<sv_2uv_flags>,
+sv_backoff X<sv_backoff>, sv_bless X<sv_bless>, sv_catpv X<sv_catpv>,
+sv_catpvf X<sv_catpvf>, sv_catpvf_mg X<sv_catpvf_mg>, sv_catpvn
+X<sv_catpvn>, sv_catpvn_flags X<sv_catpvn_flags>, sv_catpvs X<sv_catpvs>,
+sv_catpv_mg X<sv_catpv_mg>, sv_catsv X<sv_catsv>, sv_catsv_flags
+X<sv_catsv_flags>, sv_chop X<sv_chop>, sv_clear X<sv_clear>, sv_cmp
+X<sv_cmp>, sv_cmp_locale X<sv_cmp_locale>, sv_collxfrm X<sv_collxfrm>,
+sv_copypv X<sv_copypv>, sv_dec X<sv_dec>, sv_eq X<sv_eq>,
+sv_force_normal_flags X<sv_force_normal_flags>, sv_free X<sv_free>, sv_gets
+X<sv_gets>, sv_grow X<sv_grow>, sv_inc X<sv_inc>, sv_insert X<sv_insert>,
+sv_isa X<sv_isa>, sv_isobject X<sv_isobject>, sv_len X<sv_len>, sv_len_utf8
+X<sv_len_utf8>, sv_magic X<sv_magic>, sv_magicext X<sv_magicext>,
+sv_mortalcopy X<sv_mortalcopy>, sv_newmortal X<sv_newmortal>, sv_newref
+X<sv_newref>, sv_pos_b2u X<sv_pos_b2u>, sv_pos_u2b X<sv_pos_u2b>,
+sv_pvbyten_force X<sv_pvbyten_force>, sv_pvn_force X<sv_pvn_force>,
+sv_pvn_force_flags X<sv_pvn_force_flags>, sv_pvutf8n_force
+X<sv_pvutf8n_force>, sv_reftype X<sv_reftype>, sv_replace X<sv_replace>,
+sv_reset X<sv_reset>, sv_rvweaken X<sv_rvweaken>, sv_setiv X<sv_setiv>,
+sv_setiv_mg X<sv_setiv_mg>, sv_setnv X<sv_setnv>, sv_setnv_mg
+X<sv_setnv_mg>, sv_setpv X<sv_setpv>, sv_setpvf X<sv_setpvf>, sv_setpvf_mg
+X<sv_setpvf_mg>, sv_setpviv X<sv_setpviv>, sv_setpviv_mg X<sv_setpviv_mg>,
+sv_setpvn X<sv_setpvn>, sv_setpvn_mg X<sv_setpvn_mg>, sv_setpvs
+X<sv_setpvs>, sv_setpv_mg X<sv_setpv_mg>, sv_setref_iv X<sv_setref_iv>,
+sv_setref_nv X<sv_setref_nv>, sv_setref_pv X<sv_setref_pv>, sv_setref_pvn
+X<sv_setref_pvn>, sv_setref_uv X<sv_setref_uv>, sv_setsv X<sv_setsv>,
+sv_setsv_flags X<sv_setsv_flags>, sv_setsv_mg X<sv_setsv_mg>, sv_setuv
+X<sv_setuv>, sv_setuv_mg X<sv_setuv_mg>, sv_tainted X<sv_tainted>, sv_true
+X<sv_true>, sv_unmagic X<sv_unmagic>, sv_unref_flags X<sv_unref_flags>,
+sv_untaint X<sv_untaint>, sv_upgrade X<sv_upgrade>, sv_usepvn_flags
+X<sv_usepvn_flags>, sv_utf8_decode X<sv_utf8_decode>, sv_utf8_downgrade
+X<sv_utf8_downgrade>, sv_utf8_encode X<sv_utf8_encode>, sv_utf8_upgrade
+X<sv_utf8_upgrade>, sv_utf8_upgrade_flags X<sv_utf8_upgrade_flags>,
+sv_vcatpvf X<sv_vcatpvf>, sv_vcatpvfn X<sv_vcatpvfn>, sv_vcatpvf_mg
+X<sv_vcatpvf_mg>, sv_vsetpvf X<sv_vsetpvf>, sv_vsetpvfn X<sv_vsetpvfn>,
+sv_vsetpvf_mg X<sv_vsetpvf_mg>
+
+=item Unicode Support
+
+bytes_from_utf8 X<bytes_from_utf8>, bytes_to_utf8 X<bytes_to_utf8>,
+ibcmp_utf8 X<ibcmp_utf8>, is_utf8_char X<is_utf8_char>, is_utf8_string
+X<is_utf8_string>, is_utf8_string_loc X<is_utf8_string_loc>,
+is_utf8_string_loclen X<is_utf8_string_loclen>, pv_uni_display
+X<pv_uni_display>, sv_cat_decode X<sv_cat_decode>, sv_recode_to_utf8
+X<sv_recode_to_utf8>, sv_uni_display X<sv_uni_display>, to_utf8_case
+X<to_utf8_case>, to_utf8_fold X<to_utf8_fold>, to_utf8_lower
+X<to_utf8_lower>, to_utf8_title X<to_utf8_title>, to_utf8_upper
+X<to_utf8_upper>, utf8n_to_uvchr X<utf8n_to_uvchr>, utf8n_to_uvuni
+X<utf8n_to_uvuni>, utf8_distance X<utf8_distance>, utf8_hop X<utf8_hop>,
+utf8_length X<utf8_length>, utf8_to_bytes X<utf8_to_bytes>, utf8_to_uvchr
+X<utf8_to_uvchr>, utf8_to_uvuni X<utf8_to_uvuni>, uvchr_to_utf8
+X<uvchr_to_utf8>, uvuni_to_utf8_flags X<uvuni_to_utf8_flags>
+
+=item Variables created by C<xsubpp> and C<xsubpp> internal functions
+
+ax X<ax>, CLASS X<CLASS>, dAX X<dAX>, dAXMARK X<dAXMARK>, dITEMS X<dITEMS>,
+dUNDERBAR X<dUNDERBAR>, dXSARGS X<dXSARGS>, dXSI32 X<dXSI32>, items
+X<items>, ix X<ix>, newXSproto X<newXSproto>, RETVAL X<RETVAL>, ST X<ST>,
+THIS X<THIS>, UNDERBAR X<UNDERBAR>, XS X<XS>, XS_VERSION X<XS_VERSION>,
+XS_VERSION_BOOTCHECK X<XS_VERSION_BOOTCHECK>
+
+=item Warning and Dieing
+
+croak X<croak>, warn X<warn>
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 perlintern - autogenerated documentation of purely B<internal>
+ Perl functions
+
+=over 4
+
+=item DESCRIPTION
+X<internal Perl functions> X<interpreter functions>
+
+=item CV reference counts and CvOUTSIDE
+
+CvWEAKOUTSIDE X<CvWEAKOUTSIDE>
+
+=item Functions in file pad.h
+
+CX_CURPAD_SAVE X<CX_CURPAD_SAVE>, CX_CURPAD_SV X<CX_CURPAD_SV>, PAD_BASE_SV
+X<PAD_BASE_SV>, PAD_CLONE_VARS X<PAD_CLONE_VARS>, PAD_COMPNAME_FLAGS
+X<PAD_COMPNAME_FLAGS>, PAD_COMPNAME_GEN X<PAD_COMPNAME_GEN>,
+PAD_COMPNAME_GEN_set X<PAD_COMPNAME_GEN_set>, PAD_COMPNAME_OURSTASH
+X<PAD_COMPNAME_OURSTASH>, PAD_COMPNAME_PV X<PAD_COMPNAME_PV>,
+PAD_COMPNAME_TYPE X<PAD_COMPNAME_TYPE>, PAD_DUP X<PAD_DUP>,
+PAD_RESTORE_LOCAL X<PAD_RESTORE_LOCAL>, PAD_SAVE_LOCAL X<PAD_SAVE_LOCAL>,
+PAD_SAVE_SETNULLPAD X<PAD_SAVE_SETNULLPAD>, PAD_SETSV X<PAD_SETSV>,
+PAD_SET_CUR X<PAD_SET_CUR>, PAD_SET_CUR_NOSAVE X<PAD_SET_CUR_NOSAVE>,
+PAD_SV X<PAD_SV>, PAD_SVl X<PAD_SVl>, SAVECLEARSV X<SAVECLEARSV>,
+SAVECOMPPAD X<SAVECOMPPAD>, SAVEPADSV X<SAVEPADSV>
+
+=item GV Functions
+
+is_gv_magical X<is_gv_magical>, is_gv_magical_sv X<is_gv_magical_sv>
+
+=item Hash Manipulation Functions
+
+refcounted_he_chain_2hv X<refcounted_he_chain_2hv>, refcounted_he_free
+X<refcounted_he_free>, refcounted_he_new X<refcounted_he_new>
+
+=item IO Functions
+
+start_glob X<start_glob>
+
+=item Magical Functions
+
+magic_sethint X<magic_sethint>, mg_localize X<mg_localize>
+
+=item MRO Functions
+
+mro_get_linear_isa_c3 X<mro_get_linear_isa_c3>, mro_get_linear_isa_dfs
+X<mro_get_linear_isa_dfs>, mro_isa_changed_in X<mro_isa_changed_in>
+
+=item Pad Data Structures
+
+CvPADLIST X<CvPADLIST>, cv_clone X<cv_clone>, cv_dump X<cv_dump>,
+do_dump_pad X<do_dump_pad>, intro_my X<intro_my>, pad_add_anon
+X<pad_add_anon>, pad_add_name X<pad_add_name>, pad_alloc X<pad_alloc>,
+pad_block_start X<pad_block_start>, pad_check_dup X<pad_check_dup>,
+pad_findlex X<pad_findlex>, pad_findmy X<pad_findmy>, pad_fixup_inner_anons
+X<pad_fixup_inner_anons>, pad_free X<pad_free>, pad_leavemy X<pad_leavemy>,
+pad_new X<pad_new>, pad_push X<pad_push>, pad_reset X<pad_reset>, pad_setsv
+X<pad_setsv>, pad_swipe X<pad_swipe>, pad_tidy X<pad_tidy>, pad_undef
+X<pad_undef>
+
+=item Per-Interpreter Variables
+
+PL_DBsingle X<PL_DBsingle>, PL_DBsub X<PL_DBsub>, PL_DBtrace X<PL_DBtrace>,
+PL_dowarn X<PL_dowarn>, PL_last_in_gv X<PL_last_in_gv>, PL_ofs_sv
+X<PL_ofs_sv>, PL_rs X<PL_rs>
+
+=item Stack Manipulation Macros
+
+djSP X<djSP>, LVRET X<LVRET>
+
+=item SV Manipulation Functions
+
+sv_add_arena X<sv_add_arena>, sv_clean_all X<sv_clean_all>, sv_clean_objs
+X<sv_clean_objs>, sv_free_arenas X<sv_free_arenas>
+
+=item SV-Body Allocation
+
+sv_2num X<sv_2num>
+
+=item Unicode Support
+
+find_uninit_var X<find_uninit_var>, report_uninit X<report_uninit>
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 perliol - C API for Perl's implementation of IO in Layers.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item History and Background
+
+=item Basic Structure
+
+=item Layers vs Disciplines
+
+=item Data Structures
+
+=item Functions and Attributes
+
+=item Per-instance Data
+
+=item Layers in action.
+
+=item Per-instance flag bits
+
+PERLIO_F_EOF, PERLIO_F_CANWRITE, PERLIO_F_CANREAD, PERLIO_F_ERROR,
+PERLIO_F_TRUNCATE, PERLIO_F_APPEND, PERLIO_F_CRLF, PERLIO_F_UTF8,
+PERLIO_F_UNBUF, PERLIO_F_WRBUF, PERLIO_F_RDBUF, PERLIO_F_LINEBUF,
+PERLIO_F_TEMP, PERLIO_F_OPEN, PERLIO_F_FASTGETS
+
+=item Methods in Detail
+
+fsize, name, size, kind, PERLIO_K_BUFFERED, PERLIO_K_RAW, PERLIO_K_CANCRLF,
+PERLIO_K_FASTGETS, PERLIO_K_MULTIARG, Pushed, Popped, Open, Binmode,
+Getarg, Fileno, Dup, Read, Write, Seek, Tell, Close, Flush, Fill, Eof,
+Error, Clearerr, Setlinebuf, Get_base, Get_bufsiz, Get_ptr, Get_cnt,
+Set_ptrcnt
+
+=item Utilities
+
+=item Implementing PerlIO Layers
+
+C implementations, Perl implementations
+
+=item Core Layers
+
+"unix", "perlio", "stdio", "crlf", "mmap", "pending", "raw", "utf8"
+
+=item Extension Layers
+
+":encoding", ":scalar", ":via"
+
+=back
+
+=item TODO
+
+=back
+
+=head2 perlapio - perl's IO abstraction interface.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+1. USE_STDIO, 2. USE_SFIO, 3. USE_PERLIO, B<PerlIO_stdin()>,
+B<PerlIO_stdout()>, B<PerlIO_stderr()>, B<PerlIO_open(path, mode)>,
+B<PerlIO_fdopen(fd,mode)>, B<PerlIO_reopen(path,mode,f)>,
+B<PerlIO_printf(f,fmt,...)>, B<PerlIO_vprintf(f,fmt,a)>,
+B<PerlIO_stdoutf(fmt,...)>, B<PerlIO_read(f,buf,count)>,
+B<PerlIO_write(f,buf,count)>, B<PerlIO_close(f)>, B<PerlIO_puts(f,s)>,
+B<PerlIO_putc(f,c)>, B<PerlIO_ungetc(f,c)>, B<PerlIO_getc(f)>,
+B<PerlIO_eof(f)>, B<PerlIO_error(f)>, B<PerlIO_fileno(f)>,
+B<PerlIO_clearerr(f)>, B<PerlIO_flush(f)>, B<PerlIO_seek(f,offset,whence)>,
+B<PerlIO_tell(f)>, B<PerlIO_getpos(f,p)>, B<PerlIO_setpos(f,p)>,
+B<PerlIO_rewind(f)>, B<PerlIO_tmpfile()>, B<PerlIO_setlinebuf(f)>
+
+=over 4
+
+=item Co-existence with stdio
+
+B<PerlIO_importFILE(f,mode)>, B<PerlIO_exportFILE(f,mode)>,
+B<PerlIO_releaseFILE(p,f)>, B<PerlIO_findFILE(f)>
+
+=item "Fast gets" Functions
+
+B<PerlIO_fast_gets(f)>, B<PerlIO_has_cntptr(f)>, B<PerlIO_get_cnt(f)>,
+B<PerlIO_get_ptr(f)>, B<PerlIO_set_ptrcnt(f,p,c)>, B<PerlIO_canset_cnt(f)>,
+B<PerlIO_set_cnt(f,c)>, B<PerlIO_has_base(f)>, B<PerlIO_get_base(f)>,
+B<PerlIO_get_bufsiz(f)>
+
+=item Other Functions
+
+PerlIO_apply_layers(f,mode,layers), PerlIO_binmode(f,ptype,imode,layers),
+'E<lt>' read, 'E<gt>' write, '+' read/write, PerlIO_debug(fmt,...)
+
+=back
+
+=back
+
+=head2 perlhack - How to hack at the Perl internals
+
+=over 4
+
+=item DESCRIPTION
+
+Does concept match the general goals of Perl?, Where is the
+implementation?, Backwards compatibility, Could it be a module instead?, Is
+the feature generic enough?, Does it potentially introduce new bugs?, Does
+it preclude other desirable features?, Is the implementation robust?, Is
+the implementation generic enough to be portable?, Is the implementation
+tested?, Is there enough documentation?, Is there another way to do it?,
+Does it create too much work?, Patches speak louder than words
+
+=over 4
+
+=item Keeping in sync
+
+rsync'ing the source tree, Using rsync over the LAN, Using pushing over the
+NFS, rsync'ing the patches
+
+=item Why rsync the source tree
+
+It's easier to rsync the source tree, It's more reliable
+
+=item Why rsync the patches
+
+It's easier to rsync the patches, It's a good reference, Finding a start
+point, Finding how to fix a bug, Finding the source of misbehaviour
+
+=item Working with the source
+
+=item Perlbug administration
+
+=item Submitting patches
+
+L<perlguts>, L<perlxstut> and L<perlxs>, L<perlapi>,
+F<Porting/pumpkin.pod>, The perl5-porters FAQ
+
+=item Finding Your Way Around
+
+Core modules, Tests, Documentation, Configure, Interpreter
+
+=item Elements of the interpreter
+
+Startup, Parsing, Optimization, Running, Exception handing
+
+=item Internal Variable Types
+
+=item Op Trees
+
+=item Stacks
+
+Argument stack, Mark stack, Save stack
+
+=item Millions of Macros
+
+=item The .i Targets
+
+=back
+
+=item SOURCE CODE STATIC ANALYSIS
+
+=over 4
+
+=item lint, splint
+
+=item Coverity
+
+=item cpd (cut-and-paste detector)
+
+=item gcc warnings
+
+=item Warnings of other C compilers
+
+=item DEBUGGING
+
+=item Poking at Perl
+
+=item Using a source-level debugger
+
+run [args], break function_name, break source.c:xxx, step, next, continue,
+finish, 'enter', print
+
+=item gdb macro support
+
+=item Dumping Perl Data Structures
+
+=item Patching
+
+=item Patching a core module
+
+=item Adding a new function to the core
+
+=item Writing a test
+
+F<t/base/>, F<t/cmd/>, F<t/comp/>, F<t/io/>, F<t/lib/>, F<t/mro/>,
+F<t/op/>, F<t/pod/>, F<t/run/>, F<t/uni/>, F<t/win32/>, F<t/x2p>, t/base
+t/comp, t/cmd t/run t/io t/op, t/lib ext lib
+
+=item Special Make Test Targets
+
+coretest, test.deparse, test.taintwarn, minitest, test.valgrind
+check.valgrind utest.valgrind ucheck.valgrind, test.third check.third
+utest.third ucheck.third, test.torture torturetest, utest ucheck test.utf8
+check.utf8, minitest.utf16 test.utf16, test_harness, test-notty test_notty
+
+=item Running tests by hand
+
+-v, -torture, -re=PATTERN, -re LIST OF PATTERNS, PERL_CORE=1,
+PERL_DESTRUCT_LEVEL=2, PERL, PERL_SKIP_TTY_TEST, PERL_TEST_Net_Ping,
+PERL_TEST_NOVREXX, PERL_TEST_NUMCONVERTS
+
+=item Common problems when patching Perl source code
+
+=item Perl environment problems
+
+=item Portability problems
+
+=item Problematic System Interfaces
+
+=item Security problems
+
+=back
+
+=item EXTERNAL TOOLS FOR DEBUGGING PERL
+
+=over 4
+
+=item Rational Software's Purify
+
+=item Purify on Unix
+
+-Accflags=-DPURIFY, -Doptimize='-g', -Uusemymalloc, -Dusemultiplicity
+
+=item Purify on NT
+
+DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug
+
+=item valgrind
+
+=item Compaq's/Digital's/HP's Third Degree
+
+=item PERL_DESTRUCT_LEVEL
+
+=item PERL_MEM_LOG
+
+=item Profiling
+
+=item Gprof Profiling
+
+-a, -b, -e routine, -f routine, -s, -z
+
+=item GCC gcov Profiling
+
+=item Pixie Profiling
+
+-h, -l, -p[rocedures], -h[eavy], -i[nvocations], -l[ines], -testcoverage,
+-z[ero]
+
+=item Miscellaneous tricks
+
+=back
+
+=item CONCLUSION
+
+I<The Road goes ever on and on, down from the door where it began.>
+
+=item AUTHOR
+
+=back
+
+=head2 perlbook - Perl book information
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 perlcommunity - a brief overview of the Perl community
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Where to find the community
+
+=item Mailing lists and Newsgroups
+
+=item IRC
+
+=item Websites
+
+L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/>
+
+=item User Groups
+
+=item Workshops
+
+=item Hackathons
+
+=item Conventions
+
+=item Calendar of Perl Events
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perltodo - Perl TO-DO List
+
+=over 4
+
+=item DESCRIPTION
+
+=item Tasks that only need Perl knowledge
+
+=over 4
+
+=item Remove duplication of test setup.
+
+=item merge common code in installperl and installman
+
+=item common test code for timed bail out
+
+=item POD -E<gt> HTML conversion in the core still sucks
+
+=item merge checkpods and podchecker
+
+=item perlmodlib.PL rewrite
+
+=item Parallel testing
+
+=item Make Schwern poorer
+
+=item Improve the coverage of the core tests
+
+=item test B
+
+=item Deparse inlined constants
+
+=item A decent benchmark
+
+=item fix tainting bugs
+
+=item Dual life everything
+
+=item Improving C<threads::shared>
+
+=item POSIX memory footprint
+
+=item embed.pl/makedef.pl
+
+=item use strict; and AutoLoad
+
+=back
+
+=item Tasks that need a little sysadmin-type knowledge
+
+=over 4
+
+=item make HTML install work
+
+=item compressed man pages
+
+=item Add a code coverage target to the Makefile
+
+=item Make Config.pm cope with differences between built and installed perl
+
+=item linker specification files
+
+=item Cross-compile support
+
+=item roffitall
+
+=back
+
+=item Tasks that need a little C knowledge
+
+=over 4
+
+=item Exterminate PL_na!
+
+=item Modernize the order of directories in @INC
+
+=item -Duse32bit*
+
+=item Make it clear from -v if this is the exact official release
+
+=item Profile Perl - am I hot or not?
+
+=item Allocate OPs from arenas
+
+=item Improve win32/wince.c
+
+=item Use secure CRT functions when building with VC8 on Win32
+
+=item strcat(), strcpy(), strncat(), strncpy(), sprintf(), vsprintf()
+
+=item -D_FORTIFY_SOURCE=2, -fstack-protector
+
+=back
+
+=item Tasks that need a knowledge of XS
+
+=over 4
+
+=item autovivification
+
+=item Unicode in Filenames
+
+=item Unicode in %ENV
+
+=item Unicode and glob()
+
+=item Unicode and lc/uc operators
+
+=item use less 'memory'
+
+=item Re-implement C<:unique> in a way that is actually thread-safe
+
+=item Make tainting consistent
+
+=item readpipe(LIST)
+
+=item Audit the code for destruction ordering assumptions
+
+=item Extend PerlIO and PerlIO::Scalar
+
+=item -C on the #! line
+
+=item Propagate const outwards from Perl_moreswitches()
+
+=item Duplicate logic in S_method_common() and
+Perl_gv_fetchmethod_autoload()
+
+=item Organize error messages
+
+=back
+
+=item Tasks that need a knowledge of the interpreter
+
+=over 4
+
+=item state variable initialization in list context
+
+=item Implement $value ~~ 0 .. $range
+
+=item A does() built-in
+
+=item Tied filehandles and write() don't mix
+
+=item Attach/detach debugger from running program
+
+=item Optimize away empty destructors
+
+=item LVALUE functions for lists
+
+=item LVALUE functions in the debugger
+
+=item regexp optimiser optional
+
+=item delete &function
+
+=item C</w> regex modifier
+
+=item optional optimizer
+
+=item You WANT *how* many
+
+=item lexical aliases
+
+=item entersub XS vs Perl
+
+=item Self-ties
+
+=item Optimize away @_
+
+=item Properly Unicode safe tokeniser and pads.
+
+=item The yada yada yada operators
+
+=item Virtualize operating system access
+
+=item Investigate PADTMP hash pessimisation
+
+=back
+
+=item Big projects
+
+=over 4
+
+=item make ithreads more robust
+
+=item iCOW
+
+=item (?{...}) closures in regexps
+
+=item A re-entrant regexp engine
+
+=item Add class set operations to regexp engine
+
+=back
+
+=back
+
+=head2 perldoc - Look up Perl documentation in Pod format.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS
+
+B<-h>, B<-v>, B<-t>, B<-u>, B<-m> I<module>, B<-l>, B<-F>, B<-f>
+I<perlfunc>, B<-q> I<perlfaq-search-regexp>, B<-T>, B<-d>
+I<destination-filename>, B<-o> I<output-formatname>, B<-M> I<module-name>,
+B<-w> I<option:value> or B<-w> I<option>, B<-X>, B<-L> I<language_code>,
+B<PageName|ModuleName|ProgramName>, B<-n> I<some-formatter>, B<-r>, B<-i>,
+B<-V>
+
+=item SECURITY
+
+=item ENVIRONMENT
+
+=item AUTHOR
+
+=back
+
+=head2 perlhist - the Perl history records
+
+=over 4
+
+=item DESCRIPTION
+
+=item INTRODUCTION
+
+=item THE KEEPERS OF THE PUMPKIN
+
+=over 4
+
+=item PUMPKIN?
+
+=back
+
+=item THE RECORDS
+
+=over 4
+
+=item SELECTED RELEASE SIZES
+
+=item SELECTED PATCH SIZES
+
+=back
+
+=item THE KEEPERS OF THE RECORDS
+
+=back
+
+=head2 perldelta - what is new for perl 5.10.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Core Enhancements
+
+=over 4
+
+=item The C<feature> pragma
+
+=item New B<-E> command-line switch
+
+=item Defined-or operator
+
+=item Switch and Smart Match operator
+
+=item Regular expressions
+
+Recursive Patterns, Named Capture Buffers, Possessive Quantifiers,
+Backtracking control verbs, Relative backreferences, C<\K> escape, Vertical
+and horizontal whitespace, and linebreak
+
+=item C<say()>
+
+=item Lexical C<$_>
+
+=item The C<_> prototype
+
+=item UNITCHECK blocks
+
+=item New Pragma, C<mro>
+
+=item readdir() may return a "short filename" on Windows
+
+=item readpipe() is now overridable
+
+=item Default argument for readline()
+
+=item state() variables
+
+=item Stacked filetest operators
+
+=item UNIVERSAL::DOES()
+
+=item Formats
+
+=item Byte-order modifiers for pack() and unpack()
+
+=item C<no VERSION>
+
+=item C<chdir>, C<chmod> and C<chown> on filehandles
+
+=item OS groups
+
+=item Recursive sort subs
+
+=item Exceptions in constant folding
+
+=item Source filters in @INC
+
+=item New internal variables
+
+C<${^RE_DEBUG_FLAGS}>, C<${^CHILD_ERROR_NATIVE}>, C<${^RE_TRIE_MAXBUF}>,
+C<${^WIN32_SLOPPY_STAT}>
+
+=item Miscellaneous
+
+=item UCD 5.0.0
+
+=item MAD
+
+=item kill() on Windows
+
+=back
+
+=item Incompatible Changes
+
+=over 4
+
+=item Packing and UTF-8 strings
+
+=item Byte/character count feature in unpack()
+
+=item The C<$*> and C<$#> variables have been removed
+
+=item substr() lvalues are no longer fixed-length
+
+=item Parsing of C<-f _>
+
+=item C<:unique>
+
+=item Effect of pragmas in eval
+
+=item chdir FOO
+
+=item Handling of .pmc files
+
+=item $^V is now a C<version> object instead of a v-string
+
+=item @- and @+ in patterns
+
+=item $AUTOLOAD can now be tainted
+
+=item Tainting and printf
+
+=item undef and signal handlers
+
+=item strictures and dereferencing in defined()
+
+=item C<(?p{})> has been removed
+
+=item Pseudo-hashes have been removed
+
+=item Removal of the bytecode compiler and of perlcc
+
+=item Removal of the JPL
+
+=item Recursive inheritance detected earlier
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Upgrading individual core modules
+
+=item Pragmata Changes
+
+C<feature>, C<mro>, Scoping of the C<sort> pragma, Scoping of C<bignum>,
+C<bigint>, C<bigrat>, C<base>, C<strict> and C<warnings>, C<version>,
+C<warnings>, C<less>
+
+=item New modules
+
+=item Selected Changes to Core Modules
+
+C<Attribute::Handlers>, C<B::Lint>, C<B>, C<Thread>
+
+=back
+
+=item Utility Changes
+
+perl -d, ptar, ptardiff, shasum, corelist, h2ph and h2xs, perlivp,
+find2perl, config_data, cpanp, cpan2dist, pod2html
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=over 4
+
+=item In-place sorting
+
+=item Lexical array access
+
+=item XS-assisted SWASHGET
+
+=item Constant subroutines
+
+=item C<PERL_DONT_CREATE_GVSV>
+
+=item Weak references are cheaper
+
+=item sort() enhancements
+
+=item Memory optimisations
+
+=item UTF-8 cache optimisation
+
+=item Sloppy stat on Windows
+
+=item Regular expressions optimisations
+
+Engine de-recursivised, Single char char-classes treated as literals, Trie
+optimisation of literal string alternations, Aho-Corasick start-point
+optimisation
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Configuration improvements
+
+C<-Dusesitecustomize>, Relocatable installations, strlcat() and strlcpy(),
+C<d_pseudofork> and C<d_printf_format_null>, Configure help
+
+=item Compilation improvements
+
+Parallel build, Borland's compilers support, Static build on Windows,
+ppport.h files, C++ compatibility, Support for Microsoft 64-bit compiler,
+Visual C++, Win32 builds
+
+=item Installation improvements
+
+Module auxiliary files
+
+=item New Or Improved Platforms
+
+=back
+
+=item Selected Bug Fixes
+
+strictures in regexp-eval blocks, Calling CORE::require(), Subscripts of
+slices, C<no warnings 'category'> works correctly with -w, threads
+improvements, chr() and negative values, PERL5SHELL and tainting, Using
+*FILE{IO}, Overloading and reblessing, Overloading and UTF-8, eval memory
+leaks fixed, Random device on Windows, PERLIO_DEBUG, PerlIO::scalar and
+read-only scalars, study() and UTF-8, Critical signals, @INC-hook fix,
+C<-t> switch fix, Duping UTF-8 filehandles, Localisation of hash elements
+
+=item New or Changed Diagnostics
+
+Use of uninitialized value, Deprecated use of my() in false conditional,
+!=~ should be !~, Newline in left-justified string, Too late for "-T"
+option, "%s" variable %s masks earlier declaration,
+readdir()/closedir()/etc. attempted on invalid dirhandle, Opening
+dirhandle/filehandle %s also as a file/directory, Use of -P is deprecated,
+v-string in use/require is non-portable, perl -V
+
+=item Changed Internals
+
+=over 4
+
+=item Reordering of SVt_* constants
+
+=item Elimination of SVt_PVBM
+
+=item New type SVt_BIND
+
+=item Removal of CPP symbols
+
+=item Less space is used by ops
+
+=item New parser
+
+=item Use of C<const>
+
+=item Mathoms
+
+=item C<AvFLAGS> has been removed
+
+=item C<av_*> changes
+
+=item $^H and %^H
+
+=item B:: modules inheritance changed
+
+=item Anonymous hash and array constructors
+
+=back
+
+=item Known Problems
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl5100delta, perldelta - what is new for perl 5.10.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Core Enhancements
+
+=over 4
+
+=item The C<feature> pragma
+
+=item New B<-E> command-line switch
+
+=item Defined-or operator
+
+=item Switch and Smart Match operator
+
+=item Regular expressions
+
+Recursive Patterns, Named Capture Buffers, Possessive Quantifiers,
+Backtracking control verbs, Relative backreferences, C<\K> escape, Vertical
+and horizontal whitespace, and linebreak
+
+=item C<say()>
+
+=item Lexical C<$_>
+
+=item The C<_> prototype
+
+=item UNITCHECK blocks
+
+=item New Pragma, C<mro>
+
+=item readdir() may return a "short filename" on Windows
+
+=item readpipe() is now overridable
+
+=item Default argument for readline()
+
+=item state() variables
+
+=item Stacked filetest operators
+
+=item UNIVERSAL::DOES()
+
+=item Formats
+
+=item Byte-order modifiers for pack() and unpack()
+
+=item C<no VERSION>
+
+=item C<chdir>, C<chmod> and C<chown> on filehandles
+
+=item OS groups
+
+=item Recursive sort subs
+
+=item Exceptions in constant folding
+
+=item Source filters in @INC
+
+=item New internal variables
+
+C<${^RE_DEBUG_FLAGS}>, C<${^CHILD_ERROR_NATIVE}>, C<${^RE_TRIE_MAXBUF}>,
+C<${^WIN32_SLOPPY_STAT}>
+
+=item Miscellaneous
+
+=item UCD 5.0.0
+
+=item MAD
+
+=item kill() on Windows
+
+=back
+
+=item Incompatible Changes
+
+=over 4
+
+=item Packing and UTF-8 strings
+
+=item Byte/character count feature in unpack()
+
+=item The C<$*> and C<$#> variables have been removed
+
+=item substr() lvalues are no longer fixed-length
+
+=item Parsing of C<-f _>
+
+=item C<:unique>
+
+=item Effect of pragmas in eval
+
+=item chdir FOO
+
+=item Handling of .pmc files
+
+=item $^V is now a C<version> object instead of a v-string
+
+=item @- and @+ in patterns
+
+=item $AUTOLOAD can now be tainted
+
+=item Tainting and printf
+
+=item undef and signal handlers
+
+=item strictures and dereferencing in defined()
+
+=item C<(?p{})> has been removed
+
+=item Pseudo-hashes have been removed
+
+=item Removal of the bytecode compiler and of perlcc
+
+=item Removal of the JPL
+
+=item Recursive inheritance detected earlier
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Upgrading individual core modules
+
+=item Pragmata Changes
+
+C<feature>, C<mro>, Scoping of the C<sort> pragma, Scoping of C<bignum>,
+C<bigint>, C<bigrat>, C<base>, C<strict> and C<warnings>, C<version>,
+C<warnings>, C<less>
+
+=item New modules
+
+=item Selected Changes to Core Modules
+
+C<Attribute::Handlers>, C<B::Lint>, C<B>, C<Thread>
+
+=back
+
+=item Utility Changes
+
+perl -d, ptar, ptardiff, shasum, corelist, h2ph and h2xs, perlivp,
+find2perl, config_data, cpanp, cpan2dist, pod2html
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=over 4
+
+=item In-place sorting
+
+=item Lexical array access
+
+=item XS-assisted SWASHGET
+
+=item Constant subroutines
+
+=item C<PERL_DONT_CREATE_GVSV>
+
+=item Weak references are cheaper
+
+=item sort() enhancements
+
+=item Memory optimisations
+
+=item UTF-8 cache optimisation
+
+=item Sloppy stat on Windows
+
+=item Regular expressions optimisations
+
+Engine de-recursivised, Single char char-classes treated as literals, Trie
+optimisation of literal string alternations, Aho-Corasick start-point
+optimisation
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Configuration improvements
+
+C<-Dusesitecustomize>, Relocatable installations, strlcat() and strlcpy(),
+C<d_pseudofork> and C<d_printf_format_null>, Configure help
+
+=item Compilation improvements
+
+Parallel build, Borland's compilers support, Static build on Windows,
+ppport.h files, C++ compatibility, Support for Microsoft 64-bit compiler,
+Visual C++, Win32 builds
+
+=item Installation improvements
+
+Module auxiliary files
+
+=item New Or Improved Platforms
+
+=back
+
+=item Selected Bug Fixes
+
+strictures in regexp-eval blocks, Calling CORE::require(), Subscripts of
+slices, C<no warnings 'category'> works correctly with -w, threads
+improvements, chr() and negative values, PERL5SHELL and tainting, Using
+*FILE{IO}, Overloading and reblessing, Overloading and UTF-8, eval memory
+leaks fixed, Random device on Windows, PERLIO_DEBUG, PerlIO::scalar and
+read-only scalars, study() and UTF-8, Critical signals, @INC-hook fix,
+C<-t> switch fix, Duping UTF-8 filehandles, Localisation of hash elements
+
+=item New or Changed Diagnostics
+
+Use of uninitialized value, Deprecated use of my() in false conditional,
+!=~ should be !~, Newline in left-justified string, Too late for "-T"
+option, "%s" variable %s masks earlier declaration,
+readdir()/closedir()/etc. attempted on invalid dirhandle, Opening
+dirhandle/filehandle %s also as a file/directory, Use of -P is deprecated,
+v-string in use/require is non-portable, perl -V
+
+=item Changed Internals
+
+=over 4
+
+=item Reordering of SVt_* constants
+
+=item Elimination of SVt_PVBM
+
+=item New type SVt_BIND
+
+=item Removal of CPP symbols
+
+=item Less space is used by ops
+
+=item New parser
+
+=item Use of C<const>
+
+=item Mathoms
+
+=item C<AvFLAGS> has been removed
+
+=item C<av_*> changes
+
+=item $^H and %^H
+
+=item B:: modules inheritance changed
+
+=item Anonymous hash and array constructors
+
+=back
+
+=item Known Problems
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl595delta - what is new for perl v5.9.5
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item Tainting and printf
+
+=item undef and signal handlers
+
+=item strictures and array/hash dereferencing in defined()
+
+=item C<(?p{})> has been removed
+
+=item Pseudo-hashes have been removed
+
+=item Removal of the bytecode compiler and of perlcc
+
+=item Removal of the JPL
+
+=item Recursive inheritance detected earlier
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Regular expressions
+
+Recursive Patterns, Named Capture Buffers, Possessive Quantifiers,
+Backtracking control verbs, Relative backreferences, C<\K> escape, Vertical
+and horizontal whitespace, and linebreak
+
+=item The C<_> prototype
+
+=item UNITCHECK blocks
+
+=item readpipe() is now overridable
+
+=item default argument for readline()
+
+=item UCD 5.0.0
+
+=item Smart match
+
+=item Implicit loading of C<feature>
+
+=back
+
+=item Modules and Pragmas
+
+=over 4
+
+=item New Pragma, C<mro>
+
+=item bignum, bigint, bigrat
+
+=item Math::BigInt/Math::BigFloat
+
+config(), import(), roundmode common, bpi(), bcos(), bsin(), batan(),
+batan2(), bmuladd(), bexp(), bnok(), from_hex(), from_oct(), and
+from_bin(), as_oct()
+
+=item New Core Modules
+
+=item Module changes
+
+C<assertions>, C<base>, C<strict> and C<warnings>, C<warnings>, C<less>,
+C<Attribute::Handlers>, C<B::Lint>, C<B>, C<Thread>
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item C<cpanp>
+
+=item C<cpan2dist>
+
+=item C<pod2html>
+
+=back
+
+=item Documentation
+
+=over 4
+
+=item New manpage, perlunifaq
+
+=back
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item C++ compatibility
+
+=item Visual C++
+
+=item Static build on Win32
+
+=item win32 builds
+
+=item C<d_pseudofork> and C<d_printf_format_null>
+
+=item Help
+
+=item 64bit systems
+
+=item Ports
+
+=back
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=over 4
+
+=item Deprecations
+
+=back
+
+=item Changed Internals
+
+=item Known Problems
+
+=over 4
+
+=item Platform Specific Problems
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl594delta - what is new for perl v5.9.4
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item chdir FOO
+
+=item Handling of pmc files
+
+=item @- and @+ in patterns
+
+=item $AUTOLOAD can now be tainted
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item state() variables
+
+=item UNIVERSAL::DOES()
+
+=item Exceptions in constant folding
+
+=item Source filters in @INC
+
+=item MAD
+
+=back
+
+=item Modules and Pragmas
+
+=over 4
+
+=item New Core Modules
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item config_data
+
+=back
+
+=item Documentation
+
+=over 4
+
+=item New manpage, perlpragma
+
+=item New manpage, perlreguts
+
+=item New manpage, perlunitut
+
+=back
+
+=item Performance Enhancements
+
+=over 4
+
+=item Memory optimisations
+
+=item UTF-8 cache optimisation
+
+=item Regular expressions
+
+Engine de-recursivised, Single char char-classes treated as literals, Trie
+optimisation of literal string alternations, Aho-Corasick start-point
+optimisation
+
+=item Sloppy stat on Windows
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Relocatable installations
+
+=item Ports
+
+=item Compilation improvements
+
+=item New probes
+
+=item Windows build improvements
+
+Building XS extensions, Support for 64-bit compiler
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item PERL5SHELL and tainting
+
+=item Using *FILE{IO}
+
+=item Overloading and reblessing
+
+=item Overloading and UTF-8
+
+=item eval memory leaks fixed
+
+=item Random device on Windows
+
+=back
+
+=item New or Changed Diagnostics
+
+State variable %s will be reinitialized
+
+=item Changed Internals
+
+=item Known Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl593delta - what is new for perl v5.9.3
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item Parsing of C<-f _>
+
+=item C<mkdir()>
+
+=item Magic goto and eval
+
+=item C<$#> has been removed
+
+=item C<:unique>
+
+=item Scoping of the C<sort> pragma
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item The C<feature> pragma
+
+=item Switch and Smart Match operator
+
+=item C<say()>
+
+=item C<CLONE_SKIP()>
+
+=item C<${^CHILD_ERROR_NATIVE}>
+
+=item Assertions
+
+=item Unicode Character Database 4.1.0
+
+=item C<no VERSION>
+
+=item Recursive sort subs
+
+=item Effect of pragmas in eval
+
+=item New B<-E> command-line switch
+
+=item C<chdir>, C<chmod> and C<chown> on filehandles
+
+=item OS groups
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Core Modules
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item C<ptar>
+
+=item C<ptardiff>
+
+=item C<shasum>
+
+=item C<h2xs> enhancements
+
+=item C<perlivp> enhancements
+
+=back
+
+=item Documentation
+
+=over 4
+
+=item Perl Glossary
+
+=back
+
+=item Performance Enhancements
+
+=over 4
+
+=item XS-assisted SWASHGET
+
+=item Constant subroutines
+
+=item C<PERL_DONT_CREATE_GVSV>
+
+=item Weak references are cheaper
+
+=item sort() enhancements
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Compilation improvements
+
+=item New Or Improved Platforms
+
+=item New probes
+
+=item Module auxiliary files
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item C<defined $$x>
+
+=item Calling CORE::require()
+
+=item Subscripts of slices
+
+=item Remove over-optimisation
+
+=item sprintf() fixes
+
+=item no warnings 'category' works correctly with -w
+
+=item Smaller fixes
+
+=item More Unicode Fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=over 4
+
+=item Attempt to set length of freed array
+
+=item Non-string passed as bitmask
+
+=item Search pattern not terminated or ternary operator parsed as search
+pattern
+
+=item "%s" variable %s masks earlier declaration
+
+=item readdir()/closedir()/etc. attempted on invalid dirhandle
+
+=back
+
+=item Changed Internals
+
+=over 4
+
+=item B:: modules inheritance changed
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl592delta - what is new for perl v5.9.2
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item Packing and UTF-8 strings
+
+=item Miscellaneous
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Malloc wrapping
+
+=item Unicode Character Database 4.0.1
+
+=item suidperl less insecure
+
+=item PERLIO_DEBUG
+
+=item Formats
+
+=item Unicode Character Classes
+
+=item Byte-order modifiers for pack() and unpack()
+
+=item Byte count feature in pack()
+
+=item New variables
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New modules
+
+=item Updated And Improved Modules and Pragmata
+
+B::Concise, Socket, Sys::Syslog, threads
+
+=back
+
+=item Utility Changes
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Known Problems
+
+=item Plans for the next release
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl591delta - what is new for perl v5.9.1
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item substr() lvalues are no longer fixed-length
+
+=item The C<:unique> attribute is only meaningful for globals
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Lexical C<$_>
+
+=item Tied hashes in scalar context
+
+=item Formats
+
+=item Stacked filetest operators
+
+=back
+
+=item Modules and Pragmata
+
+Benchmark, Carp, Exporter, FindBin, List::Util, threads::shared
+
+=item Utility Changes
+
+=item Documentation
+
+=item Performance Enhancements
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item UTF-8 bugs
+
+=item Threading bugs
+
+=item More bugs
+
+=back
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=over 4
+
+=item Reordering of SVt_* constants
+
+=item Removal of CPP symbols
+
+=item Less space is used by ops
+
+=item New parser
+
+=back
+
+=item Configuration and Building
+
+=item Known Problems
+
+=over 4
+
+=item Platform Specific Problems
+
+=back
+
+=item To-do for perl 5.10.0
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl590delta - what is new for perl v5.9.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item Hash Randomisation
+
+=item UTF-8 On Filehandles No Longer Activated By Locale
+
+=item Single-number v-strings are no longer v-strings before "=>"
+
+=item (Win32) The -C Switch Has Been Repurposed
+
+=item (Win32) The /d Switch Of cmd.exe
+
+=item The C<$*> variable has been removed
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Assertions
+
+=item Defined-or operators
+
+=item UTF-8 no longer default under UTF-8 locales
+
+=item Unsafe signals again available
+
+=item Tied Arrays with Negative Array Indices
+
+=item local ${$x}
+
+=item Unicode Character Database 4.0.0
+
+=item Miscellaneous Enhancements
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Updated Modules And Pragmata
+
+base, B::Bytecode, B::Concise, B::Deparse, Benchmark, ByteLoader, bytes,
+CGI, charnames, CPAN, Data::Dumper, DB_File, Devel::PPPort, Digest::MD5,
+Encode, fields, libnet, Math::BigInt, MIME::Base64, NEXT, Net::Ping,
+PerlIO::scalar, podlators, Pod::LaTeX, PodParsers, Pod::Perldoc,
+Scalar::Util, Storable, strict, Term::ANSIcolor, Test::Harness, Test::More,
+Test::Simple, Text::Balanced, Time::HiRes, threads, threads::shared,
+Unicode::Collate, Unicode::Normalize, Win32::GetFolderPath,
+Win32::GetOSVersion
+
+=back
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Platform-specific enhancements
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Closures, eval and lexicals
+
+=item Generic fixes
+
+=item Platform-specific fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=over 4
+
+=item Changed "A thread exited while %d threads were running"
+
+=item Removed "Attempt to clear a restricted hash"
+
+=item New "Illegal declaration of anonymous subroutine"
+
+=item Changed "Invalid range "%s" in transliteration operator"
+
+=item New "Missing control char name in \c"
+
+=item New "Newline in left-justified string for %s"
+
+=item New "Possible precedence problem on bitwise %c operator"
+
+=item New "read() on %s filehandle %s"
+
+=item New "Tied variable freed while still in use"
+
+=item New "To%s: illegal mapping '%s'"
+
+=item New "Use of freed value in iteration"
+
+=back
+
+=item Changed Internals
+
+=item New Tests
+
+=item Known Problems
+
+=over 4
+
+=item Tied hashes in scalar context
+
+=item Net::Ping 450_service and 510_ping_udp failures
+
+=item B::C
+
+=back
+
+=item Platform Specific Problems
+
+=over 4
+
+=item EBCDIC Platforms
+
+=item Cygwin 1.5 problems
+
+=item HP-UX: HP cc warnings about sendfile and sendpath
+
+=item IRIX: t/uni/tr_7jis.t falsely failing
+
+=item Mac OS X: no usemymalloc
+
+=item Tru64: No threaded builds with GNU cc (gcc)
+
+=item Win32: sysopen, sysread, syswrite
+
+=back
+
+=item TODO
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl588delta - what is new for perl v5.8.8
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+=item Utility Changes
+
+=over 4
+
+=item C<h2xs> enhancements
+
+=item C<perlivp> enhancements
+
+=back
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item no warnings 'category' works correctly with -w
+
+=item Remove over-optimisation
+
+=item sprintf() fixes
+
+=item Debugger and Unicode slowdown
+
+=item Smaller fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=over 4
+
+=item Attempt to set length of freed array
+
+=item Non-string passed as bitmask
+
+=item Search pattern not terminated or ternary operator parsed as search
+pattern
+
+=back
+
+=item Changed Internals
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl587delta - what is new for perl v5.8.7
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=over 4
+
+=item Unicode Character Database 4.1.0
+
+=item suidperl less insecure
+
+=item Optional site customization script
+
+=item C<Config.pm> is now much smaller.
+
+=back
+
+=item Modules and Pragmata
+
+=item Utility Changes
+
+=over 4
+
+=item find2perl enhancements
+
+=back
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Known Problems
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl586delta - what is new for perl v5.8.6
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+=item Utility Changes
+
+=item Performance Enhancements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item New Tests
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl585delta - what is new for perl v5.8.5
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+=item Utility Changes
+
+=over 4
+
+=item Perl's debugger
+
+=item h2ph
+
+=back
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Known Problems
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl584delta - what is new for perl v5.8.4
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=over 4
+
+=item Malloc wrapping
+
+=item Unicode Character Database 4.0.1
+
+=item suidperl less insecure
+
+=item format
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Updated modules
+
+Attribute::Handlers, B, Benchmark, CGI, Carp, Cwd, Exporter, File::Find,
+IO, IPC::Open3, Local::Maketext, Math::BigFloat, Math::BigInt,
+Math::BigRat, MIME::Base64, ODBM_File, POSIX, Shell, Socket, Storable,
+Switch, Sys::Syslog, Term::ANSIColor, Time::HiRes, Unicode::UCD, Win32,
+base, open, threads, utf8
+
+=back
+
+=item Performance Enhancements
+
+=item Utility Changes
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Future Directions
+
+=item Platform Specific Problems
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl583delta - what is new for perl v5.8.3
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+CGI, Cwd, Digest, Digest::MD5, Encode, File::Spec, FindBin, List::Util,
+Math::BigInt, PodParser, Pod::Perldoc, POSIX, Unicode::Collate,
+Unicode::Normalize, Test::Harness, threads::shared
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Installation and Configuration Improvements
+
+=item Selected Bug Fixes
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Configuration and Building
+
+=item Platform Specific Problems
+
+=item Known Problems
+
+=item Future Directions
+
+=item Obituary
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl582delta - what is new for perl v5.8.2
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=over 4
+
+=item Hash Randomisation
+
+=item Threading
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Updated Modules And Pragmata
+
+Devel::PPPort, Digest::MD5, I18N::LangTags, libnet, MIME::Base64,
+Pod::Perldoc, strict, Tie::Hash, Time::HiRes, Unicode::Collate,
+Unicode::Normalize, UNIVERSAL
+
+=back
+
+=item Selected Bug Fixes
+
+=item Changed Internals
+
+=item Platform Specific Problems
+
+=item Future Directions
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl581delta - what is new for perl v5.8.1
+
+=over 4
+
+=item DESCRIPTION
+
+=item Incompatible Changes
+
+=over 4
+
+=item Hash Randomisation
+
+=item UTF-8 On Filehandles No Longer Activated By Locale
+
+=item Single-number v-strings are no longer v-strings before "=>"
+
+=item (Win32) The -C Switch Has Been Repurposed
+
+=item (Win32) The /d Switch Of cmd.exe
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item UTF-8 no longer default under UTF-8 locales
+
+=item Unsafe signals again available
+
+=item Tied Arrays with Negative Array Indices
+
+=item local ${$x}
+
+=item Unicode Character Database 4.0.0
+
+=item Deprecation Warnings
+
+=item Miscellaneous Enhancements
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Updated Modules And Pragmata
+
+base, B::Bytecode, B::Concise, B::Deparse, Benchmark, ByteLoader, bytes,
+CGI, charnames, CPAN, Data::Dumper, DB_File, Devel::PPPort, Digest::MD5,
+Encode, fields, libnet, Math::BigInt, MIME::Base64, NEXT, Net::Ping,
+PerlIO::scalar, podlators, Pod::LaTeX, PodParsers, Pod::Perldoc,
+Scalar::Util, Storable, strict, Term::ANSIcolor, Test::Harness, Test::More,
+Test::Simple, Text::Balanced, Time::HiRes, threads, threads::shared,
+Unicode::Collate, Unicode::Normalize, Win32::GetFolderPath,
+Win32::GetOSVersion
+
+=back
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Platform-specific enhancements
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Closures, eval and lexicals
+
+=item Generic fixes
+
+=item Platform-specific fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=over 4
+
+=item Changed "A thread exited while %d threads were running"
+
+=item Removed "Attempt to clear a restricted hash"
+
+=item New "Illegal declaration of anonymous subroutine"
+
+=item Changed "Invalid range "%s" in transliteration operator"
+
+=item New "Missing control char name in \c"
+
+=item New "Newline in left-justified string for %s"
+
+=item New "Possible precedence problem on bitwise %c operator"
+
+=item New "Pseudo-hashes are deprecated"
+
+=item New "read() on %s filehandle %s"
+
+=item New "5.005 threads are deprecated"
+
+=item New "Tied variable freed while still in use"
+
+=item New "To%s: illegal mapping '%s'"
+
+=item New "Use of freed value in iteration"
+
+=back
+
+=item Changed Internals
+
+=item New Tests
+
+=item Known Problems
+
+=over 4
+
+=item Tied hashes in scalar context
+
+=item Net::Ping 450_service and 510_ping_udp failures
+
+=item B::C
+
+=back
+
+=item Platform Specific Problems
+
+=over 4
+
+=item EBCDIC Platforms
+
+=item Cygwin 1.5 problems
+
+=item HP-UX: HP cc warnings about sendfile and sendpath
+
+=item IRIX: t/uni/tr_7jis.t falsely failing
+
+=item Mac OS X: no usemymalloc
+
+=item Tru64: No threaded builds with GNU cc (gcc)
+
+=item Win32: sysopen, sysread, syswrite
+
+=back
+
+=item Future Directions
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=back
+
+=head2 perl58delta - what is new for perl v5.8.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Highlights In 5.8.0
+
+=item Incompatible Changes
+
+=over 4
+
+=item Binary Incompatibility
+
+=item 64-bit platforms and malloc
+
+=item AIX Dynaloading
+
+=item Attributes for C<my> variables now handled at run-time
+
+=item Socket Extension Dynamic in VMS
+
+=item IEEE-format Floating Point Default on OpenVMS Alpha
+
+=item New Unicode Semantics (no more C<use utf8>, almost)
+
+=item New Unicode Properties
+
+=item REF(...) Instead Of SCALAR(...)
+
+=item pack/unpack D/F recycled
+
+=item glob() now returns filenames in alphabetical order
+
+=item Deprecations
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Unicode Overhaul
+
+=item PerlIO is Now The Default
+
+=item ithreads
+
+=item Restricted Hashes
+
+=item Safe Signals
+
+=item Understanding of Numbers
+
+=item Arrays now always interpolate into double-quoted strings [561]
+
+=item Miscellaneous Changes
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Modules and Pragmata
+
+=item Updated And Improved Modules and Pragmata
+
+=back
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Generic Improvements
+
+=item New Or Improved Platforms
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Platform Specific Changes and Fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Security Vulnerability Closed [561]
+
+=item New Tests
+
+=item Known Problems
+
+=over 4
+
+=item The Compiler Suite Is Still Very Experimental
+
+=item Localising Tied Arrays and Hashes Is Broken
+
+=item Building Extensions Can Fail Because Of Largefiles
+
+=item Modifying $_ Inside for(..)
+
+=item mod_perl 1.26 Doesn't Build With Threaded Perl
+
+=item lib/ftmp-security tests warn 'system possibly insecure'
+
+=item libwww-perl (LWP) fails base/date #51
+
+=item PDL failing some tests
+
+=item Perl_get_sv
+
+=item Self-tying Problems
+
+=item ext/threads/t/libc
+
+=item Failure of Thread (5.005-style) tests
+
+=item Timing problems
+
+=item Tied/Magical Array/Hash Elements Do Not Autovivify
+
+=item Unicode in package/class and subroutine names does not work
+
+=back
+
+=item Platform Specific Problems
+
+=over 4
+
+=item AIX
+
+=item Alpha systems with old gccs fail several tests
+
+=item AmigaOS
+
+=item BeOS
+
+=item Cygwin "unable to remap"
+
+=item Cygwin ndbm tests fail on FAT
+
+=item DJGPP Failures
+
+=item FreeBSD built with ithreads coredumps reading large directories
+
+=item FreeBSD Failing locale Test 117 For ISO 8859-15 Locales
+
+=item IRIX fails ext/List/Util/t/shuffle.t or Digest::MD5
+
+=item HP-UX lib/posix Subtest 9 Fails When LP64-Configured
+
+=item Linux with glibc 2.2.5 fails t/op/int subtest #6 with -Duse64bitint
+
+=item Linux With Sfio Fails op/misc Test 48
+
+=item Mac OS X
+
+=item Mac OS X dyld undefined symbols
+
+=item OS/2 Test Failures
+
+=item op/sprintf tests 91, 129, and 130
+
+=item SCO
+
+=item Solaris 2.5
+
+=item Solaris x86 Fails Tests With -Duse64bitint
+
+=item SUPER-UX (NEC SX)
+
+=item Term::ReadKey not working on Win32
+
+=item UNICOS/mk
+
+=item UTS
+
+=item VOS (Stratus)
+
+=item VMS
+
+=item Win32
+
+=item XML::Parser not working
+
+=item z/OS (OS/390)
+
+=item Unicode Support on EBCDIC Still Spotty
+
+=item Seen In Perl 5.7 But Gone Now
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl573delta - what's new for perl v5.7.3
+
+=over 4
+
+=item DESCRIPTION
+
+=item Changes
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl572delta - what's new for perl v5.7.2
+
+=over 4
+
+=item DESCRIPTION
+
+=item Security Vulnerability Closed
+
+=item Incompatible Changes
+
+=over 4
+
+=item 64-bit platforms and malloc
+
+=item AIX Dynaloading
+
+=item Socket Extension Dynamic in VMS
+
+=item Different Definition of the Unicode Character Classes \p{In...}
+
+=item Deprecations
+
+=back
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Modules and Distributions
+
+=item Updated And Improved Modules and Pragmata
+
+=back
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item New Or Improved Platforms
+
+=item Generic Improvements
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Platform Specific Changes and Fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=item Source Code Enhancements
+
+=over 4
+
+=item MAGIC constants
+
+=item Better commented code
+
+=item Regex pre-/post-compilation items matched up
+
+=item gcc -Wall
+
+=back
+
+=item New Tests
+
+=item Known Problems
+
+=over 4
+
+=item AIX
+
+=item Amiga Perl Invoking Mystery
+
+=item lib/ftmp-security tests warn 'system possibly insecure'
+
+=item Cygwin intermittent failures of lib/Memoize/t/expire_file 11 and 12
+
+=item HP-UX lib/io_multihomed Fails When LP64-Configured
+
+=item HP-UX lib/posix Subtest 9 Fails When LP64-Configured
+
+=item Linux With Sfio Fails op/misc Test 48
+
+=item OS/390
+
+=item op/sprintf tests 129 and 130
+
+=item Failure of Thread tests
+
+=item UNICOS
+
+=item UTS
+
+=item VMS
+
+=item Win32
+
+=item Localising a Tied Variable Leaks Memory
+
+=item Self-tying of Arrays and Hashes Is Forbidden
+
+=item Variable Attributes are not Currently Usable for Tieing
+
+=item Building Extensions Can Fail Because Of Largefiles
+
+=item The Compiler Suite Is Still Experimental
+
+=item The Long Double Support is Still Experimental
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl571delta - what's new for perl v5.7.1
+
+=over 4
+
+=item DESCRIPTION
+
+=item Security Vulnerability Closed
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=over 4
+
+=item AUTOLOAD Is Now Lvaluable
+
+=item PerlIO is Now The Default
+
+=item Signals Are Now Safe
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Modules
+
+=item Updated And Improved Modules and Pragmata
+
+=back
+
+=item Performance Enhancements
+
+=item Utility Changes
+
+=item New Documentation
+
+=over 4
+
+=item perlclib
+
+=item perliol
+
+=item README.aix
+
+=item README.bs2000
+
+=item README.macos
+
+=item README.mpeix
+
+=item README.solaris
+
+=item README.vos
+
+=item Porting/repository.pod
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item New Or Improved Platforms
+
+=item Generic Improvements
+
+d_cmsghdr, d_fcntl_can_lock, d_fsync, d_getitimer, d_getpagsz, d_msghdr_s,
+need_va_copy, d_readv, d_recvmsg, d_sendmsg, sig_size, d_sockatmark,
+d_strtoq, d_u32align, d_ualarm, d_usleep
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Platform Specific Changes and Fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item New Tests
+
+=item Known Problems
+
+=over 4
+
+=item AIX vac 5.0.0.0 May Produce Buggy Code For Perl
+
+=item lib/ftmp-security tests warn 'system possibly insecure'
+
+=item lib/io_multihomed Fails In LP64-Configured HP-UX
+
+=item Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
+
+=item lib/b test 19
+
+=item Linux With Sfio Fails op/misc Test 48
+
+=item sigaction test 13 in VMS
+
+=item sprintf tests 129 and 130
+
+=item Failure of Thread tests
+
+=item Localising a Tied Variable Leaks Memory
+
+=item Self-tying of Arrays and Hashes Is Forbidden
+
+=item Building Extensions Can Fail Because Of Largefiles
+
+=item The Compiler Suite Is Still Experimental
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl570delta - what's new for perl v5.7.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Security Vulnerability Closed
+
+=item Incompatible Changes
+
+=item Core Enhancements
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Modules
+
+=item Updated And Improved Modules and Pragmata
+
+=back
+
+=item Utility Changes
+
+=item New Documentation
+
+=item Performance Enhancements
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item Generic Improvements
+
+=back
+
+=item Selected Bug Fixes
+
+=over 4
+
+=item Platform Specific Changes and Fixes
+
+=back
+
+=item New or Changed Diagnostics
+
+=item Changed Internals
+
+=item Known Problems
+
+=over 4
+
+=item Unicode Support Still Far From Perfect
+
+=item EBCDIC Still A Lost Platform
+
+=item Building Extensions Can Fail Because Of Largefiles
+
+=item ftmp-security tests warn 'system possibly insecure'
+
+=item Test lib/posix Subtest 9 Fails In LP64-Configured HP-UX
+
+=item Long Doubles Still Don't Work In Solaris
+
+=item Linux With Sfio Fails op/misc Test 48
+
+=item Storable tests fail in some platforms
+
+=item Threads Are Still Experimental
+
+=item The Compiler Suite Is Still Experimental
+
+=back
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl561delta - what's new for perl v5.6.x
+
+=over 4
+
+=item DESCRIPTION
+
+=item Summary of changes between 5.6.0 and 5.6.1
+
+=over 4
+
+=item Security Issues
+
+=item Core bug fixes
+
+C<UNIVERSAL::isa()>, Memory leaks, Numeric conversions, qw(a\\b), caller(),
+Bugs in regular expressions, "slurp" mode, Autovivification of symbolic
+references to special variables, Lexical warnings, Spurious warnings and
+errors, glob(), Tainting, sort(), #line directives, Subroutine prototypes,
+map(), Debugger, PERL5OPT, chop(), Unicode support, 64-bit support,
+Compiler, Lvalue subroutines, IO::Socket, File::Find, xsubpp, C<no
+Module;>, Tests
+
+=item Core features
+
+=item Configuration issues
+
+=item Documentation
+
+=item Bundled modules
+
+B::Concise, File::Temp, Pod::LaTeX, Pod::Text::Overstrike, CGI, CPAN,
+Class::Struct, DB_File, Devel::Peek, File::Find, Getopt::Long, IO::Poll,
+IPC::Open3, Math::BigFloat, Math::Complex, Net::Ping, Opcode, Pod::Parser,
+Pod::Text, SDBM_File, Sys::Syslog, Tie::RefHash, Tie::SubstrHash
+
+=item Platform-specific improvements
+
+NCR MP-RAS, NonStop-UX
+
+=back
+
+=item Core Enhancements
+
+=over 4
+
+=item Interpreter cloning, threads, and concurrency
+
+=item Lexically scoped warning categories
+
+=item Unicode and UTF-8 support
+
+=item Support for interpolating named characters
+
+=item "our" declarations
+
+=item Support for strings represented as a vector of ordinals
+
+=item Improved Perl version numbering system
+
+=item New syntax for declaring subroutine attributes
+
+=item File and directory handles can be autovivified
+
+=item open() with more than two arguments
+
+=item 64-bit support
+
+=item Large file support
+
+=item Long doubles
+
+=item "more bits"
+
+=item Enhanced support for sort() subroutines
+
+=item C<sort $coderef @foo> allowed
+
+=item File globbing implemented internally
+
+=item Support for CHECK blocks
+
+=item POSIX character class syntax [: :] supported
+
+=item Better pseudo-random number generator
+
+=item Improved C<qw//> operator
+
+=item Better worst-case behavior of hashes
+
+=item pack() format 'Z' supported
+
+=item pack() format modifier '!' supported
+
+=item pack() and unpack() support counted strings
+
+=item Comments in pack() templates
+
+=item Weak references
+
+=item Binary numbers supported
+
+=item Lvalue subroutines
+
+=item Some arrows may be omitted in calls through references
+
+=item Boolean assignment operators are legal lvalues
+
+=item exists() is supported on subroutine names
+
+=item exists() and delete() are supported on array elements
+
+=item Pseudo-hashes work better
+
+=item Automatic flushing of output buffers
+
+=item Better diagnostics on meaningless filehandle operations
+
+=item Where possible, buffered data discarded from duped input filehandle
+
+=item eof() has the same old magic as <>
+
+=item binmode() can be used to set :crlf and :raw modes
+
+=item C<-T> filetest recognizes UTF-8 encoded files as "text"
+
+=item system(), backticks and pipe open now reflect exec() failure
+
+=item Improved diagnostics
+
+=item Diagnostics follow STDERR
+
+=item More consistent close-on-exec behavior
+
+=item syswrite() ease-of-use
+
+=item Better syntax checks on parenthesized unary operators
+
+=item Bit operators support full native integer width
+
+=item Improved security features
+
+=item More functional bareword prototype (*)
+
+=item C<require> and C<do> may be overridden
+
+=item $^X variables may now have names longer than one character
+
+=item New variable $^C reflects C<-c> switch
+
+=item New variable $^V contains Perl version as a string
+
+=item Optional Y2K warnings
+
+=item Arrays now always interpolate into double-quoted strings
+
+=item @- and @+ provide starting/ending offsets of regex submatches
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Modules
+
+attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
+DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
+Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
+File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
+Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
+podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
+pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
+Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
+
+=item Pragmata
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item dprofpp
+
+=item find2perl
+
+=item h2xs
+
+=item perlcc
+
+=item perldoc
+
+=item The Perl Debugger
+
+=back
+
+=item Improved Documentation
+
+perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
+perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
+perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
+perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
+
+=item Performance enhancements
+
+=over 4
+
+=item Simple sort() using { $a <=> $b } and the like are optimized
+
+=item Optimized assignments to lexical variables
+
+=item Faster subroutine calls
+
+=item delete(), each(), values() and hash iteration are faster
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item -Dusethreads means something different
+
+=item New Configure flags
+
+=item Threadedness and 64-bitness now more daring
+
+=item Long Doubles
+
+=item -Dusemorebits
+
+=item -Duselargefiles
+
+=item installusrbinperl
+
+=item SOCKS support
+
+=item C<-A> flag
+
+=item Enhanced Installation Directories
+
+=item gcc automatically tried if 'cc' does not seem to be working
+
+=back
+
+=item Platform specific changes
+
+=over 4
+
+=item Supported platforms
+
+=item DOS
+
+=item OS390 (OpenEdition MVS)
+
+=item VMS
+
+=item Win32
+
+=back
+
+=item Significant bug fixes
+
+=over 4
+
+=item <HANDLE> on empty files
+
+=item C<eval '...'> improvements
+
+=item All compilation errors are true errors
+
+=item Implicitly closed filehandles are safer
+
+=item Behavior of list slices is more consistent
+
+=item C<(\$)> prototype and C<$foo{a}>
+
+=item C<goto &sub> and AUTOLOAD
+
+=item C<-bareword> allowed under C<use integer>
+
+=item Failures in DESTROY()
+
+=item Locale bugs fixed
+
+=item Memory leaks
+
+=item Spurious subroutine stubs after failed subroutine calls
+
+=item Taint failures under C<-U>
+
+=item END blocks and the C<-c> switch
+
+=item Potential to leak DATA filehandles
+
+=back
+
+=item New or Changed Diagnostics
+
+"%s" variable %s masks earlier declaration in same %s, "my sub" not yet
+implemented, "our" variable %s redeclared, '!' allowed only after types %s,
+/ cannot take a count, / must be followed by a, A or Z, / must be followed
+by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
+\\%c passed through, /%s/: Unrecognized escape \\%c in character class
+passed through, /%s/ should probably be written as "%s", %s() called too
+early to check prototype, %s argument is not a HASH or ARRAY element, %s
+argument is not a HASH or ARRAY element or slice, %s argument is not a
+subroutine name, %s package attribute may clash with future reserved word:
+%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled
+substitution pattern, Bad realloc() ignored, Bareword found in conditional,
+Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
+size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check
+filesystem of script "%s", Can't declare class for non-scalar %s in "%s",
+Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default,
+Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
+remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't
+weaken a nonreference, Character class [:%s:] unknown, Character class
+syntax [%s] belongs inside character classes, Constant is not %s reference,
+constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated,
+defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
+"local" instead of "our"?), Document contains no data, entering effective
+%s failed, false [] range "%s" in regexp, Filehandle %s opened only for
+output, flock() on closed filehandle %s, Global symbol "%s" requires
+explicit package name, Hexadecimal number > 0xffffffff non-portable,
+Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
+|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal
+number of bits in vec, Integer overflow in %s number, Invalid %s attribute:
+%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid
+separator character %s in attribute list, Invalid separator character %s in
+subroutine attribute list, leaving effective %s failed, Lvalue subs
+returning %s not implemented yet, Method %s not permitted, Missing
+%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub",
+No %s specified for -%c, No package name allowed for variable %s in "our",
+No space allowed after -%c, no UTC offset information; assuming local time
+is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
+panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
+around "%s" list, Possible unintended interpolation of %s in string,
+Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
+instead, Premature end of script headers, Repeat count in pack overflows,
+Repeat count in unpack overflows, realloc() of freed memory ignored,
+Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
+zero-length expression, switching effective %s is not implemented, This
+Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
+environ elements (%s=%s), Too late to run %s block, Unknown open() mode
+'%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized
+escape \\%c passed through, Unterminated attribute parameter in attribute
+list, Unterminated attribute list, Unterminated attribute parameter in
+subroutine attribute list, Unterminated subroutine attribute list, Value of
+CLI symbol "%s" too long, Version number must be a constant number
+
+=item New tests
+
+=item Incompatible Changes
+
+=over 4
+
+=item Perl Source Incompatibilities
+
+CHECK is a new keyword, Treatment of list slices of undef has changed,
+Format of $English::PERL_VERSION is different, Literals of the form
+C<1.2.3> parse differently, Possibly changed pseudo-random number
+generator, Hashing function for hash keys has changed, C<undef> fails on
+read only values, Close-on-exec bit may be set on pipe and socket handles,
+Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), each(),
+values() and C<\(%h)>, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
+Text of some diagnostic output has changed, C<%@> has been removed,
+Parenthesized not() behaves like a list operator, Semantics of bareword
+prototype C<(*)> have changed, Semantics of bit operators may have changed
+on 64-bit platforms, More builtins taint their results
+
+=item C Source Incompatibilities
+
+C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC>
+
+=item Compatible C Source API Changes
+
+C<PATCHLEVEL> is now C<PERL_VERSION>
+
+=item Binary Incompatibilities
+
+=back
+
+=item Known Problems
+
+=over 4
+
+=item Localizing a tied hash element may leak memory
+
+=item Known test failures
+
+=item EBCDIC platforms not fully supported
+
+=item UNICOS/mk CC failures during Configure run
+
+=item Arrow operator and arrays
+
+=item Experimental features
+
+Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The
+pseudo-hash data type, The Compiler suite, Internal implementation of file
+globbing, The DB module, The regular expression code constructs:
+
+=back
+
+=item Obsolete Diagnostics
+
+Character class syntax [: :] is reserved for future extensions, Ill-formed
+logical name |%s| in prime_env_iter, In string, @%s now must be written as
+\@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>"
+to mean "${$}<digit>" is deprecated
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl56delta - what's new for perl v5.6.0
+
+=over 4
+
+=item DESCRIPTION
+
+=item Core Enhancements
+
+=over 4
+
+=item Interpreter cloning, threads, and concurrency
+
+=item Lexically scoped warning categories
+
+=item Unicode and UTF-8 support
+
+=item Support for interpolating named characters
+
+=item "our" declarations
+
+=item Support for strings represented as a vector of ordinals
+
+=item Improved Perl version numbering system
+
+=item New syntax for declaring subroutine attributes
+
+=item File and directory handles can be autovivified
+
+=item open() with more than two arguments
+
+=item 64-bit support
+
+=item Large file support
+
+=item Long doubles
+
+=item "more bits"
+
+=item Enhanced support for sort() subroutines
+
+=item C<sort $coderef @foo> allowed
+
+=item File globbing implemented internally
+
+=item Support for CHECK blocks
+
+=item POSIX character class syntax [: :] supported
+
+=item Better pseudo-random number generator
+
+=item Improved C<qw//> operator
+
+=item Better worst-case behavior of hashes
+
+=item pack() format 'Z' supported
+
+=item pack() format modifier '!' supported
+
+=item pack() and unpack() support counted strings
+
+=item Comments in pack() templates
+
+=item Weak references
+
+=item Binary numbers supported
+
+=item Lvalue subroutines
+
+=item Some arrows may be omitted in calls through references
+
+=item Boolean assignment operators are legal lvalues
+
+=item exists() is supported on subroutine names
+
+=item exists() and delete() are supported on array elements
+
+=item Pseudo-hashes work better
+
+=item Automatic flushing of output buffers
+
+=item Better diagnostics on meaningless filehandle operations
+
+=item Where possible, buffered data discarded from duped input filehandle
+
+=item eof() has the same old magic as <>
+
+=item binmode() can be used to set :crlf and :raw modes
+
+=item C<-T> filetest recognizes UTF-8 encoded files as "text"
+
+=item system(), backticks and pipe open now reflect exec() failure
+
+=item Improved diagnostics
+
+=item Diagnostics follow STDERR
+
+=item More consistent close-on-exec behavior
+
+=item syswrite() ease-of-use
+
+=item Better syntax checks on parenthesized unary operators
+
+=item Bit operators support full native integer width
+
+=item Improved security features
+
+=item More functional bareword prototype (*)
+
+=item C<require> and C<do> may be overridden
+
+=item $^X variables may now have names longer than one character
+
+=item New variable $^C reflects C<-c> switch
+
+=item New variable $^V contains Perl version as a string
+
+=item Optional Y2K warnings
+
+=item Arrays now always interpolate into double-quoted strings
+
+=item @- and @+ provide starting/ending offsets of regex matches
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item Modules
+
+attributes, B, Benchmark, ByteLoader, constant, charnames, Data::Dumper,
+DB, DB_File, Devel::DProf, Devel::Peek, Dumpvalue, DynaLoader, English,
+Env, Fcntl, File::Compare, File::Find, File::Glob, File::Spec,
+File::Spec::Functions, Getopt::Long, IO, JPL, lib, Math::BigInt,
+Math::Complex, Math::Trig, Pod::Parser, Pod::InputObjects, Pod::Checker,
+podchecker, Pod::ParseUtils, Pod::Find, Pod::Select, podselect, Pod::Usage,
+pod2usage, Pod::Text and Pod::Man, SDBM_File, Sys::Syslog, Sys::Hostname,
+Term::ANSIColor, Time::Local, Win32, XSLoader, DBM Filters
+
+=item Pragmata
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item dprofpp
+
+=item find2perl
+
+=item h2xs
+
+=item perlcc
+
+=item perldoc
+
+=item The Perl Debugger
+
+=back
+
+=item Improved Documentation
+
+perlapi.pod, perlboot.pod, perlcompile.pod, perldbmfilter.pod,
+perldebug.pod, perldebguts.pod, perlfork.pod, perlfilter.pod, perlhack.pod,
+perlintern.pod, perllexwarn.pod, perlnumber.pod, perlopentut.pod,
+perlreftut.pod, perltootc.pod, perltodo.pod, perlunicode.pod
+
+=item Performance enhancements
+
+=over 4
+
+=item Simple sort() using { $a <=> $b } and the like are optimized
+
+=item Optimized assignments to lexical variables
+
+=item Faster subroutine calls
+
+=item delete(), each(), values() and hash iteration are faster
+
+=back
+
+=item Installation and Configuration Improvements
+
+=over 4
+
+=item -Dusethreads means something different
+
+=item New Configure flags
+
+=item Threadedness and 64-bitness now more daring
+
+=item Long Doubles
+
+=item -Dusemorebits
+
+=item -Duselargefiles
+
+=item installusrbinperl
+
+=item SOCKS support
+
+=item C<-A> flag
+
+=item Enhanced Installation Directories
+
+=back
+
+=item Platform specific changes
+
+=over 4
+
+=item Supported platforms
+
+=item DOS
+
+=item OS390 (OpenEdition MVS)
+
+=item VMS
+
+=item Win32
+
+=back
+
+=item Significant bug fixes
+
+=over 4
+
+=item <HANDLE> on empty files
+
+=item C<eval '...'> improvements
+
+=item All compilation errors are true errors
+
+=item Implicitly closed filehandles are safer
+
+=item Behavior of list slices is more consistent
+
+=item C<(\$)> prototype and C<$foo{a}>
+
+=item C<goto &sub> and AUTOLOAD
+
+=item C<-bareword> allowed under C<use integer>
+
+=item Failures in DESTROY()
+
+=item Locale bugs fixed
+
+=item Memory leaks
+
+=item Spurious subroutine stubs after failed subroutine calls
+
+=item Taint failures under C<-U>
+
+=item END blocks and the C<-c> switch
+
+=item Potential to leak DATA filehandles
+
+=back
+
+=item New or Changed Diagnostics
+
+"%s" variable %s masks earlier declaration in same %s, "my sub" not yet
+implemented, "our" variable %s redeclared, '!' allowed only after types %s,
+/ cannot take a count, / must be followed by a, A or Z, / must be followed
+by a*, A* or Z*, / must follow a numeric type, /%s/: Unrecognized escape
+\\%c passed through, /%s/: Unrecognized escape \\%c in character class
+passed through, /%s/ should probably be written as "%s", %s() called too
+early to check prototype, %s argument is not a HASH or ARRAY element, %s
+argument is not a HASH or ARRAY element or slice, %s argument is not a
+subroutine name, %s package attribute may clash with future reserved word:
+%s, (in cleanup) %s, <> should be quotes, Attempt to join self, Bad evalled
+substitution pattern, Bad realloc() ignored, Bareword found in conditional,
+Binary number > 0b11111111111111111111111111111111 non-portable, Bit vector
+size > 32 non-portable, Buffer overflow in prime_env_iter: %s, Can't check
+filesystem of script "%s", Can't declare class for non-scalar %s in "%s",
+Can't declare %s in "%s", Can't ignore signal CHLD, forcing to default,
+Can't modify non-lvalue subroutine call, Can't read CRTL environ, Can't
+remove %s: %s, skipping file, Can't return %s from lvalue subroutine, Can't
+weaken a nonreference, Character class [:%s:] unknown, Character class
+syntax [%s] belongs inside character classes, Constant is not %s reference,
+constant(%s): %s, CORE::%s is not a keyword, defined(@array) is deprecated,
+defined(%hash) is deprecated, Did not produce a valid header, (Did you mean
+"local" instead of "our"?), Document contains no data, entering effective
+%s failed, false [] range "%s" in regexp, Filehandle %s opened only for
+output, flock() on closed filehandle %s, Global symbol "%s" requires
+explicit package name, Hexadecimal number > 0xffffffff non-portable,
+Ill-formed CRTL environ value "%s", Ill-formed message in prime_env_iter:
+|%s|, Illegal binary digit %s, Illegal binary digit %s ignored, Illegal
+number of bits in vec, Integer overflow in %s number, Invalid %s attribute:
+%s, Invalid %s attributes: %s, invalid [] range "%s" in regexp, Invalid
+separator character %s in attribute list, Invalid separator character %s in
+subroutine attribute list, leaving effective %s failed, Lvalue subs
+returning %s not implemented yet, Method %s not permitted, Missing
+%sbrace%s on \N{}, Missing command in piped open, Missing name in "my sub",
+No %s specified for -%c, No package name allowed for variable %s in "our",
+No space allowed after -%c, no UTC offset information; assuming local time
+is UTC, Octal number > 037777777777 non-portable, panic: del_backref,
+panic: kid popen errno read, panic: magic_killbackrefs, Parentheses missing
+around "%s" list, Possible unintended interpolation of %s in string,
+Possible Y2K bug: %s, pragma "attrs" is deprecated, use "sub NAME : ATTRS"
+instead, Premature end of script headers, Repeat count in pack overflows,
+Repeat count in unpack overflows, realloc() of freed memory ignored,
+Reference is already weak, setpgrp can't take arguments, Strange *+?{} on
+zero-length expression, switching effective %s is not implemented, This
+Perl can't reset CRTL environ elements (%s), This Perl can't set CRTL
+environ elements (%s=%s), Too late to run %s block, Unknown open() mode
+'%s', Unknown process %x sent message to prime_env_iter: %s, Unrecognized
+escape \\%c passed through, Unterminated attribute parameter in attribute
+list, Unterminated attribute list, Unterminated attribute parameter in
+subroutine attribute list, Unterminated subroutine attribute list, Value of
+CLI symbol "%s" too long, Version number must be a constant number
+
+=item New tests
+
+=item Incompatible Changes
+
+=over 4
+
+=item Perl Source Incompatibilities
+
+CHECK is a new keyword, Treatment of list slices of undef has changed,
+Format of $English::PERL_VERSION is different, Literals of the form
+C<1.2.3> parse differently, Possibly changed pseudo-random number
+generator, Hashing function for hash keys has changed, C<undef> fails on
+read only values, Close-on-exec bit may be set on pipe and socket handles,
+Writing C<"$$1"> to mean C<"${$}1"> is unsupported, delete(), each(),
+values() and C<\(%h)>, vec(EXPR,OFFSET,BITS) enforces powers-of-two BITS,
+Text of some diagnostic output has changed, C<%@> has been removed,
+Parenthesized not() behaves like a list operator, Semantics of bareword
+prototype C<(*)> have changed, Semantics of bit operators may have changed
+on 64-bit platforms, More builtins taint their results
+
+=item C Source Incompatibilities
+
+C<PERL_POLLUTE>, C<PERL_IMPLICIT_CONTEXT>, C<PERL_POLLUTE_MALLOC>
+
+=item Compatible C Source API Changes
+
+C<PATCHLEVEL> is now C<PERL_VERSION>
+
+=item Binary Incompatibilities
+
+=back
+
+=item Known Problems
+
+=over 4
+
+=item Thread test failures
+
+=item EBCDIC platforms not supported
+
+=item In 64-bit HP-UX the lib/io_multihomed test may hang
+
+=item NEXTSTEP 3.3 POSIX test failure
+
+=item Tru64 (aka Digital UNIX, aka DEC OSF/1) lib/sdbm test failure with
+gcc
+
+=item UNICOS/mk CC failures during Configure run
+
+=item Arrow operator and arrays
+
+=item Experimental features
+
+Threads, Unicode, 64-bit support, Lvalue subroutines, Weak references, The
+pseudo-hash data type, The Compiler suite, Internal implementation of file
+globbing, The DB module, The regular expression code constructs:
+
+=back
+
+=item Obsolete Diagnostics
+
+Character class syntax [: :] is reserved for future extensions, Ill-formed
+logical name |%s| in prime_env_iter, In string, @%s now must be written as
+\@%s, Probable precedence problem on %s, regexp too big, Use of "$$<digit>"
+to mean "${$}<digit>" is deprecated
+
+=item Reporting Bugs
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl5005delta - what's new for perl5.005
+
+=over 4
+
+=item DESCRIPTION
+
+=item About the new versioning system
+
+=item Incompatible Changes
+
+=over 4
+
+=item WARNING: This version is not binary compatible with Perl 5.004.
+
+=item Default installation structure has changed
+
+=item Perl Source Compatibility
+
+=item C Source Compatibility
+
+=item Binary Compatibility
+
+=item Security fixes may affect compatibility
+
+=item Relaxed new mandatory warnings introduced in 5.004
+
+=item Licensing
+
+=back
+
+=item Core Changes
+
+=over 4
+
+=item Threads
+
+=item Compiler
+
+=item Regular Expressions
+
+Many new and improved optimizations, Many bug fixes, New regular expression
+constructs, New operator for precompiled regular expressions, Other
+improvements, Incompatible changes
+
+=item Improved malloc()
+
+=item Quicksort is internally implemented
+
+=item Reliable signals
+
+=item Reliable stack pointers
+
+=item More generous treatment of carriage returns
+
+=item Memory leaks
+
+=item Better support for multiple interpreters
+
+=item Behavior of local() on array and hash elements is now well-defined
+
+=item C<%!> is transparently tied to the L<Errno> module
+
+=item Pseudo-hashes are supported
+
+=item C<EXPR foreach EXPR> is supported
+
+=item Keywords can be globally overridden
+
+=item C<$^E> is meaningful on Win32
+
+=item C<foreach (1..1000000)> optimized
+
+=item C<Foo::> can be used as implicitly quoted package name
+
+=item C<exists $Foo::{Bar::}> tests existence of a package
+
+=item Better locale support
+
+=item Experimental support for 64-bit platforms
+
+=item prototype() returns useful results on builtins
+
+=item Extended support for exception handling
+
+=item Re-blessing in DESTROY() supported for chaining DESTROY() methods
+
+=item All C<printf> format conversions are handled internally
+
+=item New C<INIT> keyword
+
+=item New C<lock> keyword
+
+=item New C<qr//> operator
+
+=item C<our> is now a reserved word
+
+=item Tied arrays are now fully supported
+
+=item Tied handles support is better
+
+=item 4th argument to substr
+
+=item Negative LENGTH argument to splice
+
+=item Magic lvalues are now more magical
+
+=item <> now reads in records
+
+=back
+
+=item Supported Platforms
+
+=over 4
+
+=item New Platforms
+
+=item Changes in existing support
+
+=back
+
+=item Modules and Pragmata
+
+=over 4
+
+=item New Modules
+
+B, Data::Dumper, Dumpvalue, Errno, File::Spec, ExtUtils::Installed,
+ExtUtils::Packlist, Fatal, IPC::SysV, Test, Tie::Array, Tie::Handle,
+Thread, attrs, fields, re
+
+=item Changes in existing modules
+
+Benchmark, Carp, CGI, Fcntl, Math::Complex, Math::Trig, POSIX, DB_File,
+MakeMaker, CPAN, Cwd
+
+=back
+
+=item Utility Changes
+
+=item Documentation Changes
+
+=item New Diagnostics
+
+Ambiguous call resolved as CORE::%s(), qualify as such or use &, Bad index
+while coercing array into hash, Bareword "%s" refers to nonexistent
+package, Can't call method "%s" on an undefined value, Can't check
+filesystem of script "%s" for nosuid, Can't coerce array into hash, Can't
+goto subroutine from an eval-string, Can't localize pseudo-hash element,
+Can't use %%! because Errno.pm is not available, Cannot find an opnumber
+for "%s", Character class syntax [. .] is reserved for future extensions,
+Character class syntax [: :] is reserved for future extensions, Character
+class syntax [= =] is reserved for future extensions, %s: Eval-group in
+insecure regular expression, %s: Eval-group not allowed, use re 'eval', %s:
+Eval-group not allowed at run time, Explicit blessing to '' (assuming
+package main), Illegal hex digit ignored, No such array field, No such
+field "%s" in variable %s of type %s, Out of memory during ridiculously
+large request, Range iterator outside integer range, Recursive inheritance
+detected while looking for method '%s' %s, Reference found where even-sized
+list expected, Undefined value assigned to typeglob, Use of reserved word
+"%s" is deprecated, perl: warning: Setting locale failed
+
+=item Obsolete Diagnostics
+
+Can't mktemp(), Can't write to temp file for B<-e>: %s, Cannot open
+temporary file, regexp too big
+
+=item Configuration Changes
+
+=item BUGS
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perl5004delta - what's new for perl5.004
+
+=over 4
+
+=item DESCRIPTION
+
+=item Supported Environments
+
+=item Core Changes
+
+=over 4
+
+=item List assignment to %ENV works
+
+=item Change to "Can't locate Foo.pm in @INC" error
+
+=item Compilation option: Binary compatibility with 5.003
+
+=item $PERL5OPT environment variable
+
+=item Limitations on B<-M>, B<-m>, and B<-T> options
+
+=item More precise warnings
+
+=item Deprecated: Inherited C<AUTOLOAD> for non-methods
+
+=item Previously deprecated %OVERLOAD is no longer usable
+
+=item Subroutine arguments created only when they're modified
+
+=item Group vector changeable with C<$)>
+
+=item Fixed parsing of $$<digit>, &$<digit>, etc.
+
+=item Fixed localization of $<digit>, $&, etc.
+
+=item No resetting of $. on implicit close
+
+=item C<wantarray> may return undef
+
+=item C<eval EXPR> determines value of EXPR in scalar context
+
+=item Changes to tainting checks
+
+No glob() or <*>, No spawning if tainted $CDPATH, $ENV, $BASH_ENV, No
+spawning if tainted $TERM doesn't look like a terminal name
+
+=item New Opcode module and revised Safe module
+
+=item Embedding improvements
+
+=item Internal change: FileHandle class based on IO::* classes
+
+=item Internal change: PerlIO abstraction interface
+
+=item New and changed syntax
+
+$coderef->(PARAMS)
+
+=item New and changed builtin constants
+
+__PACKAGE__
+
+=item New and changed builtin variables
+
+$^E, $^H, $^M
+
+=item New and changed builtin functions
+
+delete on slices, flock, printf and sprintf, keys as an lvalue, my() in
+Control Structures, pack() and unpack(), sysseek(), use VERSION, use Module
+VERSION LIST, prototype(FUNCTION), srand, $_ as Default, C<m//gc> does not
+reset search position on failure, C<m//x> ignores whitespace before ?*+{},
+nested C<sub{}> closures work now, formats work right on changing lexicals
+
+=item New builtin methods
+
+isa(CLASS), can(METHOD), VERSION( [NEED] )
+
+=item TIEHANDLE now supported
+
+TIEHANDLE classname, LIST, PRINT this, LIST, PRINTF this, LIST, READ this
+LIST, READLINE this, GETC this, DESTROY this
+
+=item Malloc enhancements
+
+-DPERL_EMERGENCY_SBRK, -DPACK_MALLOC, -DTWO_POT_OPTIMIZE
+
+=item Miscellaneous efficiency enhancements
+
+=back
+
+=item Support for More Operating Systems
+
+=over 4
+
+=item Win32
+
+=item Plan 9
+
+=item QNX
+
+=item AmigaOS
+
+=back
+
+=item Pragmata
+
+use autouse MODULE => qw(sub1 sub2 sub3), use blib, use blib 'dir', use
+constant NAME => VALUE, use locale, use ops, use vmsish
+
+=item Modules
+
+=over 4
+
+=item Required Updates
+
+=item Installation directories
+
+=item Module information summary
+
+=item Fcntl
+
+=item IO
+
+=item Math::Complex
+
+=item Math::Trig
+
+=item DB_File
+
+=item Net::Ping
+
+=item Object-oriented overrides for builtin operators
+
+=back
+
+=item Utility Changes
+
+=over 4
+
+=item pod2html
+
+Sends converted HTML to standard output
+
+=item xsubpp
+
+C<void> XSUBs now default to returning nothing
+
+=back
+
+=item C Language API Changes
+
+C<gv_fetchmethod> and C<perl_call_sv>, C<perl_eval_pv>, Extended API for
+manipulating hashes
+
+=item Documentation Changes
+
+L<perldelta>, L<perlfaq>, L<perllocale>, L<perltoot>, L<perlapio>,
+L<perlmodlib>, L<perldebug>, L<perlsec>
+
+=item New Diagnostics
+
+"my" variable %s masks earlier declaration in same scope, %s argument is
+not a HASH element or slice, Allocation too large: %lx, Allocation too
+large, Applying %s to %s will act on scalar(%s), Attempt to free
+nonexistent shared string, Attempt to use reference as lvalue in substr,
+Bareword "%s" refers to nonexistent package, Can't redefine active sort
+subroutine %s, Can't use bareword ("%s") as %s ref while "strict refs" in
+use, Cannot resolve method `%s' overloading `%s' in package `%s', Constant
+subroutine %s redefined, Constant subroutine %s undefined, Copy method did
+not return a reference, Died, Exiting pseudo-block via %s, Identifier too
+long, Illegal character %s (carriage return), Illegal switch in PERL5OPT:
+%s, Integer overflow in hex number, Integer overflow in octal number,
+internal error: glob failed, Invalid conversion in %s: "%s", Invalid type
+in pack: '%s', Invalid type in unpack: '%s', Name "%s::%s" used only once:
+possible typo, Null picture in formline, Offset outside string, Out of
+memory!, Out of memory during request for %s, panic: frexp, Possible
+attempt to put comments in qw() list, Possible attempt to separate words
+with commas, Scalar value @%s{%s} better written as $%s{%s}, Stub found
+while resolving method `%s' overloading `%s' in %s, Too late for "B<-T>"
+option, untie attempted while %d inner references still exist, Unrecognized
+character %s, Unsupported function fork, Use of "$$<digit>" to mean
+"${$}<digit>" is deprecated, Value of %s can be "0"; test with defined(),
+Variable "%s" may be unavailable, Variable "%s" will not stay shared,
+Warning: something's wrong, Ill-formed logical name |%s| in prime_env_iter,
+Got an error from DosAllocMem, Malformed PERLLIB_PREFIX, PERL_SH_DIR too
+long, Process terminated by SIG%s
+
+=item BUGS
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 perlartistic - the Perl Artistic License
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item The "Artistic License"
+
+=over 4
+
+=item Preamble
+
+=item Definitions
+
+"Package", "Standard Version", "Copyright Holder", "You", "Reasonable
+copying fee", "Freely Available"
+
+=item Conditions
+
+a), b), c), d), a), b), c), d)
+
+=back
+
+=back
+
+=head2 perlgpl - the GNU General Public License, version 2
+
+=over 4
+
+=item SYNOPSIS
+
+=back
+
+=over 4
+
+=item DESCRIPTION
+
+=item GNU GENERAL PUBLIC LICENSE
+
+=back
+
+=head2 perlaix, README.aix - Perl version 5 on IBM Unix (AIX) systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Compiling Perl 5 on AIX
+
+=item OS level
+
+=item Building Dynamic Extensions on AIX
+
+=item The IBM ANSI C Compiler
+
+=item The usenm option
+
+=item Using GNU's gcc for building perl
+
+=item Using Large Files with Perl
+
+=item Threaded Perl
+
+=item 64-bit Perl
+
+=item AIX 4.2 and extensions using C++ with statics
+
+=back
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlamiga - Perl under Amiga OS
+
+=over 4
+
+=item NOTE
+
+=item SYNOPSIS
+
+=back
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Prerequisites for Compiling Perl on AmigaOS
+
+B<Unix emulation for AmigaOS: ixemul.library>, B<Version of Amiga OS>
+
+=item Starting Perl programs under AmigaOS
+
+=item Shortcomings of Perl under AmigaOS
+
+=back
+
+=item INSTALLATION
+
+=item Accessing documentation
+
+=over 4
+
+=item Manpages for Perl on AmigaOS
+
+=item Perl HTML Documentation on AmigaOS
+
+=item Perl GNU Info Files on AmigaOS
+
+=item Perl LaTeX Documentation on AmigaOS
+
+=back
+
+=item BUILDING PERL ON AMIGAOS
+
+=over 4
+
+=item Build Prerequisites for Perl on AmigaOS
+
+=item Getting the Perl Source for AmigaOS
+
+=item Making Perl on AmigaOS
+
+=item Testing Perl on AmigaOS
+
+=item Installing the built Perl on AmigaOS
+
+=back
+
+=item PERL 5.8.0 BROKEN IN AMIGAOS
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 perlapollo, README.apollo - Perl version 5 on Apollo DomainOS
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=back
+
+=head2 perlbeos, README.beos - Perl version 5.8+ on BeOS
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUILD AND INSTALL
+
+=over 4
+
+=item Requirements
+
+=item Configure
+
+=item Build
+
+=item Install
+
+=back
+
+=item KNOWN PROBLEMS
+
+=item CONTACT
+
+=back
+
+=head2 perlbs2000, README.BS2000 - building and installing Perl for BS2000.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item gzip on BS2000
+
+=item bison on BS2000
+
+=item Unpacking Perl Distribution on BS2000
+
+=item Compiling Perl on BS2000
+
+=item Testing Perl on BS2000
+
+=item Installing Perl on BS2000
+
+=item Using Perl in the Posix-Shell of BS2000
+
+=item Using Perl in "native" BS2000
+
+=item Floating point anomalies on BS2000
+
+=item Using PerlIO and different encodings on ASCII and EBCDIC partitions
+
+=back
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=over 4
+
+=item Mailing list
+
+=back
+
+=item HISTORY
+
+=back
+
+=head2 perlce - Perl for WinCE
+
+=over 4
+
+=item Building Perl for WinCE
+
+=over 4
+
+=item DESCRIPTION
+
+=item General explanations on cross-compiling WinCE
+
+=item BUILD
+
+Microsoft Embedded Visual Tools, Microsoft Visual C++, Rainer Keuchel's
+celib-sources, Rainer Keuchel's console-sources, go to C<./win32>
+subdirectory, edit file C<./win32/ce-helpers/compile.bat>, run
+compile.bat, run compile.bat dist
+
+=back
+
+=item Using Perl on WinCE
+
+=over 4
+
+=item DESCRIPTION
+
+=item LIMITATIONS
+
+=item ENVIRONMENT
+
+PERL5LIB, PATH, TMP, UNIXROOTPATH, ROWS/COLS, HOME, CONSOLEFONTSIZE
+
+=item REGISTRY
+
+=item XS
+
+=item BUGS
+
+=item INSTALLATION
+
+=back
+
+=item ACKNOWLEDGEMENTS
+
+=item History of WinCE port
+
+=item AUTHORS
+
+Rainer Keuchel <coyxc at rainer-keuchel.de>, Vadim Konovalov
+
+=back
+
+=head2 perlcygwin, README.cygwin - Perl for Cygwin
+
+=over 4
+
+=item SYNOPSIS
+
+=item PREREQUISITES FOR COMPILING PERL ON CYGWIN
+
+=over 4
+
+=item Cygwin = GNU+Cygnus+Windows (Don't leave UNIX without it)
+
+=item Cygwin Configuration
+
+C<PATH>, I<nroff>, Permissions
+
+=back
+
+=item CONFIGURE PERL ON CYGWIN
+
+=over 4
+
+=item Stripping Perl Binaries on Cygwin
+
+=item Optional Libraries for Perl on Cygwin
+
+C<-lcrypt>, C<-lgdbm_compat> (C<use GDBM_File>), C<-ldb> (C<use DB_File>),
+C<cygserver> (C<use IPC::SysV>), C<-lutil>
+
+=item Configure-time Options for Perl on Cygwin
+
+C<-Uusedl>, C<-Uusemymalloc>, C<-Uuseperlio>, C<-Dusemultiplicity>,
+C<-Duse64bitint>, C<-Duselongdouble>, C<-Dusethreads>, C<-Duselargefiles>,
+C<-Dmksymlinks>
+
+=item Suspicious Warnings on Cygwin
+
+Win9x and C<d_eofnblk>, Compiler/Preprocessor defines
+
+=back
+
+=item MAKE ON CYGWIN
+
+=item TEST ON CYGWIN
+
+=over 4
+
+=item File Permissions on Cygwin
+
+=item NDBM_File and ODBM_File do not work on FAT filesystems
+
+=item C<fork()> failures in io_* tests
+
+=back
+
+=item Specific features of the Cygwin port
+
+=over 4
+
+=item Script Portability on Cygwin
+
+Pathnames, Text/Binary, PerlIO, F<.exe>, Cygwin vs. Windows process ids,
+Cygwin vs. Windows errors, C<chown()>, Miscellaneous
+
+=item Prebuilt methods:
+
+C<Cwd::cwd>, C<Cygwin::pid_to_winpid>, C<Cygwin::winpid_to_pid>,
+C<Cygwin::win_to_posix_path>, C<Cygwin::posix_to_win_path>,
+C<Cygwin::mount_table()>, C<Cygwin::mount_flags>, C<Cygwin::is_binmount>
+
+=back
+
+=item INSTALL PERL ON CYGWIN
+
+=item MANIFEST ON CYGWIN
+
+Documentation, Build, Configure, Make, Install, Tests, Compiled Perl
+Source, Compiled Module Source, Perl Modules/Scripts, Perl Module Tests
+
+=item BUGS ON CYGWIN
+
+=item AUTHORS
+
+=item HISTORY
+
+=back
+
+=head2 perldgux - Perl under DG/UX.
+
+=over 4
+
+=item SYNOPSIS
+
+=back
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUILDING PERL ON DG/UX
+
+=over 4
+
+=item Non-threaded Perl on DG/UX
+
+=item Threaded Perl on DG/UX
+
+=item Testing Perl on DG/UX
+
+=item Installing the built perl on DG/UX
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perldos - Perl under DOS, W31, W95.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Prerequisites for Compiling Perl on DOS
+
+DJGPP, Pthreads
+
+=item Shortcomings of Perl under DOS
+
+=item Building Perl on DOS
+
+=item Testing Perl on DOS
+
+=item Installation of Perl on DOS
+
+=back
+
+=item BUILDING AND INSTALLING MODULES ON DOS
+
+=over 4
+
+=item Building Prerequisites for Perl on DOS
+
+=item Unpacking CPAN Modules on DOS
+
+=item Building Non-XS Modules on DOS
+
+=item Building XS Modules on DOS
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlepoc, README.epoc - Perl for EPOC
+
+=over 4
+
+=item SYNOPSIS
+
+=item INTRODUCTION
+
+=item INSTALLING PERL ON EPOC
+
+=item STARTING PERL ON EPOC
+
+=over 4
+
+=item Editors on Epoc
+
+=item Features of Perl on Epoc
+
+=item Restrictions of Perl on Epoc
+
+=item Compiling Perl 5 on the EPOC cross compiling environment
+
+=back
+
+=item SUPPORT STATUS OF PERL ON EPOC
+
+=item AUTHOR
+
+=item LAST UPDATE
+
+=back
+
+=head2 perlfreebsd, README.freebsd - Perl version 5 on FreeBSD systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item FreeBSD core dumps from readdir_r with ithreads
+
+=item $^X doesn't always contain a full path in FreeBSD
+
+=item Perl will no longer be part of "base FreeBSD"
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlhpux, README.hpux - Perl version 5 on Hewlett-Packard Unix
+(HP-UX) systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Using perl as shipped with HP-UX
+
+=item Using perl from HP's porting centre
+
+=item Compiling Perl 5 on HP-UX
+
+=item PA-RISC
+
+=item Portability Between PA-RISC Versions
+
+=item PA-RISC 1.0
+
+=item PA-RISC 1.1
+
+=item PA-RISC 2.0
+
+=item Itanium Processor Family (IPF) and HP-UX
+
+=item Itanium, Itanium 2 & Madison 6
+
+=item Building Dynamic Extensions on HP-UX
+
+=item The HP ANSI C Compiler
+
+=item The GNU C Compiler
+
+=item Using Large Files with Perl on HP-UX
+
+=item Threaded Perl on HP-UX
+
+=item 64-bit Perl on HP-UX
+
+=item Oracle on HP-UX
+
+=item GDBM and Threads on HP-UX
+
+=item NFS filesystems and utime(2) on HP-UX
+
+=item perl -P and // and HP-UX
+
+=item HP-UX Kernel Parameters (maxdsiz) for Compiling Perl
+
+=back
+
+=item nss_delete core dump from op/pwent or op/grent
+
+=item Miscellaneous
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlhurd, README.hurd - Perl version 5 on Hurd
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Known Problems with Perl on Hurd
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlirix, README.irix - Perl version 5 on Irix systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Building 32-bit Perl in Irix
+
+=item Building 64-bit Perl in Irix
+
+=item About Compiler Versions of Irix
+
+=item Linker Problems in Irix
+
+=item Malloc in Irix
+
+=item Building with threads in Irix
+
+=item Irix 5.3
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perllinux, README.linux - Perl version 5 on Linux systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Experimental Support for Sun Studio Compilers for Linux OS
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlmachten, README.machten - Perl version 5 on Power MachTen
+systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Perl version 5.8.x and greater not supported
+
+=item Compiling Perl 5.6.x on MachTen
+
+=item Failures during C<make test> on MachTen
+
+op/lexassign.t, pragma/warnings.t
+
+=item Building external modules on MachTen
+
+=back
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlmacos, README.macos - Perl under Mac OS (Classic)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlmacosx, README.macosx - Perl under Mac OS X
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Installation Prefix
+
+=item SDK support
+
+=item Universal Binary support
+
+=item 64-bit PPC support
+
+=item libperl and Prebinding
+
+=item Updating Apple's Perl
+
+=item Known problems
+
+=item MacPerl
+
+=item Carbon
+
+=item Cocoa
+
+=back
+
+=item Starting From Scratch
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 perlmint, README.mint - Perl version 5 on Atari MiNT
+
+=over 4
+
+=item DESCRIPTION
+
+=item Known problems with Perl on MiNT
+
+=item AUTHOR
+
+=back
+
+=head2 perlmpeix, README.mpeix - Perl/iX for HP e3000 MPE
+
+=over 4
+
+=item SYNOPSIS
+
+=item NOTE
+
+=item Binary distribution from HP
+
+=item What's New in Perl for MPE/iX
+
+=item Welcome to Perl/iX
+
+=item System Requirements for Perl/iX
+
+=item How to Obtain Perl/iX
+
+=item Perl/iX Distribution Contents Highlights
+
+README, INSTALL, LIBSHP3K, PERL, .cpan/, lib/, man/,
+public_html/feedback.cgi, src/perl-5.6.0-mpe
+
+=item How to Compile Perl/iX
+
+ 4, 6
+
+=item Getting Started with Perl/iX
+
+=item MPE/iX Implementation Considerations
+
+=item Known Perl/iX Bugs Under Investigation
+
+=item Perl/iX To-Do List
+
+=item Perl/iX Change History
+
+=item AUTHOR
+
+=back
+
+=head2 perlnetware - Perl for NetWare
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUILD
+
+=over 4
+
+=item Tools & SDK
+
+=item Setup
+
+SetNWBld.bat, Buildtype.bat
+
+=item Make
+
+=item Interpreter
+
+=item Extensions
+
+=back
+
+=item INSTALL
+
+=item BUILD NEW EXTENSIONS
+
+=item ACKNOWLEDGEMENTS
+
+=item AUTHORS
+
+=item DATE
+
+=back
+
+=head2 perlopenbsd, README.openbsd - Perl version 5 on OpenBSD systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item OpenBSD core dumps from getprotobyname_r and getservbyname_r with
+ithreads
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlos2 - Perl under OS/2, DOS, Win0.3*, Win0.95 and WinNT.
+
+=over 4
+
+=item SYNOPSIS
+
+=back
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Target
+
+=item Other OSes
+
+=item Prerequisites
+
+EMX, RSX, HPFS, pdksh
+
+=item Starting Perl programs under OS/2 (and DOS and...)
+
+=item Starting OS/2 (and DOS) programs under Perl
+
+=back
+
+=item Frequently asked questions
+
+=over 4
+
+=item "It does not work"
+
+=item I cannot run external programs
+
+=item I cannot embed perl into my program, or use F<perl.dll> from my
+program.
+
+Is your program EMX-compiled with C<-Zmt -Zcrtdll>?, Did you use
+L<ExtUtils::Embed>?
+
+=item C<``> and pipe-C<open> do not work under DOS.
+
+=item Cannot start C<find.exe "pattern" file>
+
+=back
+
+=item INSTALLATION
+
+=over 4
+
+=item Automatic binary installation
+
+C<PERL_BADLANG>, C<PERL_BADFREE>, F<Config.pm>
+
+=item Manual binary installation
+
+Perl VIO and PM executables (dynamically linked), Perl_ VIO executable
+(statically linked), Executables for Perl utilities, Main Perl library,
+Additional Perl modules, Tools to compile Perl modules, Manpages for Perl
+and utilities, Manpages for Perl modules, Source for Perl documentation,
+Perl manual in F<.INF> format, Pdksh
+
+=item B<Warning>
+
+=back
+
+=item Accessing documentation
+
+=over 4
+
+=item OS/2 F<.INF> file
+
+=item Plain text
+
+=item Manpages
+
+=item HTML
+
+=item GNU C<info> files
+
+=item F<PDF> files
+
+=item C<LaTeX> docs
+
+=back
+
+=item BUILD
+
+=over 4
+
+=item The short story
+
+=item Prerequisites
+
+=item Getting perl source
+
+=item Application of the patches
+
+=item Hand-editing
+
+=item Making
+
+=item Testing
+
+A lot of C<bad free>, Process terminated by SIGTERM/SIGINT, F<op/fs.t>,
+F<op/stat.t>
+
+=item Installing the built perl
+
+=item C<a.out>-style build
+
+=back
+
+=item Building a binary distribution
+
+=item Building custom F<.EXE> files
+
+=over 4
+
+=item Making executables with a custom collection of statically loaded
+extensions
+
+=item Making executables with a custom search-paths
+
+=back
+
+=item Build FAQ
+
+=over 4
+
+=item Some C</> became C<\> in pdksh.
+
+=item C<'errno'> - unresolved external
+
+=item Problems with tr or sed
+
+=item Some problem (forget which ;-)
+
+=item Library ... not found
+
+=item Segfault in make
+
+=item op/sprintf test failure
+
+=back
+
+=item Specific (mis)features of OS/2 port
+
+=over 4
+
+=item C<setpriority>, C<getpriority>
+
+=item C<system()>
+
+=item C<extproc> on the first line
+
+=item Additional modules:
+
+=item Prebuilt methods:
+
+C<File::Copy::syscopy>, C<DynaLoader::mod2fname>, C<Cwd::current_drive()>,
+ C<Cwd::sys_chdir(name)>, C<Cwd::change_drive(name)>,
+C<Cwd::sys_is_absolute(name)>, C<Cwd::sys_is_rooted(name)>,
+C<Cwd::sys_is_relative(name)>, C<Cwd::sys_cwd(name)>,
+C<Cwd::sys_abspath(name, dir)>, C<Cwd::extLibpath([type])>,
+C<Cwd::extLibpath_set( path [, type ] )>,
+C<OS2::Error(do_harderror,do_exception)>, C<OS2::Errors2Drive(drive)>,
+OS2::SysInfo(), OS2::BootDrive(), C<OS2::MorphPM(serve)>,
+C<OS2::UnMorphPM(serve)>, C<OS2::Serve_Messages(force)>,
+C<OS2::Process_Messages(force [, cnt])>, C<OS2::_control87(new,mask)>,
+OS2::get_control87(), C<OS2::set_control87_em(new=MCW_EM,mask=MCW_EM)>,
+C<OS2::DLLname([how [, \&xsub]])>
+
+=item Prebuilt variables:
+
+$OS2::emx_rev, $OS2::emx_env, $OS2::os_ver, $OS2::is_aout, $OS2::can_fork,
+$OS2::nsyserror
+
+=item Misfeatures
+
+=item Modifications
+
+C<popen>, C<tmpnam>, C<tmpfile>, C<ctermid>, C<stat>, C<mkdir>, C<rmdir>,
+C<flock>
+
+=item Identifying DLLs
+
+=item Centralized management of resources
+
+C<HAB>, C<HMQ>, Treating errors reported by OS/2 API,
+C<CheckOSError(expr)>, C<CheckWinError(expr)>, C<SaveWinError(expr)>,
+C<SaveCroakWinError(expr,die,name1,name2)>, C<WinError_2_Perl_rc>,
+C<FillWinError>, C<FillOSError(rc)>, Loading DLLs and ordinals in DLLs
+
+=back
+
+=item Perl flavors
+
+=over 4
+
+=item F<perl.exe>
+
+=item F<perl_.exe>
+
+=item F<perl__.exe>
+
+=item F<perl___.exe>
+
+=item Why strange names?
+
+=item Why dynamic linking?
+
+=item Why chimera build?
+
+=back
+
+=item ENVIRONMENT
+
+=over 4
+
+=item C<PERLLIB_PREFIX>
+
+=item C<PERL_BADLANG>
+
+=item C<PERL_BADFREE>
+
+=item C<PERL_SH_DIR>
+
+=item C<USE_PERL_FLOCK>
+
+=item C<TMP> or C<TEMP>
+
+=back
+
+=item Evolution
+
+=over 4
+
+=item Text-mode filehandles
+
+=item Priorities
+
+=item DLL name mangling: pre 5.6.2
+
+=item DLL name mangling: 5.6.2 and beyond
+
+Global DLLs, specific DLLs, C<BEGINLIBPATH> and C<ENDLIBPATH>, F<.> from
+C<LIBPATH>
+
+=item DLL forwarder generation
+
+=item Threading
+
+=item Calls to external programs
+
+=item Memory allocation
+
+=item Threads
+
+C<COND_WAIT>, F<os2.c>
+
+=back
+
+=item BUGS
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 perlos390, README.os390 - building and installing Perl for OS/390
+and z/OS
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Tools
+
+=item Unpacking Perl distribution on OS/390
+
+=item Setup and utilities for Perl on OS/390
+
+=item Configure Perl on OS/390
+
+=item Build, Test, Install Perl on OS/390
+
+=item Build Anomalies with Perl on OS/390
+
+=item Testing Anomalies with Perl on OS/390
+
+=item Installation Anomalies with Perl on OS/390
+
+=item Usage Hints for Perl on OS/390
+
+=item Floating Point Anomalies with Perl on OS/390
+
+=item Modules and Extensions for Perl on OS/390
+
+=back
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=over 4
+
+=item Mailing list for Perl on OS/390
+
+=back
+
+=item HISTORY
+
+=back
+
+=head2 perlos400, README.os400 - Perl version 5 on OS/400
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Compiling Perl for OS/400 PASE
+
+=item Installing Perl in OS/400 PASE
+
+=item Using Perl in OS/400 PASE
+
+=item Known Problems
+
+=item Perl on ILE
+
+=back
+
+=item AUTHORS
+
+=back
+
+=head2 perlplan9 - Plan 9-specific documentation for Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Invoking Perl
+
+=item What's in Plan 9 Perl
+
+=item What's not in Plan 9 Perl
+
+=item Perl5 Functions not currently supported in Plan 9 Perl
+
+=item Signals in Plan 9 Perl
+
+=back
+
+=item COMPILING AND INSTALLING PERL ON PLAN 9
+
+=over 4
+
+=item Installing Perl Documentation on Plan 9
+
+=back
+
+=item BUGS
+
+=item Revision date
+
+=item AUTHOR
+
+=back
+
+=head2 perlqnx, README.qnx - Perl version 5 on QNX
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Required Software for Compiling Perl on QNX4
+
+/bin/sh, ar, nm, cpp, make
+
+=item Outstanding Issues with Perl on QNX4
+
+=item QNX auxiliary files
+
+qnx/ar, qnx/cpp
+
+=item Outstanding issues with perl under QNX6
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 perlriscos, README.riscos - Perl version 5 for RISC OS
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUILD
+
+=item AUTHOR
+
+=back
+
+=head2 perlsolaris, README.solaris - Perl version 5 on Solaris systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Solaris Version Numbers.
+
+=back
+
+=item RESOURCES
+
+Solaris FAQ, Precompiled Binaries, Solaris Documentation
+
+=item SETTING UP
+
+=over 4
+
+=item File Extraction Problems on Solaris.
+
+=item Compiler and Related Tools on Solaris.
+
+=item Environment for Compiling perl on Solaris
+
+=back
+
+=item RUN CONFIGURE.
+
+=over 4
+
+=item 64-bit perl on Solaris.
+
+=item Threads in perl on Solaris.
+
+=item Malloc Issues with perl on Solaris.
+
+=back
+
+=item MAKE PROBLEMS.
+
+Dynamic Loading Problems With GNU as and GNU ld, ld.so.1: ./perl: fatal:
+relocation error:, dlopen: stub interception failed, #error "No
+DATAMODEL_NATIVE specified", sh: ar: not found
+
+=item MAKE TEST
+
+=over 4
+
+=item op/stat.t test 4 in Solaris
+
+=item nss_delete core dump from op/pwent or op/grent
+
+=back
+
+=item PREBUILT BINARIES OF PERL FOR SOLARIS.
+
+=item RUNTIME ISSUES FOR PERL ON SOLARIS.
+
+=over 4
+
+=item Limits on Numbers of Open Files on Solaris.
+
+=back
+
+=item SOLARIS-SPECIFIC MODULES.
+
+=item SOLARIS-SPECIFIC PROBLEMS WITH MODULES.
+
+=over 4
+
+=item Proc::ProcessTable on Solaris
+
+=item BSD::Resource on Solaris
+
+=item Net::SSLeay on Solaris
+
+=back
+
+=item SunOS 4.x
+
+=item AUTHOR
+
+=back
+
+=head2 perlsymbian, README.symbian - Perl version 5 on Symbian OS
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Compiling Perl on Symbian
+
+=item Compilation problems
+
+=item PerlApp
+
+=item sisify.pl
+
+=item Using Perl in Symbian
+
+=back
+
+=item TO DO
+
+=item WARNING
+
+=item NOTE
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item LICENSE
+
+=item HISTORY
+
+=back
+
+=head2 perltru64, README.tru64 - Perl version 5 on Tru64 (formerly known as
+Digital UNIX formerly known as DEC OSF/1) systems
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Compiling Perl 5 on Tru64
+
+=item Using Large Files with Perl on Tru64
+
+=item Threaded Perl on Tru64
+
+=item Long Doubles on Tru64
+
+=item DB_File tests failing on Tru64
+
+=item 64-bit Perl on Tru64
+
+=item Warnings about floating-point overflow when compiling Perl on Tru64
+
+=back
+
+=item Testing Perl on Tru64
+
+=item ext/ODBM_File/odbm Test Failing With Static Builds
+
+=item Perl Fails Because Of Unresolved Symbol sockatmark
+
+=item AUTHOR
+
+=back
+
+=head2 perluts - Perl under UTS
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUILDING PERL ON UTS
+
+=item Installing the built perl on UTS
+
+=item AUTHOR
+
+=back
+
+=head2 perlvmesa, README.vmesa - building and installing Perl for VM/ESA.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Unpacking Perl Distribution on VM/ESA
+
+=item Setup Perl and utilities on VM/ESA
+
+=item Configure Perl on VM/ESA
+
+=item Testing Anomalies of Perl on VM/ESA
+
+=item Usage Hints for Perl on VM/ESA
+
+=back
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=over 4
+
+=item Mailing list for Perl on VM/ESA
+
+=back
+
+=back
+
+=head2 perlvms - VMS-specific documentation for Perl
+
+=over 4
+
+=item DESCRIPTION
+
+=item Installation
+
+=item Organization of Perl Images
+
+=over 4
+
+=item Core Images
+
+=item Perl Extensions
+
+=item Installing static extensions
+
+=item Installing dynamic extensions
+
+=back
+
+=item File specifications
+
+=over 4
+
+=item Syntax
+
+=item Filename Case
+
+=item Symbolic Links
+
+=item Wildcard expansion
+
+=item Pipes
+
+=back
+
+=item PERL5LIB and PERLLIB
+
+=item The Perl Forked Debugger
+
+=item PERL_VMS_EXCEPTION_DEBUG
+
+=item Command line
+
+=over 4
+
+=item I/O redirection and backgrounding
+
+=item Command line switches
+
+-i, -S, -u
+
+=back
+
+=item Perl functions
+
+File tests, backticks, binmode FILEHANDLE, crypt PLAINTEXT, USER, die,
+dump, exec LIST, fork, getpwent, getpwnam, getpwuid, gmtime, kill, qx//,
+select (system call), stat EXPR, system LIST, time, times, unlink LIST,
+utime LIST, waitpid PID,FLAGS
+
+=item Perl variables
+
+%ENV, CRTL_ENV, CLISYM_[LOCAL], Any other string, $!, $^E, $?, $|
+
+=item Standard modules with VMS-specific differences
+
+=over 4
+
+=item SDBM_File
+
+=back
+
+=item Revision date
+
+=item AUTHOR
+
+=back
+
+=head2 perlvos, README.vos - Perl for Stratus VOS
+
+=over 4
+
+=item SYNOPSIS
+
+=item BUILDING PERL FOR VOS
+
+=item INSTALLING PERL IN VOS
+
+=item USING PERL IN VOS
+
+=over 4
+
+=item Restrictions of Perl on VOS
+
+=item Handling of underflow and overflow
+
+=back
+
+=item TEST STATUS
+
+=item SUPPORT STATUS
+
+=item AUTHOR
+
+=item LAST UPDATE
+
+=back
+
+=head2 perlwin32 - Perl under Windows
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Setting Up Perl on Win32
+
+Make, Command Shell, Borland C++, Microsoft Visual C++, Microsoft Visual
+C++ 2008 Express Edition Beta 2, Microsoft Visual C++ 2005 Express Edition,
+Microsoft Visual C++ Toolkit 2003, Microsoft Platform SDK 64-bit Compiler,
+MinGW release 3 with gcc, MinGW release 1 with gcc
+
+=item Building
+
+=item Testing Perl on Win32
+
+=item Installation of Perl on Win32
+
+=item Usage Hints for Perl on Win32
+
+Environment Variables, File Globbing, Using perl from the command line,
+Building Extensions, Command-line Wildcard Expansion, Win32 Specific
+Extensions, Notes on 64-bit Windows
+
+=item Running Perl Scripts
+
+=item Miscellaneous Things
+
+=back
+
+=item BUGS AND CAVEATS
+
+=item ACKNOWLEDGEMENTS
+
+=item AUTHORS
+
+Gary Ng E<lt>71564.1743 at CompuServe.COME<gt>, Gurusamy Sarathy
+E<lt>gsar at activestate.comE<gt>, Nick Ing-Simmons
+E<lt>nick at ing-simmons.netE<gt>, Jan Dubois E<lt>jand at activestate.comE<gt>,
+Steve Hay E<lt>steve.hay at uk.radan.comE<gt>
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head1 PRAGMA DOCUMENTATION
+
+=head2 attrs - set/get attributes of a subroutine (deprecated)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+method, locked
+
+=back
+
+=head2 re - Perl pragma to alter regular expression behaviour
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item 'taint' mode
+
+=item 'eval' mode
+
+=item 'debug' mode
+
+=item 'Debug' mode
+
+Compile related options, COMPILE, PARSE, OPTIMISE, TRIEC, DUMP, Execute
+related options, EXECUTE, MATCH, TRIEE, INTUIT, Extra debugging options,
+EXTRA, BUFFERS, TRIEM, STATE, STACK, OPTIMISEM, OFFSETS, OFFSETSDBG, Other
+useful flags, ALL, All, MORE, More
+
+=item Exportable Functions
+
+is_regexp($ref), regexp_pattern($ref), regmust($ref), regname($name,$all),
+regnames($all), regnames_count()
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 threadshared::shared, threads::shared - Perl extension for sharing
+data structures between threads
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPORT
+
+=item FUNCTIONS
+
+share VARIABLE, is_shared VARIABLE, lock VARIABLE, cond_wait VARIABLE,
+cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE, ABS_TIMEOUT,
+cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal VARIABLE,
+cond_broadcast VARIABLE
+
+=item OBJECTS
+
+=item NOTES
+
+=item BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 threads - Perl interpreter-based threads
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$thr = threads->create(FUNCTION, ARGS), $thr->join(), $thr->detach(),
+threads->detach(), threads->self(), $thr->tid(), threads->tid(), "$thr",
+threads->object($tid), threads->yield(), threads->list(),
+threads->list(threads::all), threads->list(threads::running),
+threads->list(threads::joinable), $thr1->equal($thr2), async BLOCK;,
+$thr->error(), $thr->_handle(), threads->_handle()
+
+=item EXITING A THREAD
+
+threads->exit(), threads->exit(status), die(), exit(status), use threads
+'exit' => 'threads_only', threads->create({'exit' => 'thread_only'}, ...),
+$thr->set_thread_exit_only(boolean), threads->set_thread_exit_only(boolean)
+
+=item THREAD STATE
+
+$thr->is_running(), $thr->is_joinable(), $thr->is_detached(),
+threads->is_detached()
+
+=item THREAD CONTEXT
+
+=over 4
+
+=item Explicit context
+
+=item Implicit context
+
+=item $thr->wantarray()
+
+=item threads->wantarray()
+
+=back
+
+=item THREAD STACK SIZE
+
+threads->get_stack_size();, $size = $thr->get_stack_size();, $old_size =
+threads->set_stack_size($new_size);, use threads ('stack_size' => VALUE);,
+$ENV{'PERL5_ITHREADS_STACK_SIZE'}, threads->create({'stack_size' => VALUE},
+FUNCTION, ARGS), $thr2 = $thr1->create(FUNCTION, ARGS)
+
+=item THREAD SIGNALLING
+
+$thr->kill('SIG...');
+
+=item WARNINGS
+
+Perl exited with active threads:, Thread creation failed: pthread_create
+returned #, Thread # terminated abnormally: .., Using minimum thread stack
+size of #, Thread creation failed: pthread_attr_setstacksize(I<SIZE>)
+returned 22
+
+=item ERRORS
+
+This Perl not built to support threads, Cannot change stack size of an
+existing thread, Cannot signal threads without safe signals, Unrecognized
+signal name: ..
+
+=item BUGS AND LIMITATIONS
+
+Thread-safe modules, Using non-thread-safe modules, Current working
+directory, Environment variables, Parent-child threads, Creating threads
+inside special blocks, Unsafe signals, Perl has been built with
+C<PERL_OLD_SIGNALS> (see C<perl -V>), The environment variable
+C<PERL_SIGNALS> is set to C<unsafe> (see L<perlrun/"PERL_SIGNALS">), The
+module L<Perl::Unsafe::Signals> is used, Returning closures from threads,
+Returning objects from threads, Perl Bugs and the CPAN Version of
+L<threads>
+
+=item REQUIREMENTS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item ACKNOWLEDGEMENTS
+
+=back
+
+=head2 attributes - get/set subroutine or variable attributes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Built-in Attributes
+
+locked, method, lvalue
+
+=item Available Subroutines
+
+get, reftype
+
+=item Package-specific Attribute Handling
+
+FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES
+
+=item Syntax of Attribute Lists
+
+=back
+
+=item EXPORTS
+
+=over 4
+
+=item Default exports
+
+=item Available exports
+
+=item Export tags defined
+
+=back
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=back
+
+=head2 autouse - postpone load of modules until a function is used
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item WARNING
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 base - Establish an ISA relationship with base classes at compile
+time
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item DIAGNOSTICS
+
+Base class package "%s" is empty, Class 'Foo' tried to inherit from itself
+
+=item HISTORY
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=back
+
+=head2 bigint - Transparent BigInteger support for Perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item use integer vs. use bigint
+
+=item Options
+
+a or accuracy, p or precision, t or trace, hex, oct, l, lib, try or only, v
+or version
+
+=item Math Library
+
+=item Internal Format
+
+=item Sign
+
+=item Methods
+
+inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect()
+
+=item MATH LIBRARY
+
+=item Caveat
+
+=back
+
+=item CAVAETS
+
+in_effect(), hex()/oct()
+
+=item MODULES USED
+
+=item EXAMPLES
+
+=item LICENSE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 bignum - Transparent BigNumber support for Perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Options
+
+a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version
+
+=item Methods
+
+=item Caveats
+
+inf(), NaN(), e, PI(), bexp(), bpi(), upgrade(), in_effect()
+
+=item Math Library
+
+=item INTERNAL FORMAT
+
+=item SIGN
+
+=back
+
+=item CAVAETS
+
+in_effect(), hex()/oct()
+
+=item MODULES USED
+
+=item EXAMPLES
+
+=item LICENSE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 bigrat - Transparent BigNumber/BigRational support for Perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Modules Used
+
+=item Math Library
+
+=item Sign
+
+=item Methods
+
+inf(), NaN(), e, PI, bexp(), bpi(), upgrade(), in_effect()
+
+=item MATH LIBRARY
+
+=item Cavaet
+
+=item Options
+
+a or accuracy, p or precision, t or trace, l or lib, hex, oct, v or version
+
+=back
+
+=item CAVAETS
+
+in_effect(), hex()/oct()
+
+=item EXAMPLES
+
+ perl -Mbigrat -le 'print sqrt(33)'
+ perl -Mbigrat -le 'print 2*255'
+ perl -Mbigrat -le 'print 4.5+2*255'
+ perl -Mbigrat -le 'print 3/7 + 5/7 + 8/3'
+ perl -Mbigrat -le 'print 12->is_odd()';
+ perl -Mbignum=l,GMP -le 'print 7 ** 7777'
+
+=item LICENSE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 blib - Use MakeMaker's uninstalled version of a package
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 bytes - Perl pragma to force byte semantics rather than character
+semantics
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item LIMITATIONS
+
+=item SEE ALSO
+
+=back
+
+=head2 charnames - define character names for C<\N{named}> string literal
+escapes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ALIASES
+
+=item CUSTOM ALIASES
+
+=over 4
+
+=item Anonymous hashes
+
+=item Alias file
+
+=item Alias shortcut
+
+=back
+
+=item charnames::viacode(code)
+
+=item charnames::vianame(name)
+
+=item CUSTOM TRANSLATORS
+
+=item ILLEGAL CHARACTERS
+
+=item BUGS
+
+=back
+
+=head2 constant - Perl pragma to declare constants
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=over 4
+
+=item List constants
+
+=item Defining multiple constants at once
+
+=item Magic constants
+
+=back
+
+=item TECHNICAL NOTES
+
+=item CAVEATS
+
+=item BUGS
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 diagnostics, splain - produce verbose warning diagnostics
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item The C<diagnostics> Pragma
+
+=item The I<splain> Program
+
+=back
+
+=item EXAMPLES
+
+=item INTERNALS
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 encoding - allows you to write your script in non-ascii or non-utf8
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=over 4
+
+=item Literal Conversions
+
+=item PerlIO layers for C<STD(IN|OUT)>
+
+=item Implicit upgrading for byte strings
+
+=item Side effects
+
+=item Side effects
+
+=item Side effects
+
+=back
+
+=item FEATURES THAT REQUIRE 5.8.1
+
+"NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle
+
+=item USAGE
+
+use encoding [I<ENCNAME>] ;, use encoding I<ENCNAME> [ STDIN =E<gt>
+I<ENCNAME_IN> ...] ;, use encoding I<ENCNAME> Filter=E<gt>1;, no encoding;
+
+=item The Filter Option
+
+=over 4
+
+=item Filter-related changes at Encode version 1.87
+
+=back
+
+=item CAVEATS
+
+=over 4
+
+=item NOT SCOPED
+
+=item DO NOT MIX MULTIPLE ENCODINGS
+
+=item tr/// with ranges
+
+Legend of characters above
+
+=back
+
+=item EXAMPLE - Greekperl
+
+=item KNOWN PROBLEMS
+
+literals in regex that are longer than 127 bytes, EBCDIC, format, Thread
+safety
+
+=over 4
+
+=item The Logic of :locale
+
+=back
+
+=item HISTORY
+
+=item SEE ALSO
+
+=back
+
+=head2 encoding::warnings - Warn on implicit encoding conversions
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overview of the problem
+
+=item Detecting the problem
+
+=item Solving the problem
+
+Upgrade both sides to unicode-strings, Downgrade both sides to
+byte-strings, Specify the encoding for implicit byte-string upgrading,
+PerlIO layers for B<STDIN> and B<STDOUT>, Literal conversions, Implicit
+upgrading for byte-strings
+
+=back
+
+=item CAVEATS
+
+=back
+
+=over 4
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 feature - Perl pragma to enable new syntactic features
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Lexical effect
+
+=item C<no feature>
+
+=item The 'switch' feature
+
+=item The 'say' feature
+
+=item the 'state' feature
+
+=back
+
+=item FEATURE BUNDLES
+
+=item IMPLICIT LOADING
+
+=back
+
+=head2 fields - compile-time class fields
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+new, phash
+
+=item SEE ALSO
+
+=back
+
+=head2 filetest - Perl pragma to control the filetest permission operators
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Consider this carefully
+
+=item The "access" sub-pragma
+
+=item Limitation with regard to C<_>
+
+=back
+
+=back
+
+=head2 if - C<use> a Perl module if a condition holds
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 integer - Perl pragma to use integer arithmetic instead of floating
+point
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 less - perl pragma to request less of something
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FOR MODULE AUTHORS
+
+=over 4
+
+=item C<< BOOLEAN = less->of( FEATURE ) >>
+
+=item C<< FEATURES = less->of() >>
+
+=back
+
+=item CAVEATS
+
+This probably does nothing, This works only on 5.10+
+
+=back
+
+=head2 lib - manipulate @INC at compile time
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Adding directories to @INC
+
+=item Deleting directories from @INC
+
+=item Restoring original @INC
+
+=back
+
+=item CAVEATS
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 locale - Perl pragma to use and avoid POSIX locales for built-in
+operations
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 mro - Method Resolution Order
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OVERVIEW
+
+=item The C3 MRO
+
+=over 4
+
+=item What is C3?
+
+=item How does C3 work
+
+=back
+
+=item Functions
+
+=over 4
+
+=item mro::get_linear_isa($classname[, $type])
+
+=item mro::set_mro($classname, $type)
+
+=item mro::get_mro($classname)
+
+=item mro::get_isarev($classname)
+
+=item mro::is_universal($classname)
+
+=item mro::invalidate_all_method_caches()
+
+=item mro::method_changed_in($classname)
+
+=item mro::get_pkg_gen($classname)
+
+=item next::method
+
+=item next::can
+
+=item maybe::next::method
+
+=back
+
+=item SEE ALSO
+
+=over 4
+
+=item The original Dylan paper
+
+L<http://www.webcom.com/haahr/dylan/linearization-oopsla96.html>
+
+=item The prototype Perl 6 Object Model uses C3
+
+L<http://svn.openfoundry.org/pugs/perl5/Perl6-MetaModel/>
+
+=item Parrot now uses C3
+
+L<http://aspn.activestate.com/ASPN/Mail/Message/perl6-internals/2746631>,
+L<http://use.perl.org/~autrijus/journal/25768>
+
+=item Python 2.3 MRO related links
+
+L<http://www.python.org/2.3/mro.html>,
+L<http://www.python.org/2.2.2/descrintro.html#mro>
+
+=item C3 for TinyCLOS
+
+L<http://www.call-with-current-continuation.org/eggs/c3.html>
+
+=item Class::C3
+
+L<Class::C3>
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 open - perl pragma to set default PerlIO layers for input and output
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NONPERLIO FUNCTIONALITY
+
+=item IMPLEMENTATION DETAILS
+
+=item SEE ALSO
+
+=back
+
+=head2 ops - Perl pragma to restrict unsafe operations when compiling
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 overload - Package for overloading Perl operations
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Declaration of overloaded functions
+
+=item Calling Conventions for Binary Operations
+
+FALSE, TRUE, C<undef>
+
+=item Calling Conventions for Unary Operations
+
+=item Calling Conventions for Mutators
+
+C<++> and C<-->, C<x=> and other assignment versions
+
+=item Overloadable Operations
+
+I<Arithmetic operations>, I<Comparison operations>, I<Bit operations>,
+I<Increment and decrement>, I<Transcendental functions>, I<Boolean, string
+and numeric conversion>, I<Iteration>, I<Dereferencing>, I<Special>
+
+=item Inheritance and overloading
+
+Strings as values of C<use overload> directive, Overloading of an operation
+is inherited by derived classes
+
+=back
+
+=item SPECIAL SYMBOLS FOR C<use overload>
+
+=over 4
+
+=item Last Resort
+
+=item Fallback
+
+C<undef>, TRUE, defined, but FALSE
+
+=item Smart Match
+
+=item Copy Constructor
+
+B<Example>
+
+=back
+
+=item MAGIC AUTOGENERATION
+
+I<Assignment forms of arithmetic operations>, I<Conversion operations>,
+I<Increment and decrement>, C<abs($a)>, I<Unary minus>, I<Negation>,
+I<Concatenation>, I<Comparison operations>, I<Iterator>, I<Dereferencing>,
+I<Copy operator>
+
+=item Minimal set of overloaded operations
+
+=item Losing overloading
+
+=item Run-time Overloading
+
+=item Public functions
+
+overload::StrVal(arg), overload::Overloaded(arg), overload::Method(obj,op)
+
+=item Overloading constants
+
+integer, float, binary, q, qr
+
+=item IMPLEMENTATION
+
+=item Metaphor clash
+
+=item Cookbook
+
+=over 4
+
+=item Two-face scalars
+
+=item Two-face references
+
+=item Symbolic calculator
+
+=item I<Really> symbolic calculator
+
+=back
+
+=item AUTHOR
+
+=item DIAGNOSTICS
+
+Odd number of arguments for overload::constant, `%s' is not an overloadable
+type, `%s' is not a code reference
+
+=item BUGS
+
+=back
+
+=head2 sigtrap - Perl pragma to enable simple signal handling
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS
+
+=over 4
+
+=item SIGNAL HANDLERS
+
+B<stack-trace>, B<die>, B<handler> I<your-handler>
+
+=item SIGNAL LISTS
+
+B<normal-signals>, B<error-signals>, B<old-interface-signals>
+
+=item OTHER
+
+B<untrapped>, B<any>, I<signal>, I<number>
+
+=back
+
+=item EXAMPLES
+
+=back
+
+=head2 sort - perl pragma to control sort() behaviour
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEATS
+
+=back
+
+=head2 strict - Perl pragma to restrict unsafe constructs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<strict refs>, C<strict vars>, C<strict subs>
+
+=item HISTORY
+
+=back
+
+=head2 subs - Perl pragma to predeclare sub names
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 threadshared, threads::shared - Perl extension for sharing data
+structures between threads
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPORT
+
+=item FUNCTIONS
+
+share VARIABLE, is_shared VARIABLE, lock VARIABLE, cond_wait VARIABLE,
+cond_wait CONDVAR, LOCKVAR, cond_timedwait VARIABLE, ABS_TIMEOUT,
+cond_timedwait CONDVAR, ABS_TIMEOUT, LOCKVAR, cond_signal VARIABLE,
+cond_broadcast VARIABLE
+
+=item OBJECTS
+
+=item NOTES
+
+=item BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source
+code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Utility functions
+
+$num_octets = utf8::upgrade($string), $success = utf8::downgrade($string[,
+FAIL_OK]), utf8::encode($string), $success = utf8::decode($string), $flag =
+utf8::is_utf8(STRING), $flag = utf8::valid(STRING)
+
+=back
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 vars - Perl pragma to predeclare global variable names (obsolete)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 version - Perl extension for Version Objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item BEST PRACTICES
+
+Be consistent, Be careful
+
+=item Using modules that use version.pm
+
+Numeric versions always work, Extended version work sometimes
+
+=item What IS a version
+
+Numeric Versions, Extended Versions
+
+=item Numeric Versions
+
+=item Extended Versions
+
+=item Numeric Alpha Versions
+
+=item Object Methods
+
+New Operator, qv(), Normal Form, Numification, Stringification, Comparison
+operators, Logical Operators
+
+=item Quoting
+
+=item What about v-strings?
+
+=item Types of Versions Objects
+
+Ordinary versions, Alpha Versions
+
+=item Replacement UNIVERSAL::VERSION
+
+=back
+
+=item SUBCLASSING
+
+=item EXPORT
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 vmsish - Perl pragma to control VMS-specific language features
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<vmsish status>, C<vmsish exit>, C<vmsish time>, C<vmsish hushed>
+
+=back
+
+=head2 warnings - Perl pragma to control optional warnings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+use warnings::register, warnings::enabled(), warnings::enabled($category),
+warnings::enabled($object), warnings::warn($message),
+warnings::warn($category, $message), warnings::warn($object, $message),
+warnings::warnif($message), warnings::warnif($category, $message),
+warnings::warnif($object, $message)
+
+=back
+
+=head2 warnings::register - warnings import function
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head1 MODULE DOCUMENTATION
+
+=head2 AnyDBM_File - provide framework for multiple DBMs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item DBM Comparisons
+
+[0], [1], [2], [3]
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Archive::Extract - A generic archive extracting mechanism
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $ae = Archive::Extract->new(archive => '/path/to/archive',[type =>
+TYPE])
+
+tar, tgz, gz, Z, zip, bz2, tbz
+
+=back
+
+=back
+
+=over 4
+
+=item $ae->extract( [to => '/output/path'] )
+
+$ae->extract_path, $ae->files
+
+=back
+
+=over 4
+
+=item ACCESSORS
+
+=over 4
+
+=item $ae->error([BOOL])
+
+=item $ae->extract_path
+
+=item $ae->files
+
+=item $ae->archive
+
+=item $ae->type
+
+=item $ae->types
+
+=back
+
+=back
+
+=over 4
+
+=item $ae->is_tgz
+
+=item $ae->is_tar
+
+=item $ae->is_gz
+
+=item $ae->is_Z
+
+=item $ae->is_zip
+
+=back
+
+=over 4
+
+=item $ae->bin_tar
+
+=item $ae->bin_gzip
+
+=item $ae->bin_unzip
+
+=back
+
+=over 4
+
+=item HOW IT WORKS
+
+=item CAVEATS
+
+=over 4
+
+=item File Extensions
+
+=item Supporting Very Large Files
+
+=item Bunzip2 support of arbitrary extensions.
+
+=back
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Archive::Extract::DEBUG
+
+=item $Archive::Extract::WARN
+
+=item $Archive::Extract::PREFER_BIN
+
+=back
+
+=item TODO
+
+Mime magic support
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Archive::Tar - module for manipulations of tar archives
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Object Methods
+
+=over 4
+
+=item Archive::Tar->new( [$file, $compressed] )
+
+=back
+
+=back
+
+=over 4
+
+=item $tar->read ( $filename|$handle, $compressed, {opt => 'val'} )
+
+limit, extract
+
+=back
+
+=over 4
+
+=item $tar->contains_file( $filename )
+
+=back
+
+=over 4
+
+=item $tar->extract( [@filenames] )
+
+=back
+
+=over 4
+
+=item $tar->extract_file( $file, [$extract_path] )
+
+=back
+
+=over 4
+
+=item $tar->list_files( [\@properties] )
+
+=back
+
+=over 4
+
+=item $tar->get_files( [@filenames] )
+
+=back
+
+=over 4
+
+=item $tar->get_content( $file )
+
+=back
+
+=over 4
+
+=item $tar->replace_content( $file, $content )
+
+=back
+
+=over 4
+
+=item $tar->rename( $file, $new_name )
+
+=back
+
+=over 4
+
+=item $tar->remove (@filenamelist)
+
+=back
+
+=over 4
+
+=item $tar->clear
+
+=back
+
+=over 4
+
+=item $tar->write ( [$file, $compressed, $prefix] )
+
+=back
+
+=over 4
+
+=item $tar->add_files( @filenamelist )
+
+=back
+
+=over 4
+
+=item $tar->add_data ( $filename, $data, [$opthashref] )
+
+FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET
+
+=back
+
+=over 4
+
+=item $tar->error( [$BOOL] )
+
+=back
+
+=over 4
+
+=item $tar->setcwd( $cwd );
+
+=back
+
+=over 4
+
+=item $bool = $tar->has_io_string
+
+=back
+
+=over 4
+
+=item $bool = $tar->has_perlio
+
+=back
+
+=over 4
+
+=item Class Methods
+
+=over 4
+
+=item Archive::Tar->create_archive($file, $compression, @filelist)
+
+=back
+
+=back
+
+=over 4
+
+=item Archive::Tar->list_archive ($file, $compressed, [\@properties])
+
+=back
+
+=over 4
+
+=item Archive::Tar->extract_archive ($file, $gzip)
+
+=back
+
+=over 4
+
+=item Archive::Tar->can_handle_compressed_files
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Archive::Tar::FOLLOW_SYMLINK
+
+=item $Archive::Tar::CHOWN
+
+=item $Archive::Tar::CHMOD
+
+=item $Archive::Tar::DO_NOT_USE_PREFIX
+
+=item $Archive::Tar::DEBUG
+
+=item $Archive::Tar::WARN
+
+=item $Archive::Tar::error
+
+=item $Archive::Tar::INSECURE_EXTRACT_MODE
+
+=item $Archive::Tar::HAS_PERLIO
+
+=item $Archive::Tar::HAS_IO_STRING
+
+=back
+
+=item FAQ
+
+What's the minimum perl version required to run Archive::Tar?, Isn't
+Archive::Tar slow?, Isn't Archive::Tar heavier on memory than /bin/tar?,
+Can't you lazy-load data instead?, How much memory will an X kb tar file
+need?, What do you do with unsupported filetypes in an archive?, I'm using
+WinZip, or some other non-POSIX client, and files are not being extracted
+properly!, How do I extract only files that have property X from an
+archive?, How do I access .tar.Z files?, How do I handle Unicode strings?
+
+=item TODO
+
+Check if passed in handles are open for read/write, Allow archives to be
+passed in as string, Facilitate processing an opened filehandle of a
+compressed archive
+
+=item SEE ALSO
+
+The GNU tar specification, The PAX format specication, A comparison of GNU
+and POSIX tar standards;
+C<http://www.delorie.com/gnu/docs/tar/tar_114.html>, GNU tar intends to
+switch to POSIX compatibility, A Comparison between various tar
+implementations
+
+=item AUTHOR
+
+=item ACKNOWLEDGEMENTS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Archive::Tar::File - a subclass for in-memory extracted file from
+Archive::Tar
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Accessors
+
+name, mode, uid, gid, size, mtime, chksum, type, linkname, magic, version,
+uname, gname, devmajor, devminor, prefix, raw
+
+=back
+
+=item Methods
+
+=over 4
+
+=item new( file => $path )
+
+=item new( data => $path, $data, $opt )
+
+=item new( chunk => $chunk )
+
+=back
+
+=back
+
+=over 4
+
+=item full_path
+
+=back
+
+=over 4
+
+=item validate
+
+=back
+
+=over 4
+
+=item has_content
+
+=back
+
+=over 4
+
+=item get_content
+
+=back
+
+=over 4
+
+=item get_content_by_ref
+
+=back
+
+=over 4
+
+=item replace_content( $content )
+
+=back
+
+=over 4
+
+=item rename( $new_name )
+
+=back
+
+=over 4
+
+=item Convenience methods
+
+is_file, is_dir, is_hardlink, is_symlink, is_chardev, is_blockdev, is_fifo,
+is_socket, is_longlink, is_label, is_unknown
+
+=back
+
+=head2 Attribute::Handlers - Simpler definition of attribute handlers
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+[0], [1], [2], [3], [4], [5], [6], [7]
+
+=over 4
+
+=item Typed lexicals
+
+=item Type-specific attribute handlers
+
+=item Non-interpretive attribute handlers
+
+=item Phase-specific attribute handlers
+
+=item Attributes as C<tie> interfaces
+
+=back
+
+=item EXAMPLES
+
+=item DIAGNOSTICS
+
+C<Bad attribute type: ATTR(%s)>, C<Attribute handler %s doesn't handle %s
+attributes>, C<Declaration of %s attribute in package %s may clash with
+future reserved word>, C<Can't have two ATTR specifiers on one subroutine>,
+C<Can't autotie a %s>, C<Internal error: %s symbol went missing>, C<Won't
+be able to apply END handler>
+
+=item AUTHOR
+
+=item BUGS
+
+=item COPYRIGHT
+
+=back
+
+=head2 AutoLoader - load subroutines only on demand
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Subroutine Stubs
+
+=item Using B<AutoLoader>'s AUTOLOAD Subroutine
+
+=item Overriding B<AutoLoader>'s AUTOLOAD Subroutine
+
+=item Package Lexicals
+
+=item Not Using AutoLoader
+
+=item B<AutoLoader> vs. B<SelfLoader>
+
+=back
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=back
+
+=head2 AutoSplit - split a package for autoloading
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$keep, $check, $modtime
+
+=over 4
+
+=item Multiple packages
+
+=back
+
+=item DIAGNOSTICS
+
+=back
+
+=head2 B - The Perl Compiler
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OVERVIEW
+
+=item Utility Functions
+
+=over 4
+
+=item Functions Returning C<B::SV>, C<B::AV>, C<B::HV>, and C<B::CV>
+objects
+
+sv_undef, sv_yes, sv_no, svref_2object(SVREF), amagic_generation, init_av,
+check_av, unitcheck_av, begin_av, end_av, comppadlist, regex_padav, main_cv
+
+=item Functions for Examining the Symbol Table
+
+walksymtable(SYMREF, METHOD, RECURSE, PREFIX)
+
+=item Functions Returning C<B::OP> objects or for walking op trees
+
+main_root, main_start, walkoptree(OP, METHOD), walkoptree_debug(DEBUG)
+
+=item Miscellaneous Utility Functions
+
+ppname(OPNUM), hash(STR), cast_I32(I), minus_c, cstring(STR),
+perlstring(STR), class(OBJ), threadsv_names
+
+=item Exported utility variabiles
+
+ at optype, @specialsv_name
+
+=back
+
+=item OVERVIEW OF CLASSES
+
+=over 4
+
+=item SV-RELATED CLASSES
+
+=item B::SV Methods
+
+REFCNT, FLAGS, object_2svref
+
+=item B::IV Methods
+
+IV, IVX, UVX, int_value, needs64bits, packiv
+
+=item B::NV Methods
+
+NV, NVX
+
+=item B::RV Methods
+
+RV
+
+=item B::PV Methods
+
+PV, RV, PVX
+
+=item B::PVMG Methods
+
+MAGIC, SvSTASH
+
+=item B::MAGIC Methods
+
+MOREMAGIC, precomp, PRIVATE, TYPE, FLAGS, OBJ, PTR, REGEX
+
+=item B::PVLV Methods
+
+TARGOFF, TARGLEN, TYPE, TARG
+
+=item B::BM Methods
+
+USEFUL, PREVIOUS, RARE, TABLE
+
+=item B::GV Methods
+
+is_empty, NAME, SAFENAME, STASH, SV, IO, FORM, AV, HV, EGV, CV, CVGEN,
+LINE, FILE, FILEGV, GvREFCNT, FLAGS
+
+=item B::IO Methods
+
+LINES, PAGE, PAGE_LEN, LINES_LEFT, TOP_NAME, TOP_GV, FMT_NAME, FMT_GV,
+BOTTOM_NAME, BOTTOM_GV, SUBPROCESS, IoTYPE, IoFLAGS, IsSTD
+
+=item B::AV Methods
+
+FILL, MAX, ARRAY, ARRAYelt, OFF, AvFLAGS
+
+=item B::CV Methods
+
+STASH, START, ROOT, GV, FILE, DEPTH, PADLIST, OUTSIDE, OUTSIDE_SEQ, XSUB,
+XSUBANY, CvFLAGS, const_sv
+
+=item B::HV Methods
+
+FILL, MAX, KEYS, RITER, NAME, ARRAY, PMROOT
+
+=item OP-RELATED CLASSES
+
+=item B::OP Methods
+
+next, sibling, name, ppaddr, desc, targ, type, opt, flags, private, spare
+
+=item B::UNOP METHOD
+
+first
+
+=item B::BINOP METHOD
+
+last
+
+=item B::LOGOP METHOD
+
+other
+
+=item B::LISTOP METHOD
+
+children
+
+=item B::PMOP Methods
+
+pmreplroot, pmreplstart, pmnext, pmregexp, pmflags, extflags, precomp,
+pmoffset
+
+=item B::SVOP METHOD
+
+sv, gv
+
+=item B::PADOP METHOD
+
+padix
+
+=item B::PVOP METHOD
+
+pv
+
+=item B::LOOP Methods
+
+redoop, nextop, lastop
+
+=item B::COP Methods
+
+label, stash, stashpv, file, cop_seq, arybase, line, warnings, io, hints,
+hints_hash
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 B::Concise - Walk Perl syntax tree, printing concise info about ops
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLE
+
+=item OPTIONS
+
+=over 4
+
+=item Options for Opcode Ordering
+
+B<-basic>, B<-exec>, B<-tree>
+
+=item Options for Line-Style
+
+B<-concise>, B<-terse>, B<-linenoise>, B<-debug>, B<-env>
+
+=item Options for tree-specific formatting
+
+B<-compact>, B<-loose>, B<-vt>, B<-ascii>
+
+=item Options controlling sequence numbering
+
+B<-base>I<n>, B<-bigendian>, B<-littleendian>
+
+=item Other options
+
+B<-src>, B<-stash="somepackage">, B<-main>, B<-nomain>, B<-nobanner>,
+B<-banner>, B<-banneris> => subref
+
+=item Option Stickiness
+
+=back
+
+=item ABBREVIATIONS
+
+=over 4
+
+=item OP class abbreviations
+
+=item OP flags abbreviations
+
+=back
+
+=item FORMATTING SPECIFICATIONS
+
+=over 4
+
+=item Special Patterns
+
+B<(x(>I<exec_text>B<;>I<basic_text>B<)x)>, B<(*(>I<text>B<)*)>,
+B<(*(>I<text1>B<;>I<text2>B<)*)>, B<(?(>I<text1>B<#>I<var>I<Text2>B<)?)>,
+B<~>
+
+=item # Variables
+
+B<#>I<var>, B<#>I<var>I<N>, B<#>I<Var>, B<#addr>, B<#arg>, B<#class>,
+B<#classsym>, B<#coplabel>, B<#exname>, B<#extarg>, B<#firstaddr>,
+B<#flags>, B<#flagval>, B<#hints>, B<#hintsval>, B<#hyphseq>, B<#label>,
+B<#lastaddr>, B<#name>, B<#NAME>, B<#next>, B<#nextaddr>, B<#noise>,
+B<#private>, B<#privval>, B<#seq>, B<#seqnum>, B<#opt>, B<#sibaddr>,
+B<#svaddr>, B<#svclass>, B<#svval>, B<#targ>, B<#targarg>, B<#targarglife>,
+B<#typenum>
+
+=back
+
+=item One-Liner Command tips
+
+perl -MO=Concise,bar foo.pl, perl -MDigest::MD5=md5 -MO=Concise,md5 -e1,
+perl -MPOSIX -MO=Concise,_POSIX_ARG_MAX -e1, perl -MPOSIX -MO=Concise,a -e
+'print _POSIX_SAVED_IDS', perl -MPOSIX -MO=Concise,a -e 'sub
+a{_POSIX_SAVED_IDS}', perl -MB::Concise -e
+'B::Concise::compile("-exec","-src", \%B::Concise::)->()'
+
+=item Using B::Concise outside of the O framework
+
+=over 4
+
+=item Example: Altering Concise Renderings
+
+=item set_style()
+
+=item set_style_standard($name)
+
+=item add_style()
+
+=item add_callback()
+
+=item Running B::Concise::compile()
+
+=item B::Concise::reset_sequence()
+
+=item Errors
+
+=back
+
+=item AUTHOR
+
+=back
+
+=head2 B::Debug - Walk Perl syntax tree, printing debug info about ops
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=back
+
+=head2 B::Deparse - Perl compiler backend to produce perl code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS
+
+B<-d>, B<-f>I<FILE>, B<-l>, B<-p>, B<-P>, B<-q>, B<-s>I<LETTERS>, B<C>,
+B<i>I<NUMBER>, B<T>, B<v>I<STRING>B<.>, B<-x>I<LEVEL>
+
+=item USING B::Deparse AS A MODULE
+
+=over 4
+
+=item Synopsis
+
+=item Description
+
+=item new
+
+=item ambient_pragmas
+
+strict, $[, bytes, utf8, integer, re, warnings, hint_bits, warning_bits,
+%^H
+
+=item coderef2text
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 B::Lint - Perl lint
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS AND LINT CHECKS
+
+B<magic-diamond>, B<context>, B<implicit-read> and B<implicit-write>,
+B<bare-subs>, B<dollar-underscore>, B<private-names>, B<undefined-subs>,
+B<regexp-variables>, B<all>, B<none>
+
+=item NON LINT-CHECK OPTIONS
+
+B<-u Package>
+
+=item EXTENDING LINT
+
+=item TODO
+
+while(<FH>) stomps $_, strict oo, unchecked system calls, more tests,
+validate against older perls
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 B::O, O - Generic interface to Perl Compiler backends
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONVENTIONS
+
+=item IMPLEMENTATION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 B::Showlex - Show lexical variables used in functions or files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=over 4
+
+=item OPTIONS
+
+=back
+
+=item SEE ALSO
+
+=item TODO
+
+=item AUTHOR
+
+=back
+
+=head2 B::Terse - Walk Perl syntax tree, printing terse info about ops
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=back
+
+=head2 B::Xref - Generates cross reference reports for Perl programs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS
+
+C<-oFILENAME>, C<-r>, C<-d>, C<-D[tO]>
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 Benchmark - benchmark running times of Perl code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Methods
+
+new, debug, iters
+
+=item Standard Exports
+
+timeit(COUNT, CODE), timethis ( COUNT, CODE, [ TITLE, [ STYLE ]] ),
+timethese ( COUNT, CODEHASHREF, [ STYLE ] ), timediff ( T1, T2 ), timestr (
+TIMEDIFF, [ STYLE, [ FORMAT ] ] )
+
+=item Optional Exports
+
+clearcache ( COUNT ), clearallcache ( ), cmpthese ( COUNT, CODEHASHREF, [
+STYLE ] ), cmpthese ( RESULTSHASHREF, [ STYLE ] ), countit(TIME, CODE),
+disablecache ( ), enablecache ( ), timesum ( T1, T2 )
+
+=item :hireswallclock
+
+=back
+
+=item NOTES
+
+=item EXAMPLES
+
+=item INHERITANCE
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item MODIFICATION HISTORY
+
+=back
+
+=head2 CGI - Simple Common Gateway Interface Class
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=over 4
+
+=item PROGRAMMING STYLE
+
+=item CALLING CGI.PM ROUTINES
+
+=item CREATING A NEW QUERY OBJECT (OBJECT-ORIENTED STYLE):
+
+=item CREATING A NEW QUERY OBJECT FROM AN INPUT FILE
+
+=item FETCHING A LIST OF KEYWORDS FROM THE QUERY:
+
+=item FETCHING THE NAMES OF ALL THE PARAMETERS PASSED TO YOUR SCRIPT:
+
+=item FETCHING THE VALUE OR VALUES OF A SINGLE NAMED PARAMETER:
+
+=item SETTING THE VALUE(S) OF A NAMED PARAMETER:
+
+=item APPENDING ADDITIONAL VALUES TO A NAMED PARAMETER:
+
+=item IMPORTING ALL PARAMETERS INTO A NAMESPACE:
+
+=item DELETING A PARAMETER COMPLETELY:
+
+=item DELETING ALL PARAMETERS:
+
+=item HANDLING NON-URLENCODED ARGUMENTS
+
+=item DIRECT ACCESS TO THE PARAMETER LIST:
+
+=item FETCHING THE PARAMETER LIST AS A HASH:
+
+=item SAVING THE STATE OF THE SCRIPT TO A FILE:
+
+=item RETRIEVING CGI ERRORS
+
+=item USING THE FUNCTION-ORIENTED INTERFACE
+
+B<:cgi>, B<:form>, B<:html2>, B<:html3>, B<:html4>, B<:netscape>, B<:html>,
+B<:standard>, B<:all>
+
+=item PRAGMAS
+
+-any, -compile, -nosticky, -tabindex, -no_undef_params, -no_xhtml, -nph,
+-newstyle_urls, -oldstyle_urls, -autoload, -no_debug, -debug,
+-private_tempfiles
+
+=item SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS
+
+1. start_table() (generates a <table> tag), 2. end_table() (generates a
+</table> tag), 3. start_ul() (generates a <ul> tag), 4. end_ul() (generates
+a </ul> tag)
+
+=back
+
+=item GENERATING DYNAMIC DOCUMENTS
+
+=over 4
+
+=item CREATING A STANDARD HTTP HEADER:
+
+=item GENERATING A REDIRECTION HEADER
+
+=item CREATING THE HTML DOCUMENT HEADER
+
+B<Parameters:>, 4, 5, 6..
+
+=item ENDING THE HTML DOCUMENT:
+
+=item CREATING A SELF-REFERENCING URL THAT PRESERVES STATE INFORMATION:
+
+=item OBTAINING THE SCRIPT'S URL
+
+B<-absolute>, B<-relative>, B<-full>, B<-path> (B<-path_info>), B<-query>
+(B<-query_string>), B<-base>, B<-rewrite>
+
+=item MIXING POST AND URL PARAMETERS
+
+=back
+
+=item CREATING STANDARD HTML ELEMENTS:
+
+=over 4
+
+=item PROVIDING ARGUMENTS TO HTML SHORTCUTS
+
+=item THE DISTRIBUTIVE PROPERTY OF HTML SHORTCUTS
+
+=item HTML SHORTCUTS AND LIST INTERPOLATION
+
+=item NON-STANDARD HTML SHORTCUTS
+
+=item AUTOESCAPING HTML
+
+$escaped_string = escapeHTML("unescaped string");, $charset =
+charset([$charset]);, $flag = autoEscape([$flag]);
+
+=item PRETTY-PRINTING HTML
+
+=back
+
+=item CREATING FILL-OUT FORMS:
+
+=over 4
+
+=item CREATING AN ISINDEX TAG
+
+=item STARTING AND ENDING A FORM
+
+B<application/x-www-form-urlencoded>, B<multipart/form-data>
+
+=item FORM ELEMENTS
+
+B<-name>, B<-value>, B<-values>, B<-tabindex>, B<-id>, B<-override>,
+B<-onChange>, B<-onFocus>, B<-onBlur>, B<-onMouseOver>, B<-onMouseOut>,
+B<-onSelect>
+
+=item CREATING A TEXT FIELD
+
+B<Parameters>
+
+=item CREATING A BIG TEXT FIELD
+
+=item CREATING A PASSWORD FIELD
+
+=item CREATING A FILE UPLOAD FIELD
+
+B<Parameters>
+
+=item CREATING A POPUP MENU
+
+=item CREATING AN OPTION GROUP
+
+=item CREATING A SCROLLING LIST
+
+B<Parameters:>
+
+=item CREATING A GROUP OF RELATED CHECKBOXES
+
+B<Parameters:>
+
+=item CREATING A STANDALONE CHECKBOX
+
+B<Parameters:>
+
+=item CREATING A RADIO BUTTON GROUP
+
+B<Parameters:>
+
+=item CREATING A SUBMIT BUTTON
+
+B<Parameters:>
+
+=item CREATING A RESET BUTTON
+
+=item CREATING A DEFAULT BUTTON
+
+=item CREATING A HIDDEN FIELD
+
+B<Parameters:>
+
+=item CREATING A CLICKABLE IMAGE BUTTON
+
+B<Parameters:>, 3. The third option (-align, optional) is an alignment
+type, and may be TOP, BOTTOM or MIDDLE
+
+=item CREATING A JAVASCRIPT ACTION BUTTON
+
+=back
+
+=item HTTP COOKIES
+
+1. an expiration time, 2. a domain, 3. a path, 4. a "secure" flag,
+B<-name>, B<-value>, B<-path>, B<-domain>, B<-expires>, B<-secure>
+
+=item WORKING WITH FRAMES
+
+1. Create a <Frameset> document, 2. Specify the destination for the
+document in the HTTP header, 3. Specify the destination for the document in
+the <form> tag
+
+=item SUPPORT FOR JAVASCRIPT
+
+B<onLoad>, B<onUnload>, B<onSubmit>, B<onClick>, B<onChange>, B<onFocus>,
+B<onBlur>, B<onSelect>, B<onMouseOver>, B<onMouseOut>
+
+=item LIMITED SUPPORT FOR CASCADING STYLE SHEETS
+
+=item DEBUGGING
+
+=over 4
+
+=item DUMPING OUT ALL THE NAME/VALUE PAIRS
+
+=back
+
+=item FETCHING ENVIRONMENT VARIABLES
+
+B<Accept()>, B<raw_cookie()>, B<user_agent()>, B<path_info()>,
+B<path_translated()>, B<remote_host()>, B<script_name()> Return the script
+name as a partial URL, for self-refering scripts, B<referer()>, B<auth_type
+()>, B<server_name ()>, B<virtual_host ()>, B<server_port ()>,
+B<virtual_port ()>, B<server_software ()>, B<remote_user ()>, B<user_name
+()>, B<request_method()>, B<content_type()>, B<http()>, B<https()>
+
+=item USING NPH SCRIPTS
+
+In the B<use> statement, By calling the B<nph()> method:, By using B<-nph>
+parameters
+
+=item Server Push
+
+multipart_init(), multipart_start(), multipart_end(), multipart_final()
+
+=item Avoiding Denial of Service Attacks
+
+B<$CGI::POST_MAX>, B<$CGI::DISABLE_UPLOADS>, B<1. On a script-by-script
+basis>, B<2. Globally for all scripts>
+
+=item COMPATIBILITY WITH CGI-LIB.PL
+
+=item AUTHOR INFORMATION
+
+=item CREDITS
+
+Matt Heffron (heffron at falstaff.css.beckman.com), James Taylor
+(james.taylor at srs.gov), Scott Anguish <sanguish at digifix.com>, Mike Jewell
+(mlj3u at virginia.edu), Timothy Shimmin (tes at kbs.citri.edu.au), Joergen Haegg
+(jh at axis.se), Laurent Delfosse (delfosse at delfosse.com), Richard Resnick
+(applepi1 at aol.com), Craig Bishop (csb at barwonwater.vic.gov.au), Tony Curtis
+(tc at vcpc.univie.ac.at), Tim Bunce (Tim.Bunce at ig.co.uk), Tom Christiansen
+(tchrist at convex.com), Andreas Koenig (k at franz.ww.TU-Berlin.DE), Tim
+MacKenzie (Tim.MacKenzie at fulcrum.com.au), Kevin B. Hendricks
+(kbhend at dogwood.tyler.wm.edu), Stephen Dahmen (joyfire at inxpress.net), Ed
+Jordan (ed at fidalgo.net), David Alan Pisoni (david at cnation.com), Doug
+MacEachern (dougm at opengroup.org), Robin Houston (robin at oneworld.org),
+...and many many more..
+
+=item A COMPLETE EXAMPLE OF A SIMPLE FORM-BASED SCRIPT
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Apache - Backward compatibility module for CGI.pm
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item AUTHOR INFORMATION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Carp, B<CGI::Carp> - CGI routines for writing to the HTTPD (or
+other) error log
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item REDIRECTING ERROR MESSAGES
+
+=item MAKING PERL ERRORS APPEAR IN THE BROWSER WINDOW
+
+=over 4
+
+=item Changing the default message
+
+=back
+
+=item DOING MORE THAN PRINTING A MESSAGE IN THE EVENT OF PERL ERRORS
+
+=item MAKING WARNINGS APPEAR AS HTML COMMENTS
+
+=item OVERRIDING THE NAME OF THE PROGRAM
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Cookie - Interface to Netscape Cookies
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USING CGI::Cookie
+
+B<1. expiration date>, B<2. domain>, B<3. path>, B<4. secure flag>, B<4.
+httponly flag>
+
+=over 4
+
+=item Creating New Cookies
+
+=item Sending the Cookie to the Browser
+
+=item Recovering Previous Cookies
+
+=item Manipulating Cookies
+
+B<name()>, B<value()>, B<domain()>, B<path()>, B<expires()>
+
+=back
+
+=item AUTHOR INFORMATION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Fast - CGI Interface for Fast CGI
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OTHER PIECES OF THE PUZZLE
+
+=item WRITING FASTCGI PERL SCRIPTS
+
+=item INSTALLING FASTCGI SCRIPTS
+
+=item USING FASTCGI SCRIPTS AS CGI SCRIPTS
+
+=item EXTERNAL FASTCGI SERVER INVOCATION
+
+FCGI_SOCKET_PATH, FCGI_LISTEN_QUEUE
+
+=item CAVEATS
+
+=item AUTHOR INFORMATION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Pretty - module to produce nicely formatted HTML code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Tags that won't be formatted
+
+=item Customizing the Indenting
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Push - Simple Interface to Server Push
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USING CGI::Push
+
+-next_page, -last_page, -type, -delay, -cookie, -target, -expires, -nph
+
+=over 4
+
+=item Heterogeneous Pages
+
+=item Changing the Page Delay on the Fly
+
+=back
+
+=item INSTALLING CGI::Push SCRIPTS
+
+=item AUTHOR INFORMATION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Switch - Backward compatibility module for defunct CGI::Switch
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item AUTHOR INFORMATION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 CGI::Util - Internal utilities used by CGI module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR INFORMATION
+
+=item SEE ALSO
+
+=back
+
+=head2 CORE - Pseudo-namespace for Perl's core routines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OVERRIDING CORE FUNCTIONS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 CPAN - query, download and build perl modules from CPAN sites
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item CPAN::shell([$prompt, $command]) Starting Interactive Mode
+
+Searching for authors, bundles, distribution files and modules, C<get>,
+C<make>, C<test>, C<install>, C<clean> modules or distributions, C<readme>,
+C<perldoc>, C<look> module or distribution, C<ls> author, C<ls>
+globbing_expression, C<failed>, Persistence between sessions, The C<force>
+and the C<fforce> pragma, Lockfile, Signals
+
+=item CPAN::Shell
+
+=item autobundle
+
+=item hosts
+
+=item mkmyconfig
+
+=item recent ***EXPERIMENTAL COMMAND***
+
+=item recompile
+
+=item report Bundle|Distribution|Module
+
+=item smoke ***EXPERIMENTAL COMMAND***
+
+=item upgrade [Module|/Regex/]...
+
+=item The four C<CPAN::*> Classes: Author, Bundle, Module, Distribution
+
+=item Integrating local directories
+
+=back
+
+=item CONFIGURATION
+
+completion support, displaying some help: o conf help, displaying current
+values: o conf [KEY], changing of scalar values: o conf KEY VALUE, changing
+of list values: o conf KEY SHIFT|UNSHIFT|PUSH|POP|SPLICE|LIST, reverting to
+saved: o conf defaults, saving the config: o conf commit
+
+=over 4
+
+=item Config Variables
+
+C<o conf E<lt>scalar optionE<gt>>, C<o conf E<lt>scalar optionE<gt>
+E<lt>valueE<gt>>, C<o conf E<lt>list optionE<gt>>, C<o conf E<lt>list
+optionE<gt> [shift|pop]>, C<o conf E<lt>list optionE<gt>
+[unshift|push|splice] E<lt>listE<gt>>, interactive editing: o conf init
+[MATCH|LIST]
+
+=item CPAN::anycwd($path): Note on config variable getcwd
+
+cwd, getcwd, fastcwd, backtickcwd
+
+=item Note on the format of the urllist parameter
+
+=item The urllist parameter has CD-ROM support
+
+=item Maintaining the urllist parameter
+
+=item The C<requires> and C<build_requires> dependency declarations
+
+=item Configuration for individual distributions (I<Distroprefs>)
+
+=item Filenames
+
+=item Fallback Data::Dumper and Storable
+
+=item Blueprint
+
+=item Language Specs
+
+comment [scalar], cpanconfig [hash], depends [hash] *** EXPERIMENTAL
+FEATURE ***, disabled [boolean], goto [string], install [hash], make
+[hash], match [hash], patches [array], pl [hash], test [hash]
+
+=item Processing Instructions
+
+args [array], commandline, eexpect [hash], env [hash], expect [array]
+
+=item Schema verification with C<Kwalify>
+
+=item Example Distroprefs Files
+
+=back
+
+=item PROGRAMMER'S INTERFACE
+
+expand($type, at things), expandany(@things), Programming Examples
+
+=over 4
+
+=item Methods in the other Classes
+
+CPAN::Author::as_glimpse(), CPAN::Author::as_string(),
+CPAN::Author::email(), CPAN::Author::fullname(), CPAN::Author::name(),
+CPAN::Bundle::as_glimpse(), CPAN::Bundle::as_string(),
+CPAN::Bundle::clean(), CPAN::Bundle::contains(),
+CPAN::Bundle::force($method, at args), CPAN::Bundle::get(),
+CPAN::Bundle::inst_file(), CPAN::Bundle::inst_version(),
+CPAN::Bundle::uptodate(), CPAN::Bundle::install(), CPAN::Bundle::make(),
+CPAN::Bundle::readme(), CPAN::Bundle::test(),
+CPAN::Distribution::as_glimpse(), CPAN::Distribution::as_string(),
+CPAN::Distribution::author, CPAN::Distribution::pretty_id(),
+CPAN::Distribution::base_id(), CPAN::Distribution::clean(),
+CPAN::Distribution::containsmods(), CPAN::Distribution::cvs_import(),
+CPAN::Distribution::dir(), CPAN::Distribution::force($method, at args),
+CPAN::Distribution::get(), CPAN::Distribution::install(),
+CPAN::Distribution::install_tested(), CPAN::Distribution::isa_perl(),
+CPAN::Distribution::is_tested(), CPAN::Distribution::look(),
+CPAN::Distribution::make(), CPAN::Distribution::perldoc(),
+CPAN::Distribution::prefs(), CPAN::Distribution::prereq_pm(),
+CPAN::Distribution::readme(), CPAN::Distribution::reports(),
+CPAN::Distribution::read_yaml(), CPAN::Distribution::test(),
+CPAN::Distribution::uptodate(), CPAN::Index::force_reload(),
+CPAN::Index::reload(), CPAN::InfoObj::dump(), CPAN::Module::as_glimpse(),
+CPAN::Module::as_string(), CPAN::Module::clean(),
+CPAN::Module::cpan_file(), CPAN::Module::cpan_version(),
+CPAN::Module::cvs_import(), CPAN::Module::description(),
+CPAN::Module::distribution(), CPAN::Module::dslip_status(),
+CPAN::Module::force($method, at args), CPAN::Module::get(),
+CPAN::Module::inst_file(), CPAN::Module::available_file(),
+CPAN::Module::inst_version(), CPAN::Module::available_version(),
+CPAN::Module::install(), CPAN::Module::look(), CPAN::Module::make(),
+CPAN::Module::manpage_headline(), CPAN::Module::perldoc(),
+CPAN::Module::readme(), CPAN::Module::reports(), CPAN::Module::test(),
+CPAN::Module::uptodate(), CPAN::Module::userid()
+
+=item Cache Manager
+
+=item Bundles
+
+=back
+
+=item PREREQUISITES
+
+=item UTILITIES
+
+=over 4
+
+=item Finding packages and VERSION
+
+=item Debugging
+
+o debug package.., o debug -package.., o debug all, o debug number
+
+=item Floppy, Zip, Offline Mode
+
+=item Basic Utilities for Programmers
+
+has_inst($module), has_usable($module), instance($module)
+
+=back
+
+=item SECURITY
+
+=over 4
+
+=item Cryptographically signed modules
+
+=back
+
+=item EXPORT
+
+=item ENVIRONMENT
+
+=item POPULATE AN INSTALLATION WITH LOTS OF MODULES
+
+=item WORKING WITH CPAN.pm BEHIND FIREWALLS
+
+=over 4
+
+=item Three basic types of firewalls
+
+http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade
+
+=item Configuring lynx or ncftp for going through a firewall
+
+=back
+
+=item FAQ
+
+1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11), 12), 13), 14), 15), 16)
+
+=item COMPATIBILITY
+
+=over 4
+
+=item OLD PERL VERSIONS
+
+=item CPANPLUS
+
+=back
+
+=item SECURITY ADVICE
+
+=item BUGS
+
+=item AUTHOR
+
+=item LICENSE
+
+=item TRANSLATIONS
+
+=item SEE ALSO
+
+=back
+
+=head2 CPAN::API::HOWTO - a recipe book for programming with CPAN.pm
+
+=over 4
+
+=item RECIPES
+
+=over 4
+
+=item What distribution contains a particular module?
+
+=item What modules does a particular distribution contain?
+
+=back
+
+=item SEE ALSO
+
+=item LICENSE
+
+=item AUTHOR
+
+=back
+
+=head2 CPAN::FirstTime - Utility for CPAN::Config file Initialization
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+auto_commit, build_cache, build_dir, build_dir_reuse,
+build_requires_install_policy, cache_metadata, check_sigs, colorize_output,
+colorize_print, colorize_warn, colorize_debug, commandnumber_in_prompt,
+ftp_passive, getcwd, histfile, histsize, inactivity_timeout, index_expire,
+inhibit_startup_message, keep_source_where, load_module_verbosity,
+makepl_arg, make_arg, make_install_arg, make_install_make_command,
+mbuildpl_arg, mbuild_arg, mbuild_install_arg, mbuild_install_build_command,
+pager, prefer_installer, prefs_dir, prerequisites_policy,
+randomize_urllist, scan_cache, shell, show_unparsable_versions,
+show_upload_date, show_zero_versions, tar_verbosity, term_is_latin,
+term_ornaments, test_report, use_sqlite, yaml_load_code, yaml_module
+
+=over 4
+
+=item LICENSE
+
+=back
+
+=head2 CPAN::Kwalify - Interface between CPAN.pm and Kwalify.pm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+_validate($schema_name, $data, $file, $doc), yaml($schema_name)
+
+=item AUTHOR
+
+=item LICENSE
+
+=back
+
+=head2 CPAN::Version - utility functions to compare CPAN versions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item LICENSE
+
+=back
+
+=head2 CPANPLUS - API & CLI access to the CPAN mirrors
+
+=over 4
+
+=item SYNOPSIS
+
+=item GUIDE TO DOCUMENTATION
+
+=over 4
+
+=item GENERAL USAGE
+
+=item API REFERENCE
+
+=back
+
+=back
+
+=over 4
+
+=item COMMANDLINE TOOLS
+
+=over 4
+
+=item STARTING AN INTERACTIVE SHELL
+
+=item BUILDING PACKAGES
+
+=item $bool = install( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+=item $where = fetch( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+=item $where = get( Module::Name | /A/AU/AUTHOR/Module-Name-1.tgz )
+
+=item shell()
+
+=back
+
+=item FAQ
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=item CONTACT INFORMATION
+
+Bug reporting: I<bug-cpanplus at rt.cpan.org>, Questions & suggestions:
+I<cpanplus-devel at lists.sourceforge.net>
+
+=back
+
+=head2 CPANPLUS::Backend
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ENVIRONMENT
+
+=item METHODS
+
+=over 4
+
+=item $cb = CPANPLUS::Backend->new( [CONFIGURE_OBJ] )
+
+Provide a valid C<CPANPLUS::Configure> object, No arguments
+
+=back
+
+=back
+
+=over 4
+
+=item $href = $cb->module_tree( [@modules_names_list] )
+
+=back
+
+=over 4
+
+=item $href = $cb->author_tree( [@author_names_list] )
+
+=back
+
+=over 4
+
+=item $conf = $cb->configure_object;
+
+=back
+
+=over 4
+
+=item $su = $cb->selfupdate_object;
+
+=back
+
+=over 4
+
+=item @mods = $cb->search( type => TYPE, allow => AREF, [data => AREF,
+verbose => BOOL] )
+
+=back
+
+=over 4
+
+=item $backend_rv = $cb->fetch( modules => \@mods )
+
+=item $backend_rv = $cb->extract( modules => \@mods )
+
+=item $backend_rv = $cb->install( modules => \@mods )
+
+=item $backend_rv = $cb->readme( modules => \@mods )
+
+=item $backend_rv = $cb->files( modules => \@mods )
+
+=item $backend_rv = $cb->distributions( modules => \@mods )
+
+=back
+
+=over 4
+
+=item $mod_obj = $cb->parse_module( module =>
+$modname|$distname|$modobj|URI )
+
+Text::Bastardize, Text-Bastardize, Text-Bastardize-1.06,
+AYRNIEU/Text-Bastardize, AYRNIEU/Text-Bastardize-1.06,
+AYRNIEU/Text-Bastardize-1.06.tar.gz,
+http://example.com/Text-Bastardize-1.06.tar.gz,
+file:///tmp/Text-Bastardize-1.06.tar.gz
+
+=back
+
+=over 4
+
+=item $bool = $cb->reload_indices( [update_source => BOOL, verbose => BOOL]
+);
+
+=back
+
+=over 4
+
+=item $bool = $cb->flush(CACHE_NAME)
+
+C<methods>, C<hosts>, C<modules>, C<lib>, C<load>, C<all>
+
+=back
+
+=over 4
+
+=item @mods = $cb->installed()
+
+=back
+
+=over 4
+
+=item $bool = $cb->local_mirror([path => '/dir/to/save/to', index_files =>
+BOOL, force => BOOL, verbose => BOOL] )
+
+path, index_files, force, verbose
+
+=back
+
+=over 4
+
+=item $file = $cb->autobundle([path => OUTPUT_PATH, force => BOOL, verbose
+=> BOOL])
+
+=back
+
+=over 4
+
+=item CUSTOM MODULE SOURCES
+
+=over 4
+
+=item %files = $cb->list_custom_sources
+
+=back
+
+=back
+
+=over 4
+
+=item $local_index = $cb->add_custom_source( uri => URI, [verbose => BOOL]
+);
+
+=back
+
+=over 4
+
+=item $local_index = $cb->remove_custom_source( uri => URI, [verbose =>
+BOOL] );
+
+=back
+
+=over 4
+
+=item $bool = $cb->update_custom_source( [remote => URI] );
+
+=back
+
+=over 4
+
+=item $file = $cb->write_custom_source_index( path =>
+/path/to/package/root, [to => /path/to/index/file, verbose => BOOL] );
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUS::Backend::RV
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item new( ok => BOOL, args => DATA, rv => DATA, [function => $method_name]
+)
+
+ok, args, rv, function
+
+=back
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 CPANPLUS::Config
+
+=over 4
+
+=item DESCRIPTION
+
+=item CONFIGURATION
+
+=back
+
+=over 4
+
+=item Section 'conf'
+
+hosts
+
+=back
+
+base
+
+buildflags
+
+cpantest
+
+cpantest_mx
+
+debug
+
+dist_type
+
+email
+
+extractdir
+
+fetchdir
+
+flush
+
+force
+
+lib
+
+makeflags
+
+makemakerflags
+
+md5
+
+no_update
+
+passive
+
+prefer_bin
+
+prefer_makefile
+
+prereqs
+
+shell
+
+show_startup_tip
+
+signature
+
+skiptest
+
+storable
+
+timeout
+
+verbose
+
+write_install_log
+
+editor
+
+make
+
+pager
+
+shell
+
+sudo
+
+perlwrapper
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUS::Configure
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item $Configure = CPANPLUS::Configure->new( load_configs => BOOL )
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = $Configure->init( [rescan => BOOL])
+
+=back
+
+=over 4
+
+=item can_save( [$config_location] )
+
+=back
+
+=over 4
+
+=item $file = $conf->save( [$package_name] )
+
+=back
+
+=over 4
+
+=item options( type => TYPE )
+
+=back
+
+=over 4
+
+=item ACCESSORS
+
+=over 4
+
+=item get_SOMETHING( ITEM, [ITEM, ITEM, ... ] );
+
+=item set_SOMETHING( ITEM => VAL, [ITEM => VAL, ITEM => VAL, ... ] );
+
+=item add_SOMETHING( ITEM => VAL, [ITEM => VAL, ITEM => VAL, ... ] );
+
+set|get_conf, set|get_program, _set|_get_build, _set|_get_source,
+_set|_get_mirror, _set|_get_fetch
+
+=back
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUS::Dist
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ACCESSORS
+
+parent(), status()
+
+=item STATUS ACCESSORS
+
+created(), installed(), uninstalled(), dist()
+
+=back
+
+=over 4
+
+=item $dist = CPANPLUS::Dist->new( module => MODOBJ, [format => DIST_TYPE]
+);
+
+=back
+
+=over 4
+
+=item @dists = CPANPLUS::Dist->dist_types;
+
+=back
+
+=over 4
+
+=item prereq_satisfied( modobj => $modobj, version => $version_spec )
+
+=back
+
+=over 4
+
+=item _resolve_prereqs
+
+=back
+
+=head2 CPANPLUS::Dist::Base - Base class for custom distribution classes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FLOW
+
+=item METHODS
+
+=back
+
+=over 4
+
+=item $bool = $Class->format_available
+
+=back
+
+=over 4
+
+=item $bool = $dist->init
+
+=back
+
+=over 4
+
+=item $bool = $dist->prepare
+
+=back
+
+=over 4
+
+=item $bool = $dist->create
+
+=back
+
+=over 4
+
+=item $bool = $dist->install
+
+=back
+
+=over 4
+
+=item $bool = $dist->uninstall
+
+=back
+
+=head2 CPANPLUS::Dist::Build
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ACCESSORS
+
+parent(), status()
+
+=item STATUS ACCESSORS
+
+build_pl (), build (), test (), prepared (), distdir (), created (),
+installed (), uninstalled (), _create_args (), _install_args (), _mb_object
+()
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $bool = CPANPLUS::Dist::Build->format_available();
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = $dist->init();
+
+=back
+
+=over 4
+
+=item $bool = $dist->prepare([perl => '/path/to/perl', buildflags =>
+'EXTRA=FLAGS', force => BOOL, verbose => BOOL])
+
+=back
+
+=over 4
+
+=item $dist->create([perl => '/path/to/perl', buildflags => 'EXTRA=FLAGS',
+prereq_target => TARGET, force => BOOL, verbose => BOOL, skiptest => BOOL])
+
+=back
+
+=over 4
+
+=item $dist->install([verbose => BOOL, perl => /path/to/perl])
+
+=back
+
+=over 4
+
+=item KNOWN ISSUES
+
+Module::Build can not be upgraded using its own API (#13169), Module::Build
+does not provide access to install history (#9793)
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 CPANPLUS::Dist::MM
+
+=over 4
+
+=item SYNOPSIS
+
+=item ACCESSORS
+
+parent(), status()
+
+=item STATUS ACCESSORS
+
+makefile (), make (), test (), prepared (), distdir (), created (),
+installed (), uninstalled (), _create_args (), _install_args ()
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $bool = $dist->format_available();
+
+=back
+
+=back
+
+=over 4
+
+=item $href = $dist->_find_prereqs( file => '/path/to/Makefile', [verbose
+=> BOOL])
+
+=back
+
+=over 4
+
+=item $bool = $dist->create([perl => '/path/to/perl', make =>
+'/path/to/make', makeflags => 'EXTRA=FLAGS', prereq_target => TARGET,
+skiptest => BOOL, force => BOOL, verbose => BOOL])
+
+=back
+
+=over 4
+
+=item $bool = $dist->install([make => '/path/to/make', makemakerflags =>
+'EXTRA=FLAGS', force => BOOL, verbose => BOOL])
+
+=back
+
+=over 4
+
+=item $bool = $dist->write_makefile_pl([force => BOOL, verbose => BOOL])
+
+=back
+
+=head2 CPANPLUS::Dist::Sample -- Sample code to create your own Dist::*
+plugin
+
+=over 4
+
+=item Description.
+
+=back
+
+=head2 CPANPLUS::Error
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item cp_msg("message string" [,VERBOSE])
+
+=item msg()
+
+=item cp_error("error string" [,VERBOSE])
+
+=item error()
+
+=back
+
+=item CLASS METHODS
+
+=over 4
+
+=item CPANPLUS::Error->stack()
+
+=item CPANPLUS::Error->stack_as_string([TRACE])
+
+=item CPANPLUS::Error->flush()
+
+=back
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+$ERROR_FH, $MSG_FH
+
+=back
+
+=head2 CPANPLUS::FAQ
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 CPANPLUS::Hacking
+
+=over 4
+
+=item DESCRIPTION
+
+=item OBTAINING CPANPLUS
+
+=item INSTALLING CPANPLUS
+
+=item CONFIGURING CPANPLUS
+
+=item RUNNING CPANPLUS FROM DEVELOPMENT ENVIRONMENT
+
+=item RUNNING CPANPLUS TESTS
+
+=item FINDING BUGS
+
+Problem description, Program demonstrating the bug, [OPTIONAL] A patch to
+the test suite to test for the bug, [OPTIONAL] A patch to the code + tests
++ documentation
+
+=item SUPPLYING PATCHES
+
+In C<diff -u> or C<diff -c> format, From the root of the snapshot,
+Including patches for code + tests + docs, Sent per mail to
+cpanplus-devel at lists.sourceforge.net, With subject containing C<[PATCH]> +
+description of the patch
+
+=back
+
+=head2 CPANPLUS::Internals
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ACCESSORS
+
+_conf, _id, _lib, _perl5lib
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $internals = CPANPLUS::Internals->_init( _conf => CONFIG_OBJ )
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = $internals->_flush( list => \@caches )
+
+=back
+
+=over 4
+
+=item $bool = $internals->_register_callback( name => CALLBACK_NAME, code
+=> CODEREF );
+
+install_prerequisite, send_test_report, munge_test_report,
+edit_test_report, proceed_on_test_failure, munge_dist_metafile
+
+=back
+
+=over 4
+
+=item $bool = $internals->_add_to_includepath( directories => \@dirs )
+
+=back
+
+=over 4
+
+=item $id = CPANPLUS::Internals->_last_id
+
+=item $id = CPANPLUS::Internals->_store_id( $internals )
+
+=item $obj = CPANPLUS::Internals->_retrieve_id( $ID )
+
+=item CPANPLUS::Internals->_remove_id( $ID )
+
+=item @objs = CPANPLUS::Internals->_return_all_objects
+
+=back
+
+=head2 CPANPLUS::Internals::Extract
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item $dir = _extract( module => $modobj, [perl => '/path/to/perl',
+extractdir => '/path/to/extract/to', prefer_bin => BOOL, verbose => BOOL,
+force => BOOL] )
+
+module, extractdir, prefer_bin, perl, verbose, force
+
+=back
+
+=back
+
+=head2 CPANPLUS::Internals::Fetch
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=back
+
+=over 4
+
+=item $path = _fetch( module => $modobj, [fetchdir => '/path/to/save/to',
+fetch_from => 'scheme://path/to/fetch/from', verbose => BOOL, force =>
+BOOL, prefer_bin => BOOL] )
+
+=back
+
+=over 4
+
+=item _add_fail_host( host => $host_hashref )
+
+=item _host_ok( host => $host_hashref )
+
+=back
+
+=head2 CPANPLUS::Internals::Report
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item $bool = $cb->_have_query_report_modules
+
+=item $bool = $cb->_have_send_report_modules
+
+=back
+
+=back
+
+=over 4
+
+=item @list = $cb->_query_report( module => $modobj, [all_versions => BOOL,
+verbose => BOOL] )
+
+=back
+
+=over 4
+
+=item $bool = $cb->_send_report( module => $modobj, buffer => $make_output,
+failed => BOOL, [save => BOOL, address => $email_to, dontcc => BOOL,
+verbose => BOOL, force => BOOL]);
+
+module, buffer, failed, save, address, dontcc, verbose, force
+
+=back
+
+=head2 CPANPLUS::Internals::Search
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item _search_module_tree( type => TYPE, allow => \@regexex, [data =>
+\@previous_results ] )
+
+type, allow, data
+
+=back
+
+=back
+
+=over 4
+
+=item _search_author_tree( type => TYPE, allow => \@regexex, [data =>
+\@previous_results ] )
+
+type, allow, data
+
+=back
+
+=over 4
+
+=item _all_installed()
+
+=back
+
+=head2 CPANPLUS::Internals::Source
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=back
+
+=over 4
+
+=item $cb->_check_trees( [update_source => BOOL, path => PATH, verbose =>
+BOOL] )
+
+update_source, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->__check_uptodate( file => $file, name => $name, [update_source
+=> BOOL, verbose => BOOL] )
+
+file, name, update_source, verbose
+
+=back
+
+=over 4
+
+=item $cb->_update_source( name => $name, [path => $path, verbose => BOOL]
+)
+
+name, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->_build_trees( uptodate => BOOL, [use_stored => BOOL, path =>
+$path, verbose => BOOL] )
+
+uptodate, path, verbose, use_stored
+
+=back
+
+=over 4
+
+=item $cb->__retrieve_source(name => $name, [path => $path, uptodate =>
+BOOL, verbose => BOOL])
+
+name, uptodate, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->_save_source([verbose => BOOL, path => $path])
+
+path, verbose
+
+=back
+
+=over 4
+
+=item $cb->__create_author_tree([path => $path, uptodate => BOOL, verbose
+=> BOOL])
+
+uptodate, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->_create_mod_tree([path => $path, uptodate => BOOL, verbose =>
+BOOL])
+
+uptodate, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->__create_dslip_tree([path => $path, uptodate => BOOL, verbose =>
+BOOL])
+
+uptodate, path, verbose
+
+=back
+
+=over 4
+
+=item $cb->_dslip_defs ()
+
+=back
+
+=over 4
+
+=item $file = $cb->_add_custom_module_source( uri => URI, [verbose => BOOL]
+);
+
+=back
+
+=over 4
+
+=item $index = $cb->__custom_module_source_index_file( uri => $uri );
+
+=back
+
+=over 4
+
+=item $file = $cb->_remove_custom_module_source( uri => URI, [verbose =>
+BOOL] );
+
+=back
+
+=over 4
+
+=item %files = $cb->__list_custom_module_sources
+
+=back
+
+=over 4
+
+=item $bool = $cb->__update_custom_module_sources( [verbose => BOOL] );
+
+=back
+
+=over 4
+
+=item $ok = $cb->__update_custom_module_source
+
+=back
+
+=over 4
+
+=item $bool = $cb->__write_custom_module_index( path => /path/to/packages,
+[to => /path/to/index/file, verbose => BOOL] )
+
+=back
+
+=over 4
+
+=item $bool = $cb->__create_custom_module_entries( [verbose => BOOL] )
+
+=back
+
+=head2 CPANPLUS::Internals::Utils
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item $cb->_mkdir( dir => '/some/dir' )
+
+=back
+
+=back
+
+=over 4
+
+=item $cb->_chdir( dir => '/some/dir' )
+
+=back
+
+=over 4
+
+=item $cb->_rmdir( dir => '/some/dir' );
+
+=back
+
+=over 4
+
+=item $cb->_perl_version ( perl => 'some/perl/binary' );
+
+=back
+
+=over 4
+
+=item $cb->_version_to_number( version => $version );
+
+=back
+
+=over 4
+
+=item $cb->_whoami
+
+=back
+
+=over 4
+
+=item _get_file_contents( file => $file );
+
+=back
+
+=over 4
+
+=item $cb->_mode_plus_w( file => '/path/to/file' );
+
+=back
+
+=over 4
+
+=item $uri = $cb->_host_to_uri( scheme => SCHEME, host => HOST, path =>
+PATH );
+
+=back
+
+=over 4
+
+=item $cb->_vcmp( VERSION, VERSION );
+
+=back
+
+=over 4
+
+=item $cb->_home_dir
+
+=back
+
+=over 4
+
+=item $path = $cb->_safe_path( path => $path );
+
+=back
+
+=over 4
+
+=item ($pkg, $version, $ext) = $cb->_split_package_string( package =>
+PACKAGE_STRING );
+
+=back
+
+=head2 CPANPLUS::Module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item CLASS METHODS
+
+=over 4
+
+=item accessors ()
+
+=back
+
+=back
+
+=over 4
+
+=item ACCESSORS
+
+name, module, version, path, comment, package, description, dslip
+
+=back
+
+status, author, parent
+
+=over 4
+
+=item STATUS ACCESSORS
+
+installer_type, dist_cpan, dist, prereqs, signature, extract, fetch,
+readme, uninstall, created, installed, checksums, checksum_ok,
+checksum_value
+
+=item METHODS
+
+=over 4
+
+=item $self = CPANPLUS::Module::new( OPTIONS )
+
+=back
+
+=back
+
+=over 4
+
+=item $mod->package_name
+
+=item $mod->package_version
+
+=item $mod->package_extension
+
+=item $mod->package_is_perl_core
+
+=item $mod->module_is_supplied_with_perl_core( [version => $]] )
+
+=item $mod->is_bundle
+
+=item $mod->is_third_party
+
+=item $mod->third_party_information
+
+=back
+
+=over 4
+
+=item $clone = $self->clone
+
+=back
+
+=over 4
+
+=item $where = $self->fetch
+
+=back
+
+=over 4
+
+=item $path = $self->extract
+
+=back
+
+=over 4
+
+=item $type = $self->get_installer_type([prefer_makefile => BOOL])
+
+=back
+
+=over 4
+
+=item $dist = $self->dist([target => 'prepare|create', format =>
+DISTRIBUTION_TYPE, args => {key => val}]);
+
+=back
+
+=over 4
+
+=item $bool = $mod->prepare( )
+
+Convenience method around C<install()> that prepares a module
+without actually building it. This is equivalent to invoking C<install>
+with C<target> set to C<prepare>
+
+=back
+
+=over 4
+
+=item $bool = $mod->create( )
+
+=back
+
+=over 4
+
+=item $bool = $mod->test( )
+
+=back
+
+=over 4
+
+=item $bool = $self->install([ target => 'prepare|create|install', format
+=> FORMAT_TYPE, extractdir => DIRECTORY, fetchdir => DIRECTORY, prefer_bin
+=> BOOL, force => BOOL, verbose => BOOL, ..... ]);
+
+=back
+
+=over 4
+
+=item $text = $self->readme
+
+=back
+
+=over 4
+
+=item $version = $self->installed_version()
+
+=item $where = $self->installed_file()
+
+=item $bool = $self->is_uptodate([version => VERSION_NUMBER])
+
+=back
+
+=over 4
+
+=item $href = $self->details()
+
+=back
+
+=over 4
+
+=item @list = $self->contains()
+
+=back
+
+=over 4
+
+=item @list_of_hrefs = $self->fetch_report()
+
+=back
+
+=over 4
+
+=item $bool = $self->uninstall([type => [all|man|prog])
+
+=back
+
+=over 4
+
+=item @modobj = $self->distributions()
+
+=back
+
+=over 4
+
+=item @list = $self->files ()
+
+=back
+
+=over 4
+
+=item @list = $self->directory_tree ()
+
+=back
+
+=over 4
+
+=item @list = $self->packlist ()
+
+=back
+
+=over 4
+
+=item @list = $self->validate ()
+
+=back
+
+=over 4
+
+=item $bool = $self->add_to_includepath;
+
+=item $path = $self->best_path_to_module_build();
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 CPANPLUS::Module::Author
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ACCESSORS
+
+author, cpanid, email, parent
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $auth = CPANPLUS::Module::Author->new( author => AUTHOR_NAME, cpanid
+=> CPAN_ID, _id => INTERNALS_ID [, email => AUTHOR_EMAIL] )
+
+=back
+
+=back
+
+=over 4
+
+=item @mod_objs = $auth->modules()
+
+=back
+
+=over 4
+
+=item @dists = $auth->distributions()
+
+=back
+
+=over 4
+
+=item CLASS METHODS
+
+=over 4
+
+=item accessors ()
+
+=back
+
+=back
+
+=head2 CPANPLUS::Module::Author::Fake
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item new( _id => DIGIT )
+
+=back
+
+=back
+
+=head2 CPANPLUS::Module::Checksums
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item $mod->checksums
+
+=back
+
+=back
+
+=head2 CPANPLUS::Module::Fake
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item new( module => $mod, path => $path, package => $pkg, [_id => DIGIT] )
+
+=back
+
+=back
+
+=head2 CPANPLUS::inc
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 CPANPLUS::inc - runtime inclusion of privately bundled modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+Put a coderef at the beginning of C<@INC>, Add the full path to the
+C<CPANPLUS/inc> directory to C<$ENV{PERL5LIB>
+
+=item METHODS
+
+=over 4
+
+=item CPANPLUS::inc->inc_path()
+
+=item CPANPLUS::inc->my_path()
+
+=item CPANPLUS::inc->installer_path()
+
+=back
+
+=back
+
+=over 4
+
+=item CPANPLUS::inc->original_perl5lib
+
+=item CPANPLUS::inc->original_perl5opt
+
+=item CPANPLUS::inc->original_inc
+
+=item CPANPLUS::inc->limited_perl5opt(@modules);
+
+=back
+
+=over 4
+
+=item CPANPLUS::inc->interesting_modules()
+
+=back
+
+=over 4
+
+=item INTERESTING MODULES
+
+Loop over your @INC, Check the version on every suitable module found in
+ at INC
+
+=back
+
+=over 4
+
+=item DEBUG
+
+=item CAVEATS
+
+On multiple C<use lib> calls, our coderef may not be the first in @INC,
+Non-directories in @INC
+
+=back
+
+=head2 CPANPLUSelfupdate, CPANPLUS::Selfupdate
+
+=over 4
+
+=item SYNOPSIS
+
+=back
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $self = CPANPLUS::Selfupdate->new( $backend_object );
+
+=back
+
+=back
+
+=over 4
+
+=item %list = $self->list_modules_to_update( update =>
+"core|dependencies|enabled_features|features|all", [latest => BOOL] )
+
+List which modules C<selfupdate> would upgrade. You can update either
+the core (CPANPLUS itself), the core dependencies, all features you have
+currently turned on, or all features available, or everything.
+
+=back
+
+=over 4
+
+=item @features = $self->list_features
+
+=back
+
+=over 4
+
+=item @features = $self->list_enabled_features
+
+=back
+
+=over 4
+
+=item @mods = $self->modules_for_feature( FEATURE [,AS_HASH] )
+
+=back
+
+=over 4
+
+=item @mods = $self->list_core_dependencies( [AS_HASH] )
+
+=back
+
+=over 4
+
+=item @mods = $self->list_core_modules( [AS_HASH] )
+
+=back
+
+=over 4
+
+=item CPANPLUS::Selfupdate::Module
+
+=back
+
+=over 4
+
+=item $version = $mod->version_required
+
+=back
+
+=over 4
+
+=item $bool = $mod->is_installed_version_sufficient
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 CPANPLUShell, CPANPLUS::Shell
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUShell::Classic, CPANPLUS::Shell::Classic - CPAN.pm emulation
+for CPANPLUS
+
+=over 4
+
+=item DESCRIPTION
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=over 4
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUShell::Default, CPANPLUS::Shell::Default
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUShell::Default::Plugins::CustomSource,
+CPANPLUS::Shell::Default::Plugins::CustomSource
+
+=over 4
+
+=item SYNOPSIS
+
+ ### elaborate help text
+ CPAN Terminal> /? cs
+
+=item DESCRIPTION
+
+=back
+
+=head2 CPANPLUShell::Default::Plugins::HOWTO,
+CPANPLUS::Shell::Default::Plugins::HOWTO -- documentation on how to write
+your own plugins
+
+=over 4
+
+=item SYNOPSIS
+
+=item HOWTO
+
+=over 4
+
+=item Registering Plugin Modules
+
+=item Registering Plugin Commands
+
+=item Registering Plugin Help
+
+=item Arguments to Plugin Commands
+
+Classname -- The name of your plugin class, Shell -- The
+CPANPLUS::Shell::Default object, Backend -- The CPANPLUS::Backend object,
+Command -- The command issued by the user, Input -- The input string
+from the user, Options -- A hashref of options provided by the user
+
+=back
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUShell::Default::Plugins::Remote,
+CPANPLUS::Shell::Default::Plugins::Remote
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANPLUShell::Default::Plugins::Source,
+CPANPLUS::Shell::Default::Plugins::Source
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 CPANox, CPAN::Nox - Wrapper around CPAN.pm without using any XS
+module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item LICENSE
+
+=item SEE ALSO
+
+=back
+
+=head2 Carp, carp - warn of errors (from perspective of caller)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Forcing a Stack Trace
+
+=back
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Carp::MaxEvalLen
+
+=item $Carp::MaxArgLen
+
+=item $Carp::MaxArgNums
+
+=item $Carp::Verbose
+
+=item %Carp::Internal
+
+=item %Carp::CarpInternal
+
+=item $Carp::CarpLevel
+
+=back
+
+=item BUGS
+
+=back
+
+=head2 Carp::Heavy - heavy machinery, no user serviceable parts inside
+
+=head2 Class::ISA -- report the search path for a class's ISA tree
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+the function Class::ISA::super_path($CLASS), the function
+Class::ISA::self_and_super_path($CLASS), the function
+Class::ISA::self_and_super_versions($CLASS)
+
+=item CAUTIONARY NOTES
+
+=item COPYRIGHT
+
+=item AUTHOR
+
+=back
+
+=head2 Class::Struct - declare struct-like datatypes as Perl classes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item The C<struct()> function
+
+=item Class Creation at Compile Time
+
+=item Element Types and Accessor Methods
+
+Scalar (C<'$'> or C<'*$'>), Array (C<'@'> or C<'*@'>), Hash (C<'%'> or
+C<'*%'>), Class (C<'Class_Name'> or C<'*Class_Name'>)
+
+=item Initializing with C<new>
+
+=back
+
+=item EXAMPLES
+
+Example 1, Example 2, Example 3
+
+=item Author and Modification History
+
+=back
+
+=head2 Compress::Raw::Zlib - Low-Level Interface to zlib compression
+library
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Compress::Raw::Zlib::Deflate
+
+=over 4
+
+=item B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
+
+B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
+B<-Dictionary>, B<-Bufsize>, B<-AppendOutput>, B<-CRC32>, B<-ADLER32>
+
+=item B<$status = $d-E<gt>deflate($input, $output)>
+
+=item B<$status = $d-E<gt>flush($output [, $flush_type]) >
+
+=item B<$status = $d-E<gt>deflateParams([OPT])>
+
+B<-Level>, B<-Strategy>, B<-BufSize>
+
+=item B<$status = $d-E<gt>deflateTune($good_length, $max_lazy,
+$nice_length, $max_chain)>
+
+=item B<$d-E<gt>dict_adler()>
+
+=item B<$d-E<gt>crc32()>
+
+=item B<$d-E<gt>adler32()>
+
+=item B<$d-E<gt>msg()>
+
+=item B<$d-E<gt>total_in()>
+
+=item B<$d-E<gt>total_out()>
+
+=item B<$d-E<gt>get_Strategy()>
+
+=item B<$d-E<gt>get_Level()>
+
+=item B<$d-E<gt>get_BufSize()>
+
+=item Example
+
+=back
+
+=item Compress::Raw::Zlib::Inflate
+
+=over 4
+
+=item B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
+
+B<-WindowBits>, B<-Bufsize>, B<-Dictionary>, B<-AppendOutput>, B<-CRC32>,
+B<-ADLER32>, B<-ConsumeInput>
+
+=item B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
+
+=item B<$status = $i-E<gt>inflateSync($input)>
+
+=item B<$i-E<gt>dict_adler()>
+
+=item B<$i-E<gt>crc32()>
+
+=item B<$i-E<gt>adler32()>
+
+=item B<$i-E<gt>msg()>
+
+=item B<$i-E<gt>total_in()>
+
+=item B<$i-E<gt>total_out()>
+
+=item B<$d-E<gt>get_BufSize()>
+
+=item Example
+
+=back
+
+=item CHECKSUM FUNCTIONS
+
+=item ACCESSING ZIP FILES
+
+=item CONSTANTS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Compress::Raw::Zlib::Compress::Raw::Zlib, Compress::Raw::Zlib -
+Low-Level Interface to zlib compression library
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Compress::Raw::Zlib::Deflate
+
+=over 4
+
+=item B<($d, $status) = new Compress::Raw::Zlib::Deflate( [OPT] ) >
+
+B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
+B<-Dictionary>, B<-Bufsize>, B<-AppendOutput>, B<-CRC32>, B<-ADLER32>
+
+=item B<$status = $d-E<gt>deflate($input, $output)>
+
+=item B<$status = $d-E<gt>flush($output [, $flush_type]) >
+
+=item B<$status = $d-E<gt>deflateParams([OPT])>
+
+B<-Level>, B<-Strategy>, B<-BufSize>
+
+=item B<$status = $d-E<gt>deflateTune($good_length, $max_lazy,
+$nice_length, $max_chain)>
+
+=item B<$d-E<gt>dict_adler()>
+
+=item B<$d-E<gt>crc32()>
+
+=item B<$d-E<gt>adler32()>
+
+=item B<$d-E<gt>msg()>
+
+=item B<$d-E<gt>total_in()>
+
+=item B<$d-E<gt>total_out()>
+
+=item B<$d-E<gt>get_Strategy()>
+
+=item B<$d-E<gt>get_Level()>
+
+=item B<$d-E<gt>get_BufSize()>
+
+=item Example
+
+=back
+
+=item Compress::Raw::Zlib::Inflate
+
+=over 4
+
+=item B< ($i, $status) = new Compress::Raw::Zlib::Inflate( [OPT] ) >
+
+B<-WindowBits>, B<-Bufsize>, B<-Dictionary>, B<-AppendOutput>, B<-CRC32>,
+B<-ADLER32>, B<-ConsumeInput>
+
+=item B< $status = $i-E<gt>inflate($input, $output [,$eof]) >
+
+=item B<$status = $i-E<gt>inflateSync($input)>
+
+=item B<$i-E<gt>dict_adler()>
+
+=item B<$i-E<gt>crc32()>
+
+=item B<$i-E<gt>adler32()>
+
+=item B<$i-E<gt>msg()>
+
+=item B<$i-E<gt>total_in()>
+
+=item B<$i-E<gt>total_out()>
+
+=item B<$d-E<gt>get_BufSize()>
+
+=item Example
+
+=back
+
+=item CHECKSUM FUNCTIONS
+
+=item ACCESSING ZIP FILES
+
+=item CONSTANTS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Compress::Zlib - Interface to zlib compression library
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Notes for users of Compress::Zlib version 1
+
+=back
+
+=item GZIP INTERFACE
+
+B<$gz = gzopen($filename, $mode)>, B<$gz = gzopen($filehandle, $mode)>,
+B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>, B<$bytesread =
+$gz-E<gt>gzreadline($line) ;>, B<$byteswritten = $gz-E<gt>gzwrite($buffer)
+;>, B<$status = $gz-E<gt>gzflush($flush_type) ;>, B<$offset =
+$gz-E<gt>gztell() ;>, B<$status = $gz-E<gt>gzseek($offset, $whence) ;>,
+B<$gz-E<gt>gzclose>, B<$gz-E<gt>gzsetparams($level, $strategy>, B<$level>,
+B<$strategy>, B<$gz-E<gt>gzerror>, B<$gzerrno>
+
+=over 4
+
+=item Examples
+
+=item Compress::Zlib::memGzip
+
+=item Compress::Zlib::memGunzip
+
+=back
+
+=item COMPRESS/UNCOMPRESS
+
+B<$dest = compress($source [, $level] ) ;>, B<$dest = uncompress($source)
+;>
+
+=item Deflate Interface
+
+=over 4
+
+=item B<($d, $status) = deflateInit( [OPT] )>
+
+B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
+B<-Dictionary>, B<-Bufsize>
+
+=item B<($out, $status) = $d-E<gt>deflate($buffer)>
+
+=item B<($out, $status) = $d-E<gt>flush([flush_type])>
+
+=item B<$status = $d-E<gt>deflateParams([OPT])>
+
+B<-Level>, B<-Strategy>
+
+=item B<$d-E<gt>dict_adler()>
+
+=item B<$d-E<gt>msg()>
+
+=item B<$d-E<gt>total_in()>
+
+=item B<$d-E<gt>total_out()>
+
+=item Example
+
+=back
+
+=item Inflate Interface
+
+=over 4
+
+=item B<($i, $status) = inflateInit()>
+
+B<-WindowBits>, B<-Bufsize>, B<-Dictionary>
+
+=item B<($out, $status) = $i-E<gt>inflate($buffer)>
+
+=item B<$status = $i-E<gt>inflateSync($buffer)>
+
+=item B<$i-E<gt>dict_adler()>
+
+=item B<$i-E<gt>msg()>
+
+=item B<$i-E<gt>total_in()>
+
+=item B<$i-E<gt>total_out()>
+
+=item Example
+
+=back
+
+=item CHECKSUM FUNCTIONS
+
+=item CONSTANTS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Compress::Zlib::Compress::Zlib, Compress::Zlib - Interface to zlib
+compression library
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Notes for users of Compress::Zlib version 1
+
+=back
+
+=item GZIP INTERFACE
+
+B<$gz = gzopen($filename, $mode)>, B<$gz = gzopen($filehandle, $mode)>,
+B<$bytesread = $gz-E<gt>gzread($buffer [, $size]) ;>, B<$bytesread =
+$gz-E<gt>gzreadline($line) ;>, B<$byteswritten = $gz-E<gt>gzwrite($buffer)
+;>, B<$status = $gz-E<gt>gzflush($flush_type) ;>, B<$offset =
+$gz-E<gt>gztell() ;>, B<$status = $gz-E<gt>gzseek($offset, $whence) ;>,
+B<$gz-E<gt>gzclose>, B<$gz-E<gt>gzsetparams($level, $strategy>, B<$level>,
+B<$strategy>, B<$gz-E<gt>gzerror>, B<$gzerrno>
+
+=over 4
+
+=item Examples
+
+=item Compress::Zlib::memGzip
+
+=item Compress::Zlib::memGunzip
+
+=back
+
+=item COMPRESS/UNCOMPRESS
+
+B<$dest = compress($source [, $level] ) ;>, B<$dest = uncompress($source)
+;>
+
+=item Deflate Interface
+
+=over 4
+
+=item B<($d, $status) = deflateInit( [OPT] )>
+
+B<-Level>, B<-Method>, B<-WindowBits>, B<-MemLevel>, B<-Strategy>,
+B<-Dictionary>, B<-Bufsize>
+
+=item B<($out, $status) = $d-E<gt>deflate($buffer)>
+
+=item B<($out, $status) = $d-E<gt>flush([flush_type])>
+
+=item B<$status = $d-E<gt>deflateParams([OPT])>
+
+B<-Level>, B<-Strategy>
+
+=item B<$d-E<gt>dict_adler()>
+
+=item B<$d-E<gt>msg()>
+
+=item B<$d-E<gt>total_in()>
+
+=item B<$d-E<gt>total_out()>
+
+=item Example
+
+=back
+
+=item Inflate Interface
+
+=over 4
+
+=item B<($i, $status) = inflateInit()>
+
+B<-WindowBits>, B<-Bufsize>, B<-Dictionary>
+
+=item B<($out, $status) = $i-E<gt>inflate($buffer)>
+
+=item B<$status = $i-E<gt>inflateSync($buffer)>
+
+=item B<$i-E<gt>dict_adler()>
+
+=item B<$i-E<gt>msg()>
+
+=item B<$i-E<gt>total_in()>
+
+=item B<$i-E<gt>total_out()>
+
+=item Example
+
+=back
+
+=item CHECKSUM FUNCTIONS
+
+=item CONSTANTS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Config - access Perl configuration information
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+myconfig(), config_sh(), config_re($regex), config_vars(@names)
+
+=item EXAMPLE
+
+=item WARNING
+
+=item GLOSSARY
+
+=over 4
+
+=item _
+
+C<_a>, C<_exe>, C<_o>
+
+=item a
+
+C<afs>, C<afsroot>, C<alignbytes>, C<ansi2knr>, C<aphostname>,
+C<api_revision>, C<api_subversion>, C<api_version>, C<api_versionstring>,
+C<ar>, C<archlib>, C<archlibexp>, C<archname>, C<archname64>, C<archobjs>,
+C<asctime_r_proto>, C<awk>
+
+=item b
+
+C<baserev>, C<bash>, C<bin>, C<binexp>, C<bison>, C<byacc>, C<byteorder>
+
+=item c
+
+C<c>, C<castflags>, C<cat>, C<cc>, C<cccdlflags>, C<ccdlflags>, C<ccflags>,
+C<ccflags_uselargefiles>, C<ccname>, C<ccsymbols>, C<ccversion>, C<cf_by>,
+C<cf_email>, C<cf_time>, C<chgrp>, C<chmod>, C<chown>, C<clocktype>,
+C<comm>, C<compress>, C<contains>, C<cp>, C<cpio>, C<cpp>, C<cpp_stuff>,
+C<cppccsymbols>, C<cppflags>, C<cpplast>, C<cppminus>, C<cpprun>,
+C<cppstdin>, C<cppsymbols>, C<crypt_r_proto>, C<cryptlib>, C<csh>,
+C<ctermid_r_proto>, C<ctime_r_proto>
+
+=item d
+
+C<d__fwalk>, C<d_access>, C<d_accessx>, C<d_aintl>, C<d_alarm>,
+C<d_archlib>, C<d_asctime_r>, C<d_atolf>, C<d_atoll>,
+C<d_attribute_format>, C<d_attribute_malloc>, C<d_attribute_nonnull>,
+C<d_attribute_noreturn>, C<d_attribute_pure>, C<d_attribute_unused>,
+C<d_attribute_warn_unused_result>, C<d_bcmp>, C<d_bcopy>, C<d_bsd>,
+C<d_bsdgetpgrp>, C<d_bsdsetpgrp>, C<d_builtin_choose_expr>,
+C<d_builtin_expect>, C<d_bzero>, C<d_c99_variadic_macros>, C<d_casti32>,
+C<d_castneg>, C<d_charvspr>, C<d_chown>, C<d_chroot>, C<d_chsize>,
+C<d_class>, C<d_clearenv>, C<d_closedir>, C<d_cmsghdr_s>, C<d_const>,
+C<d_copysignl>, C<d_cplusplus>, C<d_crypt>, C<d_crypt_r>, C<d_csh>,
+C<d_ctermid>, C<d_ctermid_r>, C<d_ctime_r>, C<d_cuserid>, C<d_dbl_dig>,
+C<d_dbminitproto>, C<d_difftime>, C<d_dir_dd_fd>, C<d_dirfd>,
+C<d_dirnamlen>, C<d_dlerror>, C<d_dlopen>, C<d_dlsymun>, C<d_dosuid>,
+C<d_drand48_r>, C<d_drand48proto>, C<d_dup2>, C<d_eaccess>, C<d_endgrent>,
+C<d_endgrent_r>, C<d_endhent>, C<d_endhostent_r>, C<d_endnent>,
+C<d_endnetent_r>, C<d_endpent>, C<d_endprotoent_r>, C<d_endpwent>,
+C<d_endpwent_r>, C<d_endsent>, C<d_endservent_r>, C<d_eofnblk>,
+C<d_eunice>, C<d_faststdio>, C<d_fchdir>, C<d_fchmod>, C<d_fchown>,
+C<d_fcntl>, C<d_fcntl_can_lock>, C<d_fd_macros>, C<d_fd_set>,
+C<d_fds_bits>, C<d_fgetpos>, C<d_finite>, C<d_finitel>, C<d_flexfnam>,
+C<d_flock>, C<d_flockproto>, C<d_fork>, C<d_fp_class>, C<d_fpathconf>,
+C<d_fpclass>, C<d_fpclassify>, C<d_fpclassl>, C<d_fpos64_t>, C<d_frexpl>,
+C<d_fs_data_s>, C<d_fseeko>, C<d_fsetpos>, C<d_fstatfs>, C<d_fstatvfs>,
+C<d_fsync>, C<d_ftello>, C<d_ftime>, C<d_futimes>, C<d_Gconvert>,
+C<d_getcwd>, C<d_getespwnam>, C<d_getfsstat>, C<d_getgrent>,
+C<d_getgrent_r>, C<d_getgrgid_r>, C<d_getgrnam_r>, C<d_getgrps>,
+C<d_gethbyaddr>, C<d_gethbyname>, C<d_gethent>, C<d_gethname>,
+C<d_gethostbyaddr_r>, C<d_gethostbyname_r>, C<d_gethostent_r>,
+C<d_gethostprotos>, C<d_getitimer>, C<d_getlogin>, C<d_getlogin_r>,
+C<d_getmnt>, C<d_getmntent>, C<d_getnbyaddr>, C<d_getnbyname>,
+C<d_getnent>, C<d_getnetbyaddr_r>, C<d_getnetbyname_r>, C<d_getnetent_r>,
+C<d_getnetprotos>, C<d_getpagsz>, C<d_getpbyname>, C<d_getpbynumber>,
+C<d_getpent>, C<d_getpgid>, C<d_getpgrp>, C<d_getpgrp2>, C<d_getppid>,
+C<d_getprior>, C<d_getprotobyname_r>, C<d_getprotobynumber_r>,
+C<d_getprotoent_r>, C<d_getprotoprotos>, C<d_getprpwnam>, C<d_getpwent>,
+C<d_getpwent_r>, C<d_getpwnam_r>, C<d_getpwuid_r>, C<d_getsbyname>,
+C<d_getsbyport>, C<d_getsent>, C<d_getservbyname_r>, C<d_getservbyport_r>,
+C<d_getservent_r>, C<d_getservprotos>, C<d_getspnam>, C<d_getspnam_r>,
+C<d_gettimeod>, C<d_gmtime_r>, C<d_gnulibc>, C<d_grpasswd>, C<d_hasmntopt>,
+C<d_htonl>, C<d_ilogbl>, C<d_inc_version_list>, C<d_index>, C<d_inetaton>,
+C<d_int64_t>, C<d_isascii>, C<d_isfinite>, C<d_isinf>, C<d_isnan>,
+C<d_isnanl>, C<d_killpg>, C<d_lchown>, C<d_ldbl_dig>,
+C<d_libm_lib_version>, C<d_link>, C<d_localtime_r>,
+C<d_localtime_r_needs_tzset>, C<d_locconv>, C<d_lockf>, C<d_longdbl>,
+C<d_longlong>, C<d_lseekproto>, C<d_lstat>, C<d_madvise>,
+C<d_malloc_good_size>, C<d_malloc_size>, C<d_mblen>, C<d_mbstowcs>,
+C<d_mbtowc>, C<d_memchr>, C<d_memcmp>, C<d_memcpy>, C<d_memmove>,
+C<d_memset>, C<d_mkdir>, C<d_mkdtemp>, C<d_mkfifo>, C<d_mkstemp>,
+C<d_mkstemps>, C<d_mktime>, C<d_mmap>, C<d_modfl>, C<d_modfl_pow32_bug>,
+C<d_modflproto>, C<d_mprotect>, C<d_msg>, C<d_msg_ctrunc>,
+C<d_msg_dontroute>, C<d_msg_oob>, C<d_msg_peek>, C<d_msg_proxy>,
+C<d_msgctl>, C<d_msgget>, C<d_msghdr_s>, C<d_msgrcv>, C<d_msgsnd>,
+C<d_msync>, C<d_munmap>, C<d_mymalloc>, C<d_nice>, C<d_nl_langinfo>,
+C<d_nv_preserves_uv>, C<d_nv_zero_is_allbits_zero>, C<d_off64_t>,
+C<d_old_pthread_create_joinable>, C<d_oldpthreads>, C<d_oldsock>,
+C<d_open3>, C<d_pathconf>, C<d_pause>, C<d_perl_otherlibdirs>,
+C<d_phostname>, C<d_pipe>, C<d_poll>, C<d_portable>, C<d_PRId64>,
+C<d_PRIeldbl>, C<d_PRIEUldbl>, C<d_PRIfldbl>, C<d_PRIFUldbl>,
+C<d_PRIgldbl>, C<d_PRIGUldbl>, C<d_PRIi64>, C<d_printf_format_null>,
+C<d_PRIo64>, C<d_PRIu64>, C<d_PRIx64>, C<d_PRIXU64>, C<d_procselfexe>,
+C<d_pseudofork>, C<d_pthread_atfork>, C<d_pthread_attr_setscope>,
+C<d_pthread_yield>, C<d_pwage>, C<d_pwchange>, C<d_pwclass>,
+C<d_pwcomment>, C<d_pwexpire>, C<d_pwgecos>, C<d_pwpasswd>, C<d_pwquota>,
+C<d_qgcvt>, C<d_quad>, C<d_random_r>, C<d_readdir>, C<d_readdir64_r>,
+C<d_readdir_r>, C<d_readlink>, C<d_readv>, C<d_recvmsg>, C<d_rename>,
+C<d_rewinddir>, C<d_rmdir>, C<d_safebcpy>, C<d_safemcpy>, C<d_sanemcmp>,
+C<d_sbrkproto>, C<d_scalbnl>, C<d_sched_yield>, C<d_scm_rights>,
+C<d_SCNfldbl>, C<d_seekdir>, C<d_select>, C<d_sem>, C<d_semctl>,
+C<d_semctl_semid_ds>, C<d_semctl_semun>, C<d_semget>, C<d_semop>,
+C<d_sendmsg>, C<d_setegid>, C<d_seteuid>, C<d_setgrent>, C<d_setgrent_r>,
+C<d_setgrps>, C<d_sethent>, C<d_sethostent_r>, C<d_setitimer>,
+C<d_setlinebuf>, C<d_setlocale>, C<d_setlocale_r>, C<d_setnent>,
+C<d_setnetent_r>, C<d_setpent>, C<d_setpgid>, C<d_setpgrp>, C<d_setpgrp2>,
+C<d_setprior>, C<d_setproctitle>, C<d_setprotoent_r>, C<d_setpwent>,
+C<d_setpwent_r>, C<d_setregid>, C<d_setresgid>, C<d_setresuid>,
+C<d_setreuid>, C<d_setrgid>, C<d_setruid>, C<d_setsent>, C<d_setservent_r>,
+C<d_setsid>, C<d_setvbuf>, C<d_sfio>, C<d_shm>, C<d_shmat>,
+C<d_shmatprototype>, C<d_shmctl>, C<d_shmdt>, C<d_shmget>, C<d_sigaction>,
+C<d_signbit>, C<d_sigprocmask>, C<d_sigsetjmp>, C<d_sitearch>,
+C<d_snprintf>, C<d_sockatmark>, C<d_sockatmarkproto>, C<d_socket>,
+C<d_socklen_t>, C<d_sockpair>, C<d_socks5_init>,
+C<d_sprintf_returns_strlen>, C<d_sqrtl>, C<d_srand48_r>, C<d_srandom_r>,
+C<d_sresgproto>, C<d_sresuproto>, C<d_statblks>, C<d_statfs_f_flags>,
+C<d_statfs_s>, C<d_statvfs>, C<d_stdio_cnt_lval>, C<d_stdio_ptr_lval>,
+C<d_stdio_ptr_lval_nochange_cnt>, C<d_stdio_ptr_lval_sets_cnt>,
+C<d_stdio_stream_array>, C<d_stdiobase>, C<d_stdstdio>, C<d_strchr>,
+C<d_strcoll>, C<d_strctcpy>, C<d_strerrm>, C<d_strerror>, C<d_strerror_r>,
+C<d_strftime>, C<d_strlcat>, C<d_strlcpy>, C<d_strtod>, C<d_strtol>,
+C<d_strtold>, C<d_strtoll>, C<d_strtoq>, C<d_strtoul>, C<d_strtoull>,
+C<d_strtouq>, C<d_strxfrm>, C<d_suidsafe>, C<d_symlink>, C<d_syscall>,
+C<d_syscallproto>, C<d_sysconf>, C<d_sysernlst>, C<d_syserrlst>,
+C<d_system>, C<d_tcgetpgrp>, C<d_tcsetpgrp>, C<d_telldir>,
+C<d_telldirproto>, C<d_time>, C<d_times>, C<d_tm_tm_gmtoff>,
+C<d_tm_tm_zone>, C<d_tmpnam_r>, C<d_truncate>, C<d_ttyname_r>, C<d_tzname>,
+C<d_u32align>, C<d_ualarm>, C<d_umask>, C<d_uname>, C<d_union_semun>,
+C<d_unordered>, C<d_unsetenv>, C<d_usleep>, C<d_usleepproto>, C<d_ustat>,
+C<d_vendorarch>, C<d_vendorbin>, C<d_vendorlib>, C<d_vendorscript>,
+C<d_vfork>, C<d_void_closedir>, C<d_voidsig>, C<d_voidtty>, C<d_volatile>,
+C<d_vprintf>, C<d_vsnprintf>, C<d_wait4>, C<d_waitpid>, C<d_wcstombs>,
+C<d_wctomb>, C<d_writev>, C<d_xenix>, C<date>, C<db_hashtype>,
+C<db_prefixtype>, C<db_version_major>, C<db_version_minor>,
+C<db_version_patch>, C<defvoidused>, C<direntrytype>, C<dlext>, C<dlsrc>,
+C<doublesize>, C<drand01>, C<drand48_r_proto>, C<dynamic_ext>
+
+=item e
+
+C<eagain>, C<ebcdic>, C<echo>, C<egrep>, C<emacs>, C<endgrent_r_proto>,
+C<endhostent_r_proto>, C<endnetent_r_proto>, C<endprotoent_r_proto>,
+C<endpwent_r_proto>, C<endservent_r_proto>, C<eunicefix>, C<exe_ext>,
+C<expr>, C<extensions>, C<extras>
+
+=item f
+
+C<fflushall>, C<fflushNULL>, C<find>, C<firstmakefile>, C<flex>,
+C<fpossize>, C<fpostype>, C<freetype>, C<from>, C<full_ar>, C<full_csh>,
+C<full_sed>
+
+=item g
+
+C<gccansipedantic>, C<gccosandvers>, C<gccversion>, C<getgrent_r_proto>,
+C<getgrgid_r_proto>, C<getgrnam_r_proto>, C<gethostbyaddr_r_proto>,
+C<gethostbyname_r_proto>, C<gethostent_r_proto>, C<getlogin_r_proto>,
+C<getnetbyaddr_r_proto>, C<getnetbyname_r_proto>, C<getnetent_r_proto>,
+C<getprotobyname_r_proto>, C<getprotobynumber_r_proto>,
+C<getprotoent_r_proto>, C<getpwent_r_proto>, C<getpwnam_r_proto>,
+C<getpwuid_r_proto>, C<getservbyname_r_proto>, C<getservbyport_r_proto>,
+C<getservent_r_proto>, C<getspnam_r_proto>, C<gidformat>, C<gidsign>,
+C<gidsize>, C<gidtype>, C<glibpth>, C<gmake>, C<gmtime_r_proto>,
+C<gnulibc_version>, C<grep>, C<groupcat>, C<groupstype>, C<gzip>
+
+=item h
+
+C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<html1dir>, C<html1direxp>,
+C<html3dir>, C<html3direxp>
+
+=item i
+
+C<i16size>, C<i16type>, C<i32size>, C<i32type>, C<i64size>, C<i64type>,
+C<i8size>, C<i8type>, C<i_arpainet>, C<i_bsdioctl>, C<i_crypt>, C<i_db>,
+C<i_dbm>, C<i_dirent>, C<i_dld>, C<i_dlfcn>, C<i_fcntl>, C<i_float>,
+C<i_fp>, C<i_fp_class>, C<i_gdbm>, C<i_grp>, C<i_ieeefp>, C<i_inttypes>,
+C<i_langinfo>, C<i_libutil>, C<i_limits>, C<i_locale>, C<i_machcthr>,
+C<i_malloc>, C<i_math>, C<i_memory>, C<i_mntent>, C<i_ndbm>, C<i_netdb>,
+C<i_neterrno>, C<i_netinettcp>, C<i_niin>, C<i_poll>, C<i_prot>,
+C<i_pthread>, C<i_pwd>, C<i_rpcsvcdbm>, C<i_sfio>, C<i_sgtty>, C<i_shadow>,
+C<i_socks>, C<i_stdarg>, C<i_stddef>, C<i_stdlib>, C<i_string>,
+C<i_sunmath>, C<i_sysaccess>, C<i_sysdir>, C<i_sysfile>, C<i_sysfilio>,
+C<i_sysin>, C<i_sysioctl>, C<i_syslog>, C<i_sysmman>, C<i_sysmode>,
+C<i_sysmount>, C<i_sysndir>, C<i_sysparam>, C<i_sysresrc>, C<i_syssecrt>,
+C<i_sysselct>, C<i_syssockio>, C<i_sysstat>, C<i_sysstatfs>,
+C<i_sysstatvfs>, C<i_systime>, C<i_systimek>, C<i_systimes>, C<i_systypes>,
+C<i_sysuio>, C<i_sysun>, C<i_sysutsname>, C<i_sysvfs>, C<i_syswait>,
+C<i_termio>, C<i_termios>, C<i_time>, C<i_unistd>, C<i_ustat>, C<i_utime>,
+C<i_values>, C<i_varargs>, C<i_varhdr>, C<i_vfork>,
+C<ignore_versioned_solibs>, C<inc_version_list>, C<inc_version_list_init>,
+C<incpath>, C<inews>, C<initialinstalllocation>, C<installarchlib>,
+C<installbin>, C<installhtml1dir>, C<installhtml3dir>, C<installman1dir>,
+C<installman3dir>, C<installprefix>, C<installprefixexp>,
+C<installprivlib>, C<installscript>, C<installsitearch>, C<installsitebin>,
+C<installsitehtml1dir>, C<installsitehtml3dir>, C<installsitelib>,
+C<installsiteman1dir>, C<installsiteman3dir>, C<installsitescript>,
+C<installstyle>, C<installusrbinperl>, C<installvendorarch>,
+C<installvendorbin>, C<installvendorhtml1dir>, C<installvendorhtml3dir>,
+C<installvendorlib>, C<installvendorman1dir>, C<installvendorman3dir>,
+C<installvendorscript>, C<intsize>, C<issymlink>, C<ivdformat>, C<ivsize>,
+C<ivtype>
+
+=item k
+
+C<known_extensions>, C<ksh>
+
+=item l
+
+C<ld>, C<lddlflags>, C<ldflags>, C<ldflags_uselargefiles>, C<ldlibpthname>,
+C<less>, C<lib_ext>, C<libc>, C<libperl>, C<libpth>, C<libs>, C<libsdirs>,
+C<libsfiles>, C<libsfound>, C<libspath>, C<libswanted>,
+C<libswanted_uselargefiles>, C<line>, C<lint>, C<lkflags>, C<ln>, C<lns>,
+C<localtime_r_proto>, C<locincpth>, C<loclibpth>, C<longdblsize>,
+C<longlongsize>, C<longsize>, C<lp>, C<lpr>, C<ls>, C<lseeksize>,
+C<lseektype>
+
+=item m
+
+C<mad>, C<madlyh>, C<madlyobj>, C<madlysrc>, C<mail>, C<mailx>, C<make>,
+C<make_set_make>, C<mallocobj>, C<mallocsrc>, C<malloctype>, C<man1dir>,
+C<man1direxp>, C<man1ext>, C<man3dir>, C<man3direxp>, C<man3ext>
+
+=item M
+
+C<Mcc>, C<mips_type>, C<mistrustnm>, C<mkdir>, C<mmaptype>, C<modetype>,
+C<more>, C<multiarch>, C<mv>, C<myarchname>, C<mydomain>, C<myhostname>,
+C<myuname>
+
+=item n
+
+C<n>, C<need_va_copy>, C<netdb_hlen_type>, C<netdb_host_type>,
+C<netdb_name_type>, C<netdb_net_type>, C<nm>, C<nm_opt>, C<nm_so_opt>,
+C<nonxs_ext>, C<nroff>, C<nv_preserves_uv_bits>, C<nveformat>,
+C<nvEUformat>, C<nvfformat>, C<nvFUformat>, C<nvgformat>, C<nvGUformat>,
+C<nvsize>, C<nvtype>
+
+=item o
+
+C<o_nonblock>, C<obj_ext>, C<old_pthread_create_joinable>, C<optimize>,
+C<orderlib>, C<osname>, C<osvers>, C<otherlibdirs>
+
+=item p
+
+C<package>, C<pager>, C<passcat>, C<patchlevel>, C<path_sep>, C<perl>,
+C<perl5>
+
+=item P
+
+C<PERL_API_REVISION>, C<PERL_API_SUBVERSION>, C<PERL_API_VERSION>,
+C<PERL_CONFIG_SH>, C<PERL_PATCHLEVEL>, C<perl_patchlevel>,
+C<PERL_REVISION>, C<PERL_SUBVERSION>, C<PERL_VERSION>, C<perladmin>,
+C<perllibs>, C<perlpath>, C<pg>, C<phostname>, C<pidtype>, C<plibpth>,
+C<pmake>, C<pr>, C<prefix>, C<prefixexp>, C<privlib>, C<privlibexp>,
+C<procselfexe>, C<prototype>, C<ptrsize>
+
+=item q
+
+C<quadkind>, C<quadtype>
+
+=item r
+
+C<randbits>, C<randfunc>, C<random_r_proto>, C<randseedtype>, C<ranlib>,
+C<rd_nodata>, C<readdir64_r_proto>, C<readdir_r_proto>, C<revision>, C<rm>,
+C<rm_try>, C<rmail>, C<run>, C<runnm>
+
+=item s
+
+C<sched_yield>, C<scriptdir>, C<scriptdirexp>, C<sed>, C<seedfunc>,
+C<selectminbits>, C<selecttype>, C<sendmail>, C<setgrent_r_proto>,
+C<sethostent_r_proto>, C<setlocale_r_proto>, C<setnetent_r_proto>,
+C<setprotoent_r_proto>, C<setpwent_r_proto>, C<setservent_r_proto>, C<sh>,
+C<shar>, C<sharpbang>, C<shmattype>, C<shortsize>, C<shrpenv>, C<shsharp>,
+C<sig_count>, C<sig_name>, C<sig_name_init>, C<sig_num>, C<sig_num_init>,
+C<sig_size>, C<signal_t>, C<sitearch>, C<sitearchexp>, C<sitebin>,
+C<sitebinexp>, C<sitehtml1dir>, C<sitehtml1direxp>, C<sitehtml3dir>,
+C<sitehtml3direxp>, C<sitelib>, C<sitelib_stem>, C<sitelibexp>,
+C<siteman1dir>, C<siteman1direxp>, C<siteman3dir>, C<siteman3direxp>,
+C<siteprefix>, C<siteprefixexp>, C<sitescript>, C<sitescriptexp>,
+C<sizesize>, C<sizetype>, C<sleep>, C<smail>, C<so>, C<sockethdr>,
+C<socketlib>, C<socksizetype>, C<sort>, C<spackage>, C<spitshell>,
+C<sPRId64>, C<sPRIeldbl>, C<sPRIEUldbl>, C<sPRIfldbl>, C<sPRIFUldbl>,
+C<sPRIgldbl>, C<sPRIGUldbl>, C<sPRIi64>, C<sPRIo64>, C<sPRIu64>,
+C<sPRIx64>, C<sPRIXU64>, C<srand48_r_proto>, C<srandom_r_proto>, C<src>,
+C<sSCNfldbl>, C<ssizetype>, C<startperl>, C<startsh>, C<static_ext>,
+C<stdchar>, C<stdio_base>, C<stdio_bufsiz>, C<stdio_cnt>, C<stdio_filbuf>,
+C<stdio_ptr>, C<stdio_stream_array>, C<strerror_r_proto>, C<strings>,
+C<submit>, C<subversion>, C<sysman>
+
+=item t
+
+C<tail>, C<tar>, C<targetarch>, C<tbl>, C<tee>, C<test>, C<timeincl>,
+C<timetype>, C<tmpnam_r_proto>, C<to>, C<touch>, C<tr>, C<trnl>, C<troff>,
+C<ttyname_r_proto>
+
+=item u
+
+C<u16size>, C<u16type>, C<u32size>, C<u32type>, C<u64size>, C<u64type>,
+C<u8size>, C<u8type>, C<uidformat>, C<uidsign>, C<uidsize>, C<uidtype>,
+C<uname>, C<uniq>, C<uquadtype>, C<use5005threads>, C<use64bitall>,
+C<use64bitint>, C<usecrosscompile>, C<usedl>, C<usefaststdio>,
+C<useithreads>, C<uselargefiles>, C<uselongdouble>, C<usemallocwrap>,
+C<usemorebits>, C<usemultiplicity>, C<usemymalloc>, C<usenm>, C<useopcode>,
+C<useperlio>, C<useposix>, C<usereentrant>, C<userelocatableinc>,
+C<usesfio>, C<useshrplib>, C<usesitecustomize>, C<usesocks>, C<usethreads>,
+C<usevendorprefix>, C<usevfork>, C<usrinc>, C<uuname>, C<uvoformat>,
+C<uvsize>, C<uvtype>, C<uvuformat>, C<uvxformat>, C<uvXUformat>
+
+=item v
+
+C<vendorarch>, C<vendorarchexp>, C<vendorbin>, C<vendorbinexp>,
+C<vendorhtml1dir>, C<vendorhtml1direxp>, C<vendorhtml3dir>,
+C<vendorhtml3direxp>, C<vendorlib>, C<vendorlib_stem>, C<vendorlibexp>,
+C<vendorman1dir>, C<vendorman1direxp>, C<vendorman3dir>,
+C<vendorman3direxp>, C<vendorprefix>, C<vendorprefixexp>, C<vendorscript>,
+C<vendorscriptexp>, C<version>, C<version_patchlevel_string>,
+C<versiononly>, C<vi>, C<voidflags>
+
+=item x
+
+C<xlibpth>
+
+=item y
+
+C<yacc>, C<yaccflags>
+
+=item z
+
+C<zcat>, C<zip>
+
+=back
+
+=item NOTE
+
+=back
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+dynamic, nonxs, static
+
+=item AUTHOR
+
+=back
+
+=head2 Cwd - get pathname of current working directory
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item getcwd and friends
+
+getcwd, cwd, fastcwd, fastgetcwd, getdcwd
+
+=item abs_path and friends
+
+abs_path, realpath, fast_abs_path
+
+=item $ENV{PWD}
+
+=back
+
+=item NOTES
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 DB - programmatic interface to the Perl debugging API
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Global Variables
+
+ $DB::sub, %DB::sub, $DB::single, $DB::signal, $DB::trace, @DB::args,
+ at DB::dbline, %DB::dbline, $DB::package, $DB::filename, $DB::subname,
+$DB::lineno
+
+=item API Methods
+
+CLIENT->register(), CLIENT->evalcode(STRING), CLIENT->skippkg('D::hide'),
+CLIENT->run(), CLIENT->step(), CLIENT->next(), CLIENT->done()
+
+=item Client Callback Methods
+
+CLIENT->init(), CLIENT->prestop([STRING]), CLIENT->stop(), CLIENT->idle(),
+CLIENT->poststop([STRING]), CLIENT->evalcode(STRING), CLIENT->cleanup(),
+CLIENT->output(LIST)
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter -- Filter DBM keys/values
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item What is a DBM Filter?
+
+=over 4
+
+=item So what's new?
+
+=back
+
+=item METHODS
+
+=over 4
+
+=item $db->Filter_Push()
+
+=item $db->Filter_Key_Push()
+
+=item $db->Filter_Value_Push()
+
+Filter_Push, Filter_Key_Push, Filter_Value_Push
+
+=item $db->Filter_Pop()
+
+=item $db->Filtered()
+
+=back
+
+=item Writing a Filter
+
+=over 4
+
+=item Immediate Filters
+
+=item Canned Filters
+
+"name", params
+
+=back
+
+=item Filters Included
+
+utf8, encode, compress, int32, null
+
+=item NOTES
+
+=over 4
+
+=item Maintain Round Trip Integrity
+
+=item Don't mix filtered & non-filtered data in the same database file.
+
+=back
+
+=item EXAMPLE
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter::compress - filter for DBM_Filter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter::encode - filter for DBM_Filter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter::int32 - filter for DBM_Filter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter::null - filter for DBM_Filter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DBM_Filter::utf8 - filter for DBM_Filter
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 DB_File - Perl5 access to Berkeley DB version 1.x
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<DB_HASH>, B<DB_BTREE>, B<DB_RECNO>
+
+=over 4
+
+=item Using DB_File with Berkeley DB version 2 or greater
+
+=item Interface to Berkeley DB
+
+=item Opening a Berkeley DB Database File
+
+=item Default Parameters
+
+=item In Memory Databases
+
+=back
+
+=item DB_HASH
+
+=over 4
+
+=item A Simple Example
+
+=back
+
+=item DB_BTREE
+
+=over 4
+
+=item Changing the BTREE sort order
+
+=item Handling Duplicate Keys
+
+=item The get_dup() Method
+
+=item The find_dup() Method
+
+=item The del_dup() Method
+
+=item Matching Partial Keys
+
+=back
+
+=item DB_RECNO
+
+=over 4
+
+=item The 'bval' Option
+
+=item A Simple Example
+
+=item Extra RECNO Methods
+
+B<$X-E<gt>push(list) ;>, B<$value = $X-E<gt>pop ;>, B<$X-E<gt>shift>,
+B<$X-E<gt>unshift(list) ;>, B<$X-E<gt>length>, B<$X-E<gt>splice(offset,
+length, elements);>
+
+=item Another Example
+
+=back
+
+=item THE API INTERFACE
+
+B<$status = $X-E<gt>get($key, $value [, $flags]) ;>, B<$status =
+$X-E<gt>put($key, $value [, $flags]) ;>, B<$status = $X-E<gt>del($key [,
+$flags]) ;>, B<$status = $X-E<gt>fd ;>, B<$status = $X-E<gt>seq($key,
+$value, $flags) ;>, B<$status = $X-E<gt>sync([$flags]) ;>
+
+=item DBM FILTERS
+
+B<filter_store_key>, B<filter_store_value>, B<filter_fetch_key>,
+B<filter_fetch_value>
+
+=over 4
+
+=item The Filter
+
+=item An Example -- the NULL termination problem.
+
+=item Another Example -- Key is a C int.
+
+=back
+
+=item HINTS AND TIPS
+
+=over 4
+
+=item Locking: The Trouble with fd
+
+=item Safe ways to lock a database
+
+B<Tie::DB_Lock>, B<Tie::DB_LockFile>, B<DB_File::Lock>
+
+=item Sharing Databases With C Applications
+
+=item The untie() Gotcha
+
+=back
+
+=item COMMON QUESTIONS
+
+=over 4
+
+=item Why is there Perl source in my database?
+
+=item How do I store complex data structures with DB_File?
+
+=item What does "Invalid Argument" mean?
+
+=item What does "Bareword 'DB_File' not allowed" mean?
+
+=back
+
+=item REFERENCES
+
+=item HISTORY
+
+=item BUGS
+
+=item AVAILABILITY
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Data::Dumper - stringified perl data structures, suitable for both
+printing and C<eval>
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Methods
+
+I<PACKAGE>->new(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Dump I<or>
+I<PACKAGE>->Dump(I<ARRAYREF [>, I<ARRAYREF]>), I<$OBJ>->Seen(I<[HASHREF]>),
+I<$OBJ>->Values(I<[ARRAYREF]>), I<$OBJ>->Names(I<[ARRAYREF]>),
+I<$OBJ>->Reset
+
+=item Functions
+
+Dumper(I<LIST>)
+
+=item Configuration Variables or Methods
+
+=item Exports
+
+Dumper
+
+=back
+
+=item EXAMPLES
+
+=item BUGS
+
+=over 4
+
+=item NOTE
+
+=back
+
+=item AUTHOR
+
+=item VERSION
+
+=item SEE ALSO
+
+=back
+
+=head2 Devel::DProf - a Perl code profiler
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item PROFILE FORMAT
+
+=item AUTOLOAD
+
+=item ENVIRONMENT
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Devel::InnerPackage - find all the inner packages of a package
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item list_packages <package name>
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item COPYING
+
+=item BUGS
+
+=back
+
+=head2 Devel::PPPort - Perl/Pollution/Portability
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Why use ppport.h?
+
+=item How to use ppport.h
+
+=item Running ppport.h
+
+=back
+
+=item FUNCTIONS
+
+=over 4
+
+=item WriteFile
+
+=back
+
+=item COMPATIBILITY
+
+=over 4
+
+=item Provided Perl compatibility API
+
+=item Perl API not supported by ppport.h
+
+perl 5.9.5, perl 5.9.4, perl 5.9.3, perl 5.9.2, perl 5.9.1, perl 5.9.0,
+perl 5.8.3, perl 5.8.1, perl 5.8.0, perl 5.7.3, perl 5.7.2, perl 5.7.1,
+perl 5.6.1, perl 5.6.0, perl 5.005_03, perl 5.005, perl 5.004_05, perl
+5.004
+
+=back
+
+=item BUGS
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Devel::Peek - A data debugging tool for the XS programmer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Runtime debugging
+
+=item Memory footprint debugging
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item A simple scalar string
+
+=item A simple scalar number
+
+=item A simple scalar with an extra reference
+
+=item A reference to a simple scalar
+
+=item A reference to an array
+
+=item A reference to a hash
+
+=item Dumping a large array or hash
+
+=item A reference to an SV which holds a C pointer
+
+=item A reference to a subroutine
+
+=back
+
+=item EXPORTS
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Devel::SelfStubber - generate stubs for a SelfLoading module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 Digest - Modules that calculate message digests
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+I<binary>, I<hex>, I<base64>
+
+=item OO INTERFACE
+
+$ctx = Digest->XXX($arg,...), $ctx = Digest->new(XXX => $arg,...), $ctx =
+Digest::XXX->new($arg,...), $other_ctx = $ctx->clone, $ctx->reset,
+$ctx->add( $data ), $ctx->add( $chunk1, $chunk2, ... ), $ctx->addfile(
+$io_handle ), $ctx->add_bits( $data, $nbits ), $ctx->add_bits( $bitstring
+), $ctx->digest, $ctx->hexdigest, $ctx->b64digest
+
+=item Digest speed
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Digest::MD5 - Perl interface to the MD5 Algorithm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+md5($data,...), md5_hex($data,...), md5_base64($data,...)
+
+=item METHODS
+
+$md5 = Digest::MD5->new, $md5->reset, $md5->clone, $md5->add($data,...),
+$md5->addfile($io_handle), $md5->add_bits($data, $nbits),
+$md5->add_bits($bitstring), $md5->digest, $md5->hexdigest, $md5->b64digest
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=item AUTHORS
+
+=back
+
+=head2 Digest::SHA - Perl extension for SHA-1/224/256/384/512
+
+=over 4
+
+=item SYNOPSIS
+
+=item SYNOPSIS (HMAC-SHA)
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item NIST STATEMENT ON SHA-1
+
+=item PADDING OF BASE64 DIGESTS
+
+=item EXPORT
+
+=item EXPORTABLE FUNCTIONS
+
+B<sha1($data, ...)>, B<sha224($data, ...)>, B<sha256($data, ...)>,
+B<sha384($data, ...)>, B<sha512($data, ...)>, B<sha1_hex($data, ...)>,
+B<sha224_hex($data, ...)>, B<sha256_hex($data, ...)>, B<sha384_hex($data,
+...)>, B<sha512_hex($data, ...)>, B<sha1_base64($data, ...)>,
+B<sha224_base64($data, ...)>, B<sha256_base64($data, ...)>,
+B<sha384_base64($data, ...)>, B<sha512_base64($data, ...)>, B<new($alg)>,
+B<reset($alg)>, B<hashsize>, B<algorithm>, B<clone>, B<add($data, ...)>,
+B<add_bits($data, $nbits)>, B<add_bits($bits)>, B<addfile(*FILE)>,
+B<addfile($filename [, $mode])>, B<dump($filename)>, B<load($filename)>,
+B<digest>, B<hexdigest>, B<b64digest>, B<hmac_sha1($data, $key)>,
+B<hmac_sha224($data, $key)>, B<hmac_sha256($data, $key)>,
+B<hmac_sha384($data, $key)>, B<hmac_sha512($data, $key)>,
+B<hmac_sha1_hex($data, $key)>, B<hmac_sha224_hex($data, $key)>,
+B<hmac_sha256_hex($data, $key)>, B<hmac_sha384_hex($data, $key)>,
+B<hmac_sha512_hex($data, $key)>, B<hmac_sha1_base64($data, $key)>,
+B<hmac_sha224_base64($data, $key)>, B<hmac_sha256_base64($data, $key)>,
+B<hmac_sha384_base64($data, $key)>, B<hmac_sha512_base64($data, $key)>
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item ACKNOWLEDGMENTS
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Digest::base - Digest base class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 Digest::file - Calculate digests of files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+digest_file( $file, $algorithm, [$arg,...] ), digest_file_hex( $file,
+$algorithm, [$arg,...] ), digest_file_base64( $file, $algorithm, [$arg,...]
+)
+
+=item SEE ALSO
+
+=back
+
+=head2 DirHandle - supply object methods for directory handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=back
+
+=head2 Dumpvalue - provides screen dump of Perl data.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Creation
+
+C<arrayDepth>, C<hashDepth>, C<compactDump>, C<veryCompact>, C<globPrint>,
+C<dumpDBFiles>, C<dumpPackages>, C<dumpReused>, C<tick>, C<quoteHighBit>,
+C<printUndef>, C<usageOnly>, unctrl, subdump, bareStringify, quoteHighBit,
+stopDbSignal
+
+=item Methods
+
+dumpValue, dumpValues, stringify, dumpvars, set_quote, set_unctrl,
+compactDump, veryCompact, set, get
+
+=back
+
+=back
+
+=head2 DynaLoader - Dynamically load C libraries into Perl code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+ at dl_library_path, @dl_resolve_using, @dl_require_symbols, @dl_librefs,
+ at dl_modules, @dl_shared_objects, dl_error(), $dl_debug, dl_findfile(),
+dl_expandspec(), dl_load_file(), dl_unload_file(), dl_load_flags(),
+dl_find_symbol(), dl_find_symbol_anywhere(), dl_undef_symbols(),
+dl_install_xsub(), bootstrap()
+
+=item AUTHOR
+
+=back
+
+=head2 DynaLoader::XSLoader, XSLoader - Dynamically load C libraries into
+Perl code
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Migration from C<DynaLoader>
+
+=item Backward compatible boilerplate
+
+=back
+
+=item Order of initialization: early load()
+
+=over 4
+
+=item The most hairy case
+
+=back
+
+=item DIAGNOSTICS
+
+C<Can't find '%s' symbol in %s>, C<Can't load '%s' for module %s: %s>,
+C<Undefined symbols present after loading %s: %s>,
+C<XSLoader::load('Your::Module', $Your::Module::VERSION)>
+
+=item LIMITATIONS
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Encode - character encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=over 4
+
+=item Table of Contents
+
+=back
+
+=item DESCRIPTION
+
+=over 4
+
+=item TERMINOLOGY
+
+=back
+
+=item PERL ENCODING API
+
+$octets = encode(ENCODING, $string [, CHECK]), $string = decode(ENCODING,
+$octets [, CHECK]), [$obj =] find_encoding(ENCODING), [$length =]
+from_to($octets, FROM_ENC, TO_ENC [, CHECK]), $octets =
+encode_utf8($string);, $string = decode_utf8($octets [, CHECK]);
+
+=over 4
+
+=item Listing available encodings
+
+=item Defining Aliases
+
+=item Finding IANA Character Set Registry names
+
+=back
+
+=item Encoding via PerlIO
+
+=item Handling Malformed Data
+
+B<NOTE:> Not all encoding support this feature, I<CHECK> =
+Encode::FB_DEFAULT ( == 0), I<CHECK> = Encode::FB_CROAK ( == 1), I<CHECK> =
+Encode::FB_QUIET, I<CHECK> = Encode::FB_WARN, perlqq mode (I<CHECK> =
+Encode::FB_PERLQQ), HTML charref mode (I<CHECK> = Encode::FB_HTMLCREF), XML
+charref mode (I<CHECK> = Encode::FB_XMLCREF), The bitmask,
+Encode::LEAVE_SRC
+
+=item Defining Encodings
+
+=item The UTF8 flag
+
+Goal #1:, Goal #2:, Goal #3:, Goal #4:
+
+=over 4
+
+=item Messing with Perl's Internals
+
+is_utf8(STRING [, CHECK]), _utf8_on(STRING), _utf8_off(STRING)
+
+=back
+
+=item UTF-8 vs. utf8 vs. UTF8
+
+=item SEE ALSO
+
+=item MAINTAINER
+
+=item COPYRIGHT
+
+=back
+
+=head2 Encode::Alias - alias definitions to encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+As a simple string, As a qr// compiled regular expression, e.g.:, As a code
+reference, e.g.:
+
+=over 4
+
+=item Alias overloading
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Byte - Single Byte Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::CJKConstants -- Internally used by Encode::??::ISO_2022_*
+
+=head2 Encode::CN - China-based Chinese Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::CN::HZ -- internally used by Encode::CN
+
+=head2 Encode::Config -- internally used by Encode
+
+=head2 Encode::EBCDIC - EBCDIC Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Encoding - Encode Implementation Base Class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Methods you should implement
+
+-E<gt>encode($string [,$check]), -E<gt>decode($octets [,$check]),
+-E<gt>cat_decode($destination, $octets, $offset, $terminator [,$check])
+
+=item Other methods defined in Encode::Encodings
+
+-E<gt>name, -E<gt>mime_name, -E<gt>renew, -E<gt>renewed, -E<gt>perlio_ok(),
+-E<gt>needs_lines()
+
+=item Example: Encode::ROT13
+
+=back
+
+=item Why the heck Encode API is different?
+
+=over 4
+
+=item Compiled Encodings
+
+=back
+
+=item SEE ALSO
+
+Scheme 1, Scheme 2, Other Schemes
+
+=back
+
+=head2 Encode::GSM0338 -- ESTI GSM 03.38 Encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Guess -- Guesses encoding from data
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+Encode::Guess->set_suspects, Encode::Guess->add_suspects,
+Encode::decode("Guess" ...), Encode::Guess->guess($data),
+guess_encoding($data, [, I<list of suspects>])
+
+=item CAVEATS
+
+=item TO DO
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::JP - Japanese Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item Note on ISO-2022-JP(-1)?
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::JP::H2Z -- internally used by Encode::JP::2022_JP*
+
+=head2 Encode::JP::JIS7 -- internally used by Encode::JP
+
+=head2 Encode::KR - Korean Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::KR::2022_KR -- internally used by Encode::KR
+
+=head2 Encode::MIME::Header -- MIME 'B' and 'Q' header encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::MIME::Name, Encode::MIME::NAME -- internally used by Encode
+
+=over 4
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::PerlIO -- a detailed document on Encode and PerlIO
+
+=over 4
+
+=item Overview
+
+=item How does it work?
+
+=item Line Buffering
+
+=over 4
+
+=item How can I tell whether my encoding fully supports PerlIO ?
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Supported -- Encodings supported by Encode
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Encoding Names
+
+=back
+
+=item Supported Encodings
+
+=over 4
+
+=item Built-in Encodings
+
+=item Encode::Unicode -- other Unicode encodings
+
+=item Encode::Byte -- Extended ASCII
+
+ISO-8859 and corresponding vendor mappings, KOI8 - De Facto Standard for
+the Cyrillic world
+
+=item gsm0338 - Hentai Latin 1
+
+gsm0338 support before 2.19
+
+=item CJK: Chinese, Japanese, Korean (Multibyte)
+
+Encode::CN -- Continental China, Encode::JP -- Japan, Encode::KR -- Korea,
+Encode::TW -- Taiwan, Encode::HanExtra -- More Chinese via CPAN,
+Encode::JIS2K -- JIS X 0213 encodings via CPAN
+
+=item Miscellaneous encodings
+
+Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess
+
+=back
+
+=item Unsupported encodings
+
+ ISO-2022-JP-2 [RFC1554], ISO-2022-CN [RFC1922], Various HP-UX encodings,
+Cyrillic encoding ISO-IR-111, ISO-8859-8-1 [Hebrew], ISIRI 3342, Iran
+System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
+Various Mac encodings, (Mac) Indic encodings
+
+=item Encoding vs. Charset -- terminology
+
+=item Encoding Classification (by Anton Tagunov and Dan Kogai)
+
+=over 4
+
+=item Microsoft-related naming mess
+
+KS_C_5601-1987, GB2312, Big5, Shift_JIS
+
+=back
+
+=item Glossary
+
+character repertoire, coded character set (CCS), character encoding scheme
+(CES), charset (in MIME context), EUC, ISO-2022, UCS, UCS-2, Unicode, UTF,
+UTF-16
+
+=item See Also
+
+=item References
+
+ECMA, ECMA-035 (eq C<ISO-2022>), IANA, Assigned Charset Names by IANA, ISO,
+RFC, UC, Unicode Glossary
+
+=over 4
+
+=item Other Notable Sites
+
+czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org:
+"Introduction to i18n"
+
+=item Offline sources
+
+C<CJKV Information Processing> by Ken Lunde
+
+=back
+
+=back
+
+=head2 Encode::Symbol - Symbol Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::TW - Taiwan-based Chinese Encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Unicode -- Various Unicode Transformation Formats
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+L<http://www.unicode.org/glossary/> says:, Quick Reference
+
+=item Size, Endianness, and BOM
+
+=over 4
+
+=item by size
+
+=item by endianness
+
+BOM as integer when fetched in network byte order
+
+=back
+
+=item Surrogate Pairs
+
+=item Error Checking
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::Unicode::UTF7 -- UTF-7 encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item In Practice
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::Alias, Encode::Alias - alias definitions to
+encodings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+As a simple string, As a qr// compiled regular expression, e.g.:, As a code
+reference, e.g.:
+
+=over 4
+
+=item Alias overloading
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::CJKConstants, Encode::CJKConstants.pm --
+Internally used by Encode::??::ISO_2022_*
+
+=head2 Encode::lib::Encode::CN::HZ, Encode::CN::HZ -- internally used by
+Encode::CN
+
+=head2 Encode::lib::Encode::Config, Encode::Config -- internally used by
+Encode
+
+=head2 Encode::lib::Encode::Encoding, Encode::Encoding - Encode
+Implementation Base Class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Methods you should implement
+
+-E<gt>encode($string [,$check]), -E<gt>decode($octets [,$check]),
+-E<gt>cat_decode($destination, $octets, $offset, $terminator [,$check])
+
+=item Other methods defined in Encode::Encodings
+
+-E<gt>name, -E<gt>mime_name, -E<gt>renew, -E<gt>renewed, -E<gt>perlio_ok(),
+-E<gt>needs_lines()
+
+=item Example: Encode::ROT13
+
+=back
+
+=item Why the heck Encode API is different?
+
+=over 4
+
+=item Compiled Encodings
+
+=back
+
+=item SEE ALSO
+
+Scheme 1, Scheme 2, Other Schemes
+
+=back
+
+=head2 Encode::lib::Encode::GSM0338, Encode::GSM0338 -- ESTI GSM 03.38
+Encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::Guess, Encode::Guess -- Guesses encoding from
+data
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+Encode::Guess->set_suspects, Encode::Guess->add_suspects,
+Encode::decode("Guess" ...), Encode::Guess->guess($data),
+guess_encoding($data, [, I<list of suspects>])
+
+=item CAVEATS
+
+=item TO DO
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::JP::H2Z, Encode::JP::H2Z -- internally used by
+Encode::JP::2022_JP*
+
+=head2 Encode::lib::Encode::JP::JIS7, Encode::JP::JIS7 -- internally used
+by Encode::JP
+
+=head2 Encode::lib::Encode::KR::2022_KR, Encode::KR::2022_KR -- internally
+used by Encode::KR
+
+=head2 Encode::lib::Encode::MIME::Header, Encode::MIME::Header -- MIME 'B'
+and 'Q' header encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::MIME::Name, Encode::MIME::NAME -- internally
+used by Encode
+
+=over 4
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::PerlIO, Encode::PerlIO -- a detailed document
+on Encode and PerlIO
+
+=over 4
+
+=item Overview
+
+=item How does it work?
+
+=item Line Buffering
+
+=over 4
+
+=item How can I tell whether my encoding fully supports PerlIO ?
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encode::Supported, Encode::Supported -- Encodings
+supported by Encode
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Encoding Names
+
+=back
+
+=item Supported Encodings
+
+=over 4
+
+=item Built-in Encodings
+
+=item Encode::Unicode -- other Unicode encodings
+
+=item Encode::Byte -- Extended ASCII
+
+ISO-8859 and corresponding vendor mappings, KOI8 - De Facto Standard for
+the Cyrillic world
+
+=item gsm0338 - Hentai Latin 1
+
+gsm0338 support before 2.19
+
+=item CJK: Chinese, Japanese, Korean (Multibyte)
+
+Encode::CN -- Continental China, Encode::JP -- Japan, Encode::KR -- Korea,
+Encode::TW -- Taiwan, Encode::HanExtra -- More Chinese via CPAN,
+Encode::JIS2K -- JIS X 0213 encodings via CPAN
+
+=item Miscellaneous encodings
+
+Encode::EBCDIC, Encode::Symbols, Encode::MIME::Header, Encode::Guess
+
+=back
+
+=item Unsupported encodings
+
+ ISO-2022-JP-2 [RFC1554], ISO-2022-CN [RFC1922], Various HP-UX encodings,
+Cyrillic encoding ISO-IR-111, ISO-8859-8-1 [Hebrew], ISIRI 3342, Iran
+System, ISIRI 2900 [Farsi], Thai encoding TCVN, Vietnamese encodings VPS,
+Various Mac encodings, (Mac) Indic encodings
+
+=item Encoding vs. Charset -- terminology
+
+=item Encoding Classification (by Anton Tagunov and Dan Kogai)
+
+=over 4
+
+=item Microsoft-related naming mess
+
+KS_C_5601-1987, GB2312, Big5, Shift_JIS
+
+=back
+
+=item Glossary
+
+character repertoire, coded character set (CCS), character encoding scheme
+(CES), charset (in MIME context), EUC, ISO-2022, UCS, UCS-2, Unicode, UTF,
+UTF-16
+
+=item See Also
+
+=item References
+
+ECMA, ECMA-035 (eq C<ISO-2022>), IANA, Assigned Charset Names by IANA, ISO,
+RFC, UC, Unicode Glossary
+
+=over 4
+
+=item Other Notable Sites
+
+czyborra.com, CJK.inf, Jungshik Shin's Hangul FAQ, debian.org:
+"Introduction to i18n"
+
+=item Offline sources
+
+C<CJKV Information Processing> by Ken Lunde
+
+=back
+
+=back
+
+=head2 Encode::lib::Encode::Unicode::UTF7, Encode::Unicode::UTF7 -- UTF-7
+encoding
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item In Practice
+
+=item SEE ALSO
+
+=back
+
+=head2 Encode::lib::Encoder, Encode::Encoder -- Object Oriented Encoder
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item Description
+
+=over 4
+
+=item Predefined Methods
+
+$e = Encode::Encoder-E<gt>new([$data, $encoding]);, encoder(),
+$e-E<gt>data([$data]), $e-E<gt>encoding([$encoding]),
+$e-E<gt>bytes([$encoding])
+
+=item Example: base64 transcoder
+
+=item Operator Overloading
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 Encodencoding, encoding - allows you to write your script in
+non-ascii or non-utf8
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=over 4
+
+=item Literal Conversions
+
+=item PerlIO layers for C<STD(IN|OUT)>
+
+=item Implicit upgrading for byte strings
+
+=item Side effects
+
+=item Side effects
+
+=item Side effects
+
+=back
+
+=item FEATURES THAT REQUIRE 5.8.1
+
+"NON-EUC" doublebyte encodings, tr//, DATA pseudo-filehandle
+
+=item USAGE
+
+use encoding [I<ENCNAME>] ;, use encoding I<ENCNAME> [ STDIN =E<gt>
+I<ENCNAME_IN> ...] ;, use encoding I<ENCNAME> Filter=E<gt>1;, no encoding;
+
+=item The Filter Option
+
+=over 4
+
+=item Filter-related changes at Encode version 1.87
+
+=back
+
+=item CAVEATS
+
+=over 4
+
+=item NOT SCOPED
+
+=item DO NOT MIX MULTIPLE ENCODINGS
+
+=item tr/// with ranges
+
+Legend of characters above
+
+=back
+
+=item EXAMPLE - Greekperl
+
+=item KNOWN PROBLEMS
+
+literals in regex that are longer than 127 bytes, EBCDIC, format, Thread
+safety
+
+=over 4
+
+=item The Logic of :locale
+
+=back
+
+=item HISTORY
+
+=item SEE ALSO
+
+=back
+
+=head2 Encoder, Encode::Encoder -- Object Oriented Encoder
+
+=over 4
+
+=item SYNOPSIS
+
+=item ABSTRACT
+
+=item Description
+
+=over 4
+
+=item Predefined Methods
+
+$e = Encode::Encoder-E<gt>new([$data, $encoding]);, encoder(),
+$e-E<gt>data([$data]), $e-E<gt>encoding([$encoding]),
+$e-E<gt>bytes([$encoding])
+
+=item Example: base64 transcoder
+
+=item Operator Overloading
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 English - use nice English (or awk) names for ugly punctuation
+variables
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item PERFORMANCE
+
+=back
+
+=head2 Env - perl module that imports environment variables as scalars or
+arrays
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item LIMITATIONS
+
+=item AUTHOR
+
+=back
+
+=head2 Errno - System errno constants
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEATS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Exporter - Implements default import method for modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item How to Export
+
+=item Selecting What To Export
+
+=item How to Import
+
+C<use ModuleName;>, C<use ModuleName ();>, C<use ModuleName qw(...);>
+
+=back
+
+=item Advanced features
+
+=over 4
+
+=item Specialised Import Lists
+
+=item Exporting without using Exporter's import method
+
+=item Exporting without inheriting from Exporter
+
+=item Module Version Checking
+
+=item Managing Unknown Symbols
+
+=item Tag Handling Utility Functions
+
+=item Generating combined tags
+
+=item C<AUTOLOAD>ed Constants
+
+=back
+
+=item Good Practices
+
+=over 4
+
+=item Declaring C<@EXPORT_OK> and Friends
+
+=item Playing Safe
+
+=item What not to Export
+
+=back
+
+=item SEE ALSO
+
+=item LICENSE
+
+=back
+
+=head2 Exporter::Heavy - Exporter guts
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::CBuilder - Compile and link C code for Perl modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+new, have_compiler, compile, C<object_file>, C<include_dirs>,
+C<extra_compiler_flags>, link, lib_file, module_name, extra_linker_flags,
+link_executable, exe_file, object_file, lib_file, exe_file, prelink,
+need_prelink, extra_link_args_after_prelink
+
+=item TO DO
+
+=item HISTORY
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::CBuilder::Platform::Windows - Builder class for Windows
+platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::Command - utilities to replace common UNIX commands in
+Makefiles etc.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item FUNCTIONS
+
+=back
+
+=back
+
+cat
+
+eqtime
+
+rm_rf
+
+rm_f
+
+touch
+
+mv
+
+cp
+
+chmod
+
+mkpath
+
+test_f
+
+test_d
+
+dos2unix
+
+=over 4
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Command::MM - Commands for the MM's to use in Makefiles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<test_harness>
+
+=back
+
+B<pod2man>
+
+B<warn_if_old_packlist>
+
+B<perllocal_install>
+
+B<uninstall>
+
+=head2 ExtUtils::Constant - generate XS code to import C header constants
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF
+
+=item FUNCTIONS
+
+=back
+
+constant_types
+
+XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME
+
+autoload PACKAGE, VERSION, AUTOLOADER
+
+WriteMakefileSnippet
+
+WriteConstants ATTRIBUTE =E<gt> VALUE [, ...], NAME, DEFAULT_TYPE,
+BREAKOUT_AT, NAMES, C_FH, C_FILE, XS_FH, XS_FILE, SUBNAME, C_SUBNAME
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Constant::Base - base class for ExtUtils::Constant objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+=back
+
+header
+
+memEQ_clause args_hashref
+
+dump_names arg_hashref, ITEM..
+
+assign arg_hashref, VALUE..
+
+return_clause arg_hashref, ITEM
+
+switch_clause arg_hashref, NAMELEN, ITEMHASH, ITEM..
+
+params WHAT
+
+dogfood arg_hashref, ITEM..
+
+normalise_items args, default_type, seen_types, seen_items, ITEM..
+
+C_constant arg_hashref, ITEM.., name, type, value, macro, default, pre,
+post, def_pre, def_post, utf8, weight
+
+=over 4
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Constant::Utils - helper functions for ExtUtils::Constant
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+C_stringify NAME
+
+=back
+
+perl_stringify NAME
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Constant::XS, ExtUtils::Constant::Base - base class for
+ExtUtils::Constant objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Embed - Utilities for embedding Perl in C/C++ applications
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item @EXPORT
+
+=item FUNCTIONS
+
+xsinit(), Examples, ldopts(), Examples, perl_inc(), ccflags(), ccdlflags(),
+ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules)
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Install - install files from here to there
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+_chmod($$;$), _warnonce(@), _choke(@)
+
+=back
+
+_move_file_at_boot( $file, $target, $moan )
+
+_unlink_or_rename( $file, $tryhard, $installing )
+
+=over 4
+
+=item Functions
+
+B<install>
+
+=back
+
+_get_install_skip
+
+_have_write_access
+
+_can_write_dir(C<$dir>)
+
+_mkpath($dir,$show,$mode,$verbose,$fake)
+
+_copy($from,$to,$verbose,$fake)
+
+_chdir($from)
+
+_do_cleanup
+
+install_rooted_file( $file ), install_rooted_dir( $dir )
+
+forceunlink( $file, $tryhard )
+
+directory_not_empty( $dir )
+
+B<install_default> I<DISCOURAGED>
+
+B<uninstall>
+
+inc_uninstall($filepath,$libdir,$verbose,$nonono,$ignore)
+
+run_filter($cmd,$src,$dest)
+
+B<pm_to_blib>
+
+_autosplit
+
+_invokant
+
+=over 4
+
+=item ENVIRONMENT
+
+B<PERL_INSTALL_ROOT>, B<EU_INSTALL_IGNORE_SKIP>,
+B<EU_INSTALL_SITE_SKIPFILE>
+
+=item AUTHOR
+
+=item LICENSE
+
+=back
+
+=head2 ExtUtils::Installed - Inventory management of installed modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+=item FUNCTIONS
+
+new(), modules(), files(), directories(), directory_tree(), validate(),
+packlist(), version()
+
+=item EXAMPLE
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Liblist - determine libraries to use and how to use them
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+For static extensions, For dynamic extensions at build/link time, For
+dynamic extensions at load time
+
+=over 4
+
+=item EXTRALIBS
+
+=item LDLOADLIBS and LD_RUN_PATH
+
+=item BSLOADLIBS
+
+=back
+
+=item PORTABILITY
+
+=over 4
+
+=item VMS implementation
+
+=item Win32 implementation
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM - OS adjusted ExtUtils::MakeMaker subclass
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::MM_AIX - AIX specific subclass of ExtUtils::MM_Unix
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_Any - Platform-agnostic MM methods
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item Cross-platform helper methods
+
+=back
+
+=back
+
+=over 4
+
+=item Targets
+
+=back
+
+=over 4
+
+=item Init methods
+
+=back
+
+=over 4
+
+=item Tools
+
+=back
+
+=over 4
+
+=item File::Spec wrappers
+
+=back
+
+=over 4
+
+=item Misc
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::MM_BeOS - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+os_flavor
+
+init_linker
+
+=head2 ExtUtils::MM_Cygwin - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+os_flavor
+
+=back
+
+cflags
+
+replace_manpage_separator
+
+init_linker
+
+=head2 ExtUtils::MM_DOS - DOS specific subclass of ExtUtils::MM_Unix
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+os_flavor
+
+=back
+
+=back
+
+B<replace_manpage_separator>
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::MM_NW5 - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+os_flavor
+
+init_platform, platform_constants
+
+const_cccmd
+
+static_lib
+
+dynamic_lib
+
+=head2 ExtUtils::MM_OS2 - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+init_dist
+
+=back
+
+init_linker
+
+os_flavor
+
+=head2 ExtUtils::MM_QNX - QNX specific subclass of ExtUtils::MM_Unix
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_UWIN - U/WIN specific subclass of ExtUtils::MM_Unix
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+os_flavor
+
+=back
+
+=back
+
+B<replace_manpage_separator>
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_Unix - methods used by ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=back
+
+=over 4
+
+=item Methods
+
+os_flavor
+
+=back
+
+c_o (o)
+
+cflags (o)
+
+const_cccmd (o)
+
+const_config (o)
+
+const_loadlibs (o)
+
+constants (o)
+
+depend (o)
+
+init_DEST
+
+init_dist
+
+dist (o)
+
+dist_basics (o)
+
+dist_ci (o)
+
+dist_core (o)
+
+B<dist_target>
+
+B<tardist_target>
+
+B<zipdist_target>
+
+B<tarfile_target>
+
+zipfile_target
+
+uutardist_target
+
+shdist_target
+
+dlsyms (o)
+
+dynamic_bs (o)
+
+dynamic_lib (o)
+
+exescan
+
+extliblist
+
+find_perl
+
+fixin
+
+force (o)
+
+guess_name
+
+has_link_code
+
+init_dirscan
+
+init_MANPODS
+
+init_MAN1PODS
+
+init_MAN3PODS
+
+init_PM
+
+init_DIRFILESEP
+
+init_main
+
+init_others
+
+init_linker
+
+init_lib2arch
+
+init_PERL
+
+init_platform, platform_constants
+
+init_PERM
+
+init_xs
+
+install (o)
+
+installbin (o)
+
+linkext (o)
+
+lsdir
+
+macro (o)
+
+makeaperl (o)
+
+makefile (o)
+
+maybe_command
+
+needs_linking (o)
+
+parse_abstract
+
+parse_version
+
+pasthru (o)
+
+perl_script
+
+perldepend (o)
+
+perm_rw (o)
+
+perm_rwx (o)
+
+pm_to_blib
+
+post_constants (o)
+
+post_initialize (o)
+
+postamble (o)
+
+ppd
+
+prefixify
+
+processPL (o)
+
+quote_paren
+
+replace_manpage_separator
+
+cd
+
+oneliner
+
+quote_literal
+
+escape_newlines
+
+max_exec_len
+
+static (o)
+
+static_lib (o)
+
+staticmake (o)
+
+subdir_x (o)
+
+subdirs (o)
+
+test (o)
+
+test_via_harness (override)
+
+test_via_script (override)
+
+tools_other (o)
+
+tool_xsubpp (o)
+
+all_target
+
+top_targets (o)
+
+writedoc
+
+xs_c (o)
+
+xs_cpp (o)
+
+xs_o (o)
+
+=over 4
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_VMS - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Methods always loaded
+
+wraplist
+
+=back
+
+=back
+
+=over 4
+
+=item Methods
+
+guess_name (override)
+
+=back
+
+find_perl (override)
+
+maybe_command (override)
+
+pasthru (override)
+
+pm_to_blib (override)
+
+perl_script (override)
+
+replace_manpage_separator
+
+init_DEST
+
+init_DIRFILESEP
+
+init_main (override)
+
+init_others (override)
+
+init_platform (override)
+
+platform_constants
+
+init_VERSION (override)
+
+constants (override)
+
+special_targets
+
+cflags (override)
+
+const_cccmd (override)
+
+tools_other (override)
+
+init_dist (override)
+
+c_o (override)
+
+xs_c (override)
+
+xs_o (override)
+
+dlsyms (override)
+
+dynamic_lib (override)
+
+static_lib (override)
+
+extra_clean_files
+
+zipfile_target, tarfile_target, shdist_target
+
+install (override)
+
+perldepend (override)
+
+makeaperl (override)
+
+maketext_filter (override)
+
+prefixify (override)
+
+cd
+
+oneliner
+
+B<echo>
+
+quote_literal
+
+escape_newlines
+
+max_exec_len
+
+init_linker
+
+eliminate_macros
+
+fixpath
+
+os_flavor
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::MM_VOS - VOS specific subclass of ExtUtils::MM_Unix
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MM_Win32 - methods to override UN*X behaviour in
+ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item Overridden methods
+
+B<dlsyms>
+
+=back
+
+replace_manpage_separator
+
+B<maybe_command>
+
+B<init_DIRFILESEP>
+
+B<init_others>
+
+init_platform, platform_constants
+
+special_targets
+
+static_lib
+
+dynamic_lib
+
+extra_clean_files
+
+init_linker
+
+perl_script
+
+xs_o
+
+pasthru
+
+oneliner
+
+cd
+
+max_exec_len
+
+os_flavor
+
+cflags
+
+=head2 ExtUtils::MM_Win95 - method to customize MakeMaker for Win9X
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden methods
+
+xs_c
+
+=back
+
+=back
+
+xs_cpp
+
+xs_o
+
+max_exec_len
+
+os_flavor
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::MY - ExtUtils::MakeMaker subclass for customization
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::MakeMaker - Create a module Makefile
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item How To Write A Makefile.PL
+
+=item Default Makefile Behaviour
+
+=item make test
+
+=item make testdb
+
+=item make install
+
+=item INSTALL_BASE
+
+=item PREFIX and LIB attribute
+
+=item AFS users
+
+=item Static Linking of a new Perl Binary
+
+=item Determination of Perl Library and Installation Locations
+
+=item Which architecture dependent directory?
+
+=item Using Attributes and Parameters
+
+ABSTRACT, ABSTRACT_FROM, AUTHOR, BINARY_LOCATION, C, CCFLAGS, CONFIG,
+CONFIGURE, DEFINE, DESTDIR, DIR, DISTNAME, DISTVNAME, DL_FUNCS, DL_VARS,
+EXCLUDE_EXT, EXE_FILES, FIRST_MAKEFILE, FULLPERL, FULLPERLRUN,
+FULLPERLRUNINST, FUNCLIST, H, IMPORTS, INC, INCLUDE_EXT, INSTALLARCHLIB,
+INSTALLBIN, INSTALLDIRS, INSTALLMAN1DIR, INSTALLMAN3DIR, INSTALLPRIVLIB,
+INSTALLSCRIPT, INSTALLSITEARCH, INSTALLSITEBIN, INSTALLSITELIB,
+INSTALLSITEMAN1DIR, INSTALLSITEMAN3DIR, INSTALLSITESCRIPT,
+INSTALLVENDORARCH, INSTALLVENDORBIN, INSTALLVENDORLIB,
+INSTALLVENDORMAN1DIR, INSTALLVENDORMAN3DIR, INSTALLVENDORSCRIPT,
+INST_ARCHLIB, INST_BIN, INST_LIB, INST_MAN1DIR, INST_MAN3DIR, INST_SCRIPT,
+LD, LDDLFLAGS, LDFROM, LIB, LIBPERL_A, LIBS, LICENSE, LINKTYPE, MAKE,
+MAKEAPERL, MAKEFILE_OLD, MAN1PODS, MAN3PODS, MAP_TARGET, MYEXTLIB, NAME,
+NEEDS_LINKING, NOECHO, NORECURS, NO_META, NO_VC, OBJECT, OPTIMIZE, PERL,
+PERL_CORE, PERLMAINCC, PERL_ARCHLIB, PERL_LIB, PERL_MALLOC_OK, PERLPREFIX,
+PERLRUN, PERLRUNINST, PERL_SRC, PERM_RW, PERM_RWX, PL_FILES, PM, PMLIBDIRS,
+PM_FILTER, POLLUTE, PPM_INSTALL_EXEC, PPM_INSTALL_SCRIPT, PREFIX,
+PREREQ_FATAL, PREREQ_PM, PREREQ_PRINT, PRINT_PREREQ, SITEPREFIX, SIGN,
+SKIP, TYPEMAPS, VENDORPREFIX, VERBINST, VERSION, VERSION_FROM, VERSION_SYM,
+XS, XSOPT, XSPROTOARG, XS_VERSION
+
+=item Additional lowercase attributes
+
+clean, depend, dist, dynamic_lib, linkext, macro, postamble, realclean,
+test, tool_autosplit
+
+=item Overriding MakeMaker Methods
+
+=item The End Of Cargo Cult Programming
+
+C<< MAN3PODS => ' ' >>
+
+=item Hintsfile support
+
+=item Distribution Support
+
+ make distcheck, make skipcheck, make distclean, make manifest,
+ make distdir, make disttest, make tardist, make dist, make
+uutardist, make shdist, make zipdist, make ci
+
+=item Module Meta-Data
+
+=item Disabling an extension
+
+=item Other Handy Functions
+
+prompt
+
+=back
+
+=item ENVIRONMENT
+
+PERL_MM_OPT, PERL_MM_USE_DEFAULT, PERL_CORE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item LICENSE
+
+=back
+
+=head2 ExtUtils::MakeMaker::Config - Wrapper around Config.pm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::MakeMaker::FAQ - Frequently Asked Questions About
+MakeMaker
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Module Installation
+
+How do I install a module into my home directory?, How do I get MakeMaker
+and Module::Build to install to the same place?, How do I keep from
+installing man pages?, How do I use a module without installing it?, PREFIX
+vs INSTALL_BASE from Module::Build::Cookbook
+
+=item Philosophy and History
+
+Why not just use <insert other build config tool here>?, What is
+Module::Build and how does it relate to MakeMaker?, pure perl. no make, no
+shell commands, easier to customize, cleaner internals, less cruft
+
+=item Module Writing
+
+How do I keep my $VERSION up to date without resetting it manually?, What's
+this F<META.yml> thing and how did it get in my F<MANIFEST>?!, How do I
+delete everything not in my F<MANIFEST>?
+
+=item XS
+
+How to I prevent "object version X.XX does not match bootstrap parameter
+Y.YY" errors?, How do I make two or more XS files coexist in the same
+directory?
+
+=back
+
+=item PATCHING
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MakeMaker::Tutorial - Writing a module with MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item The Mantra
+
+=item The Layout
+
+Makefile.PL, MANIFEST, lib/, t/, Changes, README, INSTALL, MANIFEST.SKIP,
+bin/
+
+=back
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::MakeMaker::bytes - Version-agnostic bytes.pm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::MakeMaker::vmsish - Platform-agnostic vmsish.pm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::Manifest - utilities to write and check a MANIFEST file
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Functions
+
+mkmanifest
+
+=back
+
+=back
+
+manifind
+
+manicheck
+
+filecheck
+
+fullcheck
+
+skipcheck
+
+maniread
+
+manicopy
+
+maniadd
+
+=over 4
+
+=item MANIFEST
+
+=item MANIFEST.SKIP
+
+#!include_default, #!include /Path/to/another/manifest.skip
+
+=item EXPORT_OK
+
+=item GLOBAL VARIABLES
+
+=back
+
+=over 4
+
+=item DIAGNOSTICS
+
+C<Not in MANIFEST:> I<file>, C<Skipping> I<file>, C<No such file:> I<file>,
+C<MANIFEST:> I<$!>, C<Added to MANIFEST:> I<file>
+
+=item ENVIRONMENT
+
+B<PERL_MM_MANIFEST_DEBUG>
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::Miniperl, writemain - write the C code for perlmain.c
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::Mkbootstrap - make a bootstrap file for use by DynaLoader
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 ExtUtils::Mksymlists - write linker options files for dynamic
+extension
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+DLBASE, DL_FUNCS, DL_VARS, FILE, FUNCLIST, IMPORTS, NAME
+
+=item AUTHOR
+
+=item REVISION
+
+mkfh()
+
+=back
+
+__find_relocations
+
+=head2 ExtUtils::Packlist - manage .packlist files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+=item FUNCTIONS
+
+new(), read(), write(), validate(), packlist_file()
+
+=item EXAMPLE
+
+=item AUTHOR
+
+=back
+
+=head2 ExtUtils::ParseXS - converts Perl XS code into C code
+
+=over 4
+
+=item SYNOPSIS
+
+=item EXPORT
+
+=item FUNCTIONS
+
+process_xs(), B<C++>, B<hiertype>, B<except>, B<typemap>, B<prototypes>,
+B<versioncheck>, B<linenumbers>, B<optimize>, B<inout>, B<argtypes>, B<s>,
+errors()
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 ExtUtils::testlib - add blib/* directories to @INC
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 Fatal - replace functions with equivalents which succeed or die
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 Fcntl - load the C Fcntl.h defines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item EXPORTED SYMBOLS
+
+=back
+
+=head2 File::Basename - Parse file paths into directory, filename and
+suffix.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+C<fileparse> X<fileparse>
+
+C<basename> X<basename> X<filename>
+
+C<dirname> X<dirname>
+
+C<fileparse_set_fstype> X<filesystem>
+
+=over 4
+
+=item SEE ALSO
+
+=back
+
+=head2 File::CheckTree - run many filetest checks on a tree
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item HISTORY
+
+=back
+
+=head2 File::Compare - Compare files or filehandles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item RETURN
+
+=item AUTHOR
+
+=back
+
+=head2 File::Copy - Copy files or filehandles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+copy X<copy> X<cp>, move X<move> X<mv> X<rename>, syscopy X<syscopy>,
+rmscopy($from,$to[,$date_flag]) X<rmscopy>
+
+=item RETURN
+
+=item NOTES
+
+=item AUTHOR
+
+=back
+
+=head2 File::DosGlob - DOS like globbing and then some
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item EXPORTS (by request only)
+
+=item BUGS
+
+=item AUTHOR
+
+=item HISTORY
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Fetch - A generic file fetching mechanism
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ACCESSORS
+
+$ff->uri, $ff->scheme, $ff->host, $ff->vol, $ff->share, $ff->path,
+$ff->file
+
+=back
+
+$ff->output_file
+
+=over 4
+
+=item METHODS
+
+=over 4
+
+=item $ff = File::Fetch->new( uri => 'http://some.where.com/dir/file.txt'
+);
+
+=back
+
+=back
+
+=over 4
+
+=item $ff->fetch( [to => /my/output/dir/] )
+
+=back
+
+=over 4
+
+=item $ff->error([BOOL])
+
+=back
+
+=over 4
+
+=item HOW IT WORKS
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $File::Fetch::FROM_EMAIL
+
+=item $File::Fetch::USER_AGENT
+
+=item $File::Fetch::FTP_PASSIVE
+
+=item $File::Fetch::TIMEOUT
+
+=item $File::Fetch::WARN
+
+=item $File::Fetch::DEBUG
+
+=item $File::Fetch::BLACKLIST
+
+=item $File::Fetch::METHOD_FAIL
+
+=back
+
+=item MAPPING
+
+=item FREQUENTLY ASKED QUESTIONS
+
+=over 4
+
+=item So how do I use a proxy with File::Fetch?
+
+=item I used 'lynx' to fetch a file, but its contents is all wrong!
+
+=item Files I'm trying to fetch have reserved characters or non-ASCII
+characters in them. What do I do?
+
+=back
+
+=item TODO
+
+Implement $PREFER_BIN
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 File::Find - Traverse a directory tree.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<find>, B<finddepth>
+
+=over 4
+
+=item %options
+
+C<wanted>, C<bydepth>, C<preprocess>, C<postprocess>, C<follow>,
+C<follow_fast>, C<follow_skip>, C<dangling_symlinks>, C<no_chdir>,
+C<untaint>, C<untaint_pattern>, C<untaint_skip>
+
+=item The wanted function
+
+C<$File::Find::dir> is the current directory name,, C<$_> is the current
+filename within that directory, C<$File::Find::name> is the complete
+pathname to the file
+
+=back
+
+=item WARNINGS
+
+=item CAVEAT
+
+$dont_use_nlink, symlinks
+
+=item NOTES
+
+=item BUGS AND CAVEATS
+
+=item HISTORY
+
+=back
+
+=head2 File::Glob - Perl extension for BSD glob routine
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item META CHARACTERS
+
+=item POSIX FLAGS
+
+C<GLOB_ERR>, C<GLOB_LIMIT>, C<GLOB_MARK>, C<GLOB_NOCASE>, C<GLOB_NOCHECK>,
+C<GLOB_NOSORT>, C<GLOB_BRACE>, C<GLOB_NOMAGIC>, C<GLOB_QUOTE>,
+C<GLOB_TILDE>, C<GLOB_CSH>, C<GLOB_ALPHASORT>
+
+=back
+
+=item DIAGNOSTICS
+
+C<GLOB_NOSPACE>, C<GLOB_ABEND>
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 File::GlobMapper - Extend File Glob to Allow Input and Output Files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+This code is a work in progress, There are known bugs, The interface
+defined here is tentative, There are portability issues, Do not use in
+production code, Consider yourself warned!
+
+=over 4
+
+=item Behind The Scenes
+
+=item Limitations
+
+=item Input File Glob
+
+B<~>, B<~user>, B<.>, B<*>, B<?>, B<\>, B<[]>, B<{,}>, B<()>
+
+=item Output File Glob
+
+"*", #1
+
+=item Returned Data
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item A Rename script
+
+=item A few example globmaps
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 File::Path - Create or remove directory trees
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item FUNCTIONS
+
+mode, verbose, error, verbose, safe, keep_root, result, error
+
+=item TRADITIONAL INTERFACE
+
+=item ERROR HANDLING
+
+=item NOTES
+
+=back
+
+=item DIAGNOSTICS
+
+mkdir [path]: [errmsg] (SEVERE), No root path(s) specified, No such file or
+directory, cannot fetch initial working directory: [errmsg], cannot stat
+initial working directory: [errmsg], cannot chdir to [dir]: [errmsg],
+directory [dir] changed before chdir, expected dev=[n] inode=[n], actual
+dev=[n] ino=[n], aborting. (FATAL), cannot make directory [dir]
+read+writeable: [errmsg], cannot read [dir]: [errmsg], cannot reset chmod
+[dir]: [errmsg], cannot chdir to [parent-dir] from [child-dir]: [errmsg],
+aborting. (FATAL), cannot stat prior working directory [dir]: [errmsg],
+aborting. (FATAL), previous directory [parent-dir] changed before entering
+[child-dir], expected dev=[n] inode=[n], actual dev=[n] ino=[n], aborting.
+(FATAL), cannot make directory [dir] writeable: [errmsg], cannot remove
+directory [dir]: [errmsg], cannot restore permissions of [dir] to [0nnn]:
+[errmsg], cannot make file [file] writeable: [errmsg], cannot unlink file
+[file]: [errmsg], cannot restore permissions of [file] to [0nnn]: [errmsg]
+
+=item SEE ALSO
+
+=item BUGS
+
+=item ACKNOWLEDGEMENTS
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=item LICENSE
+
+=back
+
+=head2 File::Spec - portably perform operations on file names
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+canonpath X<canonpath>, catdir X<catdir>, catfile X<catfile>, curdir
+X<curdir>, devnull X<devnull>, rootdir X<rootdir>, tmpdir X<tmpdir>, updir
+X<updir>, no_upwards, case_tolerant, file_name_is_absolute, path X<path>,
+join X<join, path>, splitpath X<splitpath> X<split, path>, splitdir
+X<splitdir> X<split, dir>, catpath(), abs2rel X<abs2rel> X<absolute, path>
+X<relative, path>, rel2abs() X<rel2abs> X<absolute, path> X<relative, path>
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 File::Spec::Cygwin - methods for Cygwin file specs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+canonpath
+
+file_name_is_absolute
+
+tmpdir (override)
+
+case_tolerant
+
+=over 4
+
+=item COPYRIGHT
+
+=back
+
+=head2 File::Spec::Epoc - methods for Epoc file specs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+canonpath()
+
+=over 4
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Spec::Functions - portably perform operations on file names
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Exports
+
+=back
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Spec::Mac - File::Spec for Mac OS (Classic)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+canonpath
+
+=back
+
+catdir()
+
+catfile
+
+curdir
+
+devnull
+
+rootdir
+
+tmpdir
+
+updir
+
+file_name_is_absolute
+
+path
+
+splitpath
+
+splitdir
+
+catpath
+
+abs2rel
+
+rel2abs
+
+=over 4
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Spec::OS2 - methods for OS/2 file specs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+tmpdir, splitpath
+
+=item COPYRIGHT
+
+=back
+
+=head2 File::Spec::Unix - File::Spec for Unix, base for other File::Spec
+modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+canonpath()
+
+=back
+
+catdir()
+
+catfile
+
+curdir
+
+devnull
+
+rootdir
+
+tmpdir
+
+updir
+
+no_upwards
+
+case_tolerant
+
+file_name_is_absolute
+
+path
+
+join
+
+splitpath
+
+splitdir
+
+catpath()
+
+abs2rel
+
+rel2abs()
+
+=over 4
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Spec::VMS - methods for VMS file specs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+canonpath (override)
+
+=back
+
+catdir (override)
+
+catfile (override)
+
+curdir (override)
+
+devnull (override)
+
+rootdir (override)
+
+tmpdir (override)
+
+updir (override)
+
+case_tolerant (override)
+
+path (override)
+
+file_name_is_absolute (override)
+
+splitpath (override)
+
+splitdir (override)
+
+catpath (override)
+
+abs2rel (override)
+
+rel2abs (override)
+
+=over 4
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Spec::Win32 - methods for Win32 file specs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+devnull
+
+=back
+
+tmpdir
+
+case_tolerant
+
+file_name_is_absolute
+
+catfile
+
+canonpath
+
+splitpath
+
+splitdir
+
+catpath
+
+=over 4
+
+=item Note For File::Spec::Win32 Maintainers
+
+=back
+
+=over 4
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 File::Temp - return name and handle of a temporary file safely
+
+=over 4
+
+=item PORTABILITY
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item OBJECT-ORIENTED INTERFACE
+
+B<new>
+
+=back
+
+B<filename>
+
+B<unlink_on_destroy>
+
+B<DESTROY>
+
+=over 4
+
+=item FUNCTIONS
+
+B<tempfile>
+
+=back
+
+B<tempdir>
+
+=over 4
+
+=item MKTEMP FUNCTIONS
+
+B<mkstemp>
+
+=back
+
+B<mkstemps>
+
+B<mkdtemp>
+
+B<mktemp>
+
+=over 4
+
+=item POSIX FUNCTIONS
+
+B<tmpnam>
+
+=back
+
+B<tmpfile>
+
+=over 4
+
+=item ADDITIONAL FUNCTIONS
+
+B<tempnam>
+
+=back
+
+=over 4
+
+=item UTILITY FUNCTIONS
+
+B<unlink0>
+
+=back
+
+B<cmpstat>
+
+B<unlink1>
+
+B<cleanup>
+
+=over 4
+
+=item PACKAGE VARIABLES
+
+B<safe_level>, STANDARD, MEDIUM, HIGH
+
+=back
+
+TopSystemUID
+
+B<$KEEP_ALL>, B<$DEBUG>
+
+=over 4
+
+=item WARNING
+
+=over 4
+
+=item Temporary files and NFS
+
+=item Forking
+
+=item BINMODE
+
+=back
+
+=item HISTORY
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 File::stat - by-name interface to Perl's built-in stat() functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 FileCache - keep more files open than the system permits
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+cacheout EXPR, cacheout MODE, EXPR
+
+=item CAVEATS
+
+=item BUGS
+
+=back
+
+=head2 FileHandle - supply object methods for filehandles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$fh->print, $fh->printf, $fh->getline, $fh->getlines
+
+=item SEE ALSO
+
+=back
+
+=head2 Filter::Simple - Simplified source filtering
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item The Problem
+
+=item A Solution
+
+=item Disabling or changing <no> behaviour
+
+=item All-in-one interface
+
+=item Filtering only specific components of source code
+
+C<"code">, C<"code_no_comments">, C<"executable">,
+C<"executable_no_comments">, C<"quotelike">, C<"string">, C<"regex">,
+C<"all">
+
+=item Filtering only the code parts of source code
+
+Most source code ceases to be grammatically correct when it is broken up
+into the pieces between string literals and regexes. So the C<'code'>
+and C<'code_no_comments'> component filter behave slightly differently
+from the other partial filters described in the previous section.
+
+=item Using Filter::Simple with an explicit C<import> subroutine
+
+=item Using Filter::Simple and Exporter together
+
+=item How it works
+
+=back
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Filter::Util::Call - Perl Source Filter Utility Module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item B<use Filter::Util::Call>
+
+=item B<import()>
+
+=item B<filter() and anonymous sub>
+
+B<$_>, B<$status>, B<filter_read> and B<filter_read_exact>, B<filter_del>
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item Example 1: A simple filter.
+
+=item Example 2: Using the context
+
+=item Example 3: Using the context within the filter
+
+=item Example 4: Using filter_del
+
+=back
+
+=item Filter::Simple
+
+=item AUTHOR
+
+=item DATE
+
+=back
+
+=head2 FindBin - Locate directory of original perl script
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPORTABLE VARIABLES
+
+=item KNOWN ISSUES
+
+=item KNOWN BUGS
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 GDBM_File - Perl5 access to the gdbm library.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AVAILABILITY
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Getopt::Long - Extended processing of command line options
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Command Line Options, an Introduction
+
+=item Getting Started with Getopt::Long
+
+=over 4
+
+=item Simple options
+
+=item A little bit less simple options
+
+=item Mixing command line option with other arguments
+
+=item Options with values
+
+=item Options with multiple values
+
+=item Options with hash values
+
+=item User-defined subroutines to handle options
+
+=item Options with multiple names
+
+=item Case and abbreviations
+
+=item Summary of Option Specifications
+
+!, +, s, i, o, f, : I<type> [ I<desttype> ], : I<number> [ I<desttype> ], :
++ [ I<desttype> ]
+
+=back
+
+=item Advanced Possibilities
+
+=over 4
+
+=item Object oriented interface
+
+=item Thread Safety
+
+=item Documentation and help texts
+
+=item Parsing options from an arbitrary array
+
+=item Parsing options from an arbitrary string
+
+=item Storing options values in a hash
+
+=item Bundling
+
+=item The lonesome dash
+
+=item Argument callback
+
+=back
+
+=item Configuring Getopt::Long
+
+default, posix_default, auto_abbrev, getopt_compat, gnu_compat, gnu_getopt,
+require_order, permute, bundling (default: disabled), bundling_override
+(default: disabled), ignore_case (default: enabled), ignore_case_always
+(default: disabled), auto_version (default:disabled), auto_help
+(default:disabled), pass_through (default: disabled), prefix,
+prefix_pattern, long_prefix_pattern, debug (default: disabled)
+
+=item Exportable Methods
+
+VersionMessage, C<-message>, C<-msg>, C<-exitval>, C<-output>, HelpMessage
+
+=item Return values and Errors
+
+=item Legacy
+
+=over 4
+
+=item Default destinations
+
+=item Alternative option starters
+
+=item Configuration variables
+
+=back
+
+=item Tips and Techniques
+
+=over 4
+
+=item Pushing multiple values in a hash option
+
+=back
+
+=item Trouble Shooting
+
+=over 4
+
+=item GetOptions does not return a false result when an option is not
+supplied
+
+=item GetOptions does not split the command line correctly
+
+=item Undefined subroutine &main::GetOptions called
+
+=item How do I put a "-?" option into a Getopt::Long?
+
+=back
+
+=item AUTHOR
+
+=item COPYRIGHT AND DISCLAIMER
+
+=back
+
+=head2 Getopt::Std, getopt, getopts - Process single-character switches
+with switch clustering
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item C<--help> and C<--version>
+
+=back
+
+=head2 Hash::Util - A selection of general-utility hash subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Restricted hashes
+
+B<lock_keys>, B<unlock_keys>
+
+=back
+
+=back
+
+B<lock_keys_plus>
+
+B<lock_value>, B<unlock_value>
+
+B<lock_hash>, B<unlock_hash>
+
+B<lock_hash_recurse>, B<unlock_hash_recurse>
+
+B<hash_unlocked>
+
+B<legal_keys>, B<hidden_keys>, B<all_keys>, B<hash_seed>
+
+B<hv_store>
+
+=over 4
+
+=item Operating on references to hashes.
+
+lock_ref_keys, unlock_ref_keys, lock_ref_keys_plus, lock_ref_value,
+unlock_ref_value, lock_hashref, unlock_hashref, lock_hashref_recurse,
+unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys
+
+=back
+
+=over 4
+
+=item CAVEATS
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Hash::Util::FieldHash - Support for Inside-Out Classes
+
+=over 4
+
+=item SYNOPSIS
+
+=item FUNCTIONS
+
+id, id_2obj, register, idhash, idhashes, fieldhash, fieldhashes
+
+=item DESCRIPTION
+
+=over 4
+
+=item The Inside-out Technique
+
+=item Problems of Inside-out
+
+=item Solutions
+
+=item More Problems
+
+=item The Generic Object
+
+=item How to use Field Hashes
+
+=item Garbage-Collected Hashes
+
+=back
+
+=item EXAMPLES
+
+C<init()>, C<first()>, C<last()>, C<name()>, C<Name_hash>, C<Name_id>,
+C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash>
+
+=over 4
+
+=item Example 1
+
+=item Example 2
+
+=back
+
+=item GUTS
+
+=over 4
+
+=item The C<PERL_MAGIC_uvar> interface for hashes
+
+=item Weakrefs call uvar magic
+
+=item How field hashes work
+
+=item Internal function Hash::Util::FieldHash::_fieldhash
+
+=back
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Hash::Util::FieldHash::lib::Hash::Util::FieldHash,
+Hash::Util::FieldHash - Support for Inside-Out Classes
+
+=over 4
+
+=item SYNOPSIS
+
+=item FUNCTIONS
+
+id, id_2obj, register, idhash, idhashes, fieldhash, fieldhashes
+
+=item DESCRIPTION
+
+=over 4
+
+=item The Inside-out Technique
+
+=item Problems of Inside-out
+
+=item Solutions
+
+=item More Problems
+
+=item The Generic Object
+
+=item How to use Field Hashes
+
+=item Garbage-Collected Hashes
+
+=back
+
+=item EXAMPLES
+
+C<init()>, C<first()>, C<last()>, C<name()>, C<Name_hash>, C<Name_id>,
+C<Name_idhash>, C<Name_id_reg>, C<Name_idhash_reg>, C<Name_fieldhash>
+
+=over 4
+
+=item Example 1
+
+=item Example 2
+
+=back
+
+=item GUTS
+
+=over 4
+
+=item The C<PERL_MAGIC_uvar> interface for hashes
+
+=item Weakrefs call uvar magic
+
+=item How field hashes work
+
+=item Internal function Hash::Util::FieldHash::_fieldhash
+
+=back
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Hash::Utilib::Hash::Util, Hash::Util - A selection of
+general-utility hash subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Restricted hashes
+
+B<lock_keys>, B<unlock_keys>
+
+=back
+
+=back
+
+B<lock_keys_plus>
+
+B<lock_value>, B<unlock_value>
+
+B<lock_hash>, B<unlock_hash>
+
+B<lock_hash_recurse>, B<unlock_hash_recurse>
+
+B<hash_unlocked>
+
+B<legal_keys>, B<hidden_keys>, B<all_keys>, B<hash_seed>
+
+B<hv_store>
+
+=over 4
+
+=item Operating on references to hashes.
+
+lock_ref_keys, unlock_ref_keys, lock_ref_keys_plus, lock_ref_value,
+unlock_ref_value, lock_hashref, unlock_hashref, lock_hashref_recurse,
+unlock_hashref_recurse, hash_ref_unlocked, legal_ref_keys, hidden_ref_keys
+
+=back
+
+=over 4
+
+=item CAVEATS
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 I18N::Collate - compare 8-bit scalar data according to the current
+locale
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 I18N::LangTags - functions for dealing with RFC3066-style language
+tags
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+the function is_language_tag($lang1)
+
+the function extract_language_tags($whatever)
+
+the function same_language_tag($lang1, $lang2)
+
+the function similarity_language_tag($lang1, $lang2)
+
+the function is_dialect_of($lang1, $lang2)
+
+the function super_languages($lang1)
+
+the function locale2language_tag($locale_identifier)
+
+the function encode_language_tag($lang1)
+
+the function alternate_language_tags($lang1)
+
+the function @langs = panic_languages(@accept_languages)
+
+the function implicate_supers( ...languages... ), the function
+implicate_supers_strictly( ...languages... )
+
+=over 4
+
+=item ABOUT LOWERCASING
+
+=item ABOUT UNICODE PLAINTEXT LANGUAGE TAGS
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=item AUTHOR
+
+=back
+
+=head2 I18N::LangTags::Detect - detect the user's language preferences
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=item ENVIRONMENT
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=item AUTHOR
+
+=back
+
+=head2 I18N::LangTags::List -- tags and names for human languages
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item ABOUT LANGUAGE TAGS
+
+=item LIST OF LANGUAGES
+
+{ab} : Abkhazian, {ace} : Achinese, {ach} : Acoli, {ada} : Adangme, {ady} :
+Adyghe, {aa} : Afar, {afh} : Afrihili, {af} : Afrikaans, [{afa} :
+Afro-Asiatic (Other)], {ak} : Akan, {akk} : Akkadian, {sq} : Albanian,
+{ale} : Aleut, [{alg} : Algonquian languages], [{tut} : Altaic (Other)],
+{am} : Amharic, {i-ami} : Ami, [{apa} : Apache languages], {ar} : Arabic,
+{arc} : Aramaic, {arp} : Arapaho, {arn} : Araucanian, {arw} : Arawak, {hy}
+: Armenian, {an} : Aragonese, [{art} : Artificial (Other)], {ast} :
+Asturian, {as} : Assamese, [{ath} : Athapascan languages], [{aus} :
+Australian languages], [{map} : Austronesian (Other)], {av} : Avaric, {ae}
+: Avestan, {awa} : Awadhi, {ay} : Aymara, {az} : Azerbaijani, {ban} :
+Balinese, [{bat} : Baltic (Other)], {bal} : Baluchi, {bm} : Bambara, [{bai}
+: Bamileke languages], {bad} : Banda, [{bnt} : Bantu (Other)], {bas} :
+Basa, {ba} : Bashkir, {eu} : Basque, {btk} : Batak (Indonesia), {bej} :
+Beja, {be} : Belarusian, {bem} : Bemba, {bn} : Bengali, [{ber} : Berber
+(Other)], {bho} : Bhojpuri, {bh} : Bihari, {bik} : Bikol, {bin} : Bini,
+{bi} : Bislama, {bs} : Bosnian, {bra} : Braj, {br} : Breton, {bug} :
+Buginese, {bg} : Bulgarian, {i-bnn} : Bunun, {bua} : Buriat, {my} :
+Burmese, {cad} : Caddo, {car} : Carib, {ca} : Catalan, [{cau} : Caucasian
+(Other)], {ceb} : Cebuano, [{cel} : Celtic (Other)], [{cai} : Central
+American Indian (Other)], {chg} : Chagatai, [{cmc} : Chamic languages],
+{ch} : Chamorro, {ce} : Chechen, {chr} : Cherokee, {chy} : Cheyenne, {chb}
+: Chibcha, {ny} : Chichewa, {zh} : Chinese, {chn} : Chinook Jargon, {chp} :
+Chipewyan, {cho} : Choctaw, {cu} : Church Slavic, {chk} : Chuukese, {cv} :
+Chuvash, {cop} : Coptic, {kw} : Cornish, {co} : Corsican, {cr} : Cree,
+{mus} : Creek, [{cpe} : English-based Creoles and pidgins (Other)], [{cpf}
+: French-based Creoles and pidgins (Other)], [{cpp} : Portuguese-based
+Creoles and pidgins (Other)], [{crp} : Creoles and pidgins (Other)], {hr} :
+Croatian, [{cus} : Cushitic (Other)], {cs} : Czech, {dak} : Dakota, {da} :
+Danish, {dar} : Dargwa, {day} : Dayak, {i-default} : Default (Fallthru)
+Language, {del} : Delaware, {din} : Dinka, {dv} : Divehi, {doi} : Dogri,
+{dgr} : Dogrib, [{dra} : Dravidian (Other)], {dua} : Duala, {nl} : Dutch,
+{dum} : Middle Dutch (ca.1050-1350), {dyu} : Dyula, {dz} : Dzongkha, {efi}
+: Efik, {egy} : Ancient Egyptian, {eka} : Ekajuk, {elx} : Elamite, {en} :
+English, {enm} : Old English (1100-1500), {ang} : Old English
+(ca.450-1100), {i-enochian} : Enochian (Artificial), {myv} : Erzya, {eo} :
+Esperanto, {et} : Estonian, {ee} : Ewe, {ewo} : Ewondo, {fan} : Fang, {fat}
+: Fanti, {fo} : Faroese, {fj} : Fijian, {fi} : Finnish, [{fiu} :
+Finno-Ugrian (Other)], {fon} : Fon, {fr} : French, {frm} : Middle French
+(ca.1400-1600), {fro} : Old French (842-ca.1400), {fy} : Frisian, {fur} :
+Friulian, {ff} : Fulah, {gaa} : Ga, {gd} : Scots Gaelic, {gl} : Gallegan,
+{lg} : Ganda, {gay} : Gayo, {gba} : Gbaya, {gez} : Geez, {ka} : Georgian,
+{de} : German, {gmh} : Middle High German (ca.1050-1500), {goh} : Old High
+German (ca.750-1050), [{gem} : Germanic (Other)], {gil} : Gilbertese, {gon}
+: Gondi, {gor} : Gorontalo, {got} : Gothic, {grb} : Grebo, {grc} : Ancient
+Greek, {el} : Modern Greek, {gn} : Guarani, {gu} : Gujarati, {gwi} :
+Gwich'in, {hai} : Haida, {ht} : Haitian, {ha} : Hausa, {haw} : Hawaiian,
+{he} : Hebrew, {hz} : Herero, {hil} : Hiligaynon, {him} : Himachali, {hi} :
+Hindi, {ho} : Hiri Motu, {hit} : Hittite, {hmn} : Hmong, {hu} : Hungarian,
+{hup} : Hupa, {iba} : Iban, {is} : Icelandic, {io} : Ido, {ig} : Igbo,
+{ijo} : Ijo, {ilo} : Iloko, [{inc} : Indic (Other)], [{ine} : Indo-European
+(Other)], {id} : Indonesian, {inh} : Ingush, {ia} : Interlingua
+(International Auxiliary Language Association), {ie} : Interlingue, {iu} :
+Inuktitut, {ik} : Inupiaq, [{ira} : Iranian (Other)], {ga} : Irish, {mga} :
+Middle Irish (900-1200), {sga} : Old Irish (to 900), [{iro} : Iroquoian
+languages], {it} : Italian, {ja} : Japanese, {jv} : Javanese, {jrb} :
+Judeo-Arabic, {jpr} : Judeo-Persian, {kbd} : Kabardian, {kab} : Kabyle,
+{kac} : Kachin, {kl} : Kalaallisut, {xal} : Kalmyk, {kam} : Kamba, {kn} :
+Kannada, {kr} : Kanuri, {krc} : Karachay-Balkar, {kaa} : Kara-Kalpak, {kar}
+: Karen, {ks} : Kashmiri, {csb} : Kashubian, {kaw} : Kawi, {kk} : Kazakh,
+{kha} : Khasi, {km} : Khmer, [{khi} : Khoisan (Other)], {kho} : Khotanese,
+{ki} : Kikuyu, {kmb} : Kimbundu, {rw} : Kinyarwanda, {ky} : Kirghiz,
+{i-klingon} : Klingon, {kv} : Komi, {kg} : Kongo, {kok} : Konkani, {ko} :
+Korean, {kos} : Kosraean, {kpe} : Kpelle, {kro} : Kru, {kj} : Kuanyama,
+{kum} : Kumyk, {ku} : Kurdish, {kru} : Kurukh, {kut} : Kutenai, {lad} :
+Ladino, {lah} : Lahnda, {lam} : Lamba, {lo} : Lao, {la} : Latin, {lv} :
+Latvian, {lb} : Letzeburgesch, {lez} : Lezghian, {li} : Limburgish, {ln} :
+Lingala, {lt} : Lithuanian, {nds} : Low German, {art-lojban} : Lojban
+(Artificial), {loz} : Lozi, {lu} : Luba-Katanga, {lua} : Luba-Lulua, {lui}
+: Luiseno, {lun} : Lunda, {luo} : Luo (Kenya and Tanzania), {lus} : Lushai,
+{mk} : Macedonian, {mad} : Madurese, {mag} : Magahi, {mai} : Maithili,
+{mak} : Makasar, {mg} : Malagasy, {ms} : Malay, {ml} : Malayalam, {mt} :
+Maltese, {mnc} : Manchu, {mdr} : Mandar, {man} : Mandingo, {mni} :
+Manipuri, [{mno} : Manobo languages], {gv} : Manx, {mi} : Maori, {mr} :
+Marathi, {chm} : Mari, {mh} : Marshall, {mwr} : Marwari, {mas} : Masai,
+[{myn} : Mayan languages], {men} : Mende, {mic} : Micmac, {min} :
+Minangkabau, {i-mingo} : Mingo, [{mis} : Miscellaneous languages], {moh} :
+Mohawk, {mdf} : Moksha, {mo} : Moldavian, [{mkh} : Mon-Khmer (Other)],
+{lol} : Mongo, {mn} : Mongolian, {mos} : Mossi, [{mul} : Multiple
+languages], [{mun} : Munda languages], {nah} : Nahuatl, {nap} : Neapolitan,
+{na} : Nauru, {nv} : Navajo, {nd} : North Ndebele, {nr} : South Ndebele,
+{ng} : Ndonga, {ne} : Nepali, {new} : Newari, {nia} : Nias, [{nic} :
+Niger-Kordofanian (Other)], [{ssa} : Nilo-Saharan (Other)], {niu} : Niuean,
+{nog} : Nogai, {non} : Old Norse, [{nai} : North American Indian], {no} :
+Norwegian, {nb} : Norwegian Bokmal, {nn} : Norwegian Nynorsk, [{nub} :
+Nubian languages], {nym} : Nyamwezi, {nyn} : Nyankole, {nyo} : Nyoro, {nzi}
+: Nzima, {oc} : Occitan (post 1500), {oj} : Ojibwa, {or} : Oriya, {om} :
+Oromo, {osa} : Osage, {os} : Ossetian; Ossetic, [{oto} : Otomian
+languages], {pal} : Pahlavi, {i-pwn} : Paiwan, {pau} : Palauan, {pi} :
+Pali, {pam} : Pampanga, {pag} : Pangasinan, {pa} : Panjabi, {pap} :
+Papiamento, [{paa} : Papuan (Other)], {fa} : Persian, {peo} : Old Persian
+(ca.600-400 B.C.), [{phi} : Philippine (Other)], {phn} : Phoenician, {pon}
+: Pohnpeian, {pl} : Polish, {pt} : Portuguese, [{pra} : Prakrit languages],
+{pro} : Old Provencal (to 1500), {ps} : Pushto, {qu} : Quechua, {rm} :
+Raeto-Romance, {raj} : Rajasthani, {rap} : Rapanui, {rar} : Rarotongan,
+[{qaa - qtz} : Reserved for local use.], [{roa} : Romance (Other)], {ro} :
+Romanian, {rom} : Romany, {rn} : Rundi, {ru} : Russian, [{sal} : Salishan
+languages], {sam} : Samaritan Aramaic, {se} : Northern Sami, {sma} :
+Southern Sami, {smn} : Inari Sami, {smj} : Lule Sami, {sms} : Skolt Sami,
+[{smi} : Sami languages (Other)], {sm} : Samoan, {sad} : Sandawe, {sg} :
+Sango, {sa} : Sanskrit, {sat} : Santali, {sc} : Sardinian, {sas} : Sasak,
+{sco} : Scots, {sel} : Selkup, [{sem} : Semitic (Other)], {sr} : Serbian,
+{srr} : Serer, {shn} : Shan, {sn} : Shona, {sid} : Sidamo, {sgn-...} : Sign
+Languages, {bla} : Siksika, {sd} : Sindhi, {si} : Sinhalese, [{sit} :
+Sino-Tibetan (Other)], [{sio} : Siouan languages], {den} : Slave
+(Athapascan), [{sla} : Slavic (Other)], {sk} : Slovak, {sl} : Slovenian,
+{sog} : Sogdian, {so} : Somali, {son} : Songhai, {snk} : Soninke, {wen} :
+Sorbian languages, {nso} : Northern Sotho, {st} : Southern Sotho, [{sai} :
+South American Indian (Other)], {es} : Spanish, {suk} : Sukuma, {sux} :
+Sumerian, {su} : Sundanese, {sus} : Susu, {sw} : Swahili, {ss} : Swati,
+{sv} : Swedish, {syr} : Syriac, {tl} : Tagalog, {ty} : Tahitian, [{tai} :
+Tai (Other)], {tg} : Tajik, {tmh} : Tamashek, {ta} : Tamil, {i-tao} : Tao,
+{tt} : Tatar, {i-tay} : Tayal, {te} : Telugu, {ter} : Tereno, {tet} :
+Tetum, {th} : Thai, {bo} : Tibetan, {tig} : Tigre, {ti} : Tigrinya, {tem} :
+Timne, {tiv} : Tiv, {tli} : Tlingit, {tpi} : Tok Pisin, {tkl} : Tokelau,
+{tog} : Tonga (Nyasa), {to} : Tonga (Tonga Islands), {tsi} : Tsimshian,
+{ts} : Tsonga, {i-tsu} : Tsou, {tn} : Tswana, {tum} : Tumbuka, [{tup} :
+Tupi languages], {tr} : Turkish, {ota} : Ottoman Turkish (1500-1928), {crh}
+: Crimean Turkish, {tk} : Turkmen, {tvl} : Tuvalu, {tyv} : Tuvinian, {tw} :
+Twi, {udm} : Udmurt, {uga} : Ugaritic, {ug} : Uighur, {uk} : Ukrainian,
+{umb} : Umbundu, {und} : Undetermined, {ur} : Urdu, {uz} : Uzbek, {vai} :
+Vai, {ve} : Venda, {vi} : Vietnamese, {vo} : Volapuk, {vot} : Votic, [{wak}
+: Wakashan languages], {wa} : Walloon, {wal} : Walamo, {war} : Waray, {was}
+: Washo, {cy} : Welsh, {wo} : Wolof, {x-...} : Unregistered (Semi-Private
+Use), {xh} : Xhosa, {sah} : Yakut, {yao} : Yao, {yap} : Yapese, {ii} :
+Sichuan Yi, {yi} : Yiddish, {yo} : Yoruba, [{ypk} : Yupik languages], {znd}
+: Zande, [{zap} : Zapotec], {zen} : Zenaga, {za} : Zhuang, {zu} : Zulu,
+{zun} : Zuni
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMER
+
+=item AUTHOR
+
+=back
+
+=head2 I18N::Langinfo - query locale information
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item EXPORT
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO - load various IO modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item DEPRECATED
+
+=back
+
+=head2 IO::Compress::Base - Base Class for IO::Compress modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Compress::Deflate - Write RFC 1950 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item deflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Compress::Gzip - Write RFC 1952 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item gzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Minimal => 0|1 >>,
+C<< Comment => $comment >>, C<< Name => $string >>, C<< Time => $number >>,
+C<< TextFlag => 0|1 >>, C<< HeaderCRC => 0|1 >>, C<< OS_Code => $value >>,
+C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1
+>>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Compress::RawDeflate - Write RFC 1951 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item rawdeflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Compress::Zip - Write zip files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item zip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Name => $string >>, C<< Time => $number >>, C<< ExtAttr =>
+$attr >>, C<< exTime => [$atime, $mtime, $ctime] >>, C<< Comment =>
+$comment >>, C<< ZipComment => $comment >>, C<< Method => $method >>, C<<
+Stream => 0|1 >>, C<< Zip64 => 0|1 >>, C<< TextFlag => 0|1 >>, C<<
+ExtraFieldLocal => $data >> =item C<< ExtraFieldCentral => $data >>, C<<
+Minimal => 1|0 >>, C<< BlockSize100K => number >>, C<< WorkFactor => number
+>>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy, :zip_method
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Dir - supply object methods for directory handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (),
+rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::File - supply object methods for filehandles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile
+
+=item METHODS
+
+open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode(
+[LAYER] )
+
+=item NOTE
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 IO::Handle - supply object methods for I/O handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new (), new_from_fd ( FD, MODE )
+
+=item METHODS
+
+$io->fdopen ( FD, MODE ), $io->opened, $io->getline, $io->getlines,
+$io->ungetc ( ORD ), $io->write ( BUF, LEN [, OFFSET ] ), $io->error,
+$io->clearerr, $io->sync, $io->flush, $io->printflush ( ARGS ),
+$io->blocking ( [ BOOL ] ), $io->untaint
+
+=item NOTE
+
+=item SEE ALSO
+
+=item BUGS
+
+=item HISTORY
+
+=back
+
+=head2 IO::Pipe - supply object methods for pipes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [READER, WRITER] )
+
+=item METHODS
+
+reader ([ARGS]), writer ([ARGS]), handles ()
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Poll - Object interface to system poll call
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove (
+IO ), handles( [ EVENT_MASK ] )
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Seekable - supply seek based methods for I/O objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$io->getpos, $io->setpos, $io->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
+WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), $io->sysseek( POS, WHENCE ),
+$io->tell
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 IO::Select - OO interface to the select system call
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ HANDLES ] )
+
+=item METHODS
+
+add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read (
+[ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ),
+count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )
+
+=item EXAMPLE
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Socket - Object interface to socket communications
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=item METHODS
+
+accept([PKG]), socketpair(DOMAIN, TYPE, PROTOCOL), atmark, connected,
+protocol, sockdomain, sockopt(OPT [, VAL]), socktype, timeout([VAL])
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Socket::INET - Object interface for AF_INET domain sockets
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=over 4
+
+=item METHODS
+
+sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost
+()
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Socket::UNIX - Object interface for AF_UNIX domain sockets
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=item METHODS
+
+hostpath(), peerpath()
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip)
+file/buffer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip
+
+=item Functional Interface
+
+=over 4
+
+=item anyinflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
+>>, C<< ParseExtra => 0|1 >> If the gzip FEXTRA header field is present and
+this option is set, it will force the module to check that it conforms to
+the sub-field structure as defined in RFC 1952
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop
+file/buffer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip, bzip2, lzop, lzf
+
+=item Functional Interface
+
+=over 4
+
+=item anyuncompress $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
+>>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::Base - Base Class for IO::Uncompress modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::Gunzip - Read RFC 1952 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item gunzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< ParseExtra => 0|1
+>> If the gzip FEXTRA header field is present and this option is set, it
+will force the module to check that it conforms to the sub-field structure
+as defined in RFC 1952
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+Name, Comment
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::Inflate - Read RFC 1950 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item inflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item rawinflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Uncompress::Unzip - Read zip files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item unzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO::Zlib - IO:: style interface to L<Compress::Zlib>
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=item OBJECT METHODS
+
+open ( FILENAME, MODE ), opened, close, getc, getline, getlines, print (
+ARGS... ), read ( BUF, NBYTES, [OFFSET] ), eof, seek ( OFFSET, WHENCE ),
+tell, setpos ( POS ), getpos ( POS )
+
+=item USING THE EXTERNAL GZIP
+
+=item CLASS METHODS
+
+has_Compress_Zlib, gzip_external, gzip_used, gzip_read_open,
+gzip_write_open
+
+=item DIAGNOSTICS
+
+IO::Zlib::getlines: must be called in list context,
+IO::Zlib::gzopen_external: mode '...' is illegal, IO::Zlib::import: '...'
+is illegal, IO::Zlib::import: ':gzip_external' requires an argument,
+IO::Zlib::import: 'gzip_read_open' requires an argument, IO::Zlib::import:
+'gzip_read' '...' is illegal, IO::Zlib::import: 'gzip_write_open' requires
+an argument, IO::Zlib::import: 'gzip_write_open' '...' is illegal,
+IO::Zlib::import: no Compress::Zlib and no external gzip, IO::Zlib::open:
+needs a filename, IO::Zlib::READ: NBYTES must be specified,
+IO::Zlib::WRITE: too long LENGTH, IO::Zlib::WRITE: OFFSET is not supported
+
+=item SEE ALSO
+
+=item HISTORY
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Dir, IO::Dir - supply object methods for directory
+handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+new ( [ DIRNAME ] ), open ( DIRNAME ), read (), seek ( POS ), tell (),
+rewind (), close (), tie %hash, 'IO::Dir', DIRNAME [, OPTIONS ]
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::File, IO::File - supply object methods for filehandles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( FILENAME [,MODE [,PERMS]] ), new_tmpfile
+
+=item METHODS
+
+open( FILENAME [,MODE [,PERMS]] ), open( FILENAME, IOLAYERS ), binmode(
+[LAYER] )
+
+=item NOTE
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 IO::lib::IO::Handle, IO::Handle - supply object methods for I/O
+handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new (), new_from_fd ( FD, MODE )
+
+=item METHODS
+
+$io->fdopen ( FD, MODE ), $io->opened, $io->getline, $io->getlines,
+$io->ungetc ( ORD ), $io->write ( BUF, LEN [, OFFSET ] ), $io->error,
+$io->clearerr, $io->sync, $io->flush, $io->printflush ( ARGS ),
+$io->blocking ( [ BOOL ] ), $io->untaint
+
+=item NOTE
+
+=item SEE ALSO
+
+=item BUGS
+
+=item HISTORY
+
+=back
+
+=head2 IO::lib::IO::Pipe, IO::Pipe - supply object methods for pipes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [READER, WRITER] )
+
+=item METHODS
+
+reader ([ARGS]), writer ([ARGS]), handles ()
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Poll, IO::Poll - Object interface to system poll call
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+mask ( IO [, EVENT_MASK ] ), poll ( [ TIMEOUT ] ), events ( IO ), remove (
+IO ), handles( [ EVENT_MASK ] )
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Seekable, IO::Seekable - supply seek based methods for
+I/O objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$io->getpos, $io->setpos, $io->seek ( POS, WHENCE ), WHENCE=0 (SEEK_SET),
+WHENCE=1 (SEEK_CUR), WHENCE=2 (SEEK_END), $io->sysseek( POS, WHENCE ),
+$io->tell
+
+=item SEE ALSO
+
+=item HISTORY
+
+=back
+
+=head2 IO::lib::IO::Select, IO::Select - OO interface to the select system
+call
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ HANDLES ] )
+
+=item METHODS
+
+add ( HANDLES ), remove ( HANDLES ), exists ( HANDLE ), handles, can_read (
+[ TIMEOUT ] ), can_write ( [ TIMEOUT ] ), has_exception ( [ TIMEOUT ] ),
+count (), bits(), select ( READ, WRITE, EXCEPTION [, TIMEOUT ] )
+
+=item EXAMPLE
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Socket, IO::Socket - Object interface to socket
+communications
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=item METHODS
+
+accept([PKG]), socketpair(DOMAIN, TYPE, PROTOCOL), atmark, connected,
+protocol, sockdomain, sockopt(OPT [, VAL]), socktype, timeout([VAL])
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Socket::INET, IO::Socket::INET - Object interface for
+AF_INET domain sockets
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=over 4
+
+=item METHODS
+
+sockaddr (), sockport (), sockhost (), peeraddr (), peerport (), peerhost
+()
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO::lib::IO::Socket::UNIX, IO::Socket::UNIX - Object interface for
+AF_UNIX domain sockets
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ARGS] )
+
+=item METHODS
+
+hostpath(), peerpath()
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IO_Compress_Base::lib::File::GlobMapper, File::GlobMapper - Extend
+File Glob to Allow Input and Output Files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+This code is a work in progress, There are known bugs, The interface
+defined here is tentative, There are portability issues, Do not use in
+production code, Consider yourself warned!
+
+=over 4
+
+=item Behind The Scenes
+
+=item Limitations
+
+=item Input File Glob
+
+B<~>, B<~user>, B<.>, B<*>, B<?>, B<\>, B<[]>, B<{,}>, B<()>
+
+=item Output File Glob
+
+"*", #1
+
+=item Returned Data
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item A Rename script
+
+=item A few example globmaps
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Base::lib::IO::Compress::Base, IO::Compress::Base - Base
+Class for IO::Compress modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Base::lib::IO::Uncompress::AnyUncompress,
+IO::Uncompress::AnyUncompress - Uncompress gzip, zip, bzip2 or lzop
+file/buffer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip, bzip2, lzop, lzf
+
+=item Functional Interface
+
+=over 4
+
+=item anyuncompress $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
+>>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Base::lib::IO::Uncompress::Base, IO::Uncompress::Base -
+Base Class for IO::Uncompress modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Compress::Deflate, IO::Compress::Deflate -
+Write RFC 1950 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item deflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Compress::Gzip, IO::Compress::Gzip - Write RFC
+1952 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item gzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Minimal => 0|1 >>,
+C<< Comment => $comment >>, C<< Name => $string >>, C<< Time => $number >>,
+C<< TextFlag => 0|1 >>, C<< HeaderCRC => 0|1 >>, C<< OS_Code => $value >>,
+C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1
+>>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Compress::RawDeflate, IO::Compress::RawDeflate
+- Write RFC 1951 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item rawdeflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Compress::Zip, IO::Compress::Zip - Write zip
+files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item zip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeIn => 0|1 >>, C<< Append => 0|1 >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< Append => 0|1 >>, A Buffer, A Filename, A
+Filehandle, C<< Name => $string >>, C<< Time => $number >>, C<< ExtAttr =>
+$attr >>, C<< exTime => [$atime, $mtime, $ctime] >>, C<< Comment =>
+$comment >>, C<< ZipComment => $comment >>, C<< Method => $method >>, C<<
+Stream => 0|1 >>, C<< Zip64 => 0|1 >>, C<< TextFlag => 0|1 >>, C<<
+ExtraFieldLocal => $data >> =item C<< ExtraFieldCentral => $data >>, C<<
+Minimal => 1|0 >>, C<< BlockSize100K => number >>, C<< WorkFactor => number
+>>, -Level, -Strategy, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item print
+
+=item printf
+
+=item syswrite
+
+=item write
+
+=item flush
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item newStream([OPTS])
+
+=item deflateParams
+
+=back
+
+=item Importing
+
+:all, :constants, :flush, :level, :strategy, :zip_method
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Uncompress::AnyInflate,
+IO::Uncompress::AnyInflate - Uncompress zlib-based (zip, gzip) file/buffer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+RFC 1950, RFC 1951 (optionally), gzip (RFC 1952), zip
+
+=item Functional Interface
+
+=over 4
+
+=item anyinflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< RawInflate => 0|1
+>>, C<< ParseExtra => 0|1 >> If the gzip FEXTRA header field is present and
+this option is set, it will force the module to check that it conforms to
+the sub-field structure as defined in RFC 1952
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Uncompress::Gunzip, IO::Uncompress::Gunzip -
+Read RFC 1952 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item gunzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>, C<< ParseExtra => 0|1
+>> If the gzip FEXTRA header field is present and this option is set, it
+will force the module to check that it conforms to the sub-field structure
+as defined in RFC 1952
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+Name, Comment
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Uncompress::Inflate, IO::Uncompress::Inflate -
+Read RFC 1950 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item inflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Uncompress::RawInflate,
+IO::Uncompress::RawInflate - Read RFC 1951 files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item rawinflate $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IO_Compress_Zlib::IO::Uncompress::Unzip, IO::Uncompress::Unzip -
+Read zip files/buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Functional Interface
+
+=over 4
+
+=item unzip $input => $output [, OPTS]
+
+A filename, A filehandle, A scalar reference, An array reference, An Input
+FileGlob string, A filename, A filehandle, A scalar reference, An Array
+Reference, An Output FileGlob
+
+=item Notes
+
+=item Optional Parameters
+
+C<< AutoClose => 0|1 >>, C<< BinModeOut => 0|1 >>, C<< Append => 0|1 >>,
+C<< MultiStream => 0|1 >>, C<< TrailingData => $scalar >>
+
+=item Examples
+
+=back
+
+=item OO Interface
+
+=over 4
+
+=item Constructor
+
+A filename, A filehandle, A scalar reference
+
+=item Constructor Options
+
+C<< AutoClose => 0|1 >>, C<< MultiStream => 0|1 >>, C<< Prime => $string
+>>, C<< Transparent => 0|1 >>, C<< BlockSize => $num >>, C<< InputLength =>
+$size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >>
+
+=item Examples
+
+=back
+
+=item Methods
+
+=over 4
+
+=item read
+
+=item read
+
+=item getline
+
+=item getc
+
+=item ungetc
+
+=item inflateSync
+
+=item getHeaderInfo
+
+=item tell
+
+=item eof
+
+=item seek
+
+=item binmode
+
+=item opened
+
+=item autoflush
+
+=item input_line_number
+
+=item fileno
+
+=item close
+
+=item nextStream
+
+=item trailingData
+
+=back
+
+=item Importing
+
+:all
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item MODIFICATION HISTORY
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 IPC::Msg - SysV Msg IPC object class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+new ( KEY , FLAGS ), id, rcv ( BUF, LEN [, TYPE [, FLAGS ]] ), remove, set
+( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), snd ( TYPE, MSG [,
+FLAGS ] ), stat
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IPC::Open2, open2 - open a process for both reading and writing
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item WARNING
+
+=item SEE ALSO
+
+=back
+
+=head2 IPC::Open3, open3 - open a process for reading, writing, and error
+handling
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item See Also
+
+L<IPC::Open2>, L<IPC::Run>
+
+=item WARNING
+
+=back
+
+=head2 IPC::Semaphore - SysV Semaphore IPC object class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+new ( KEY , NSEMS , FLAGS ), getall, getncnt ( SEM ), getpid ( SEM ),
+getval ( SEM ), getzcnt ( SEM ), id, op ( OPLIST ), remove, set ( STAT ),
+set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N
+, VALUE ), stat
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IPC::SysV - SysV IPC constants
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+ftok( PATH, ID )
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 IPC::SysV::Msg, IPC::Msg - SysV Msg IPC object class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+new ( KEY , FLAGS ), id, rcv ( BUF, LEN [, TYPE [, FLAGS ]] ), remove, set
+( STAT ), set ( NAME => VALUE [, NAME => VALUE ...] ), snd ( TYPE, MSG [,
+FLAGS ] ), stat
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IPC::SysV::Semaphore, IPC::Semaphore - SysV Semaphore IPC object
+class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+new ( KEY , NSEMS , FLAGS ), getall, getncnt ( SEM ), getpid ( SEM ),
+getval ( SEM ), getzcnt ( SEM ), id, op ( OPLIST ), remove, set ( STAT ),
+set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N
+, VALUE ), stat
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 IPCmd, IPC::Cmd - finding and running system commands made easy
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CLASS METHODS
+
+=over 4
+
+=item $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] )
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] )
+
+=back
+
+=over 4
+
+=item $bool = IPC::Cmd->can_capture_buffer
+
+=back
+
+=over 4
+
+=item FUNCTIONS
+
+=over 4
+
+=item $path = can_run( PROGRAM );
+
+=back
+
+=back
+
+=over 4
+
+=item $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run(
+command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] );
+
+command, verbose, buffer, success, errorcode, full_buffer, out_buffer,
+error_buffer
+
+=back
+
+=over 4
+
+=item HOW IT WORKS
+
+=item Global Variables
+
+=over 4
+
+=item $IPC::Cmd::VERBOSE
+
+=item $IPC::Cmd::USE_IPC_RUN
+
+=item $IPC::Cmd::USE_IPC_OPEN3
+
+=item $IPC::Cmd::WARN
+
+=back
+
+=item Caveats
+
+Whitespace, IO Redirect
+
+=item See Also
+
+=item ACKNOWLEDGEMENTS
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 List::Util - A selection of general-utility list subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+first BLOCK LIST, max LIST, maxstr LIST, min LIST, minstr LIST, reduce
+BLOCK LIST, shuffle LIST, sum LIST
+
+=item KNOWN BUGS
+
+=item SUGGESTED ADDITIONS
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
+=head2 List::Utilib::List::Util, List::Util - A selection of
+general-utility list subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+first BLOCK LIST, max LIST, maxstr LIST, min LIST, minstr LIST, reduce
+BLOCK LIST, shuffle LIST, sum LIST
+
+=item KNOWN BUGS
+
+=item SUGGESTED ADDITIONS
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
+=head2 List::Utilib::Scalar::Util, Scalar::Util - A selection of
+general-utility scalar subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+blessed EXPR, dualvar NUM, STRING, isvstring EXPR, isweak EXPR,
+looks_like_number EXPR, openhandle FH, refaddr EXPR, reftype EXPR,
+set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF
+
+=item KNOWN BUGS
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=item BLATANT PLUG
+
+=back
+
+=head2 Locale::Constants - constants for Locale codes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item KNOWN BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+Locale::Language, Locale::Country, Locale::Script, Locale::Currency
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Locale::Country - ISO codes for country identification (ISO 3166)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<alpha-2>, B<alpha-3>, B<numeric>
+
+=item CONVERSION ROUTINES
+
+code2country( CODE, [ CODESET ] ), country2code( STRING, [ CODESET ] ),
+country_code2code( CODE, CODESET, CODESET )
+
+=item QUERY ROUTINES
+
+C<all_country_codes( [ CODESET ] )>, C<all_country_names( [ CODESET ] )>
+
+=item SEMI-PRIVATE ROUTINES
+
+=over 4
+
+=item alias_code
+
+=item rename_country
+
+=back
+
+=item EXAMPLES
+
+=item DOMAIN NAMES
+
+=item KNOWN BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+Locale::Language, Locale::Script, Locale::Currency, Locale::SubCountry, ISO
+3166-1, http://www.iso.org/iso/en/prods-services/iso3166ma/index.html,
+http://www.egt.ie/standards/iso3166/iso3166-1-en.html,
+http://www.cia.gov/cia/publications/factbook/docs/app-d-1.html
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Locale::Currency - ISO three letter codes for currency
+identification (ISO 4217)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+XTS, XXX
+
+=item CONVERSION ROUTINES
+
+code2currency(), currency2code()
+
+=item QUERY ROUTINES
+
+C<all_currency_codes()>, C<all_currency_names()>
+
+=item EXAMPLES
+
+=item KNOWN BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+Locale::Country, Locale::Script, ISO 4217:1995,
+http://www.bsi-global.com/iso4217currency
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Locale::Language - ISO two letter codes for language identification
+(ISO 639)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONVERSION ROUTINES
+
+code2language(), language2code()
+
+=item QUERY ROUTINES
+
+C<all_language_codes()>, C<all_language_names()>
+
+=item EXAMPLES
+
+=item KNOWN BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+Locale::Country, Locale::Script, Locale::Currency, ISO 639:1988 (E/F),
+http://lcweb.loc.gov/standards/iso639-2/langhome.html
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Locale::Maketext - framework for localization
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item QUICK OVERVIEW
+
+=item METHODS
+
+=over 4
+
+=item Construction Methods
+
+=item The "maketext" Method
+
+$lh->fail_with I<or> $lh->fail_with(I<PARAM>), $lh->failure_handler_auto
+
+=item Utility Methods
+
+$language->quant($number, $singular), $language->quant($number, $singular,
+$plural), $language->quant($number, $singular, $plural, $negative),
+$language->numf($number), $language->sprintf($format, @items),
+$language->language_tag(), $language->encoding()
+
+=item Language Handle Attributes and Internals
+
+=back
+
+=item LANGUAGE CLASS HIERARCHIES
+
+=item ENTRIES IN EACH LEXICON
+
+=item BRACKET NOTATION
+
+=item AUTO LEXICONS
+
+=item CONTROLLING LOOKUP FAILURE
+
+=item HOW TO USE MAKETEXT
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMER
+
+=item AUTHOR
+
+=back
+
+=head2 Locale::Maketext::Simple - Simple interface to
+Locale::Maketext::Lexicon
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPTIONS
+
+=over 4
+
+=item Class
+
+=item Path
+
+=item Style
+
+=item Export
+
+=item Subclass
+
+=item Decode
+
+=item Encoding
+
+=back
+
+=back
+
+=over 4
+
+=item ACKNOWLEDGMENTS
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=over 4
+
+=item The "MIT" License
+
+=back
+
+=back
+
+=head2 Locale::Maketext::TPJ13 -- article about software localization
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Localization and Perl: gettext breaks, Maketext fixes
+
+=over 4
+
+=item A Localization Horror Story: It Could Happen To You
+
+=item The Linguistic View
+
+=item Breaking gettext
+
+=item Replacing gettext
+
+=item Buzzwords: Abstraction and Encapsulation
+
+=item Buzzword: Isomorphism
+
+=item Buzzword: Inheritance
+
+=item Buzzword: Concision
+
+=item The Devil in the Details
+
+=item The Proof in the Pudding: Localizing Web Sites
+
+=item References
+
+=back
+
+=back
+
+=head2 Locale::Script - ISO codes for script identification (ISO 15924)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<alpha-2>, B<alpha-3>, B<numeric>
+
+=over 4
+
+=item SPECIAL CODES
+
+=back
+
+=item CONVERSION ROUTINES
+
+code2script( CODE, [ CODESET ] ), script2code( STRING, [ CODESET ] ),
+script_code2code( CODE, CODESET, CODESET )
+
+=item QUERY ROUTINES
+
+C<all_script_codes ( [ CODESET ] )>, C<all_script_names ( [ CODESET ] )>
+
+=item EXAMPLES
+
+=item KNOWN BUGS AND LIMITATIONS
+
+=item SEE ALSO
+
+Locale::Language, Locale::Currency, Locale::Country, ISO 15924,
+http://www.evertype.com/standards/iso15924/
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Log::Message - A generic message storing mechanism;
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Hierarchy
+
+Log::Message, Log::Message::Item, Log::Message::Handlers,
+Log::Message::Config
+
+=item Options
+
+config, private, verbose, tag, level, remove, chrono
+
+=back
+
+=over 4
+
+=item Methods
+
+=over 4
+
+=item new
+
+=back
+
+=back
+
+=over 4
+
+=item store
+
+message, tag, level, extra
+
+=back
+
+=over 4
+
+=item retrieve
+
+tag, level, message, amount, chrono, remove
+
+=back
+
+=over 4
+
+=item first
+
+=back
+
+=over 4
+
+=item last
+
+=back
+
+=over 4
+
+=item flush
+
+=back
+
+=over 4
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item Acknowledgements
+
+=item COPYRIGHT
+
+=back
+
+=head2 Log::Message::Config - Configuration options for Log::Message
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item Acknowledgements
+
+=item COPYRIGHT
+
+=back
+
+=head2 Log::Message::Handlers - Message handlers for Log::Message
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Default Handlers
+
+=over 4
+
+=item log
+
+=back
+
+=back
+
+=over 4
+
+=item carp
+
+=back
+
+=over 4
+
+=item croak
+
+=back
+
+=over 4
+
+=item cluck
+
+=back
+
+=over 4
+
+=item confess
+
+=back
+
+=over 4
+
+=item die
+
+=back
+
+=over 4
+
+=item warn
+
+=back
+
+=over 4
+
+=item trace
+
+=back
+
+=over 4
+
+=item Custom Handlers
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item Acknowledgements
+
+=item COPYRIGHT
+
+=back
+
+=head2 Log::Message::Item - Message objects for Log::Message
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Methods and Accessors
+
+=over 4
+
+=item remove
+
+=item id
+
+=item when
+
+=item message
+
+=item level
+
+=item tag
+
+=item shortmess
+
+=item longmess
+
+=item parent
+
+=back
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item Acknowledgements
+
+=item COPYRIGHT
+
+=back
+
+=head2 Log::Message::Simple
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item msg("message string" [,VERBOSE])
+
+=item debug("message string" [,VERBOSE])
+
+=item error("error string" [,VERBOSE])
+
+=back
+
+=back
+
+=over 4
+
+=item carp();
+
+=item croak();
+
+=item confess();
+
+=item cluck();
+
+=back
+
+=over 4
+
+=item CLASS METHODS
+
+=over 4
+
+=item Log::Message::Simple->stack()
+
+=item Log::Message::Simple->stack_as_string([TRACE])
+
+=item Log::Message::Simple->flush()
+
+=back
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+$ERROR_FH, $MSG_FH, $DEBUG_FH, $STACKTRACE_ON_ERROR
+
+=back
+
+=head2 MIME::Base64 - Encoding and decoding of base64 strings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+encode_base64($str), encode_base64($str, $eol);, decode_base64($str)
+
+=item DIAGNOSTICS
+
+Premature end of base64 data, Premature padding of base64 data, Wide
+character in subroutine entry
+
+=item EXAMPLES
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 MIME::Base64::QuotedPrint, MIME::QuotedPrint - Encoding and decoding
+of quoted-printable strings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+encode_qp($str), encode_qp($str, $eol), encode_qp($str, $eol, $binmode),
+decode_qp($str);
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 MIME::QuotedPrint - Encoding and decoding of quoted-printable
+strings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+encode_qp($str), encode_qp($str, $eol), encode_qp($str, $eol, $binmode),
+decode_qp($str);
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Math::BigFloat - Arbitrary size floating point math package
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Canonical notation
+
+=item Output
+
+=item C<mantissa()>, C<exponent()> and C<parts()>
+
+=item Accuracy vs. Precision
+
+=item Rounding
+
+ffround ( +$scale ), ffround ( -$scale ), ffround ( 0 ), fround ( +$scale
+), fround ( -$scale ) and fround ( 0 )
+
+=back
+
+=item METHODS
+
+=over 4
+
+=item accuracy
+
+=item precision()
+
+=item bexp()
+
+=item bnok()
+
+=item bpi()
+
+=item bcos()
+
+=item bsin()
+
+=item batan2()
+
+=item batan()
+
+=item bmuladd()
+
+=back
+
+=item Autocreating constants
+
+=over 4
+
+=item Math library
+
+=item Using Math::BigInt::Lite
+
+=back
+
+=item EXPORTS
+
+=item BUGS
+
+=item CAVEATS
+
+stringify, bstr(), bdiv, brsft, Modifying and =, bpow, precision() vs.
+accuracy()
+
+=item SEE ALSO
+
+=item LICENSE
+
+=item AUTHORS
+
+=back
+
+=head2 Math::BigInt - Arbitrary size integer/float math package
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+Input, Output
+
+=item METHODS
+
+=over 4
+
+=item config()
+
+=item accuracy()
+
+=item precision()
+
+=item brsft()
+
+=item new()
+
+=item from_oct()
+
+=item from_hex()
+
+=item from_bin()
+
+=item bnan()
+
+=item bzero()
+
+=item binf()
+
+=item bone()
+
+=item is_one()/is_zero()/is_nan()/is_inf()
+
+=item is_pos()/is_neg()/is_positive()/is_negative()
+
+ $x->is_pos(); # true if > 0
+ $x->is_neg(); # true if < 0
+
+=item is_odd()/is_even()/is_int()
+
+=item bcmp()
+
+=item bacmp()
+
+=item sign()
+
+=item digit()
+
+=item bneg()
+
+=item babs()
+
+=item bnorm()
+
+=item bnot()
+
+=item binc()
+
+=item bdec()
+
+=item badd()
+
+=item bsub()
+
+=item bmul()
+
+=item bmuladd()
+
+=item bdiv()
+
+=item bmod()
+
+=item bmodinv()
+
+=item bmodpow()
+
+=item bpow()
+
+=item blog()
+
+=item bexp()
+
+=item bnok()
+
+=item bpi()
+
+=item bcos()
+
+=item bsin()
+
+=item batan2()
+
+=item batan()
+
+=item blsft()
+
+=item brsft()
+
+=item band()
+
+=item bior()
+
+=item bxor()
+
+=item bnot()
+
+=item bsqrt()
+
+=item broot()
+
+=item bfac()
+
+=item round()
+
+=item bround()
+
+=item bfround()
+
+=item bfloor()
+
+=item bceil()
+
+=item bgcd()
+
+=item blcm()
+
+=item exponent()
+
+=item mantissa()
+
+=item parts()
+
+=item copy()
+
+=item as_int()/as_number()
+
+=item bsstr()
+
+=item as_hex()
+
+=item as_bin()
+
+=item as_oct()
+
+=item numify()
+
+=item modify()
+
+=item upgrade()/downgrade()
+
+=item div_scale()
+
+=item round_mode()
+
+=back
+
+=item ACCURACY and PRECISION
+
+=over 4
+
+=item Precision P
+
+=item Accuracy A
+
+=item Fallback F
+
+=item Rounding mode R
+
+'trunc', 'even', 'odd', '+inf', '-inf', 'zero', 'common', Precision,
+Accuracy (significant digits), Setting/Accessing, Creating numbers, Usage,
+Precedence, Overriding globals, Local settings, Rounding, Default values,
+Remarks
+
+=back
+
+=item Infinity and Not a Number
+
+oct()/hex(), log(-inf), exp(), cos(), sin(), atan2()
+
+=item INTERNALS
+
+=over 4
+
+=item MATH LIBRARY
+
+=item SIGN
+
+=item mantissa(), exponent() and parts()
+
+=back
+
+=item EXAMPLES
+
+ use Math::BigInt;
+
+=item Autocreating constants
+
+=item PERFORMANCE
+
+=over 4
+
+=item Alternative math libraries
+
+=item SUBCLASSING
+
+=back
+
+=item Subclassing Math::BigInt
+
+=item UPGRADING
+
+=over 4
+
+=item Auto-upgrade
+
+bsqrt(), div(), blog(), bexp()
+
+=back
+
+=item EXPORTS
+
+=item CAVEATS
+
+bstr(), bsstr() and 'cmp', int(), length, bdiv, infinity handling,
+Modifying and =, bpow, Overloading -$x, Mixing different object types,
+bsqrt(), brsft()
+
+=item LICENSE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 Math::BigInt::Calc - Pure Perl module to support Math::BigInt
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item STORAGE
+
+=item METHODS
+
+=item WRAP YOUR OWN
+
+=item LICENSE
+
+This program is free software; you may redistribute it and/or modify it
+under
+the same terms as Perl itself.
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 Math::BigInt::CalcEmu - Emulate low-level math with BigInt code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item __emu_bxor
+
+=item __emu_band
+
+=item __emu_bior
+
+=back
+
+=item LICENSE
+
+This program is free software; you may redistribute it and/or modify it
+under
+the same terms as Perl itself.
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 Math::BigInt::FastCalc - Math::BigInt::Calc with some XS for more
+speed
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item STORAGE
+
+=item METHODS
+
+=item LICENSE
+
+This program is free software; you may redistribute it and/or modify it
+under
+the same terms as Perl itself.
+
+=item AUTHORS
+
+=item SEE ALSO
+
+=back
+
+=head2 Math::BigRat - Arbitrary big rational numbers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item MATH LIBRARY
+
+=back
+
+=item METHODS
+
+=over 4
+
+=item new()
+
+=item numerator()
+
+=item denominator()
+
+ $d = $x->denominator();
+
+=item parts()
+
+=item numify()
+
+=item as_int()/as_number()
+
+=item as_hex()
+
+=item as_bin()
+
+=item as_oct()
+
+=item from_hex()/from_bin()/from_oct()
+
+=item length()
+
+=item digit()
+
+=item bnorm()
+
+=item bfac()
+
+=item bround()/round()/bfround()
+
+=item bmod()
+
+=item bneg()
+
+=item is_one()
+
+=item is_zero()
+
+=item is_pos()/is_positive()
+
+=item is_neg()/is_negative()
+
+=item is_int()
+
+=item is_odd()
+
+=item is_even()
+
+=item bceil()
+
+=item bfloor()
+
+ $x->bfloor();
+
+=item bsqrt()
+
+ $x->bsqrt();
+
+=item broot()
+
+ $x->broot($n);
+
+=item badd()/bmul()/bsub()/bdiv()/bdec()/binc()
+
+=item copy()
+
+=item bstr()/bsstr()
+
+=item bacmp()/bcmp()
+
+=item blsft()/brsft()
+
+=item bpow()
+
+=item bexp()
+
+=item bnok()
+
+=item config()
+
+=back
+
+=item BUGS
+
+inf handling (partial), NaN handling (partial), rounding (not implemented
+except for bceil/bfloor), $x ** $y where $y is not an integer, bmod(),
+blog(), bmodinv() and bmodpow() (partial)
+
+=item LICENSE
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 Math::Complex - complex numbers and associated mathematical
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OPERATIONS
+
+=item CREATION
+
+=item DISPLAYING
+
+=over 4
+
+=item CHANGED IN PERL 5.6
+
+=back
+
+=item USAGE
+
+=over 4
+
+=item PI
+
+=back
+
+=item ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO
+
+=item ERRORS DUE TO INDIGESTIBLE ARGUMENTS
+
+=item BUGS
+
+=item AUTHORS
+
+=back
+
+=head2 Math::Trig - trigonometric functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item TRIGONOMETRIC FUNCTIONS
+
+B<tan>
+
+=over 4
+
+=item ERRORS DUE TO DIVISION BY ZERO
+
+=item SIMPLE (REAL) ARGUMENTS, COMPLEX RESULTS
+
+=back
+
+=item PLANE ANGLE CONVERSIONS
+
+deg2rad, grad2rad, rad2deg, grad2deg, deg2grad, rad2grad, rad2rad, deg2deg,
+grad2grad
+
+=item RADIAL COORDINATE CONVERSIONS
+
+=over 4
+
+=item COORDINATE SYSTEMS
+
+=item 3-D ANGLE CONVERSIONS
+
+cartesian_to_cylindrical, cartesian_to_spherical, cylindrical_to_cartesian,
+cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical
+
+=back
+
+=item GREAT CIRCLE DISTANCES AND DIRECTIONS
+
+=over 4
+
+=item great_circle_distance
+
+=item great_circle_direction
+
+=item great_circle_bearing
+
+=item great_circle_destination
+
+=item great_circle_midpoint
+
+=item great_circle_waypoint
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item CAVEAT FOR GREAT CIRCLE FORMULAS
+
+=back
+
+=item BUGS
+
+=item AUTHORS
+
+=back
+
+=head2 Memoize - Make functions faster by trading space for time
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item DETAILS
+
+=item OPTIONS
+
+=over 4
+
+=item INSTALL
+
+=item NORMALIZER
+
+=item C<SCALAR_CACHE>, C<LIST_CACHE>
+
+C<MEMORY>, C<HASH>, C<TIE>, C<FAULT>, C<MERGE>
+
+=back
+
+=item OTHER FACILITIES
+
+=over 4
+
+=item C<unmemoize>
+
+=item C<flush_cache>
+
+=back
+
+=item CAVEATS
+
+=item PERSISTENT CACHE SUPPORT
+
+=item EXPIRATION SUPPORT
+
+=item BUGS
+
+=item MAILING LIST
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=item THANK YOU
+
+=back
+
+=head2 Memoize::AnyDBM_File - glue to provide EXISTS for AnyDBM_File for
+Storable use
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Memoize::Expire - Plug-in module for automatic expiration of
+memoized values
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item INTERFACE
+
+ TIEHASH, EXISTS, STORE
+
+=item ALTERNATIVES
+
+=item CAVEATS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Memoize::ExpireFile - test for Memoize expiration semantics
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Memoize::ExpireTest - test for Memoize expiration semantics
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Memoize::NDBM_File - glue to provide EXISTS for NDBM_File for
+Storable use
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Memoize::SDBM_File - glue to provide EXISTS for SDBM_File for
+Storable use
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Memoize::Storable - store Memoized data in Storable database
+
+=over 4
+
+=item DESCRIPTION
+
+=back
+
+=head2 Module::Build - Build and install Perl modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item GUIDE TO DOCUMENTATION
+
+General Usage (L<Module::Build>), Authoring Reference
+(L<Module::Build::Authoring>), API Reference (L<Module::Build::API>),
+Cookbook (L<Module::Build::Cookbook>)
+
+=item ACTIONS
+
+build, clean, code, config_data, diff, dist, distcheck, distclean, distdir,
+distmeta, distsign, disttest, docs, fakeinstall, help, html, install,
+manifest, manpages, pardist, ppd, ppmdist, prereq_report, pure_install,
+realclean, retest, skipcheck, test, testall, testcover, testdb, testpod,
+testpodcoverage, versioninstall
+
+=item OPTIONS
+
+=over 4
+
+=item Command Line Options
+
+quiet, use_rcfile, verbose, allow_mb_mismatch
+
+=item Default Options File (F<.modulebuildrc>)
+
+=back
+
+=item INSTALL PATHS
+
+lib, arch, script, bin, bindoc, libdoc, binhtml, libhtml, installdirs,
+install_path, install_base, destdir, prefix
+
+=item MOTIVATIONS
+
++, +
+
+=item TO DO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::API - API Reference for Module Authors
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item CONSTRUCTORS
+
+current(), new(), add_to_cleanup, auto_features, autosplit, build_class,
+build_requires, create_packlist, c_source, conflicts, create_makefile_pl,
+create_readme, dist_abstract, dist_author, dist_name, dist_version,
+dist_version_from, dynamic_config, extra_compiler_flags,
+extra_linker_flags, get_options, type, store, default, include_dirs,
+install_path, installdirs, license, apache, artistic, artistic_2, bsd, gpl,
+lgpl, mit, mozilla, open_source, perl, restrictive, unrestricted, meta_add,
+meta_merge, module_name, PL_files, pm_files, pod_files, recommends,
+recursive_test_files, requires, script_files, sign, test_files, xs_files,
+new_from_context(%args), resume(), subclass()
+
+=item METHODS
+
+add_build_element($type), add_to_cleanup(@files), args(),
+autosplit_file($from, $to), base_dir(), build_requires(),
+check_installed_status($module, $version), check_installed_version($module,
+$version), compare_versions($v1, $op, $v2), config($key), config($key,
+$value), config() [deprecated], config_data($name), config_data($name =>
+$value), conflicts(), contains_pod($file), copy_if_modified(%parameters),
+create_build_script(), current_action(), depends_on(@actions),
+dir_contains($first_dir, $second_dir), dispatch($action, %args),
+dist_dir(), dist_name(), dist_version(), do_system($cmd, @args),
+feature($name), feature($name => $value), have_c_compiler(),
+install_base_relpaths(), install_base_relpaths($type),
+install_base_relpaths($type => $path), install_destination($type),
+install_path(), install_path($type), install_path($type => $path),
+install_types(), invoked_action(), notes(), notes($key), notes($key =>
+$value), orig_dir(), os_type(), is_vmsish(), is_windowsish(), is_unixish(),
+prefix_relpaths(), prefix_relpaths($installdirs),
+prefix_relpaths($installdirs, $type), prefix_relpaths($installdirs, $type
+=> $path), prepare_metadata(), prereq_failures(), prereq_report(),
+prompt($message, $default), recommends(), requires(), rscan_dir($dir,
+$pattern), runtime_params(), runtime_params($key), script_files(),
+up_to_date($source_file, $derived_file), up_to_date(\@source_files,
+\@derived_files), y_n($message, $default)
+
+=item Autogenerated Accessors
+
+PL_files(), allow_mb_mismatch(), autosplit(), base_dir(), bindoc_dirs(),
+blib(), build_bat(), build_class(), build_elements(), build_requires(),
+build_script(), c_source(), config_dir(), configure_requires(),
+conflicts(), create_makefile_pl(), create_packlist(), create_readme(),
+debugger(), destdir(), get_options(), html_css(), include_dirs(),
+install_base(), install_sets(), installdirs(), libdoc_dirs(), license(),
+magic_number(), mb_version(), meta_add(), meta_merge(), metafile(),
+module_name(), orig_dir(), original_prefix(), perl(), pm_files(),
+pod_files(), pollute(), prefix(), prereq_action_types(), quiet(),
+recommends(), recurse_into(), recursive_test_files(), requires(),
+scripts(), use_rcfile(), verbose(), xs_files()
+
+=back
+
+=item MODULE METADATA
+
+keywords, resources
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Authoring - Authoring Module::Build modules
+
+=over 4
+
+=item DESCRIPTION
+
+=item STRUCTURE
+
+=item SUBCLASSING
+
+=item PREREQUISITES
+
+=over 4
+
+=item Types of prerequisites
+
+configure_requires, build_requires, requires, recommends, conflicts
+
+=item Format of prerequisites
+
+=item XS Extensions
+
+=back
+
+=item SAVING CONFIGURATION INFORMATION
+
+=item STARTING MODULE DEVELOPMENT
+
+=item AUTOMATION
+
+=item MIGRATION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Base - Default methods for Module::Build
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Compat - Compatibility with ExtUtils::MakeMaker
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+create_makefile_pl($style, $build), small, passthrough, traditional,
+run_build_pl(args => \@ARGV), args, script, write_makefile(), makefile
+
+=item SCENARIOS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::ConfigData - Configuration for Module::Build
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+config($name), feature($name), set_config($name, $value),
+set_feature($name, $value), config_names(), feature_names(),
+auto_feature_names(), write()
+
+=item AUTHOR
+
+=back
+
+=head2 Module::Build::Cookbook - Examples of Module::Build Usage
+
+=over 4
+
+=item DESCRIPTION
+
+=item BASIC RECIPES
+
+=over 4
+
+=item Installing modules that use Module::Build
+
+=item Modifying Config.pm values
+
+=item Installing modules using the programmatic interface
+
+=item Installing to a temporary directory
+
+=item Installing to a non-standard directory
+
+=item Installing in the same location as ExtUtils::MakeMaker
+
+=item Running a single test file
+
+=back
+
+=item ADVANCED RECIPES
+
+=over 4
+
+=item Making a CPAN.pm-compatible distribution
+
+=item Changing the order of the build process
+
+=item Adding new file types to the build process
+
+=item Adding new elements to the install process
+
+=back
+
+=item EXAMPLES ON CPAN
+
+=over 4
+
+=item SVN-Notify-Mirror
+
+1. Using C<auto_features>, I check to see whether two optional modules are
+available - SVN::Notify::Config and Net::SSH;, 2. If the S::N::Config
+module is loaded, I automatically generate testfiles for it during Build
+(using the C<PL_files> property), 3. If the C<ssh_feature> is available, I
+ask if the user wishes to perform the ssh tests (since it requires a little
+preliminary setup);, 4. Only if the user has C<ssh_feature> and answers yes
+to the testing, do I generate a test file
+
+=item Modifying an action
+
+=back
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::ModuleInfo, ModuleInfo - Gather package and POD
+information from a perl module files
+
+=over 4
+
+=item DESCRIPTION
+
+new_from_file($filename, collect_pod => 1), new_from_module($module,
+collect_pod => 1, inc => \@dirs), name(), version($package), filename(),
+packages_inside(), pod_inside(), contains_pod(), pod($section),
+find_module_by_name($module, \@dirs), find_module_dir_by_name($module,
+\@dirs)
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Notes, $notes_name - Configuration for $module_name
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+config(\$name), feature(\$name), set_config(\$name, \$value),
+set_feature(\$name, \$value), config_names(), feature_names(),
+auto_feature_names(), write()
+
+=item AUTHOR
+
+=back
+
+=head2 Module::Build::PPMMaker - Perl Package Manager file creation
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::Amiga - Builder class for Amiga platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::Default - Stub class for unknown platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::EBCDIC - Builder class for EBCDIC platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::MPEiX - Builder class for MPEiX platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::MacOS - Builder class for MacOS platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overriden Methods
+
+new(), make_executable(), dispatch(), ACTION_realclean()
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::RiscOS - Builder class for RiscOS platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::Unix - Builder class for Unix platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::VMS - Builder class for VMS platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Overridden Methods
+
+_set_defaults
+
+=back
+
+=back
+
+cull_args
+
+manpage_separator
+
+prefixify
+
+_quote_args
+
+have_forkpipe
+
+_backticks
+
+do_system
+
+_infer_xs_spec
+
+rscan_dir
+
+dist_dir
+
+man3page_name
+
+expand_test_dir
+
+_detildefy
+
+find_perl_interpreter
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::VOS - Builder class for VOS platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::Windows - Builder class for Windows
+platforms
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::aix - Builder class for AIX platform
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::cygwin - Builder class for Cygwin platform
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::darwin - Builder class for Mac OS X
+platform
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::Platform::os2 - Builder class for OS/2 platform
+
+=over 4
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Build::YAML - Provides just enough YAML support so that
+Module::Build works even if YAML.pm is not installed
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Module::CoreList - what modules shipped with versions of perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEATS
+
+=item HISTORY
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Load - runtime require of both modules and files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Rules
+
+=item Caveats
+
+=item ACKNOWLEDGEMENTS
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Module::Load::Conditional - Looking up module information / loading
+at runtime
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Methods
+
+=item $href = check_install( module => NAME [, version => VERSION, verbose
+=> BOOL ] );
+
+module, version, verbose, file, version, uptodate
+
+=back
+
+=over 4
+
+=item $bool = can_load( modules => { NAME => VERSION [,NAME => VERSION] },
+[verbose => BOOL, nocache => BOOL] )
+
+modules, verbose, nocache
+
+=back
+
+=over 4
+
+=item @list = requires( MODULE );
+
+=back
+
+=over 4
+
+=item Global Variables
+
+=over 4
+
+=item $Module::Load::Conditional::VERBOSE
+
+=item $Module::Load::Conditional::FIND_VERSION
+
+=item $Module::Load::Conditional::CHECK_INC_HASH
+
+=item $Module::Load::Conditional::CACHE
+
+=item $Module::Load::Conditional::ERROR
+
+=back
+
+=item See Also
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Module::Loaded - mark modules as loaded or unloaded
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item $bool = mark_as_loaded( PACKAGE );
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = mark_as_unloaded( PACKAGE );
+
+=back
+
+=over 4
+
+=item $loc = is_loaded( PACKAGE );
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Module::Pluggable - automatically give your module the ability to
+have plugins
+
+=over 4
+
+=item SYNOPSIS
+
+=item EXAMPLE
+
+=item DESCRIPTION
+
+=item ADVANCED USAGE
+
+=item INNER PACKAGES
+
+=item OPTIONS
+
+=over 4
+
+=item sub_name
+
+=item search_path
+
+=item search_dirs
+
+=item instantiate
+
+=item require
+
+=item inner
+
+=item only
+
+=item except
+
+=item package
+
+=item file_regex
+
+=back
+
+=item METHODs
+
+=over 4
+
+=item search_path
+
+=back
+
+=item FUTURE PLANS
+
+=item AUTHOR
+
+=item COPYING
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Module::Pluggable::Object - automatically give your module the
+ability to have plugins
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=item COPYING
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 NDBM_File - Tied access to ndbm files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>
+
+=item DIAGNOSTICS
+
+=over 4
+
+=item C<ndbm store returned -1, errno 22, key "..." at ...>
+
+=back
+
+=item BUGS AND WARNINGS
+
+=back
+
+=head2 NEXT - Provide a pseudo-class NEXT (et al) that allows method
+redispatch
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Enforcing redispatch
+
+=item Avoiding repetitions
+
+=item Invoking all versions of a method with a single call
+
+=item Using C<EVERY> methods
+
+=back
+
+=item AUTHOR
+
+=item BUGS AND IRRITATIONS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::Cmd - Network Command class (as used by FTP, SMTP etc)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USER METHODS
+
+debug ( VALUE ), message (), code (), ok (), status (), datasend ( DATA ),
+dataend ()
+
+=item CLASS METHODS
+
+debug_print ( DIR, TEXT ), debug_text ( TEXT ), command ( CMD [, ARGS, ...
+]), unsupported (), response (), parse_response ( TEXT ), getline (),
+ungetline ( TEXT ), rawdatasend ( DATA ), read_until_dot (), tied_fh ()
+
+=item EXPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::Config - Local configuration data for libnet
+
+=over 4
+
+=item SYNOPSYS
+
+=item DESCRIPTION
+
+=item METHODS
+
+requires_firewall HOST
+
+=item NetConfig VALUES
+
+nntp_hosts, snpp_hosts, pop3_hosts, smtp_hosts, ph_hosts, daytime_hosts,
+time_hosts, inet_domain, ftp_firewall, ftp_firewall_type, ftp_ext_passive,
+ftp_int_passive, local_netmask, test_hosts, test_exists
+
+=back
+
+=head2 Net::Domain - Attempt to evaluate the current host's internet name
+and domain
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+hostfqdn (), domainname (), hostname (), hostdomain ()
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::FTP - FTP Client class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OVERVIEW
+
+=item CONSTRUCTOR
+
+new ([ HOST ] [, OPTIONS ])
+
+=item METHODS
+
+login ([LOGIN [,PASSWORD [, ACCOUNT] ] ]), authorize ( [AUTH [, RESP]]),
+site (ARGS), ascii, binary, rename ( OLDNAME, NEWNAME ), delete ( FILENAME
+), cwd ( [ DIR ] ), cdup (), pwd (), restart ( WHERE ), rmdir ( DIR [,
+RECURSE ]), mkdir ( DIR [, RECURSE ]), alloc ( SIZE [, RECORD_SIZE] ), ls (
+[ DIR ] ), dir ( [ DIR ] ), get ( REMOTE_FILE [, LOCAL_FILE [, WHERE]] ),
+put ( LOCAL_FILE [, REMOTE_FILE ] ), put_unique ( LOCAL_FILE [, REMOTE_FILE
+] ), append ( LOCAL_FILE [, REMOTE_FILE ] ), unique_name (), mdtm ( FILE ),
+size ( FILE ), supported ( CMD ), hash ( [FILEHANDLE_GLOB_REF],[
+BYTES_PER_HASH_MARK] ), feature ( NAME ), nlst ( [ DIR ] ), list ( [ DIR ]
+), retr ( FILE ), stor ( FILE ), stou ( FILE ), appe ( FILE ), port ( [
+PORT ] ), pasv (), pasv_xfer ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ),
+pasv_xfer_unique ( SRC_FILE, DEST_SERVER [, DEST_FILE ] ), pasv_wait (
+NON_PASV_SERVER ), abort (), quit ()
+
+=over 4
+
+=item Methods for the adventurous
+
+quot (CMD [,ARGS])
+
+=back
+
+=item THE dataconn CLASS
+
+read ( BUFFER, SIZE [, TIMEOUT ] ), write ( BUFFER, SIZE [, TIMEOUT ] ),
+bytes_read (), abort (), close ()
+
+=item UNIMPLEMENTED
+
+B<SMNT>, B<HELP>, B<MODE>, B<SYST>, B<STAT>, B<STRU>, B<REIN>
+
+=item REPORTING BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=item USE EXAMPLES
+
+http://www.csh.rit.edu/~adam/Progs/
+
+=item CREDITS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::NNTP - NNTP Client class
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ HOST ] [, OPTIONS ])
+
+=item METHODS
+
+article ( [ MSGID|MSGNUM ], [FH] ), body ( [ MSGID|MSGNUM ], [FH] ), head (
+[ MSGID|MSGNUM ], [FH] ), articlefh ( [ MSGID|MSGNUM ] ), bodyfh ( [
+MSGID|MSGNUM ] ), headfh ( [ MSGID|MSGNUM ] ), nntpstat ( [ MSGID|MSGNUM ]
+), group ( [ GROUP ] ), ihave ( MSGID [, MESSAGE ]), last (), date (),
+postok (), authinfo ( USER, PASS ), list (), newgroups ( SINCE [,
+DISTRIBUTIONS ]), newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]]), next (),
+post ( [ MESSAGE ] ), postfh (), slave (), quit ()
+
+=over 4
+
+=item Extension methods
+
+newsgroups ( [ PATTERN ] ), distributions (), subscriptions (),
+overview_fmt (), active_times (), active ( [ PATTERN ] ), xgtitle ( PATTERN
+), xhdr ( HEADER, MESSAGE-SPEC ), xover ( MESSAGE-SPEC ), xpath (
+MESSAGE-ID ), xpat ( HEADER, PATTERN, MESSAGE-SPEC), xrover, listgroup ( [
+GROUP ] ), reader
+
+=back
+
+=item UNSUPPORTED
+
+=item DEFINITIONS
+
+MESSAGE-SPEC, PATTERN, Examples, C<[^]-]>, C<*bdc>, C<[0-9a-zA-Z]>, C<a??d>
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::POP3 - Post Office Protocol 3 Client class (RFC1939)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+new ( [ HOST ] [, OPTIONS ] 0
+
+=item METHODS
+
+auth ( USERNAME, PASSWORD ), user ( USER ), pass ( PASS ), login ( [ USER
+[, PASS ]] ), apop ( [ USER [, PASS ]] ), banner (), capa (), capabilities
+(), top ( MSGNUM [, NUMLINES ] ), list ( [ MSGNUM ] ), get ( MSGNUM [, FH ]
+), getfh ( MSGNUM ), last (), popstat (), ping ( USER ), uidl ( [ MSGNUM ]
+), delete ( MSGNUM ), reset (), quit ()
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::Ping - check a remote host for reachability
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Functions
+
+Net::Ping->new([$proto [, $def_timeout [, $bytes [, $device [, $tos
+]]]]]);, $p->ping($host [, $timeout]);, $p->source_verify( { 0 | 1 } );,
+$p->service_check( { 0 | 1 } );, $p->tcp_service_check( { 0 | 1 } );,
+$p->hires( { 0 | 1 } );, $p->bind($local_addr);, $p->open($host);, $p->ack(
+[ $host ] );, $p->nack( $failed_ack_host );, $p->close();,
+$p->port_number([$port_number]), pingecho($host [, $timeout]);
+
+=back
+
+=item NOTES
+
+=item INSTALL
+
+=item BUGS
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::SMTP - Simple Mail Transfer Protocol Client
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item CONSTRUCTOR
+
+new ( [ HOST ] [, OPTIONS ] )
+
+=item METHODS
+
+banner (), domain (), hello ( DOMAIN ), host (), etrn ( DOMAIN ), auth (
+USERNAME, PASSWORD ), mail ( ADDRESS [, OPTIONS] ), send ( ADDRESS ),
+send_or_mail ( ADDRESS ), send_and_mail ( ADDRESS ), reset (), recipient (
+ADDRESS [, ADDRESS, [...]] [, OPTIONS ] ), to ( ADDRESS [, ADDRESS [...]]
+), cc ( ADDRESS [, ADDRESS [...]] ), bcc ( ADDRESS [, ADDRESS [...]] ),
+data ( [ DATA ] ), expand ( ADDRESS ), verify ( ADDRESS ), help ( [
+$subject ] ), quit ()
+
+=item ADDRESSES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::Time - time and daytime network client interface
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+inet_time ( [HOST [, PROTOCOL [, TIMEOUT]]]), inet_daytime ( [HOST [,
+PROTOCOL [, TIMEOUT]]])
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Net::hostent - by-name interface to Perl's built-in gethost*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Net::libnetFAQ, libnetFAQ - libnet Frequently Asked Questions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Where to get this document
+
+=item How to contribute to this document
+
+=back
+
+=item Author and Copyright Information
+
+=over 4
+
+=item Disclaimer
+
+=back
+
+=item Obtaining and installing libnet
+
+=over 4
+
+=item What is libnet ?
+
+=item Which version of perl do I need ?
+
+=item What other modules do I need ?
+
+=item What machines support libnet ?
+
+=item Where can I get the latest libnet release
+
+=back
+
+=item Using Net::FTP
+
+=over 4
+
+=item How do I download files from an FTP server ?
+
+=item How do I transfer files in binary mode ?
+
+=item How can I get the size of a file on a remote FTP server ?
+
+=item How can I get the modification time of a file on a remote FTP server
+?
+
+=item How can I change the permissions of a file on a remote server ?
+
+=item Can I do a reget operation like the ftp command ?
+
+=item How do I get a directory listing from an FTP server ?
+
+=item Changing directory to "" does not fail ?
+
+=item I am behind a SOCKS firewall, but the Firewall option does not work ?
+
+=item I am behind an FTP proxy firewall, but cannot access machines outside
+?
+
+=item My ftp proxy firewall does not listen on port 21
+
+=item Is it possible to change the file permissions of a file on an FTP
+server ?
+
+=item I have seen scripts call a method message, but cannot find it
+documented ?
+
+=item Why does Net::FTP not implement mput and mget methods
+
+=back
+
+=item Using Net::SMTP
+
+=over 4
+
+=item Why can't the part of an Email address after the @ be used as the
+hostname ?
+
+=item Why does Net::SMTP not do DNS MX lookups ?
+
+=item The verify method always returns true ?
+
+=back
+
+=item Debugging scripts
+
+=over 4
+
+=item How can I debug my scripts that use Net::* modules ?
+
+=back
+
+=item AUTHOR AND COPYRIGHT
+
+=back
+
+=head2 Net::netent - by-name interface to Perl's built-in getnet*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Net::protoent - by-name interface to Perl's built-in getproto*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Net::servent - by-name interface to Perl's built-in getserv*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Netrc, Net::Netrc - OO interface to users netrc file
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item THE .netrc FILE
+
+machine name, default, login name, password string, account string, macdef
+name
+
+=item CONSTRUCTOR
+
+lookup ( MACHINE [, LOGIN ])
+
+=item METHODS
+
+login (), password (), account (), lpa ()
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
+=head2 O - Generic interface to Perl Compiler backends
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONVENTIONS
+
+=item IMPLEMENTATION
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 ODBM_File - Tied access to odbm files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>
+
+=item DIAGNOSTICS
+
+=over 4
+
+=item C<odbm store returned -1, errno 22, key "..." at ...>
+
+=back
+
+=item BUGS AND WARNINGS
+
+=back
+
+=head2 Object::Accessor
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=over 4
+
+=item $object = Object::Accessor->new( [ARGS] );
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = $object->mk_accessors( @ACCESSORS | \%ACCESSOR_MAP );
+
+=back
+
+=over 4
+
+=item @list = $self->ls_accessors;
+
+=back
+
+=over 4
+
+=item $ref = $self->ls_allow(KEY)
+
+=back
+
+=over 4
+
+=item $clone = $self->mk_clone;
+
+=back
+
+=over 4
+
+=item $bool = $self->mk_flush;
+
+=back
+
+=over 4
+
+=item $bool = $self->mk_verify;
+
+=back
+
+=over 4
+
+=item $bool = $self->register_callback( sub { ... } );
+
+=back
+
+=over 4
+
+=item $bool = $self->can( METHOD_NAME )
+
+=back
+
+=over 4
+
+=item $val = $self->___get( METHOD_NAME );
+
+=back
+
+=over 4
+
+=item $bool = $self->___set( METHOD_NAME => VALUE );
+
+=back
+
+=over 4
+
+=item LVALUE ACCESSORS
+
+=over 4
+
+=item CAVEATS
+
+Allow handlers, Callbacks
+
+=back
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Object::Accessor::FATAL
+
+=item $Object::Accessor::DEBUG
+
+=back
+
+=item TODO
+
+=over 4
+
+=item Create read-only accessors
+
+=back
+
+=item CAVEATS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Opcode - Disable named opcodes when compiling perl code
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item WARNING
+
+=item Operator Names and Operator Lists
+
+an operator name (opname), an operator tag name (optag), a negated opname
+or optag, an operator set (opset)
+
+=item Opcode Functions
+
+opcodes, opset (OP, ...), opset_to_ops (OPSET), opset_to_hex (OPSET),
+full_opset, empty_opset, invert_opset (OPSET), verify_opset (OPSET, ...),
+define_optag (OPTAG, OPSET), opmask_add (OPSET), opmask, opdesc (OP, ...),
+opdump (PAT)
+
+=item Manipulating Opsets
+
+=item TO DO (maybe)
+
+=back
+
+=over 4
+
+=item Predefined Opcode Tags
+
+:base_core, :base_mem, :base_loop, :base_io, :base_orig, :base_math,
+:base_thread, :default, :filesys_read, :sys_db, :browse, :filesys_open,
+:filesys_write, :subprocess, :ownprocess, :others, :load,
+:still_to_be_decided, :dangerous
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=back
+
+=head2 Opcode::Safe, Safe - Compile and execute code in restricted
+compartments
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+a new namespace, an operator mask
+
+=item WARNING
+
+=over 4
+
+=item RECENT CHANGES
+
+=item Methods in class Safe
+
+permit (OP, ...), permit_only (OP, ...), deny (OP, ...), deny_only (OP,
+...), trap (OP, ...), untrap (OP, ...), share (NAME, ...), share_from
+(PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING), rdo (FILENAME),
+root (NAMESPACE), mask (MASK)
+
+=item Some Safety Issues
+
+Memory, CPU, Snooping, Signals, State Changes
+
+=item AUTHOR
+
+=back
+
+=back
+
+=head2 Opcode::ops, ops - Perl pragma to restrict unsafe operations when
+compiling
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 POSIX - Perl interface to IEEE Std 1003.1
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item CAVEATS
+
+=item FUNCTIONS
+
+_exit, abort, abs, access, acos, alarm, asctime, asin, assert, atan, atan2,
+atexit, atof, atoi, atol, bsearch, calloc, ceil, chdir, chmod, chown,
+clearerr, clock, close, closedir, cos, cosh, creat, ctermid, ctime,
+cuserid, difftime, div, dup, dup2, errno, execl, execle, execlp, execv,
+execve, execvp, exit, exp, fabs, fclose, fcntl, fdopen, feof, ferror,
+fflush, fgetc, fgetpos, fgets, fileno, floor, fmod, fopen, fork, fpathconf,
+fprintf, fputc, fputs, fread, free, freopen, frexp, fscanf, fseek, fsetpos,
+fstat, fsync, ftell, fwrite, getc, getchar, getcwd, getegid, getenv,
+geteuid, getgid, getgrgid, getgrnam, getgroups, getlogin, getpgrp, getpid,
+getppid, getpwnam, getpwuid, gets, getuid, gmtime, isalnum, isalpha,
+isatty, iscntrl, isdigit, isgraph, islower, isprint, ispunct, isspace,
+isupper, isxdigit, kill, labs, ldexp, ldiv, link, localeconv, localtime,
+log, log10, longjmp, lseek, malloc, mblen, mbstowcs, mbtowc, memchr,
+memcmp, memcpy, memmove, memset, mkdir, mkfifo, mktime, modf, nice,
+offsetof, open, opendir, pathconf, pause, perror, pipe, pow, printf, putc,
+putchar, puts, qsort, raise, rand, read, readdir, realloc, remove, rename,
+rewind, rewinddir, rmdir, scanf, setgid, setjmp, setlocale, setpgid,
+setsid, setuid, sigaction, siglongjmp, sigpending, sigprocmask, sigsetjmp,
+sigsuspend, sin, sinh, sleep, sprintf, sqrt, srand, sscanf, stat, strcat,
+strchr, strcmp, strcoll, strcpy, strcspn, strerror, strftime, strlen,
+strncat, strncmp, strncpy, strpbrk, strrchr, strspn, strstr, strtod,
+strtok, strtol, strtoul, strxfrm, sysconf, system, tan, tanh, tcdrain,
+tcflow, tcflush, tcgetpgrp, tcsendbreak, tcsetpgrp, time, times, tmpfile,
+tmpnam, tolower, toupper, ttyname, tzname, tzset, umask, uname, ungetc,
+unlink, utime, vfprintf, vprintf, vsprintf, wait, waitpid, wcstombs,
+wctomb, write
+
+=item CLASSES
+
+=over 4
+
+=item POSIX::SigAction
+
+new, handler, mask, flags, safe
+
+=item POSIX::SigRt
+
+%SIGRT, SIGRTMIN, SIGRTMAX
+
+=item POSIX::SigSet
+
+new, addset, delset, emptyset, fillset, ismember
+
+=item POSIX::Termios
+
+new, getattr, getcc, getcflag, getiflag, getispeed, getlflag, getoflag,
+getospeed, setattr, setcc, setcflag, setiflag, setispeed, setlflag,
+setoflag, setospeed, Baud rate values, Terminal interface values, c_cc
+field values, c_cflag field values, c_iflag field values, c_lflag field
+values, c_oflag field values
+
+=back
+
+=item PATHNAME CONSTANTS
+
+Constants
+
+=item POSIX CONSTANTS
+
+Constants
+
+=item SYSTEM CONFIGURATION
+
+Constants
+
+=item ERRNO
+
+Constants
+
+=item FCNTL
+
+Constants
+
+=item FLOAT
+
+Constants
+
+=item LIMITS
+
+Constants
+
+=item LOCALE
+
+Constants
+
+=item MATH
+
+Constants
+
+=item SIGNAL
+
+Constants
+
+=item STAT
+
+Constants, Macros
+
+=item STDLIB
+
+Constants
+
+=item STDIO
+
+Constants
+
+=item TIME
+
+Constants
+
+=item UNISTD
+
+Constants
+
+=item WAIT
+
+Constants, WNOHANG, WUNTRACED, Macros, WIFEXITED, WEXITSTATUS, WIFSIGNALED,
+WTERMSIG, WIFSTOPPED, WSTOPSIG
+
+=back
+
+=head2 Package::Constants - List all constants declared in a package
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CLASS METHODS
+
+=over 4
+
+=item @const = Package::Constants->list( PACKAGE_NAME );
+
+=back
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Package::Constants::DEBUG
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Params::Check - A generic input parsing/checking mechanism.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Template
+
+default, required, strict_type, defined, no_override, store, allow
+
+=item Functions
+
+=over 4
+
+=item check( \%tmpl, \%args, [$verbose] );
+
+Template, Arguments, Verbose
+
+=back
+
+=back
+
+=over 4
+
+=item allow( $test_me, \@criteria );
+
+string, regexp, subroutine, array ref
+
+=back
+
+=over 4
+
+=item last_error()
+
+=back
+
+=over 4
+
+=item Global Variables
+
+=over 4
+
+=item $Params::Check::VERBOSE
+
+=item $Params::Check::STRICT_TYPE
+
+=item $Params::Check::ALLOW_UNKNOWN
+
+=item $Params::Check::STRIP_LEADING_DASHES
+
+=item $Params::Check::NO_DUPLICATES
+
+=item $Params::Check::PRESERVE_CASE
+
+=item $Params::Check::ONLY_ALLOW_DEFINED
+
+=item $Params::Check::SANITY_CHECK_TEMPLATE
+
+=item $Params::Check::WARNINGS_FATAL
+
+=item $Params::Check::CALLER_DEPTH
+
+=back
+
+=item AUTHOR
+
+=item Acknowledgements
+
+=item COPYRIGHT
+
+=back
+
+=head2 PerlIO - On demand loader for PerlIO layers and root of PerlIO::*
+name space
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+:unix, :stdio, :perlio, :crlf, :mmap, :utf8, :bytes, :raw, :pop, :win32
+
+=over 4
+
+=item Custom Layers
+
+:encoding, :via
+
+=item Alternatives to raw
+
+=item Defaults and how to override them
+
+=item Querying the layers of filehandles
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 PerlIO::encoding - encoding layer
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 PerlIO::scalar - in-memory IO, scalar IO
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item IMPLEMENTATION NOTE
+
+=back
+
+=head2 PerlIO::via - Helper class for PerlIO layers implemented in perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPECTED METHODS
+
+$class->PUSHED([$mode[,$fh]]), $obj->POPPED([$fh]),
+$obj->UTF8($bellowFlag,[$fh]), $obj->OPEN($path,$mode[,$fh]),
+$obj->BINMODE([,$fh]), $obj->FDOPEN($fd[,$fh]),
+$obj->SYSOPEN($path,$imode,$perm,[,$fh]), $obj->FILENO($fh),
+$obj->READ($buffer,$len,$fh), $obj->WRITE($buffer,$fh), $obj->FILL($fh),
+$obj->CLOSE($fh), $obj->SEEK($posn,$whence,$fh), $obj->TELL($fh),
+$obj->UNREAD($buffer,$fh), $obj->FLUSH($fh), $obj->SETLINEBUF($fh),
+$obj->CLEARERR($fh), $obj->ERROR($fh), $obj->EOF($fh)
+
+=item EXAMPLES
+
+=over 4
+
+=item Example - a Hexadecimal Handle
+
+=back
+
+=back
+
+=head2 PerlIO::via::QuotedPrint - PerlIO layer for quoted-printable strings
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item REQUIRED MODULES
+
+=item SEE ALSO
+
+=item ACKNOWLEDGEMENTS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Pod::Checker, podchecker() - check pod documents for syntax errors
+
+=over 4
+
+=item SYNOPSIS
+
+=item OPTIONS/ARGUMENTS
+
+=over 4
+
+=item podchecker()
+
+B<-warnings> =E<gt> I<val>
+
+=back
+
+=item DESCRIPTION
+
+=item DIAGNOSTICS
+
+=over 4
+
+=item Errors
+
+empty =headn, =over on line I<N> without closing =back, =item without
+previous =over, =back without previous =over, No argument for =begin, =end
+without =begin, Nested =begin's, =for without formatter specification,
+unresolved internal link I<NAME>, Unknown command "I<CMD>", Unknown
+interior-sequence "I<SEQ>", nested commands
+I<CMD>E<lt>...I<CMD>E<lt>...E<gt>...E<gt>, garbled entity I<STRING>, Entity
+number out of range, malformed link LE<lt>E<gt>, nonempty ZE<lt>E<gt>,
+empty XE<lt>E<gt>, Spurious text after =pod / =cut, Spurious character(s)
+after =back
+
+=item Warnings
+
+multiple occurrence of link target I<name>, line containing nothing but
+whitespace in paragraph, file does not start with =head, previous =item has
+no contents, preceding non-item paragraph(s), =item type mismatch (I<one>
+vs. I<two>), I<N> unescaped C<E<lt>E<gt>> in paragraph, Unknown entity, No
+items in =over, No argument for =item, empty section in previous paragraph,
+Verbatim paragraph in NAME section, =headI<n> without preceding higher
+level
+
+=item Hyperlinks
+
+ignoring leading/trailing whitespace in link, (section) in '$page'
+deprecated, alternative text/node '%s' contains non-escaped | or /
+
+=back
+
+=item RETURN VALUE
+
+=item EXAMPLES
+
+=item INTERFACE
+
+=back
+
+C<Pod::Checker-E<gt>new( %options )>
+
+C<$checker-E<gt>poderror( @args )>, C<$checker-E<gt>poderror( {%opts},
+ at args )>
+
+C<$checker-E<gt>num_errors()>
+
+C<$checker-E<gt>num_warnings()>
+
+C<$checker-E<gt>name()>
+
+C<$checker-E<gt>node()>
+
+C<$checker-E<gt>idx()>
+
+C<$checker-E<gt>hyperlink()>
+
+=over 4
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Escapes -- for resolving Pod EE<lt>...E<gt> sequences
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item GOODIES
+
+e2char($e_content), e2charnum($e_content), $Name2character{I<name>},
+$Name2character_number{I<name>}, $Latin1Code_to_fallback{I<integer>},
+$Latin1Char_to_fallback{I<character>}, $Code2USASCII{I<integer>}
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Find - find POD documents in directory trees
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item C<pod_find( { %opts } , @directories )>
+
+C<-verbose =E<gt> 1>, C<-perl =E<gt> 1>, C<-script =E<gt> 1>, C<-inc =E<gt>
+1>
+
+=back
+
+=over 4
+
+=item C<simplify_name( $str )>
+
+=back
+
+=over 4
+
+=item C<pod_where( { %opts }, $pod )>
+
+C<-inc =E<gt> 1>, C<-dirs =E<gt> [ $dir1, $dir2, ... ]>, C<-verbose =E<gt>
+1>
+
+=back
+
+=over 4
+
+=item C<contains_pod( $file , $verbose )>
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Pod::Html - module to convert pod files to HTML
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item pod2html
+
+backlink, cachedir, css, flush, header, help, hiddendirs, htmldir,
+htmlroot, index, infile, libpods, netscape, outfile, podpath, podroot,
+quiet, recurse, title, verbose
+
+=item htmlify
+
+=item anchorify
+
+=back
+
+=item ENVIRONMENT
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=back
+
+=head2 Pod::InputObjects - objects representing POD input paragraphs,
+commands, etc.
+
+=over 4
+
+=item SYNOPSIS
+
+=item REQUIRES
+
+=item EXPORTS
+
+=item DESCRIPTION
+
+package B<Pod::InputSource>, package B<Pod::Paragraph>, package
+B<Pod::InteriorSequence>, package B<Pod::ParseTree>
+
+=back
+
+=over 4
+
+=item B<Pod::InputSource>
+
+=back
+
+=over 4
+
+=item B<new()>
+
+=back
+
+=over 4
+
+=item B<name()>
+
+=back
+
+=over 4
+
+=item B<handle()>
+
+=back
+
+=over 4
+
+=item B<was_cutting()>
+
+=back
+
+=over 4
+
+=item B<Pod::Paragraph>
+
+=back
+
+=over 4
+
+=item Pod::Paragraph-E<gt>B<new()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<cmd_name()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<text()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<raw_text()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<cmd_prefix()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<cmd_separator()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<parse_tree()>
+
+=back
+
+=over 4
+
+=item $pod_para-E<gt>B<file_line()>
+
+=back
+
+=over 4
+
+=item B<Pod::InteriorSequence>
+
+=back
+
+=over 4
+
+=item Pod::InteriorSequence-E<gt>B<new()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<cmd_name()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<prepend()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<append()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<nested()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<raw_text()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<left_delimiter()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<right_delimiter()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<parse_tree()>
+
+=back
+
+=over 4
+
+=item $pod_seq-E<gt>B<file_line()>
+
+=back
+
+=over 4
+
+=item Pod::InteriorSequence::B<DESTROY()>
+
+=back
+
+=over 4
+
+=item B<Pod::ParseTree>
+
+=back
+
+=over 4
+
+=item Pod::ParseTree-E<gt>B<new()>
+
+=back
+
+=over 4
+
+=item $ptree-E<gt>B<top()>
+
+=back
+
+=over 4
+
+=item $ptree-E<gt>B<children()>
+
+=back
+
+=over 4
+
+=item $ptree-E<gt>B<prepend()>
+
+=back
+
+=over 4
+
+=item $ptree-E<gt>B<append()>
+
+=back
+
+=over 4
+
+=item $ptree-E<gt>B<raw_text()>
+
+=back
+
+=over 4
+
+=item Pod::ParseTree::B<DESTROY()>
+
+=back
+
+=over 4
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::LaTeX - Convert Pod data to formatted Latex
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item OBJECT METHODS
+
+C<initialize>
+
+=back
+
+=over 4
+
+=item Data Accessors
+
+B<AddPreamble>
+
+=back
+
+B<AddPostamble>
+
+B<Head1Level>
+
+B<Label>
+
+B<LevelNoNum>
+
+B<MakeIndex>
+
+B<ReplaceNAMEwithSection>
+
+B<StartWithNewPage>
+
+B<TableOfContents>
+
+B<UniqueLabels>
+
+B<UserPreamble>
+
+B<UserPostamble>
+
+B<Lists>
+
+=over 4
+
+=item Subclassed methods
+
+=back
+
+B<begin_pod>
+
+B<end_pod>
+
+B<command>
+
+B<verbatim>
+
+B<textblock>
+
+B<interior_sequence>
+
+=over 4
+
+=item List Methods
+
+B<begin_list>
+
+=back
+
+B<end_list>
+
+B<add_item>
+
+=over 4
+
+=item Methods for headings
+
+B<head>
+
+=back
+
+=over 4
+
+=item Internal methods
+
+B<_output>
+
+=back
+
+B<_replace_special_chars>
+
+B<_replace_special_chars_late>
+
+B<_create_label>
+
+B<_create_index>
+
+B<_clean_latex_commands>
+
+B<_split_delimited>
+
+=over 4
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=item REVISION
+
+=back
+
+=head2 Pod::Man - Convert POD data to formatted *roff input
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, name, quotes,
+release, section
+
+=item DIAGNOSTICS
+
+roff font should be 1 or 2 chars, not "%s", Invalid quote specification
+"%s"
+
+=item BUGS
+
+=item CAVEATS
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=item SEE ALSO
+
+=back
+
+=head2 Pod::ParseLink - Parse an LE<lt>E<gt> formatting code in POD text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Pod::ParseUtils - helpers for POD parsing and conversion
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item Pod::List
+
+Pod::List-E<gt>new()
+
+=back
+
+$list-E<gt>file()
+
+$list-E<gt>start()
+
+$list-E<gt>indent()
+
+$list-E<gt>type()
+
+$list-E<gt>rx()
+
+$list-E<gt>item()
+
+$list-E<gt>parent()
+
+$list-E<gt>tag()
+
+=over 4
+
+=item Pod::Hyperlink
+
+Pod::Hyperlink-E<gt>new()
+
+=back
+
+$link-E<gt>parse($string)
+
+$link-E<gt>markup($string)
+
+$link-E<gt>text()
+
+$link-E<gt>warning()
+
+$link-E<gt>file(), $link-E<gt>line()
+
+$link-E<gt>page()
+
+$link-E<gt>node()
+
+$link-E<gt>alttext()
+
+$link-E<gt>type()
+
+$link-E<gt>link()
+
+=over 4
+
+=item Pod::Cache
+
+Pod::Cache-E<gt>new()
+
+=back
+
+$cache-E<gt>item()
+
+$cache-E<gt>find_page($name)
+
+=over 4
+
+=item Pod::Cache::Item
+
+Pod::Cache::Item-E<gt>new()
+
+=back
+
+$cacheitem-E<gt>page()
+
+$cacheitem-E<gt>description()
+
+$cacheitem-E<gt>path()
+
+$cacheitem-E<gt>file()
+
+$cacheitem-E<gt>nodes()
+
+$cacheitem-E<gt>find_node($name)
+
+$cacheitem-E<gt>idx()
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Pod::Parser - base class for creating POD filters and translators
+
+=over 4
+
+=item SYNOPSIS
+
+=item REQUIRES
+
+=item EXPORTS
+
+=item DESCRIPTION
+
+=item QUICK OVERVIEW
+
+=item PARSING OPTIONS
+
+B<-want_nonPODs> (default: unset), B<-process_cut_cmd> (default: unset),
+B<-warnings> (default: unset)
+
+=back
+
+=over 4
+
+=item RECOMMENDED SUBROUTINE/METHOD OVERRIDES
+
+=back
+
+=over 4
+
+=item B<command()>
+
+C<$cmd>, C<$text>, C<$line_num>, C<$pod_para>
+
+=back
+
+=over 4
+
+=item B<verbatim()>
+
+C<$text>, C<$line_num>, C<$pod_para>
+
+=back
+
+=over 4
+
+=item B<textblock()>
+
+C<$text>, C<$line_num>, C<$pod_para>
+
+=back
+
+=over 4
+
+=item B<interior_sequence()>
+
+=back
+
+=over 4
+
+=item OPTIONAL SUBROUTINE/METHOD OVERRIDES
+
+=back
+
+=over 4
+
+=item B<new()>
+
+=back
+
+=over 4
+
+=item B<initialize()>
+
+=back
+
+=over 4
+
+=item B<begin_pod()>
+
+=back
+
+=over 4
+
+=item B<begin_input()>
+
+=back
+
+=over 4
+
+=item B<end_input()>
+
+=back
+
+=over 4
+
+=item B<end_pod()>
+
+=back
+
+=over 4
+
+=item B<preprocess_line()>
+
+=back
+
+=over 4
+
+=item B<preprocess_paragraph()>
+
+=back
+
+=over 4
+
+=item METHODS FOR PARSING AND PROCESSING
+
+=back
+
+=over 4
+
+=item B<parse_text()>
+
+B<-expand_seq> =E<gt> I<code-ref>|I<method-name>, B<-expand_text> =E<gt>
+I<code-ref>|I<method-name>, B<-expand_ptree> =E<gt>
+I<code-ref>|I<method-name>
+
+=back
+
+=over 4
+
+=item B<interpolate()>
+
+=back
+
+=over 4
+
+=item B<parse_paragraph()>
+
+=back
+
+=over 4
+
+=item B<parse_from_filehandle()>
+
+=back
+
+=over 4
+
+=item B<parse_from_file()>
+
+=back
+
+=over 4
+
+=item ACCESSOR METHODS
+
+=back
+
+=over 4
+
+=item B<errorsub()>
+
+=back
+
+=over 4
+
+=item B<cutting()>
+
+=back
+
+=over 4
+
+=item B<parseopts()>
+
+=back
+
+=over 4
+
+=item B<output_file()>
+
+=back
+
+=over 4
+
+=item B<output_handle()>
+
+=back
+
+=over 4
+
+=item B<input_file()>
+
+=back
+
+=over 4
+
+=item B<input_handle()>
+
+=back
+
+=over 4
+
+=item B<input_streams()>
+
+=back
+
+=over 4
+
+=item B<top_stream()>
+
+=back
+
+=over 4
+
+=item PRIVATE METHODS AND DATA
+
+=back
+
+=over 4
+
+=item B<_push_input_stream()>
+
+=back
+
+=over 4
+
+=item B<_pop_input_stream()>
+
+=back
+
+=over 4
+
+=item TREE-BASED PARSING
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToChecker - let Perldoc check Pod for errors
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToMan - let Perldoc render Pod as man pages
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEAT
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToNroff - let Perldoc convert Pod to nroff
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEAT
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToPod - let Perldoc render Pod as ... Pod!
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToRtf - let Perldoc render Pod as RTF
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToText - let Perldoc render Pod as plaintext
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEAT
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToTk - let Perldoc use Tk::Pod to render Pod
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Perldoc::ToXml - let Perldoc render Pod as XML
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::PlainText - Convert POD data to formatted ASCII text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+alt, indent, loose, sentence, width
+
+=item DIAGNOSTICS
+
+Bizarre space in item, Can't open %s for reading: %s, Unknown escape: %s,
+Unknown sequence: %s, Unmatched =back
+
+=item RESTRICTIONS
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Plainer - Perl extension for converting Pod to old style Pod.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item EXPORT
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Pod::Select, podselect() - extract selected sections of POD from
+input
+
+=over 4
+
+=item SYNOPSIS
+
+=item REQUIRES
+
+=item EXPORTS
+
+=item DESCRIPTION
+
+=item SECTION SPECIFICATIONS
+
+=item RANGE SPECIFICATIONS
+
+=back
+
+=over 4
+
+=item OBJECT METHODS
+
+=back
+
+=over 4
+
+=item B<curr_headings()>
+
+=back
+
+=over 4
+
+=item B<select()>
+
+=back
+
+=over 4
+
+=item B<add_selection()>
+
+=back
+
+=over 4
+
+=item B<clear_selections()>
+
+=back
+
+=over 4
+
+=item B<match_section()>
+
+=back
+
+=over 4
+
+=item B<is_selected()>
+
+=back
+
+=over 4
+
+=item EXPORTED FUNCTIONS
+
+=back
+
+=over 4
+
+=item B<podselect()>
+
+B<-output>, B<-sections>, B<-ranges>
+
+=back
+
+=over 4
+
+=item PRIVATE METHODS AND DATA
+
+=back
+
+=over 4
+
+=item B<_compile_section_spec()>
+
+=back
+
+=over 4
+
+=item $self->{_SECTION_HEADINGS}
+
+=back
+
+=over 4
+
+=item $self->{_SELECTED_SECTIONS}
+
+=back
+
+=over 4
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple - framework for parsing Pod
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item MAIN METHODS
+
+C<< $parser = I<SomeClass>->new(); >>, C<< $parser->output_fh( *OUT ); >>,
+C<< $parser->output_string( \$somestring ); >>, C<< $parser->parse_file(
+I<$some_filename> ); >>, C<< $parser->parse_file( *INPUT_FH ); >>, C<<
+$parser->parse_string_document( I<$all_content> ); >>, C<<
+$parser->parse_lines( I<... at lines...>, undef ); >>, C<<
+$parser->content_seen >>, C<< I<SomeClass>->filter( I<$filename> ); >>, C<<
+I<SomeClass>->filter( I<*INPUT_FH> ); >>, C<< I<SomeClass>->filter(
+I<\$document_content> ); >>
+
+=item SECONDARY METHODS
+
+C<< $parser->no_whining( I<SOMEVALUE> ) >>, C<< $parser->no_errata_section(
+I<SOMEVALUE> ) >>, C<< $parser->complain_stderr( I<SOMEVALUE> ) >>, C<<
+$parser->source_filename >>, C<< $parser->doc_has_started >>, C<<
+$parser->source_dead >>
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::Checker -- check the Pod syntax of a document
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::Debug -- put Pod::Simple into trace/debug mode
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEATS
+
+=item GUTS
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::DumpAsText -- dump Pod-parsing events as text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::DumpAsXML -- turn Pod into XML
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::HTML - convert Pod to HTML
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CALLING FROM THE COMMAND LINE
+
+=item CALLING FROM PERL
+
+=item METHODS
+
+=item SUBCLASSING
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::HTMLBatch - convert several Pod files to several HTML
+files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item FROM THE COMMAND LINE
+
+=back
+
+=item MAIN METHODS
+
+$batchconv = Pod::Simple::HTMLBatch->new;, $batchconv->batch_convert(
+I<indirs>, I<outdir> );, $batchconv->batch_convert( undef , ...);,
+$batchconv->batch_convert( q{@INC}, ...);, $batchconv->batch_convert(
+\@dirs , ...);, $batchconv->batch_convert( "somedir" , ...);,
+$batchconv->batch_convert( 'somedir:someother:also' , ...);,
+$batchconv->batch_convert( ... , undef );, $batchconv->batch_convert( ... ,
+'somedir' );
+
+=over 4
+
+=item ACCESSOR METHODS
+
+$batchconv->verbose( I<nonnegative_integer> );, $batchconv->index(
+I<true-or-false> );, $batchconv->contents_file( I<filename> );,
+$batchconv->contents_page_start( I<HTML_string> );,
+$batchconv->contents_page_end( I<HTML_string> );, $batchconv->add_css( $url
+);, $batchconv->add_javascript( $url );, $batchconv->css_flurry(
+I<true-or-false> );, $batchconv->javascript_flurry( I<true-or-false> );,
+$batchconv->no_contents_links( I<true-or-false> );,
+$batchconv->html_render_class( I<classname> );
+
+=back
+
+=item NOTES ON CUSTOMIZATION
+
+=item ASK ME!
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::LinkSection -- represent "section" attributes of L
+codes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::Methody -- turn Pod::Simple events into method calls
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHOD CALLING
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::PullParser -- a pull-parser interface to parsing Pod
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+my $token = $parser->get_token, $parser->unget_token( $token ),
+$parser->unget_token( $token1, $token2, ... ), $parser->set_source(
+$filename ), $parser->set_source( $filehandle_object ),
+$parser->set_source( \$document_source ), $parser->set_source(
+\@document_lines ), $parser->parse_file(...),
+$parser->parse_string_document(...), $parser->filter(...),
+$parser->parse_from_file(...), my $title_string = $parser->get_title, my
+$title_string = $parser->get_short_title, $author_name =
+$parser->get_author, $description_name = $parser->get_description,
+$version_block = $parser->get_version
+
+=item NOTE
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::PullParserEndToken -- end-tokens from
+Pod::Simple::PullParser
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$token->tagname, $token->tagname(I<somestring>), $token->tag(...),
+$token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>)
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::PullParserStartToken -- start-tokens from
+Pod::Simple::PullParser
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$token->tagname, $token->tagname(I<somestring>), $token->tag(...),
+$token->is_tag(I<somestring>) or $token->is_tagname(I<somestring>),
+$token->attr(I<attrname>), $token->attr(I<attrname>, I<newvalue>),
+$token->attr_hash
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::PullParserTextToken -- text-tokens from
+Pod::Simple::PullParser
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$token->text, $token->text(I<somestring>), $token->text_r()
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::PullParserToken -- tokens from Pod::Simple::PullParser
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+$token->type, $token->is_start, $token->is_text, $token->is_end,
+$token->dump
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::RTF -- format Pod as RTF
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FORMAT CONTROL ATTRIBUTES
+
+$parser->head1_halfpoint_size( I<halfpoint_integer> );,
+$parser->head2_halfpoint_size( I<halfpoint_integer> );,
+$parser->head3_halfpoint_size( I<halfpoint_integer> );,
+$parser->head4_halfpoint_size( I<halfpoint_integer> );,
+$parser->codeblock_halfpoint_size( I<halfpoint_integer> );,
+$parser->header_halfpoint_size( I<halfpoint_integer> );,
+$parser->normal_halfpoint_size( I<halfpoint_integer> );,
+$parser->no_proofing_exemptions( I<true_or_false> );, $parser->doc_lang(
+I<microsoft_decimal_language_code> )
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::Search - find POD documents in directory trees
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTOR
+
+=item ACCESSORS
+
+$search->inc( I<true-or-false> );, $search->verbose( I<nonnegative-number>
+);, $search->limit_glob( I<some-glob-string> );, $search->callback(
+I<\&some_routine> );, $search->laborious( I<true-or-false> );,
+$search->shadows( I<true-or-false> );, $search->limit_re( I<some-regxp> );,
+$search->dir_prefix( I<some-string-value> );, $search->progress(
+I<some-progress-object> );, $name2path = $self->name2path;, $path2name =
+$self->path2name;
+
+=item MAIN SEARCH METHODS
+
+=over 4
+
+=item C<< $search->survey( @directories ) >>
+
+C<name2path>, C<path2name>
+
+=item C<< $search->simplify_name( $str ) >>
+
+=item C<< $search->find( $pod ) >>
+
+=item C<< $search->find( $pod, @search_dirs ) >>
+
+=item C<< $self->contains_pod( $file ) >>
+
+=back
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Pod::Simple::Subclassing -- write a formatter as a Pod::Simple
+subclass
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Events
+
+C<< $parser->_handle_element_start( I<element_name>, I<attr_hashref> ) >>,
+C<< $parser->_handle_element_end( I<element_name> ) >>, C<<
+$parser->_handle_text( I<text_string> ) >>, events with an element_name
+of Document, events with an element_name of Para, events with an
+element_name of B, C, F, or I, events with an element_name of S, events
+with an element_name of X, events with an element_name of L, events with an
+element_name of E or Z, events with an element_name of Verbatim, events
+with an element_name of head1 .. head4, events with an element_name of
+over-bullet, events with an element_name of over-number, events with an
+element_name of over-text, events with an element_name of over-block,
+events with an element_name of item-bullet, events with an element_name of
+item-number, events with an element_name of item-text, events with an
+element_name of for, events with an element_name of Data
+
+=item More Pod::Simple Methods
+
+C<< $parser->accept_targets( I<SOMEVALUE> ) >>, C<<
+$parser->accept_targets_as_text( I<SOMEVALUE> ) >>, C<<
+$parser->accept_codes( I<Codename>, I<Codename>... ) >>, C<<
+$parser->accept_directive_as_data( I<directive_name> ) >>, C<<
+$parser->accept_directive_as_verbatim( I<directive_name> ) >>, C<<
+$parser->accept_directive_as_processed( I<directive_name> ) >>, C<<
+$parser->nbsp_for_S( I<BOOLEAN> ); >>, C<< $parser->version_report() >>,
+C<< $parser->pod_para_count() >>, C<< $parser->line_count() >>, C<<
+$parser->nix_X_codes( I<SOMEVALUE> ) >>, C<< $parser->merge_text(
+I<SOMEVALUE> ) >>, C<< $parser->code_handler( I<CODE_REF> ) >>, C<<
+$parser->cut_handler( I<CODE_REF> ) >>, C<< $parser->whine(
+I<linenumber>, I<complaint string> ) >>, C<< $parser->scream(
+I<linenumber>, I<complaint string> ) >>, C<< $parser->source_dead(1) >>,
+C<< $parser->hide_line_numbers( I<SOMEVALUE> ) >>, C<< $parser->no_whining(
+I<SOMEVALUE> ) >>, C<< $parser->no_errata_section( I<SOMEVALUE> ) >>, C<<
+$parser->complain_stderr( I<SOMEVALUE> ) >>, C<< $parser->bare_output(
+I<SOMEVALUE> ) >>, C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >>
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::Text -- format Pod as plaintext
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::TextContent -- get the text content of Pod
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Simple::XMLOutStream -- turn Pod into XML
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item ABOUT EXTENDING POD
+
+=item ASK ME!
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::SimpleTree, Pod::Simple::SimpleTree -- parse Pod into a simple
+parse tree
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=item Tree Contents
+
+=item SEE ALSO
+
+=item COPYRIGHT AND DISCLAIMERS
+
+=item AUTHOR
+
+=back
+
+=head2 Pod::Text - Convert POD data to formatted ASCII text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+alt, code, indent, loose, margin, quotes, sentence, width
+
+=item DIAGNOSTICS
+
+Bizarre space in item, Item called without tag, Can't open %s for reading:
+%s, Invalid quote specification "%s"
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Pod::Text::Color - Convert POD data to formatted color ASCII text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Pod::Text::Overstrike - Convert POD data to formatted overstrike
+text
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Pod::Text::Termcap - Convert POD data to ASCII text with format
+escapes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Pod::Usage, pod2usage() - print a usage message from embedded pod
+documentation
+
+=over 4
+
+=item SYNOPSIS
+
+=item ARGUMENTS
+
+C<-message>, C<-msg>, C<-exitval>, C<-verbose>, C<-sections>, C<-output>,
+C<-input>, C<-pathlist>, C<-noperldoc>
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=over 4
+
+=item Recommended Use
+
+=back
+
+=item CAVEATS
+
+=item AUTHOR
+
+=item ACKNOWLEDGMENTS
+
+=back
+
+=head2 SDBM_File - Tied access to sdbm files
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR>
+
+=item DIAGNOSTICS
+
+=over 4
+
+=item C<sdbm store returned -1, errno 22, key "..." at ...>
+
+=back
+
+=item BUGS AND WARNINGS
+
+=back
+
+=head2 Safe - Compile and execute code in restricted compartments
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+a new namespace, an operator mask
+
+=item WARNING
+
+=over 4
+
+=item RECENT CHANGES
+
+=item Methods in class Safe
+
+permit (OP, ...), permit_only (OP, ...), deny (OP, ...), deny_only (OP,
+...), trap (OP, ...), untrap (OP, ...), share (NAME, ...), share_from
+(PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING), rdo (FILENAME),
+root (NAMESPACE), mask (MASK)
+
+=item Some Safety Issues
+
+Memory, CPU, Snooping, Signals, State Changes
+
+=item AUTHOR
+
+=back
+
+=back
+
+=head2 Scalar::Util - A selection of general-utility scalar subroutines
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+blessed EXPR, dualvar NUM, STRING, isvstring EXPR, isweak EXPR,
+looks_like_number EXPR, openhandle FH, refaddr EXPR, reftype EXPR,
+set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF
+
+=item KNOWN BUGS
+
+=item SEE ALSO
+
+=item COPYRIGHT
+
+=item BLATANT PLUG
+
+=back
+
+=head2 Search::Dict, look - search for key in dictionary file
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 SelectSaver - save and restore selected file handle
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=head2 SelfLoader - load functions only on demand
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item The __DATA__ token
+
+=item SelfLoader autoloading
+
+=item Autoloading and package lexicals
+
+=item SelfLoader and AutoLoader
+
+=item __DATA__, __END__, and the FOOBAR::DATA filehandle.
+
+=item Classes and inherited methods.
+
+=back
+
+=item Multiple packages and fully qualified subroutine names
+
+=back
+
+B<_make_cmd>
+
+=head2 Shell - run shell commands transparently within perl
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Caveats
+
+=item Escaping Magic Characters
+
+=item Configuration
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 Socket, sockaddr_in, sockaddr_un, inet_aton, inet_ntoa - load the C
+socket.h defines and structure manipulators
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+inet_aton HOSTNAME, inet_ntoa IP_ADDRESS, INADDR_ANY, INADDR_BROADCAST,
+INADDR_LOOPBACK, INADDR_NONE, sockaddr_family SOCKADDR, sockaddr_in PORT,
+ADDRESS, sockaddr_in SOCKADDR_IN, pack_sockaddr_in PORT, IP_ADDRESS,
+unpack_sockaddr_in SOCKADDR_IN, sockaddr_un PATHNAME, sockaddr_un
+SOCKADDR_UN, pack_sockaddr_un PATH, unpack_sockaddr_un SOCKADDR_UN
+
+=back
+
+=head2 Storable - persistence for Perl data structures
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item MEMORY STORE
+
+=item ADVISORY LOCKING
+
+=item SPEED
+
+=item CANONICAL REPRESENTATION
+
+=item CODE REFERENCES
+
+=item FORWARD COMPATIBILITY
+
+utf8 data, restricted hashes, files from future versions of Storable
+
+=item ERROR REPORTING
+
+=item WIZARDS ONLY
+
+=over 4
+
+=item Hooks
+
+C<STORABLE_freeze> I<obj>, I<cloning>, C<STORABLE_thaw> I<obj>, I<cloning>,
+I<serialized>, .., C<STORABLE_attach> I<class>, I<cloning>, I<serialized>
+
+=item Predicates
+
+C<Storable::last_op_in_netorder>, C<Storable::is_storing>,
+C<Storable::is_retrieving>
+
+=item Recursion
+
+=item Deep Cloning
+
+=back
+
+=item Storable magic
+
+$info = Storable::file_magic( $filename ), C<version>, C<version_nv>,
+C<major>, C<minor>, C<hdrsize>, C<netorder>, C<byteorder>, C<intsize>,
+C<longsize>, C<ptrsize>, C<nvsize>, C<file>, $info = Storable::read_magic(
+$buffer ), $info = Storable::read_magic( $buffer, $must_be_file )
+
+=item EXAMPLES
+
+=item WARNING
+
+=item BUGS
+
+=over 4
+
+=item 64 bit data in perl 5.6.0 and 5.6.1
+
+=back
+
+=item CREDITS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Switch - A switch statement for Perl
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item BACKGROUND
+
+=item DESCRIPTION
+
+=over 4
+
+=item Allowing fall-through
+
+=item Automating fall-through
+
+=item Alternative syntax
+
+=item Higher-order Operations
+
+=back
+
+=item DEPENDENCIES
+
+=item AUTHOR
+
+=item BUGS
+
+=item LIMITATIONS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Symbol - manipulate Perl symbols and their names
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item BUGS
+
+=back
+
+=head2 Sys::Hostname - Try every conceivable way to get hostname
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=back
+
+=head2 Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3) calls
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPORTS
+
+=item FUNCTIONS
+
+B<openlog($ident, $logopt, $facility)>, B<syslog($priority, $message)>,
+B<syslog($priority, $format, @args)>, B<Note>,
+B<setlogmask($mask_priority)>, B<setlogsock($sock_type)>,
+B<setlogsock($sock_type, $stream_location)> (added in Perl 5.004_02),
+B<Note>, B<closelog()>
+
+=item THE RULES OF SYS::SYSLOG
+
+=item EXAMPLES
+
+=item CONSTANTS
+
+=over 4
+
+=item Facilities
+
+=item Levels
+
+=back
+
+=item DIAGNOSTICS
+
+C<Invalid argument passed to setlogsock>, C<eventlog passed to setlogsock,
+but no Win32 API available>, C<no connection to syslog available>, C<stream
+passed to setlogsock, but %s is not writable>, C<stream passed to
+setlogsock, but could not find any device>, C<tcp passed to setlogsock, but
+tcp service unavailable>, C<syslog: expecting argument %s>, C<syslog:
+invalid level/facility: %s>, C<syslog: too many levels given: %s>,
+C<syslog: too many facilities given: %s>, C<syslog: level must be given>,
+C<udp passed to setlogsock, but udp service unavailable>, C<unix passed to
+setlogsock, but path not available>
+
+=item SEE ALSO
+
+=over 4
+
+=item Manual Pages
+
+=item RFCs
+
+=item Articles
+
+=item Event Log
+
+=back
+
+=item AUTHORS & ACKNOWLEDGEMENTS
+
+=item BUGS
+
+=item SUPPORT
+
+AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request
+tracker, Search CPAN, Kobes' CPAN Search, Perl Documentation
+
+=item COPYRIGHT
+
+=item LICENSE
+
+=back
+
+=head2 Syslog::Syslog, Sys::Syslog - Perl interface to the UNIX syslog(3)
+calls
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXPORTS
+
+=item FUNCTIONS
+
+B<openlog($ident, $logopt, $facility)>, B<syslog($priority, $message)>,
+B<syslog($priority, $format, @args)>, B<Note>,
+B<setlogmask($mask_priority)>, B<setlogsock($sock_type)>,
+B<setlogsock($sock_type, $stream_location)> (added in Perl 5.004_02),
+B<Note>, B<closelog()>
+
+=item THE RULES OF SYS::SYSLOG
+
+=item EXAMPLES
+
+=item CONSTANTS
+
+=over 4
+
+=item Facilities
+
+=item Levels
+
+=back
+
+=item DIAGNOSTICS
+
+C<Invalid argument passed to setlogsock>, C<eventlog passed to setlogsock,
+but no Win32 API available>, C<no connection to syslog available>, C<stream
+passed to setlogsock, but %s is not writable>, C<stream passed to
+setlogsock, but could not find any device>, C<tcp passed to setlogsock, but
+tcp service unavailable>, C<syslog: expecting argument %s>, C<syslog:
+invalid level/facility: %s>, C<syslog: too many levels given: %s>,
+C<syslog: too many facilities given: %s>, C<syslog: level must be given>,
+C<udp passed to setlogsock, but udp service unavailable>, C<unix passed to
+setlogsock, but path not available>
+
+=item SEE ALSO
+
+=over 4
+
+=item Manual Pages
+
+=item RFCs
+
+=item Articles
+
+=item Event Log
+
+=back
+
+=item AUTHORS & ACKNOWLEDGEMENTS
+
+=item BUGS
+
+=item SUPPORT
+
+AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request
+tracker, Search CPAN, Kobes' CPAN Search, Perl Documentation
+
+=item COPYRIGHT
+
+=item LICENSE
+
+=back
+
+=head2 Syslog::win32::Win32, Sys::Syslog::Win32 - Win32 support for
+Sys::Syslog
+
+=over 4
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item LICENSE
+
+=back
+
+=head2 Term::ANSIColor - Color screen output using ANSI escape sequences
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item DIAGNOSTICS
+
+Bad escape sequence %s, Bareword "%s" not allowed while "strict subs" in
+use, Invalid attribute name %s, Name "%s" used only once: possible typo, No
+comma allowed after filehandle, No name for escape sequence %s
+
+=item ENVIRONMENT
+
+ANSI_COLORS_DISABLED
+
+=item RESTRICTIONS
+
+=item NOTES
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Term::Cap - Perl termcap interface
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item METHODS
+
+=back
+
+=back
+
+B<Tgetent>, OSPEED, TERM
+
+B<Tpad>, B<$string>, B<$cnt>, B<$FH>
+
+B<Tputs>, B<$cap>, B<$cnt>, B<$FH>
+
+B<Tgoto>, B<$cap>, B<$col>, B<$row>, B<$FH>
+
+B<Trequire>
+
+=over 4
+
+=item EXAMPLES
+
+=item COPYRIGHT AND LICENSE
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Term::Complete - Perl word completion module
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+E<lt>tabE<gt>, ^D, ^U, E<lt>delE<gt>, E<lt>bsE<gt>
+
+=item DIAGNOSTICS
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 Term::ReadLine - Perl interface to various C<readline> packages.
+If no real package is found, substitutes stubs instead of basic functions.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Minimal set of supported functions
+
+C<ReadLine>, C<new>, C<readline>, C<addhistory>, C<IN>, C<OUT>, C<MinLine>,
+C<findConsole>, Attribs, C<Features>
+
+=item Additional supported functions
+
+C<tkRunning>, C<ornaments>, C<newTTY>
+
+=item EXPORTS
+
+=item ENVIRONMENT
+
+=item CAVEATS
+
+=back
+
+=head2 Term::UI - Term::ReadLine UI made easy
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item HOW IT WORKS
+
+=item METHODS
+
+=over 4
+
+=item $reply = $term->get_reply( prompt => 'question?', [choices => \@list,
+default => $list[0], multi => BOOL, print_me => "extra text to print &
+record", allow => $ref] );
+
+=back
+
+=back
+
+=over 4
+
+=item $bool = $term->ask_yn( prompt => "your question", [default =>
+(y|1,n|0), print_me => "extra text to print & record"] )
+
+=back
+
+=over 4
+
+=item ($opts, $munged) = $term->parse_options( STRING );
+
+=back
+
+=over 4
+
+=item $str = $term->history_as_string
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+=over 4
+
+=item $Term::UI::VERBOSE
+
+=item $Term::UI::AUTOREPLY
+
+=item $Term::UI::INVALID
+
+=item $Term::UI::History::HISTORY_FH
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item Basic get_reply sample
+
+=item get_reply with choices
+
+=item get_reply with choices and default
+
+=item get_reply using print_me & multi
+
+=item get_reply & allow
+
+=item an elaborate ask_yn sample
+
+=back
+
+=item See Also
+
+=item BUG REPORTS
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Term::UI::History
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item history("message string" [,VERBOSE])
+
+=back
+
+=back
+
+=over 4
+
+=item GLOBAL VARIABLES
+
+$HISTORY_FH
+
+=item See Also
+
+=item AUTHOR
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test - provides a simple framework for writing test scripts
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item QUICK START GUIDE
+
+=over 4
+
+=item Functions
+
+C<plan(...)>, C<tests =E<gt> I<number>>, C<todo =E<gt> [I<1,5,14>]>,
+C<onfail =E<gt> sub { ... }>, C<onfail =E<gt> \&some_sub>
+
+=back
+
+=back
+
+B<_to_value>
+
+C<ok(...)>
+
+C<skip(I<skip_if_true>, I<args...>)>
+
+=over 4
+
+=item TEST TYPES
+
+NORMAL TESTS, SKIPPED TESTS, TODO TESTS
+
+=item ONFAIL
+
+=item BUGS and CAVEATS
+
+=item ENVIRONMENT
+
+=item NOTE
+
+=item SEE ALSO
+
+=item AUTHOR
+
+=back
+
+=head2 Test::Builder - Backend for building test libraries
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Construction
+
+B<new>
+
+=back
+
+=back
+
+B<create>
+
+B<reset>
+
+=over 4
+
+=item Setting up tests
+
+B<exported_to>
+
+=back
+
+B<plan>
+
+B<expected_tests>
+
+B<no_plan>
+
+B<has_plan>
+
+B<skip_all>
+
+=over 4
+
+=item Running tests
+
+B<ok>
+
+=back
+
+B<is_eq>, B<is_num>
+
+B<isnt_eq>, B<isnt_num>
+
+B<like>, B<unlike>
+
+B<cmp_ok>
+
+=over 4
+
+=item Other Testing Methods
+
+B<BAIL_OUT>
+
+=back
+
+B<skip>
+
+B<todo_skip>
+
+B<skip_rest>
+
+=over 4
+
+=item Test building utility methods
+
+B<maybe_regex>
+
+=back
+
+B<_try>
+
+B<is_fh>
+
+=over 4
+
+=item Test style
+
+B<level>
+
+=back
+
+B<use_numbers>
+
+B<no_diag>, B<no_ending>, B<no_header>
+
+=over 4
+
+=item Output
+
+B<diag>
+
+=back
+
+B<_print>
+
+B<_print_diag>
+
+B<output>, B<failure_output>, B<todo_output>
+
+carp, croak
+
+=over 4
+
+=item Test Status and Info
+
+B<current_test>
+
+=back
+
+B<summary>
+
+B<details>
+
+B<todo>
+
+B<caller>
+
+B<_sanity_check>
+
+B<_whoa>
+
+B<_my_exit>
+
+=over 4
+
+=item EXIT CODES
+
+=item THREADS
+
+=item EXAMPLES
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test::Builder::Module - Base class for test modules
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Importing
+
+=back
+
+=back
+
+=over 4
+
+=item Builder
+
+=back
+
+=head2 Test::Builder::Tester - test testsuites that have been built with
+Test::Builder
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item Functions
+
+test_out, test_err
+
+=back
+
+test_fail
+
+test_diag
+
+test_test, title (synonym 'name', 'label'), skip_out, skip_err
+
+line_num
+
+color
+
+=over 4
+
+=item BUGS
+
+=item AUTHOR
+
+=item NOTES
+
+=item SEE ALSO
+
+=back
+
+=head2 Test::Builder::Tester::Color - turn on colour in
+Test::Builder::Tester
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item BUGS
+
+=item SEE ALSO
+
+=back
+
+=head2 Test::Harness - Run Perl standard test scripts with statistics
+
+=over 4
+
+=item VERSION
+
+=back
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Taint mode
+
+=item Configuration variables.
+
+C<$Test::Harness::Verbose>, C<$Test::Harness::switches>,
+C<$Test::Harness::Timer>
+
+=item Failure
+
+B<Failed Test>, B<Stat>, B<Wstat>, B<Total>, B<Fail>, B<List of Failed>
+
+=back
+
+=item FUNCTIONS
+
+=over 4
+
+=item runtests( @test_files )
+
+=back
+
+=back
+
+=over 4
+
+=item execute_tests( tests => \@test_files, out => \*FH )
+
+=back
+
+=over 4
+
+=item EXPORT
+
+=item DIAGNOSTICS
+
+C<All tests successful.\nFiles=%d, Tests=%d, %s>, C<FAILED tests
+%s\n\tFailed %d/%d tests, %.2f%% okay.>, C<Test returned status %d (wstat
+%d)>, C<Failed 1 test, %.2f%% okay. %s>, C<Failed %d/%d tests, %.2f%% okay.
+%s>, C<FAILED--Further testing stopped: %s>
+
+=item ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS
+
+C<HARNESS_ACTIVE>, C<HARNESS_VERSION>
+
+=item ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS
+
+C<HARNESS_COLUMNS>, C<HARNESS_COMPILE_TEST>, C<HARNESS_DEBUG>,
+C<HARNESS_FILELEAK_IN_DIR>, C<HARNESS_NOTTY>, C<HARNESS_PERL>,
+C<HARNESS_PERL_SWITCHES>, C<HARNESS_TIMER>, C<HARNESS_VERBOSE>,
+C<HARNESS_STRAP_CLASS>
+
+=item EXAMPLE
+
+=item SEE ALSO
+
+=item TODO
+
+=item BUGS
+
+=item SUPPORT
+
+AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request
+tracker, Search CPAN
+
+=item SOURCE CODE
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test::Harness::Assert - simple assert
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item C<assert()>
+
+=back
+
+=back
+
+=over 4
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Test::Harness::Iterator - Internal Test::Harness Iterator
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item new()
+
+=item next()
+
+=back
+
+=back
+
+=head2 Test::Harness::Point - object for tracking a single test point
+
+=over 4
+
+=item SYNOPSIS
+
+=item CONSTRUCTION
+
+=over 4
+
+=item new()
+
+=back
+
+=back
+
+=over 4
+
+=item from_test_line( $line )
+
+=back
+
+=over 4
+
+=item ACCESSORS
+
+ok, number
+
+=back
+
+=head2 Test::Harness::Results - object for tracking results from a single
+test file
+
+=over 4
+
+=item SYNOPSIS
+
+=item CONSTRUCTION
+
+=over 4
+
+=item new()
+
+=back
+
+=back
+
+=over 4
+
+=item ACCESSORS
+
+wait, exit
+
+=back
+
+=head2 Test::Harness::Straps - detailed analysis of test results
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CONSTRUCTION
+
+=over 4
+
+=item new()
+
+=back
+
+=back
+
+=over 4
+
+=item ANALYSIS
+
+=over 4
+
+=item $strap->analyze( $name, \@output_lines )
+
+=back
+
+=back
+
+=over 4
+
+=item $strap->analyze_file( $test_file )
+
+=back
+
+=over 4
+
+=item Parsing
+
+=back
+
+=over 4
+
+=item EXAMPLES
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Test::Harness::TAP - Documentation for the TAP format
+
+=over 4
+
+=item SYNOPSIS
+
+=item TODO
+
+=item THE TAP FORMAT
+
+=item HARNESS BEHAVIOR
+
+=item TESTS LINES AND THE PLAN
+
+=over 4
+
+=item The plan
+
+=item The test line
+
+C<ok> or C<not ok>, Test number, Description, Directive, ok/not ok
+(required), Test number (recommended), Description (recommended), Directive
+(only when necessary)
+
+=back
+
+=item DIRECTIVES
+
+=over 4
+
+=item TODO tests
+
+=item Skipping tests
+
+=back
+
+=item OTHER LINES
+
+=over 4
+
+=item Bail out!
+
+=item Diagnostics
+
+=item Anything else
+
+=back
+
+=item EXAMPLES
+
+=over 4
+
+=item Common with explanation
+
+=item Unknown amount and failures
+
+=item Giving up
+
+=item Skipping a few
+
+=item Skipping everything
+
+=item Got spare tuits?
+
+=item Creative liberties
+
+=back
+
+=item Non-Perl TAP
+
+=over 4
+
+=item C/C++
+
+Specify a test plan, Run tests, Skip tests in certain situations, Have TODO
+tests, Produce TAP compatible diagnostics
+
+=item Python
+
+=item JavaScript
+
+=item PHP
+
+phpt, PHPUnit, SimpleTest, Apache-Test
+
+=back
+
+=item AUTHORS
+
+=item ACKNOWLEDGEMENTS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test::Harness::Util - Utility functions for Test::Harness::*
+
+=over 4
+
+=item SYNOPSIS
+
+=item PUBLIC FUNCTIONS
+
+=over 4
+
+=item all_in( {parm => value, parm => value} )
+
+start, recurse
+
+=back
+
+=back
+
+=over 4
+
+=item shuffle( @list )
+
+=back
+
+=over 4
+
+=item blibdir()
+
+=back
+
+=head2 Test::More - yet another framework for writing test scripts
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item I love it when a plan comes together
+
+=back
+
+=back
+
+=over 4
+
+=item Test names
+
+=item I'm ok, you're not ok.
+
+B<ok>
+
+=back
+
+B<is>, B<isnt>
+
+B<like>
+
+B<unlike>
+
+B<cmp_ok>
+
+B<can_ok>
+
+B<isa_ok>
+
+B<pass>, B<fail>
+
+=over 4
+
+=item Module tests
+
+B<use_ok>
+
+=back
+
+B<require_ok>
+
+=over 4
+
+=item Complex data structures
+
+B<is_deeply>
+
+=back
+
+=over 4
+
+=item Diagnostics
+
+B<diag>
+
+=back
+
+=over 4
+
+=item Conditional tests
+
+B<SKIP: BLOCK>
+
+=back
+
+B<TODO: BLOCK>, B<todo_skip>
+
+When do I use SKIP vs. TODO?
+
+=over 4
+
+=item Test control
+
+B<BAIL_OUT>
+
+=back
+
+=over 4
+
+=item Discouraged comparison functions
+
+B<eq_array>
+
+=back
+
+B<eq_hash>
+
+B<eq_set>
+
+=over 4
+
+=item Extending and Embedding Test::More
+
+B<builder>
+
+=back
+
+=over 4
+
+=item EXIT CODES
+
+=item CAVEATS and NOTES
+
+Backwards compatibility, Overloaded objects, Threads, Test::Harness upgrade
+
+=item HISTORY
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item BUGS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test::Simple - Basic utilities for writing tests.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+B<ok>
+
+=back
+
+=over 4
+
+=item EXAMPLE
+
+=item CAVEATS
+
+=item NOTES
+
+=item HISTORY
+
+=item SEE ALSO
+
+L<Test::More>, L<Test>, L<Test::Unit>, L<Test::Inline>, L<SelfTest>,
+L<Test::Harness>
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Test::Tutorial - A tutorial about writing really basic tests
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Nuts and bolts of testing.
+
+=item Where to start?
+
+=item Names
+
+=item Test the manual
+
+=item Sometimes the tests are wrong
+
+=item Testing lots of values
+
+=item Informative names
+
+=item Skipping tests
+
+=item Todo tests
+
+=item Testing with taint mode.
+
+=back
+
+=item FOOTNOTES
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Text::Abbrev, abbrev - create an abbreviation table from a list
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLE
+
+=back
+
+=head2 Text::Balanced - Extract delimited text sequences from strings.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item General behaviour in list contexts
+
+[0], [1], [2]
+
+=item General behaviour in scalar and void contexts
+
+=item A note about prefixes
+
+=item C<extract_delimited>
+
+=item C<extract_bracketed>
+
+=item C<extract_variable>
+
+[0], [1], [2]
+
+=item C<extract_tagged>
+
+C<reject =E<gt> $listref>, C<ignore =E<gt> $listref>, C<fail =E<gt> $str>,
+[0], [1], [2], [3], [4], [5]
+
+=item C<gen_extract_tagged>
+
+=item C<extract_quotelike>
+
+[0], [1], [2], [3], [4], [5], [6], [7], [8], [9], [10]
+
+=item C<extract_quotelike> and "here documents"
+
+[0], [1], [2], [3], [4], [5], [6], [7..10]
+
+=item C<extract_codeblock>
+
+=item C<extract_multiple>
+
+=item C<gen_delimited_pat>
+
+=item C<delimited_pat>
+
+=back
+
+=item DIAGNOSTICS
+
+ C<Did not find a suitable bracket: "%s">, C<Did not find prefix: /%s/>,
+C<Did not find opening bracket after prefix: "%s">, C<No quotelike
+operator found after prefix: "%s">, C<Unmatched closing bracket: "%c">,
+C<Unmatched opening bracket(s): "%s">, C<Unmatched embedded quote (%s)>,
+C<Did not find closing delimiter to match '%s'>, C<Mismatched closing
+bracket: expected "%c" but found "%s">, C<No block delimiter found after
+quotelike "%s">, C<Did not find leading dereferencer>, C<Bad identifier
+after dereferencer>, C<Did not find expected opening bracket at %s>,
+C<Improperly nested codeblock at %s>, C<Missing second block for quotelike
+"%s">, C<No match found for opening bracket>, C<Did not find opening tag:
+/%s/>, C<Unable to construct closing tag to match: /%s/>, C<Found invalid
+nested tag: %s>, C<Found unbalanced nested tag: %s>, C<Did not find closing
+tag>
+
+=item AUTHOR
+
+=item BUGS AND IRRITATIONS
+
+=item COPYRIGHT
+
+=back
+
+=head2 Text::ParseWords - parse text into an array of tokens or array of
+arrays
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item AUTHORS
+
+=back
+
+=head2 Text::Soundex - Implementation of the soundex algorithm.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLES
+
+=item LIMITATIONS
+
+=item MAINTAINER
+
+=item HISTORY
+
+=back
+
+=head2 Text::Tabs -- expand and unexpand tabs per the unix expand(1) and
+unexpand(1)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLE
+
+=item LICENSE
+
+=back
+
+=head2 Text::Wrap - line wrapping to form simple paragraphs
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item OVERRIDES
+
+=item EXAMPLES
+
+=item LICENSE
+
+=back
+
+=head2 Thread - Manipulate threads in Perl (for old code only)
+
+=over 4
+
+=item DEPRECATED
+
+=item HISTORY
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+$thread = Thread->new(\&start_sub), $thread = Thread->new(\&start_sub,
+LIST), lock VARIABLE, async BLOCK;, Thread->self, Thread->list, cond_wait
+VARIABLE, cond_signal VARIABLE, cond_broadcast VARIABLE, yield
+
+=item METHODS
+
+join, detach, equal, tid, done
+
+=item DEFUNCT
+
+lock(\&sub), eval, flags
+
+=item SEE ALSO
+
+=back
+
+=head2 Thread::Queue - thread-safe queues
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS AND METHODS
+
+new, enqueue LIST, dequeue, dequeue_nb, pending
+
+=item SEE ALSO
+
+=back
+
+=head2 Thread::Semaphore - thread-safe semaphores
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS AND METHODS
+
+new, new NUMBER, down, down NUMBER, up, up NUMBER
+
+=back
+
+=head2 Tie::Array - base class for tied arrays
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+TIEARRAY classname, LIST, STORE this, index, value, FETCH this, index,
+FETCHSIZE this, STORESIZE this, count, EXTEND this, count, EXISTS this,
+key, DELETE this, key, CLEAR this, DESTROY this, PUSH this, LIST, POP this,
+SHIFT this, UNSHIFT this, LIST, SPLICE this, offset, length, LIST
+
+=item CAVEATS
+
+=item AUTHOR
+
+=back
+
+=head2 Tie::File - Access the lines of a disk file via a Perl array
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item C<recsep>
+
+=item C<autochomp>
+
+=item C<mode>
+
+=item C<memory>
+
+=item C<dw_size>
+
+=item Option Format
+
+=back
+
+=item Public Methods
+
+=over 4
+
+=item C<flock>
+
+=item C<autochomp>
+
+=item C<defer>, C<flush>, C<discard>, and C<autodefer>
+
+=item C<offset>
+
+=back
+
+=item Tying to an already-opened filehandle
+
+=item Deferred Writing
+
+=over 4
+
+=item Autodeferring
+
+=back
+
+=item CONCURRENT ACCESS TO FILES
+
+=item CAVEATS
+
+=item SUBCLASSING
+
+=item WHAT ABOUT C<DB_File>?
+
+=item AUTHOR
+
+=item LICENSE
+
+=item WARRANTY
+
+=item THANKS
+
+=item TODO
+
+=back
+
+=head2 Tie::Handle - base class definitions for tied handles
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+TIEHANDLE classname, LIST, WRITE this, scalar, length, offset, PRINT this,
+LIST, PRINTF this, format, LIST, READ this, scalar, length, offset,
+READLINE this, GETC this, CLOSE this, OPEN this, filename, BINMODE this,
+EOF this, TELL this, SEEK this, offset, whence, DESTROY this
+
+=item MORE INFORMATION
+
+=item COMPATIBILITY
+
+=back
+
+=head2 Tie::Hash, Tie::StdHash, Tie::ExtraHash - base class definitions for
+tied hashes
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+TIEHASH classname, LIST, STORE this, key, value, FETCH this, key, FIRSTKEY
+this, NEXTKEY this, lastkey, EXISTS this, key, DELETE this, key, CLEAR
+this, SCALAR this
+
+=item Inheriting from B<Tie::StdHash>
+
+=item Inheriting from B<Tie::ExtraHash>
+
+=item C<SCALAR>, C<UNTIE> and C<DESTROY>
+
+=item MORE INFORMATION
+
+=back
+
+=head2 Tie::Hash::NamedCapture - Named regexp capture buffers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item SEE ALSO
+
+=back
+
+=head2 Tie::Memoize - add data to hash when needed
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item Inheriting from B<Tie::Memoize>
+
+=item EXAMPLE
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 Tie::RefHash - use references as hash keys
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item EXAMPLE
+
+=item THREAD SUPPORT
+
+=item STORABLE SUPPORT
+
+=item RELIC SUPPORT
+
+=item MAINTAINER
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Tie::Scalar, Tie::StdScalar - base class definitions for tied
+scalars
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this
+
+=item MORE INFORMATION
+
+=back
+
+=head2 Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item CAVEATS
+
+=back
+
+=head2 Time::HiRes - High resolution alarm, sleep, gettimeofday, interval
+timers
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+gettimeofday (), usleep ( $useconds ), nanosleep ( $nanoseconds ), ualarm (
+$useconds [, $interval_useconds ] ), tv_interval, time (), sleep (
+$floating_seconds ), alarm ( $floating_seconds [,
+$interval_floating_seconds ] ), setitimer ( $which, $floating_seconds [,
+$interval_floating_seconds ] ), getitimer ( $which ), clock_gettime (
+$which ), clock_getres ( $which ), clock_nanosleep ( $which, $nanoseconds,
+$flags = 0), clock(), stat, stat FH, stat EXPR
+
+=item EXAMPLES
+
+=item C API
+
+=item DIAGNOSTICS
+
+=over 4
+
+=item useconds or interval more than ...
+
+=item negative time not invented yet
+
+=item internal error: useconds < 0 (unsigned ... signed ...)
+
+=back
+
+=item CAVEATS
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT AND LICENSE
+
+=back
+
+=head2 Time::Local - efficiently compute time from local and GMT time
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item FUNCTIONS
+
+=over 4
+
+=item C<timelocal()> and C<timegm()>
+
+=item C<timelocal_nocheck()> and C<timegm_nocheck()>
+
+=item Year Value Interpretation
+
+=item Limits of time_t
+
+=item Ambiguous Local Times (DST)
+
+=item Non-Existent Local Times (DST)
+
+=item Negative Epoch Values
+
+=back
+
+=item IMPLEMENTATION
+
+=item BUGS
+
+=item SUPPORT
+
+=item COPYRIGHT
+
+=item AUTHOR
+
+=back
+
+=head2 Time::Piece - Object Oriented time objects
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item USAGE
+
+=over 4
+
+=item Local Locales
+
+=item Date Calculations
+
+=item Date Comparisons
+
+=item Date Parsing
+
+=item YYYY-MM-DDThh:mm:ss
+
+=item Week Number
+
+=item Global Overriding
+
+=back
+
+=item AUTHOR
+
+=item License
+
+=item SEE ALSO
+
+=item BUGS
+
+=back
+
+=head2 Time::Piece::Seconds, Time::Seconds - a simple API to convert
+seconds to other date values
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=item AUTHOR
+
+=item LICENSE
+
+=item Bugs
+
+=back
+
+=head2 Time::Seconds - a simple API to convert seconds to other date values
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item METHODS
+
+=item AUTHOR
+
+=item LICENSE
+
+=item Bugs
+
+=back
+
+=head2 Time::gmtime - by-name interface to Perl's built-in gmtime()
+function
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Time::localtime - by-name interface to Perl's built-in localtime()
+function
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 Time::tm - internal object used by Time::gmtime and Time::localtime
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item AUTHOR
+
+=back
+
+=head2 UNIVERSAL - base class for ALL classes (blessed references)
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+C<< $obj->isa( TYPE ) >>, C<< CLASS->isa( TYPE ) >>, C<< eval { VAL->isa(
+TYPE ) } >>, C<TYPE>, C<$obj>, C<CLASS>, C<VAL>, C<< $obj->DOES( ROLE ) >>,
+C<< CLASS->DOES( ROLE ) >>, C<< $obj->can( METHOD ) >>, C<< CLASS->can(
+METHOD ) >>, C<< eval { VAL->can( METHOD ) } >>, C<VERSION ( [ REQUIRE ] )>
+
+=item EXPORTS
+
+=back
+
+=head2 Unicode::Collate - Unicode Collation Algorithm
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Constructor and Tailoring
+
+UCA_Version, alternate, backwards, entry, hangul_terminator, ignoreChar,
+ignoreName, katakana_before_hiragana, level, normalization, overrideCJK,
+overrideHangul, preprocess, rearrange, table, undefChar, undefName,
+upper_before_lower, variable
+
+=item Methods for Collation
+
+C<@sorted = $Collator-E<gt>sort(@not_sorted)>, C<$result =
+$Collator-E<gt>cmp($a, $b)>, C<$result = $Collator-E<gt>eq($a, $b)>,
+C<$result = $Collator-E<gt>ne($a, $b)>, C<$result = $Collator-E<gt>lt($a,
+$b)>, C<$result = $Collator-E<gt>le($a, $b)>, C<$result =
+$Collator-E<gt>gt($a, $b)>, C<$result = $Collator-E<gt>ge($a, $b)>,
+C<$sortKey = $Collator-E<gt>getSortKey($string)>, C<$sortKeyForm =
+$Collator-E<gt>viewSortKey($string)>
+
+=item Methods for Searching
+
+C<$position = $Collator-E<gt>index($string, $substring[, $position])>,
+C<($position, $length) = $Collator-E<gt>index($string, $substring[,
+$position])>, C<$match_ref = $Collator-E<gt>match($string, $substring)>,
+C<($match) = $Collator-E<gt>match($string, $substring)>, C<@match =
+$Collator-E<gt>gmatch($string, $substring)>, C<$count =
+$Collator-E<gt>subst($string, $substring, $replacement)>, C<$count =
+$Collator-E<gt>gsubst($string, $substring, $replacement)>
+
+=item Other Methods
+
+C<%old_tailoring = $Collator-E<gt>change(%new_tailoring)>, C<$version =
+$Collator-E<gt>version()>, C<UCA_Version()>, C<Base_Unicode_Version()>
+
+=back
+
+=item EXPORT
+
+=item INSTALL
+
+=item CAVEATS
+
+Normalization, Conformance Test
+
+=item AUTHOR, COPYRIGHT AND LICENSE
+
+=item SEE ALSO
+
+Unicode Collation Algorithm - UTS #10, The Default Unicode Collation
+Element Table (DUCET), The conformance test for the UCA, Hangul Syllable
+Type, Unicode Normalization Forms - UAX #15
+
+=back
+
+=head2 Unicode::Normalize - Unicode Normalization Forms
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Normalization Forms
+
+C<$NFD_string = NFD($string)>, C<$NFC_string = NFC($string)>,
+C<$NFKD_string = NFKD($string)>, C<$NFKC_string = NFKC($string)>,
+C<$FCD_string = FCD($string)>, C<$FCC_string = FCC($string)>,
+C<$normalized_string = normalize($form_name, $string)>
+
+=item Decomposition and Composition
+
+C<$decomposed_string = decompose($string [, $useCompatMapping])>,
+C<$reordered_string = reorder($string)>, C<$composed_string =
+compose($string)>
+
+=item Quick Check
+
+C<$result = checkNFD($string)>, C<$result = checkNFC($string)>, C<$result =
+checkNFKD($string)>, C<$result = checkNFKC($string)>, C<$result =
+checkFCD($string)>, C<$result = checkFCC($string)>, C<$result =
+check($form_name, $string)>
+
+=item Character Data
+
+C<$canonical_decomposition = getCanon($code_point)>,
+C<$compatibility_decomposition = getCompat($code_point)>,
+C<$code_point_composite = getComposite($code_point_here,
+$code_point_next)>, C<$combining_class = getCombinClass($code_point)>,
+C<$may_be_composed_with_prev_char = isComp2nd($code_point)>,
+C<$is_exclusion = isExclusion($code_point)>, C<$is_singleton =
+isSingleton($code_point)>, C<$is_non_starter_decomposition =
+isNonStDecomp($code_point)>, C<$is_Full_Composition_Exclusion =
+isComp_Ex($code_point)>, C<$NFD_is_NO = isNFD_NO($code_point)>,
+C<$NFC_is_NO = isNFC_NO($code_point)>, C<$NFC_is_MAYBE =
+isNFC_MAYBE($code_point)>, C<$NFKD_is_NO = isNFKD_NO($code_point)>,
+C<$NFKC_is_NO = isNFKC_NO($code_point)>, C<$NFKC_is_MAYBE =
+isNFKC_MAYBE($code_point)>
+
+=back
+
+=item EXPORT
+
+=item CAVEATS
+
+Perl's version vs. Unicode version, Correction of decomposition mapping,
+Revised definition of canonical composition
+
+=item AUTHOR
+
+=item SEE ALSO
+
+http://www.unicode.org/reports/tr15/,
+http://www.unicode.org/Public/UNIDATA/CompositionExclusions.txt,
+http://www.unicode.org/Public/UNIDATA/DerivedNormalizationProps.txt,
+http://www.unicode.org/Public/UNIDATA/NormalizationCorrections.txt,
+http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/
+
+=back
+
+=head2 Unicode::UCD - Unicode character database
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=back
+
+=over 4
+
+=item charinfo
+
+=back
+
+=over 4
+
+=item charblock
+
+=back
+
+=over 4
+
+=item charscript
+
+=back
+
+=over 4
+
+=item charblocks
+
+=back
+
+=over 4
+
+=item charscripts
+
+=back
+
+=over 4
+
+=item Blocks versus Scripts
+
+=item Matching Scripts and Blocks
+
+=item Code Point Arguments
+
+=item charinrange
+
+=back
+
+=over 4
+
+=item general_categories
+
+=back
+
+=over 4
+
+=item bidi_types
+
+=back
+
+=over 4
+
+=item compexcl
+
+=back
+
+=over 4
+
+=item casefold
+
+=back
+
+=over 4
+
+=item casespec
+
+=back
+
+=over 4
+
+=item namedseq()
+
+=back
+
+=over 4
+
+=item Unicode::UCD::UnicodeVersion
+
+=back
+
+=over 4
+
+=item Implementation Note
+
+=back
+
+=over 4
+
+=item BUGS
+
+=item AUTHOR
+
+=back
+
+=head2 User::grent - by-name interface to Perl's built-in getgr*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=item NOTE
+
+=item AUTHOR
+
+=back
+
+=head2 User::pwent - by-name interface to Perl's built-in getpw*()
+functions
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item System Specifics
+
+=back
+
+=item NOTE
+
+=item AUTHOR
+
+=item HISTORY
+
+March 18th, 2000
+
+=back
+
+=head2 Win32 - Interfaces to some Win32 API Functions
+
+=over 4
+
+=item DESCRIPTION
+
+=over 4
+
+=item Alphabetical Listing of Win32 Functions
+
+Win32::AbortSystemShutdown(MACHINE), Win32::BuildNumber(),
+Win32::CopyFile(FROM, TO, OVERWRITE), Win32::CreateDirectory(DIRECTORY),
+Win32::CreateFile(FILE), Win32::DomainName(),
+Win32::ExpandEnvironmentStrings(STRING), Win32::FormatMessage(ERRORCODE),
+Win32::FsType(), Win32::FreeLibrary(HANDLE),
+Win32::GetANSIPathName(FILENAME), Win32::GetArchName(),
+Win32::GetChipName(), Win32::GetCwd(), Win32::GetCurrentThreadId(),
+Win32::GetFileVersion(FILENAME), Win32::GetFolderPath(FOLDER [, CREATE]),
+Win32::GetFullPathName(FILENAME), Win32::GetLastError(),
+Win32::GetLongPathName(PATHNAME), Win32::GetNextAvailDrive(),
+Win32::GetOSVersion(), Win32::GetOSName(),
+Win32::GetShortPathName(PATHNAME), Win32::GetProcAddress(INSTANCE,
+PROCNAME), Win32::GetTickCount(), Win32::GuidGen(), Win32::IsAdminUser(),
+Win32::IsWinNT(), Win32::IsWin95(), Win32::LoadLibrary(LIBNAME),
+Win32::LoginName(), Win32::LookupAccountName(SYSTEM, ACCOUNT, DOMAIN, SID,
+SIDTYPE), Win32::LookupAccountSID(SYSTEM, SID, ACCOUNT, DOMAIN, SIDTYPE),
+Win32::MsgBox(MESSAGE [, FLAGS [, TITLE]]), Win32::NodeName(),
+Win32::OutputDebugString(STRING), Win32::RegisterServer(LIBRARYNAME),
+Win32::SetChildShowWindow(SHOWWINDOW), Win32::SetCwd(NEWDIRECTORY),
+Win32::SetLastError(ERROR), Win32::Sleep(TIME), Win32::Spawn(COMMAND, ARGS,
+PID), Win32::UnregisterServer(LIBRARYNAME)
+
+=back
+
+=back
+
+=head2 Win32API::File - Low-level access to Win32 system API calls for
+files/dirs.
+
+=over 4
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Object Oriented/Tied Handle Interface
+
+=item Exports
+
+C<":Func">, attrLetsToBits, C<$uBits= attrLetsToBits( $sAttributeLetters
+)>, C<"a">, C<"c">, C<"h">, C<"o">, C<"r">, C<"s">, C<"t">, createFile,
+C<$hObject= createFile( $sPath )>, C<$hObject= createFile( $sPath,
+$rvhvOptions )>, C<$hObject= createFile( $sPath, $svAccess )>, C<$hObject=
+createFile( $sPath, $svAccess, $rvhvOptions )>, C<$hObject= createFile(
+$sPath, $svAccess, $svShare )>, C<$hObject= createFile( $sPath, $svAccess,
+$svShare, $rvhvOptions )>, C<"q">, C<"r">, C<"w">, C<"k">, C<"t">, C<"n">,
+C<"c">, C<"e">, C<"kc">, C<"ke">, C<"tc">, C<"te">, C<"nc">, C<"ne">, Flags
+=> $uFlags, Attributes => $sAttributes, Security => $pSecurityAttributes,
+Model => $hModelFile, Access => $sAccess, Access => $uAccess, Create =>
+$sCreate, Create => $uCreate, Share => $sShare, Share => $uShare,
+getLogicalDrives, C<@roots= getLogicalDrives()>, CloseHandle,
+C<CloseHandle( $hObject )>, CopyFile, C<CopyFile( $sOldFileName,
+$sNewFileName, $bFailIfExists )>, CreateFile, C<$hObject= CreateFile(
+$sPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>,
+C<"//./PhysicalDrive0">, C<"//./C:">, C<"//./A:">, C<"//./PIPE/PipeName">,
+DefineDosDevice, C<DefineDosDevice( $uFlags, $sDosDeviceName, $sTargetPath
+)>, C<DDD_RAW_TARGET_PATH>, C<DDD_REMOVE_DEFINITION>,
+C<DDD_EXACT_MATCH_ON_REMOVE>, DeleteFile, C<DeleteFile( $sFileName )>,
+DeviceIoControl, C<DeviceIoControl( $hDevice, $uIoControlCode, $pInBuf,
+$lInBuf, $opOutBuf, $lOutBuf, $olRetBytes, $pOverlapped )>, FdGetOsFHandle,
+C<$hNativeHandle= FdGetOsFHandle( $ivFd )>, fileConstant, C<$value=
+fileConstant( $sConstantName )>, fileLastError, C<$svError=
+fileLastError();>, C<fileLastError( $uError );>, GetDriveType,
+C<$uDriveType= GetDriveType( $sRootPath )>, C<DRIVE_UNKNOWN>,
+C<DRIVE_NO_ROOT_DIR>, C<DRIVE_REMOVABLE>, C<DRIVE_FIXED>, C<DRIVE_REMOTE>,
+C<DRIVE_CDROM>, C<DRIVE_RAMDISK>, GetFileAttributes, C<$uAttrs =
+GetFileAttributes( $sPath )>, C<FILE_ATTRIBUTE_ARCHIVE>,
+C<FILE_ATTRIBUTE_COMPRESSED>, C<FILE_ATTRIBUTE_DEVICE>,
+C<FILE_ATTRIBUTE_DIRECTORY>, C<FILE_ATTRIBUTE_ENCRYPTED>,
+C<FILE_ATTRIBUTE_HIDDEN>, C<FILE_ATTRIBUTE_NORMAL>,
+C<FILE_ATTRIBUTE_NOT_CONTENT_INDEXED>, C<FILE_ATTRIBUTE_OFFLINE>,
+C<FILE_ATTRIBUTE_READONLY>, C<FILE_ATTRIBUTE_REPARSE_POINT>,
+C<FILE_ATTRIBUTE_SPARSE_FILE>, C<FILE_ATTRIBUTE_SYSTEM>,
+C<FILE_ATTRIBUTE_TEMPORARY>, GetFileType, C<$uFileType= GetFileType( $hFile
+)>, C<FILE_TYPE_UNKNOWN>, C<FILE_TYPE_DISK>, C<FILE_TYPE_CHAR>,
+C<FILE_TYPE_PIPE>, getFileSize, C<$size= getFileSize( $hFile )>,
+GetFileSize, C<$iSizeLow= GetFileSize($win32Handle, $iSizeHigh)>,
+GetOverlappedResult, C<$bRetval= GetOverlappedResult( $win32Handle,
+$pOverlapped, $numBytesTransferred, $bWait )>, GetLogicalDrives,
+C<$uDriveBits= GetLogicalDrives()>, GetLogicalDriveStrings, C<$olOutLength=
+GetLogicalDriveStrings( $lBufSize, $osBuffer )>, GetHandleInformation,
+C<GetHandleInformation( $hObject, $ouFlags )>, GetOsFHandle,
+C<$hNativeHandle= GetOsFHandle( FILE )>, GetVolumeInformation,
+C<GetVolumeInformation( $sRootPath, $osVolName, $lVolName, $ouSerialNum,
+$ouMaxNameLen, $ouFsFlags, $osFsType, $lFsType )>, C<FS_CASE_IS_PRESERVED>,
+C<FS_CASE_SENSITIVE>, C<FS_UNICODE_STORED_ON_DISK>, C<FS_PERSISTENT_ACLS>,
+C<FS_FILE_COMPRESSION>, C<FS_VOL_IS_COMPRESSED>, IsRecognizedPartition,
+C<IsRecognizedPartition( $ivPartitionType )>, IsContainerPartition,
+C<IsContainerPartition( $ivPartitionType )>, MoveFile, C<MoveFile(
+$sOldName, $sNewName )>, MoveFileEx, C<MoveFileEx( $sOldName, $sNewName,
+$uFlags )>, C<MOVEFILE_REPLACE_EXISTING>, C<MOVEFILE_COPY_ALLOWED>,
+C<MOVEFILE_DELAY_UNTIL_REBOOT>, C<MOVEFILE_WRITE_THROUGH>, OsFHandleOpen,
+C<OsFHandleOpen( FILE, $hNativeHandle, $sMode )>, OsFHandleOpenFd, C<$ivFD=
+OsFHandleOpenFd( $hNativeHandle, $uMode )>, QueryDosDevice, C<$olTargetLen=
+QueryDosDevice( $sDosDeviceName, $osTargetPath, $lTargetBuf )>, ReadFile,
+C<ReadFile( $hFile, $opBuffer, $lBytes, $olBytesRead, $pOverlapped )>,
+SetErrorMode, C<$uOldMode= SetErrorMode( $uNewMode )>,
+C<SEM_FAILCRITICALERRORS>, C<SEM_NOALIGNMENTFAULTEXCEPT>,
+C<SEM_NOGPFAULTERRORBOX>, C<SEM_NOOPENFILEERRORBOX>, setFilePointer,
+C<$uNewPos = setFilePointer( $hFile, $ivOffset, $uFromWhere )>,
+SetFilePointer, C<$uNewPos = SetFilePointer( $hFile, $ivOffset,
+$ioivOffsetHigh, $uFromWhere )>, SetHandleInformation,
+C<SetHandleInformation( $hObject, $uMask, $uFlags )>, WriteFile,
+C<WriteFile( $hFile, $pBuffer, $lBytes, $ouBytesWritten, $pOverlapped )>,
+C<":FuncA">, C<":FuncW">, CopyFileW, C<CopyFileW( $swOldFileName,
+$swNewFileName, $bFailIfExists )>, CreateFileW, C<$hObject= CreateFileW(
+$swPath, $uAccess, $uShare, $pSecAttr, $uCreate, $uFlags, $hModel )>,
+DefineDosDeviceW, C<DefineDosDeviceW( $uFlags, $swDosDeviceName,
+$swTargetPath )>, DeleteFileW, C<DeleteFileW( $swFileName )>,
+GetDriveTypeW, C<$uDriveType= GetDriveTypeW( $swRootPath )>,
+GetFileAttributesW, C<$uAttrs= GetFileAttributesW( $swPath )>,
+GetLogicalDriveStringsW, C<$olwOutLength= GetLogicalDriveStringsW(
+$lwBufSize, $oswBuffer )>, GetVolumeInformationW, C<GetVolumeInformationW(
+$swRootPath, $oswVolName, $lwVolName, $ouSerialNum, $ouMaxNameLen,
+$ouFsFlags, $oswFsType, $lwFsType )>, MoveFileW, C<MoveFileW( $swOldName,
+$swNewName )>, MoveFileExW, C<MoveFileExW( $swOldName, $swNewName, $uFlags
+)>, QueryDosDeviceW, C<$olwTargetLen= QueryDosDeviceW( $swDeviceName,
+$oswTargetPath, $lwTargetBuf )>, C<":Misc">, C<":DDD_">, C<":DRIVE_">,
+C<":FILE_">, C<":FILE_ATTRIBUTE_">, C<":FILE_FLAG_">, C<":FILE_SHARE_">,
+C<":FILE_TYPE_">, C<":FS_">, C<":HANDLE_FLAG_">, HANDLE_FLAG_INHERIT,
+HANDLE_FLAG_PROTECT_FROM_CLOSE, C<":IOCTL_STORAGE_">,
+C<IOCTL_STORAGE_CHECK_VERIFY>, C<IOCTL_STORAGE_MEDIA_REMOVAL>,
+C<IOCTL_STORAGE_EJECT_MEDIA>, C<IOCTL_STORAGE_LOAD_MEDIA>,
+C<IOCTL_STORAGE_RESERVE>, C<IOCTL_STORAGE_RELEASE>,
+C<IOCTL_STORAGE_FIND_NEW_DEVICES>, C<IOCTL_STORAGE_GET_MEDIA_TYPES>,
+C<$ucCylsLow[$i]>, C<$ivcCylsHigh[$i]>, C<$uMediaType[$i]>,
+C<$uTracksPerCyl[$i]>, C<$uSectsPerTrack[$i]>, C<$uBytesPerSect[$i]>,
+C<":IOCTL_DISK_">, C<IOCTL_DISK_GET_DRIVE_GEOMETRY>, C<$ucCylsLow>,
+C<$ivcCylsHigh>, C<$uMediaType>, C<$uTracksPerCyl>, C<$uSectsPerTrack>,
+C<$uBytesPerSect>, C<IOCTL_DISK_GET_PARTITION_INFO>, C<$uStartLow> and
+C<$ivStartHigh>, C<$ucHiddenSects>, C<$uPartitionSeqNumber>,
+C<$uPartitionType>, C<$bActive>, C<$bRecognized>, C<$bToRewrite>,
+C<IOCTL_DISK_SET_PARTITION_INFO>, C<IOCTL_DISK_GET_DRIVE_LAYOUT>,
+C<$cPartitions>, C<$uDiskSignature>, C<IOCTL_DISK_GET_MEDIA_TYPES>,
+C<IOCTL_DISK_SET_DRIVE_LAYOUT>, C<IOCTL_DISK_VERIFY>, C<$uStartOffsetLow>
+and C<$ivStartOffsetHigh>, C<$uLength>, C<IOCTL_DISK_FORMAT_TRACKS>,
+C<IOCTL_DISK_REASSIGN_BLOCKS>, C<IOCTL_DISK_PERFORMANCE>,
+C<IOCTL_DISK_IS_WRITABLE>, C<IOCTL_DISK_LOGGING>, DISK_LOGGING_START,
+DISK_LOGGING_STOP, DISK_LOGGING_DUMP, DISK_LOGGING_BINNING,
+C<IOCTL_DISK_FORMAT_TRACKS_EX>, C<IOCTL_DISK_HISTOGRAM_STRUCTURE>,
+C<IOCTL_DISK_HISTOGRAM_DATA>, C<IOCTL_DISK_HISTOGRAM_RESET>,
+C<IOCTL_DISK_REQUEST_STRUCTURE>, C<IOCTL_DISK_REQUEST_DATA>, C<":FSCTL_">,
+C<FSCTL_SET_REPARSE_POINT>, C<FSCTL_GET_REPARSE_POINT>,
+C<FSCTL_DELETE_REPARSE_POINT>, C<":GENERIC_">, C<":MEDIA_TYPE">,
+C<Unknown>, C<F5_1Pt2_512>, C<F3_1Pt44_512>, C<F3_2Pt88_512>,
+C<F3_20Pt8_512>, C<F3_720_512>, C<F5_360_512>, C<F5_320_512>,
+C<F5_320_1024>, C<F5_180_512>, C<F5_160_512>, C<RemovableMedia>,
+C<FixedMedia>, C<F3_120M_512>, C<":MOVEFILE_">, C<":SECURITY_">,
+C<":SEM_">, C<":PARTITION_">, C<":ALL">
+
+=back
+
+=item BUGS
+
+=item AUTHOR
+
+=item SEE ALSO
+
+=back
+
+=head2 Win32CORE - Win32 CORE function stubs
+
+=over 4
+
+=item DESCRIPTION
+
+=item HISTORY
+
+=back
+
+=head2 XSLoader - Dynamically load C libraries into Perl code
+
+=over 4
+
+=item VERSION
+
+=item SYNOPSIS
+
+=item DESCRIPTION
+
+=over 4
+
+=item Migration from C<DynaLoader>
+
+=item Backward compatible boilerplate
+
+=back
+
+=item Order of initialization: early load()
+
+=over 4
+
+=item The most hairy case
+
+=back
+
+=item DIAGNOSTICS
+
+C<Can't find '%s' symbol in %s>, C<Can't load '%s' for module %s: %s>,
+C<Undefined symbols present after loading %s: %s>,
+C<XSLoader::load('Your::Module', $Your::Module::VERSION)>
+
+=item LIMITATIONS
+
+=item BUGS
+
+=item SEE ALSO
+
+=item AUTHORS
+
+=item COPYRIGHT
+
+=back
+
+=head1 AUXILIARY DOCUMENTATION
+
+Here should be listed all the extra programs' documentation, but they
+don't all have manual pages yet:
+
+=over 4
+
+=item a2p
+
+=item c2ph
+
+=item dprofpp
+
+=item h2ph
+
+=item h2xs
+
+=item perlbug
+
+=item perldoc
+
+=item pl2pm
+
+=item pod2html
+
+=item pod2man
+
+=item s2p
+
+=item splain
+
+=item xsubpp
+
+=back
+
+=head1 AUTHOR
+
+Larry Wall <F<larry at wall.org>>, with the help of oodles
+of other folks.
+
Modified: trunk/contrib/perl/pod/perltodo.pod
===================================================================
--- trunk/contrib/perl/pod/perltodo.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perltodo.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -4,1277 +4,7 @@
=head1 DESCRIPTION
-This is a list of wishes for Perl. The most up to date version of this file
-is at L<http://perl5.git.perl.org/perl.git/blob_plain/HEAD:/pod/perltodo.pod>
-
-The tasks we think are smaller or easier are listed first. Anyone is welcome
-to work on any of these, but it's a good idea to first contact
-I<perl5-porters at perl.org> to avoid duplication of effort, and to learn from
-any previous attempts. By all means contact a pumpking privately first if you
-prefer.
-
-Whilst patches to make the list shorter are most welcome, ideas to add to
-the list are also encouraged. Check the perl5-porters archives for past
-ideas, and any discussion about them. One set of archives may be found at
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/>
-
-What can we offer you in return? Fame, fortune, and everlasting glory? Maybe
-not, but if your patch is incorporated, then we'll add your name to the
-F<AUTHORS> file, which ships in the official distribution. How many other
-programming languages offer you 1 line of immortality?
-
-=head1 Tasks that only need Perl knowledge
-
-=head2 Migrate t/ from custom TAP generation
-
-Many tests below F<t/> still generate TAP by "hand", rather than using library
-functions. As explained in L<perlhack/TESTING>, tests in F<t/> are
-written in a particular way to test that more complex constructions actually
-work before using them routinely. Hence they don't use C<Test::More>, but
-instead there is an intentionally simpler library, F<t/test.pl>. However,
-quite a few tests in F<t/> have not been refactored to use it. Refactoring
-any of these tests, one at a time, is a useful thing TODO.
-
-The subdirectories F<base>, F<cmd> and F<comp>, that contain the most
-basic tests, should be excluded from this task.
-
-=head2 Automate perldelta generation
-
-The perldelta file accompanying each release summaries the major changes.
-It's mostly manually generated currently, but some of that could be
-automated with a bit of perl, specifically the generation of
-
-=over
-
-=item Modules and Pragmata
-
-=item New Documentation
-
-=item New Tests
-
-=back
-
-See F<Porting/how_to_write_a_perldelta.pod> for details.
-
-=head2 Remove duplication of test setup.
-
-Schwern notes, that there's duplication of code - lots and lots of tests have
-some variation on the big block of C<$Is_Foo> checks. We can safely put this
-into a file, change it to build an C<%Is> hash and require it. Maybe just put
-it into F<test.pl>. Throw in the handy tainting subroutines.
-
-=head2 POD -E<gt> HTML conversion in the core still sucks
-
-Which is crazy given just how simple POD purports to be, and how simple HTML
-can be. It's not actually I<as> simple as it sounds, particularly with the
-flexibility POD allows for C<=item>, but it would be good to improve the
-visual appeal of the HTML generated, and to avoid it having any validation
-errors. See also L</make HTML install work>, as the layout of installation tree
-is needed to improve the cross-linking.
-
-The addition of C<Pod::Simple> and its related modules may make this task
-easier to complete.
-
-=head2 Make ExtUtils::ParseXS use strict;
-
-F<lib/ExtUtils/ParseXS.pm> contains this line
-
- # use strict; # One of these days...
-
-Simply uncomment it, and fix all the resulting issues :-)
-
-The more practical approach, to break the task down into manageable chunks, is
-to work your way though the code from bottom to top, or if necessary adding
-extra C<{ ... }> blocks, and turning on strict within them.
-
-=head2 Make Schwern poorer
-
-We should have tests for everything. When all the core's modules are tested,
-Schwern has promised to donate to $500 to TPF. We may need volunteers to
-hold him upside down and shake vigorously in order to actually extract the
-cash.
-
-=head2 Improve the coverage of the core tests
-
-Use Devel::Cover to ascertain the core modules' test coverage, then add
-tests that are currently missing.
-
-=head2 test B
-
-A full test suite for the B module would be nice.
-
-=head2 A decent benchmark
-
-C<perlbench> seems impervious to any recent changes made to the perl core. It
-would be useful to have a reasonable general benchmarking suite that roughly
-represented what current perl programs do, and measurably reported whether
-tweaks to the core improve, degrade or don't really affect performance, to
-guide people attempting to optimise the guts of perl. Gisle would welcome
-new tests for perlbench.
-
-=head2 fix tainting bugs
-
-Fix the bugs revealed by running the test suite with the C<-t> switch (via
-C<make test.taintwarn>).
-
-=head2 Dual life everything
-
-As part of the "dists" plan, anything that doesn't belong in the smallest perl
-distribution needs to be dual lifed. Anything else can be too. Figure out what
-changes would be needed to package that module and its tests up for CPAN, and
-do so. Test it with older perl releases, and fix the problems you find.
-
-To make a minimal perl distribution, it's useful to look at
-F<t/lib/commonsense.t>.
-
-=head2 POSIX memory footprint
-
-Ilya observed that use POSIX; eats memory like there's no tomorrow, and at
-various times worked to cut it down. There is probably still fat to cut out -
-for example POSIX passes Exporter some very memory hungry data structures.
-
-=head2 embed.pl/makedef.pl
-
-There is a script F<embed.pl> that generates several header files to prefix
-all of Perl's symbols in a consistent way, to provide some semblance of
-namespace support in C<C>. Functions are declared in F<embed.fnc>, variables
-in F<interpvar.h>. Quite a few of the functions and variables
-are conditionally declared there, using C<#ifdef>. However, F<embed.pl>
-doesn't understand the C macros, so the rules about which symbols are present
-when is duplicated in F<makedef.pl>. Writing things twice is bad, m'kay.
-It would be good to teach C<embed.pl> to understand the conditional
-compilation, and hence remove the duplication, and the mistakes it has caused.
-
-=head2 use strict; and AutoLoad
-
-Currently if you write
-
- package Whack;
- use AutoLoader 'AUTOLOAD';
- use strict;
- 1;
- __END__
- sub bloop {
- print join (' ', No, strict, here), "!\n";
- }
-
-then C<use strict;> isn't in force within the autoloaded subroutines. It would
-be more consistent (and less surprising) to arrange for all lexical pragmas
-in force at the __END__ block to be in force within each autoloaded subroutine.
-
-There's a similar problem with SelfLoader.
-
-=head2 profile installman
-
-The F<installman> script is slow. All it is doing text processing, which we're
-told is something Perl is good at. So it would be nice to know what it is doing
-that is taking so much CPU, and where possible address it.
-
-=head2 enable lexical enabling/disabling of individual warnings
-
-Currently, warnings can only be enabled or disabled by category. There
-are times when it would be useful to quash a single warning, not a
-whole category.
-
-=head1 Tasks that need a little sysadmin-type knowledge
-
-Or if you prefer, tasks that you would learn from, and broaden your skills
-base...
-
-=head2 make HTML install work
-
-There is an C<installhtml> target in the Makefile. It's marked as
-"experimental". It would be good to get this tested, make it work reliably, and
-remove the "experimental" tag. This would include
-
-=over 4
-
-=item 1
-
-Checking that cross linking between various parts of the documentation works.
-In particular that links work between the modules (files with POD in F<lib/>)
-and the core documentation (files in F<pod/>)
-
-=item 2
-
-Work out how to split C<perlfunc> into chunks, preferably one per function
-group, preferably with general case code that could be used elsewhere.
-Challenges here are correctly identifying the groups of functions that go
-together, and making the right named external cross-links point to the right
-page. Things to be aware of are C<-X>, groups such as C<getpwnam> to
-C<endservent>, two or more C<=items> giving the different parameter lists, such
-as
-
- =item substr EXPR,OFFSET,LENGTH,REPLACEMENT
- =item substr EXPR,OFFSET,LENGTH
- =item substr EXPR,OFFSET
-
-and different parameter lists having different meanings. (eg C<select>)
-
-=back
-
-=head2 compressed man pages
-
-Be able to install them. This would probably need a configure test to see how
-the system does compressed man pages (same directory/different directory?
-same filename/different filename), as well as tweaking the F<installman> script
-to compress as necessary.
-
-=head2 Add a code coverage target to the Makefile
-
-Make it easy for anyone to run Devel::Cover on the core's tests. The steps
-to do this manually are roughly
-
-=over 4
-
-=item *
-
-do a normal C<Configure>, but include Devel::Cover as a module to install
-(see L<INSTALL> for how to do this)
-
-=item *
-
- make perl
-
-=item *
-
- cd t; HARNESS_PERL_SWITCHES=-MDevel::Cover ./perl -I../lib harness
-
-=item *
-
-Process the resulting Devel::Cover database
-
-=back
-
-This just give you the coverage of the F<.pm>s. To also get the C level
-coverage you need to
-
-=over 4
-
-=item *
-
-Additionally tell C<Configure> to use the appropriate C compiler flags for
-C<gcov>
-
-=item *
-
- make perl.gcov
-
-(instead of C<make perl>)
-
-=item *
-
-After running the tests run C<gcov> to generate all the F<.gcov> files.
-(Including down in the subdirectories of F<ext/>
-
-=item *
-
-(From the top level perl directory) run C<gcov2perl> on all the C<.gcov> files
-to get their stats into the cover_db directory.
-
-=item *
-
-Then process the Devel::Cover database
-
-=back
-
-It would be good to add a single switch to C<Configure> to specify that you
-wanted to perform perl level coverage, and another to specify C level
-coverage, and have C<Configure> and the F<Makefile> do all the right things
-automatically.
-
-=head2 Make Config.pm cope with differences between built and installed perl
-
-Quite often vendors ship a perl binary compiled with their (pay-for)
-compilers. People install a free compiler, such as gcc. To work out how to
-build extensions, Perl interrogates C<%Config>, so in this situation
-C<%Config> describes compilers that aren't there, and extension building
-fails. This forces people into choosing between re-compiling perl themselves
-using the compiler they have, or only using modules that the vendor ships.
-
-It would be good to find a way teach C<Config.pm> about the installation setup,
-possibly involving probing at install time or later, so that the C<%Config> in
-a binary distribution better describes the installed machine, when the
-installed machine differs from the build machine in some significant way.
-
-=head2 linker specification files
-
-Some platforms mandate that you provide a list of a shared library's external
-symbols to the linker, so the core already has the infrastructure in place to
-do this for generating shared perl libraries. My understanding is that the
-GNU toolchain can accept an optional linker specification file, and restrict
-visibility just to symbols declared in that file. It would be good to extend
-F<makedef.pl> to support this format, and to provide a means within
-C<Configure> to enable it. This would allow Unix users to test that the
-export list is correct, and to build a perl that does not pollute the global
-namespace with private symbols, and will fail in the same way as msvc or mingw
-builds or when using PERL_DL_NONLAZY=1.
-
-=head2 Cross-compile support
-
-Currently C<Configure> understands C<-Dusecrosscompile> option. This option
-arranges for building C<miniperl> for TARGET machine, so this C<miniperl> is
-assumed then to be copied to TARGET machine and used as a replacement of full
-C<perl> executable.
-
-This could be done little differently. Namely C<miniperl> should be built for
-HOST and then full C<perl> with extensions should be compiled for TARGET.
-This, however, might require extra trickery for %Config: we have one config
-first for HOST and then another for TARGET. Tools like MakeMaker will be
-mightily confused. Having around two different types of executables and
-libraries (HOST and TARGET) makes life interesting for Makefiles and
-shell (and Perl) scripts. There is $Config{run}, normally empty, which
-can be used as an execution wrapper. Also note that in some
-cross-compilation/execution environments the HOST and the TARGET do
-not see the same filesystem(s), the $Config{run} may need to do some
-file/directory copying back and forth.
-
-=head2 roffitall
-
-Make F<pod/roffitall> be updated by F<pod/buildtoc>.
-
-=head2 Split "linker" from "compiler"
-
-Right now, Configure probes for two commands, and sets two variables:
-
-=over 4
-
-=item * C<cc> (in F<cc.U>)
-
-This variable holds the name of a command to execute a C compiler which
-can resolve multiple global references that happen to have the same
-name. Usual values are F<cc> and F<gcc>.
-Fervent ANSI compilers may be called F<c89>. AIX has F<xlc>.
-
-=item * C<ld> (in F<dlsrc.U>)
-
-This variable indicates the program to be used to link
-libraries for dynamic loading. On some systems, it is F<ld>.
-On ELF systems, it should be C<$cc>. Mostly, we'll try to respect
-the hint file setting.
-
-=back
-
-There is an implicit historical assumption from around Perl5.000alpha
-something, that C<$cc> is also the correct command for linking object files
-together to make an executable. This may be true on Unix, but it's not true
-on other platforms, and there are a maze of work arounds in other places (such
-as F<Makefile.SH>) to cope with this.
-
-Ideally, we should create a new variable to hold the name of the executable
-linker program, probe for it in F<Configure>, and centralise all the special
-case logic there or in hints files.
-
-A small bikeshed issue remains - what to call it, given that C<$ld> is already
-taken (arguably for the wrong thing now, but on SunOS 4.1 it is the command
-for creating dynamically-loadable modules) and C<$link> could be confused with
-the Unix command line executable of the same name, which does something
-completely different. Andy Dougherty makes the counter argument "In parrot, I
-tried to call the command used to link object files and libraries into an
-executable F<link>, since that's what my vaguely-remembered DOS and VMS
-experience suggested. I don't think any real confusion has ensued, so it's
-probably a reasonable name for perl5 to use."
-
-"Alas, I've always worried that introducing it would make things worse,
-since now the module building utilities would have to look for
-C<$Config{link}> and institute a fall-back plan if it weren't found."
-Although I can see that as confusing, given that C<$Config{d_link}> is true
-when (hard) links are available.
-
-=head2 Configure Windows using PowerShell
-
-Currently, Windows uses hard-coded config files based to build the
-config.h for compiling Perl. Makefiles are also hard-coded and need to be
-hand edited prior to building Perl. While this makes it easy to create a perl.exe
-that works across multiple Windows versions, being able to accurately
-configure a perl.exe for a specific Windows versions and VS C++ would be
-a nice enhancement. With PowerShell available on Windows XP and up, this
-may now be possible. Step 1 might be to investigate whether this is possible
-and use this to clean up our current makefile situation. Step 2 would be to
-see if there would be a way to use our existing metaconfig units to configure a
-Windows Perl or whether we go in a separate direction and make it so. Of
-course, we all know what step 3 is.
-
-=head2 decouple -g and -DDEBUGGING
-
-Currently F<Configure> automatically adds C<-DDEBUGGING> to the C compiler
-flags if it spots C<-g> in the optimiser flags. The pre-processor directive
-C<DEBUGGING> enables F<perl>'s command line C<-D> options, but in the process
-makes F<perl> slower. It would be good to disentangle this logic, so that
-C-level debugging with C<-g> and Perl level debugging with C<-D> can easily
-be enabled independently.
-
-=head1 Tasks that need a little C knowledge
-
-These tasks would need a little C knowledge, but don't need any specific
-background or experience with XS, or how the Perl interpreter works
-
-=head2 Weed out needless PERL_UNUSED_ARG
-
-The C code uses the macro C<PERL_UNUSED_ARG> to stop compilers warning about
-unused arguments. Often the arguments can't be removed, as there is an
-external constraint that determines the prototype of the function, so this
-approach is valid. However, there are some cases where C<PERL_UNUSED_ARG>
-could be removed. Specifically
-
-=over 4
-
-=item *
-
-The prototypes of (nearly all) static functions can be changed
-
-=item *
-
-Unused arguments generated by short cut macros are wasteful - the short cut
-macro used can be changed.
-
-=back
-
-=head2 Modernize the order of directories in @INC
-
-The way @INC is laid out by default, one cannot upgrade core (dual-life)
-modules without overwriting files. This causes problems for binary
-package builders. One possible proposal is laid out in this
-message:
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2002-04/msg02380.html>
-
-=head2 -Duse32bit*
-
-Natively 64-bit systems need neither -Duse64bitint nor -Duse64bitall.
-On these systems, it might be the default compilation mode, and there
-is currently no guarantee that passing no use64bitall option to the
-Configure process will build a 32bit perl. Implementing -Duse32bit*
-options would be nice for perl 5.14.
-
-=head2 Profile Perl - am I hot or not?
-
-The Perl source code is stable enough that it makes sense to profile it,
-identify and optimise the hotspots. It would be good to measure the
-performance of the Perl interpreter using free tools such as cachegrind,
-gprof, and dtrace, and work to reduce the bottlenecks they reveal.
-
-As part of this, the idea of F<pp_hot.c> is that it contains the I<hot> ops,
-the ops that are most commonly used. The idea is that by grouping them, their
-object code will be adjacent in the executable, so they have a greater chance
-of already being in the CPU cache (or swapped in) due to being near another op
-already in use.
-
-Except that it's not clear if these really are the most commonly used ops. So
-as part of exercising your skills with coverage and profiling tools you might
-want to determine what ops I<really> are the most commonly used. And in turn
-suggest evictions and promotions to achieve a better F<pp_hot.c>.
-
-One piece of Perl code that might make a good testbed is F<installman>.
-
-=head2 Allocate OPs from arenas
-
-Currently all new OP structures are individually malloc()ed and free()d.
-All C<malloc> implementations have space overheads, and are now as fast as
-custom allocates so it would both use less memory and less CPU to allocate
-the various OP structures from arenas. The SV arena code can probably be
-re-used for this.
-
-Note that Configuring perl with C<-Accflags=-DPL_OP_SLAB_ALLOC> will use
-Perl_Slab_alloc() to pack optrees into a contiguous block, which is
-probably superior to the use of OP arenas, esp. from a cache locality
-standpoint. See L<Profile Perl - am I hot or not?>.
-
-=head2 Improve win32/wince.c
-
-Currently, numerous functions look virtually, if not completely,
-identical in both C<win32/wince.c> and C<win32/win32.c> files, which can't
-be good.
-
-=head2 Use secure CRT functions when building with VC8 on Win32
-
-Visual C++ 2005 (VC++ 8.x) deprecated a number of CRT functions on the basis
-that they were "unsafe" and introduced differently named secure versions of
-them as replacements, e.g. instead of writing
-
- FILE* f = fopen(__FILE__, "r");
-
-one should now write
-
- FILE* f;
- errno_t err = fopen_s(&f, __FILE__, "r");
-
-Currently, the warnings about these deprecations have been disabled by adding
--D_CRT_SECURE_NO_DEPRECATE to the CFLAGS. It would be nice to remove that
-warning suppressant and actually make use of the new secure CRT functions.
-
-There is also a similar issue with POSIX CRT function names like fileno having
-been deprecated in favour of ISO C++ conformant names like _fileno. These
-warnings are also currently suppressed by adding -D_CRT_NONSTDC_NO_DEPRECATE. It
-might be nice to do as Microsoft suggest here too, although, unlike the secure
-functions issue, there is presumably little or no benefit in this case.
-
-=head2 Fix POSIX::access() and chdir() on Win32
-
-These functions currently take no account of DACLs and therefore do not behave
-correctly in situations where access is restricted by DACLs (as opposed to the
-read-only attribute).
-
-Furthermore, POSIX::access() behaves differently for directories having the
-read-only attribute set depending on what CRT library is being used. For
-example, the _access() function in the VC6 and VC7 CRTs (wrongly) claim that
-such directories are not writable, whereas in fact all directories are writable
-unless access is denied by DACLs. (In the case of directories, the read-only
-attribute actually only means that the directory cannot be deleted.) This CRT
-bug is fixed in the VC8 and VC9 CRTs (but, of course, the directory may still
-not actually be writable if access is indeed denied by DACLs).
-
-For the chdir() issue, see ActiveState bug #74552:
-L<http://bugs.activestate.com/show_bug.cgi?id=74552>
-
-Therefore, DACLs should be checked both for consistency across CRTs and for
-the correct answer.
-
-(Note that perl's -w operator should not be modified to check DACLs. It has
-been written so that it reflects the state of the read-only attribute, even
-for directories (whatever CRT is being used), for symmetry with chmod().)
-
-=head2 strcat(), strcpy(), strncat(), strncpy(), sprintf(), vsprintf()
-
-Maybe create a utility that checks after each libperl.a creation that
-none of the above (nor sprintf(), vsprintf(), or *SHUDDER* gets())
-ever creep back to libperl.a.
-
- nm libperl.a | ./miniperl -alne '$o = $F[0] if /:$/; print "$o $F[1]" if $F[0] eq "U" && $F[1] =~ /^(?:strn?c(?:at|py)|v?sprintf|gets)$/'
-
-Note, of course, that this will only tell whether B<your> platform
-is using those naughty interfaces.
-
-=head2 -D_FORTIFY_SOURCE=2, -fstack-protector
-
-Recent glibcs support C<-D_FORTIFY_SOURCE=2> and recent gcc
-(4.1 onwards?) supports C<-fstack-protector>, both of which give
-protection against various kinds of buffer overflow problems.
-These should probably be used for compiling Perl whenever available,
-Configure and/or hints files should be adjusted to probe for the
-availability of these features and enable them as appropriate.
-
-=head2 Arenas for GPs? For MAGIC?
-
-C<struct gp> and C<struct magic> are both currently allocated by C<malloc>.
-It might be a speed or memory saving to change to using arenas. Or it might
-not. It would need some suitable benchmarking first. In particular, C<GP>s
-can probably be changed with minimal compatibility impact (probably nothing
-outside of the core, or even outside of F<gv.c> allocates them), but they
-probably aren't allocated/deallocated often enough for a speed saving. Whereas
-C<MAGIC> is allocated/deallocated more often, but in turn, is also something
-more externally visible, so changing the rules here may bite external code.
-
-=head2 Shared arenas
-
-Several SV body structs are now the same size, notably PVMG and PVGV, PVAV and
-PVHV, and PVCV and PVFM. It should be possible to allocate and return same
-sized bodies from the same actual arena, rather than maintaining one arena for
-each. This could save 4-6K per thread, of memory no longer tied up in the
-not-yet-allocated part of an arena.
-
-
-=head1 Tasks that need a knowledge of XS
-
-These tasks would need C knowledge, and roughly the level of knowledge of
-the perl API that comes from writing modules that use XS to interface to
-C.
-
-=head2 Write an XS cookbook
-
-Create pod/perlxscookbook.pod with short, task-focused 'recipes' in XS that
-demonstrate common tasks and good practices. (Some of these might be
-extracted from perlguts.) The target audience should be XS novices, who need
-more examples than perlguts but something less overwhelming than perlapi.
-Recipes should provide "one pretty good way to do it" instead of TIMTOWTDI.
-
-Rather than focusing on interfacing Perl to C libraries, such a cookbook
-should probably focus on how to optimize Perl routines by re-writing them
-in XS. This will likely be more motivating to those who mostly work in
-Perl but are looking to take the next step into XS.
-
-Deconstructing and explaining some simpler XS modules could be one way to
-bootstrap a cookbook. (List::Util? Class::XSAccessor? Tree::Ternary_XS?)
-Another option could be deconstructing the implementation of some simpler
-functions in op.c.
-
-=head2 Allow XSUBs to inline themselves as OPs
-
-For a simple XSUB, often the subroutine dispatch takes more time than the
-XSUB itself. The tokeniser already has the ability to inline constant
-subroutines - it would be good to provide a way to inline other subroutines.
-
-Specifically, simplest approach looks to be to allow an XSUB to provide an
-alternative implementation of itself as a custom OP. A new flag bit in
-C<CvFLAGS()> would signal to the peephole optimiser to take an optree
-such as this:
-
- b <@> leave[1 ref] vKP/REFC ->(end)
- 1 <0> enter ->2
- 2 <;> nextstate(main 1 -e:1) v:{ ->3
- a <2> sassign vKS/2 ->b
- 8 <1> entersub[t2] sKS/TARG,1 ->9
- - <1> ex-list sK ->8
- 3 <0> pushmark s ->4
- 4 <$> const(IV 1) sM ->5
- 6 <1> rv2av[t1] lKM/1 ->7
- 5 <$> gv(*a) s ->6
- - <1> ex-rv2cv sK ->-
- 7 <$> gv(*x) s/EARLYCV ->8
- - <1> ex-rv2sv sKRM*/1 ->a
- 9 <$> gvsv(*b) s ->a
-
-perform the symbol table lookup of C<rv2cv> and C<gv(*x)>, locate the
-pointer to the custom OP that provides the direct implementation, and re-
-write the optree something like:
-
- b <@> leave[1 ref] vKP/REFC ->(end)
- 1 <0> enter ->2
- 2 <;> nextstate(main 1 -e:1) v:{ ->3
- a <2> sassign vKS/2 ->b
- 7 <1> custom_x -> 8
- - <1> ex-list sK ->7
- 3 <0> pushmark s ->4
- 4 <$> const(IV 1) sM ->5
- 6 <1> rv2av[t1] lKM/1 ->7
- 5 <$> gv(*a) s ->6
- - <1> ex-rv2cv sK ->-
- - <$> ex-gv(*x) s/EARLYCV ->7
- - <1> ex-rv2sv sKRM*/1 ->a
- 8 <$> gvsv(*b) s ->a
-
-I<i.e.> the C<gv(*)> OP has been nulled and spliced out of the execution
-path, and the C<entersub> OP has been replaced by the custom op.
-
-This approach should provide a measurable speed up to simple XSUBs inside
-tight loops. Initially one would have to write the OP alternative
-implementation by hand, but it's likely that this should be reasonably
-straightforward for the type of XSUB that would benefit the most. Longer
-term, once the run-time implementation is proven, it should be possible to
-progressively update ExtUtils::ParseXS to generate OP implementations for
-some XSUBs.
-
-=head2 Remove the use of SVs as temporaries in dump.c
-
-F<dump.c> contains debugging routines to dump out the contains of perl data
-structures, such as C<SV>s, C<AV>s and C<HV>s. Currently, the dumping code
-B<uses> C<SV>s for its temporary buffers, which was a logical initial
-implementation choice, as they provide ready made memory handling.
-
-However, they also lead to a lot of confusion when it happens that what you're
-trying to debug is seen by the code in F<dump.c>, correctly or incorrectly, as
-a temporary scalar it can use for a temporary buffer. It's also not possible
-to dump scalars before the interpreter is properly set up, such as during
-ithreads cloning. It would be good to progressively replace the use of scalars
-as string accumulation buffers with something much simpler, directly allocated
-by C<malloc>. The F<dump.c> code is (or should be) only producing 7 bit
-US-ASCII, so output character sets are not an issue.
-
-Producing and proving an internal simple buffer allocation would make it easier
-to re-write the internals of the PerlIO subsystem to avoid using C<SV>s for
-B<its> buffers, use of which can cause problems similar to those of F<dump.c>,
-at similar times.
-
-=head2 safely supporting POSIX SA_SIGINFO
-
-Some years ago Jarkko supplied patches to provide support for the POSIX
-SA_SIGINFO feature in Perl, passing the extra data to the Perl signal handler.
-
-Unfortunately, it only works with "unsafe" signals, because under safe
-signals, by the time Perl gets to run the signal handler, the extra
-information has been lost. Moreover, it's not easy to store it somewhere,
-as you can't call mutexs, or do anything else fancy, from inside a signal
-handler.
-
-So it strikes me that we could provide safe SA_SIGINFO support
-
-=over 4
-
-=item 1
-
-Provide global variables for two file descriptors
-
-=item 2
-
-When the first request is made via C<sigaction> for C<SA_SIGINFO>, create a
-pipe, store the reader in one, the writer in the other
-
-=item 3
-
-In the "safe" signal handler (C<Perl_csighandler()>/C<S_raise_signal()>), if
-the C<siginfo_t> pointer non-C<NULL>, and the writer file handle is open,
-
-=over 8
-
-=item 1
-
-serialise signal number, C<struct siginfo_t> (or at least the parts we care
-about) into a small auto char buff
-
-=item 2
-
-C<write()> that (non-blocking) to the writer fd
-
-=over 12
-
-=item 1
-
-if it writes 100%, flag the signal in a counter of "signals on the pipe" akin
-to the current per-signal-number counts
-
-=item 2
-
-if it writes 0%, assume the pipe is full. Flag the data as lost?
-
-=item 3
-
-if it writes partially, croak a panic, as your OS is broken.
-
-=back
-
-=back
-
-=item 4
-
-in the regular C<PERL_ASYNC_CHECK()> processing, if there are "signals on
-the pipe", read the data out, deserialise, build the Perl structures on
-the stack (code in C<Perl_sighandler()>, the "unsafe" handler), and call as
-usual.
-
-=back
-
-I think that this gets us decent C<SA_SIGINFO> support, without the current risk
-of running Perl code inside the signal handler context. (With all the dangers
-of things like C<malloc> corruption that that currently offers us)
-
-For more information see the thread starting with this message:
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-03/msg00305.html>
-
-=head2 autovivification
-
-Make all autovivification consistent w.r.t LVALUE/RVALUE and strict/no strict;
-
-This task is incremental - even a little bit of work on it will help.
-
-=head2 Unicode in Filenames
-
-chdir, chmod, chown, chroot, exec, glob, link, lstat, mkdir, open,
-opendir, qx, readdir, readlink, rename, rmdir, stat, symlink, sysopen,
-system, truncate, unlink, utime, -X. All these could potentially accept
-Unicode filenames either as input or output (and in the case of system
-and qx Unicode in general, as input or output to/from the shell).
-Whether a filesystem - an operating system pair understands Unicode in
-filenames varies.
-
-Known combinations that have some level of understanding include
-Microsoft NTFS, Apple HFS+ (In Mac OS 9 and X) and Apple UFS (in Mac
-OS X), NFS v4 is rumored to be Unicode, and of course Plan 9. How to
-create Unicode filenames, what forms of Unicode are accepted and used
-(UCS-2, UTF-16, UTF-8), what (if any) is the normalization form used,
-and so on, varies. Finding the right level of interfacing to Perl
-requires some thought. Remember that an OS does not implicate a
-filesystem.
-
-(The Windows -C command flag "wide API support" has been at least
-temporarily retired in 5.8.1, and the -C has been repurposed, see
-L<perlrun>.)
-
-Most probably the right way to do this would be this:
-L</"Virtualize operating system access">.
-
-=head2 Unicode in %ENV
-
-Currently the %ENV entries are always byte strings.
-See L</"Virtualize operating system access">.
-
-=head2 Unicode and glob()
-
-Currently glob patterns and filenames returned from File::Glob::glob()
-are always byte strings. See L</"Virtualize operating system access">.
-
-=head2 use less 'memory'
-
-Investigate trade offs to switch out perl's choices on memory usage.
-Particularly perl should be able to give memory back.
-
-This task is incremental - even a little bit of work on it will help.
-
-=head2 Re-implement C<:unique> in a way that is actually thread-safe
-
-The old implementation made bad assumptions on several levels. A good 90%
-solution might be just to make C<:unique> work to share the string buffer
-of SvPVs. That way large constant strings can be shared between ithreads,
-such as the configuration information in F<Config>.
-
-=head2 Make tainting consistent
-
-Tainting would be easier to use if it didn't take documented shortcuts and
-allow taint to "leak" everywhere within an expression.
-
-=head2 readpipe(LIST)
-
-system() accepts a LIST syntax (and a PROGRAM LIST syntax) to avoid
-running a shell. readpipe() (the function behind qx//) could be similarly
-extended.
-
-=head2 Audit the code for destruction ordering assumptions
-
-Change 25773 notes
-
- /* Need to check SvMAGICAL, as during global destruction it may be that
- AvARYLEN(av) has been freed before av, and hence the SvANY() pointer
- is now part of the linked list of SV heads, rather than pointing to
- the original body. */
- /* FIXME - audit the code for other bugs like this one. */
-
-adding the C<SvMAGICAL> check to
-
- if (AvARYLEN(av) && SvMAGICAL(AvARYLEN(av))) {
- MAGIC *mg = mg_find (AvARYLEN(av), PERL_MAGIC_arylen);
-
-Go through the core and look for similar assumptions that SVs have particular
-types, as all bets are off during global destruction.
-
-=head2 Extend PerlIO and PerlIO::Scalar
-
-PerlIO::Scalar doesn't know how to truncate(). Implementing this
-would require extending the PerlIO vtable.
-
-Similarly the PerlIO vtable doesn't know about formats (write()), or
-about stat(), or chmod()/chown(), utime(), or flock().
-
-(For PerlIO::Scalar it's hard to see what e.g. mode bits or ownership
-would mean.)
-
-PerlIO doesn't do directories or symlinks, either: mkdir(), rmdir(),
-opendir(), closedir(), seekdir(), rewinddir(), glob(); symlink(),
-readlink().
-
-See also L</"Virtualize operating system access">.
-
-=head2 -C on the #! line
-
-It should be possible to make -C work correctly if found on the #! line,
-given that all perl command line options are strict ASCII, and -C changes
-only the interpretation of non-ASCII characters, and not for the script file
-handle. To make it work needs some investigation of the ordering of function
-calls during startup, and (by implication) a bit of tweaking of that order.
-
-=head2 Organize error messages
-
-Perl's diagnostics (error messages, see L<perldiag>) could use
-reorganizing and formalizing so that each error message has its
-stable-for-all-eternity unique id, categorized by severity, type, and
-subsystem. (The error messages would be listed in a datafile outside
-of the Perl source code, and the source code would only refer to the
-messages by the id.) This clean-up and regularizing should apply
-for all croak() messages.
-
-This would enable all sorts of things: easier translation/localization
-of the messages (though please do keep in mind the caveats of
-L<Locale::Maketext> about too straightforward approaches to
-translation), filtering by severity, and instead of grepping for a
-particular error message one could look for a stable error id. (Of
-course, changing the error messages by default would break all the
-existing software depending on some particular error message...)
-
-This kind of functionality is known as I<message catalogs>. Look for
-inspiration for example in the catgets() system, possibly even use it
-if available-- but B<only> if available, all platforms will B<not>
-have catgets().
-
-For the really pure at heart, consider extending this item to cover
-also the warning messages (see L<perllexwarn>, C<warnings.pl>).
-
-=head1 Tasks that need a knowledge of the interpreter
-
-These tasks would need C knowledge, and knowledge of how the interpreter works,
-or a willingness to learn.
-
-=head2 forbid labels with keyword names
-
-Currently C<goto keyword> "computes" the label value:
-
- $ perl -e 'goto print'
- Can't find label 1 at -e line 1.
-
-It is controversial if the right way to avoid the confusion is to forbid
-labels with keyword names, or if it would be better to always treat
-bareword expressions after a "goto" as a label and never as a keyword.
-
-=head2 truncate() prototype
-
-The prototype of truncate() is currently C<$$>. It should probably
-be C<*$> instead. (This is changed in F<opcode.pl>)
-
-=head2 decapsulation of smart match argument
-
-Currently C<$foo ~~ $object> will die with the message "Smart matching a
-non-overloaded object breaks encapsulation". It would be nice to allow
-to bypass this by using explicitly the syntax C<$foo ~~ %$object> or
-C<$foo ~~ @$object>.
-
-=head2 error reporting of [$a ; $b]
-
-Using C<;> inside brackets is a syntax error, and we don't propose to change
-that by giving it any meaning. However, it's not reported very helpfully:
-
- $ perl -e '$a = [$b; $c];'
- syntax error at -e line 1, near "$b;"
- syntax error at -e line 1, near "$c]"
- Execution of -e aborted due to compilation errors.
-
-It should be possible to hook into the tokeniser or the lexer, so that when a
-C<;> is parsed where it is not legal as a statement terminator (ie inside
-C<{}> used as a hashref, C<[]> or C<()>) it issues an error something like
-I<';' isn't legal inside an expression - if you need multiple statements use a
-do {...} block>. See the thread starting at
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-09/msg00573.html>
-
-=head2 lexicals used only once
-
-This warns:
-
- $ perl -we '$pie = 42'
- Name "main::pie" used only once: possible typo at -e line 1.
-
-This does not:
-
- $ perl -we 'my $pie = 42'
-
-Logically all lexicals used only once should warn, if the user asks for
-warnings. An unworked RT ticket (#5087) has been open for almost seven
-years for this discrepancy.
-
-=head2 UTF-8 revamp
-
-The handling of Unicode is unclean in many places. In the regex engine
-there are especially many problems. The swash data structure could be
-replaced my something better. Inversion lists and maps are likely
-candidates. The whole Unicode database could be placed in-core for a
-huge speed-up. Only minimal work was done on the optimizer when utf8
-was added, with the result that the synthetic start class often will
-fail to narrow down the possible choices when given non-Latin1 input.
-
-=head2 Properly Unicode safe tokeniser and pads.
-
-The tokeniser isn't actually very UTF-8 clean. C<use utf8;> is a hack -
-variable names are stored in stashes as raw bytes, without the utf-8 flag
-set. The pad API only takes a C<char *> pointer, so that's all bytes too. The
-tokeniser ignores the UTF-8-ness of C<PL_rsfp>, or any SVs returned from
-source filters. All this could be fixed.
-
-=head2 state variable initialization in list context
-
-Currently this is illegal:
-
- state ($a, $b) = foo();
-
-In Perl 6, C<state ($a) = foo();> and C<(state $a) = foo();> have different
-semantics, which is tricky to implement in Perl 5 as currently they produce
-the same opcode trees. The Perl 6 design is firm, so it would be good to
-implement the necessary code in Perl 5. There are comments in
-C<Perl_newASSIGNOP()> that show the code paths taken by various assignment
-constructions involving state variables.
-
-=head2 Implement $value ~~ 0 .. $range
-
-It would be nice to extend the syntax of the C<~~> operator to also
-understand numeric (and maybe alphanumeric) ranges.
-
-=head2 A does() built-in
-
-Like ref(), only useful. It would call the C<DOES> method on objects; it
-would also tell whether something can be dereferenced as an
-array/hash/etc., or used as a regexp, etc.
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-03/msg00481.html>
-
-=head2 Tied filehandles and write() don't mix
-
-There is no method on tied filehandles to allow them to be called back by
-formats.
-
-=head2 Propagate compilation hints to the debugger
-
-Currently a debugger started with -dE on the command-line doesn't see the
-features enabled by -E. More generally hints (C<$^H> and C<%^H>) aren't
-propagated to the debugger. Probably it would be a good thing to propagate
-hints from the innermost non-C<DB::> scope: this would make code eval'ed
-in the debugger see the features (and strictures, etc.) currently in
-scope.
-
-=head2 Attach/detach debugger from running program
-
-The old perltodo notes "With C<gdb>, you can attach the debugger to a running
-program if you pass the process ID. It would be good to do this with the Perl
-debugger on a running Perl program, although I'm not sure how it would be
-done." ssh and screen do this with named pipes in /tmp. Maybe we can too.
-
-=head2 LVALUE functions for lists
-
-The old perltodo notes that lvalue functions don't work for list or hash
-slices. This would be good to fix.
-
-=head2 regexp optimiser optional
-
-The regexp optimiser is not optional. It should configurable to be, to allow
-its performance to be measured, and its bugs to be easily demonstrated.
-
-=head2 C</w> regex modifier
-
-That flag would enable to match whole words, and also to interpolate
-arrays as alternations. With it, C</P/w> would be roughly equivalent to:
-
- do { local $"='|'; /\b(?:P)\b/ }
-
-See
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-01/msg00400.html>
-for the discussion.
-
-=head2 optional optimizer
-
-Make the peephole optimizer optional. Currently it performs two tasks as
-it walks the optree - genuine peephole optimisations, and necessary fixups of
-ops. It would be good to find an efficient way to switch out the
-optimisations whilst keeping the fixups.
-
-=head2 You WANT *how* many
-
-Currently contexts are void, scalar and list. split has a special mechanism in
-place to pass in the number of return values wanted. It would be useful to
-have a general mechanism for this, backwards compatible and little speed hit.
-This would allow proposals such as short circuiting sort to be implemented
-as a module on CPAN.
-
-=head2 lexical aliases
-
-Allow lexical aliases (maybe via the syntax C<my \$alias = \$foo>.
-
-=head2 entersub XS vs Perl
-
-At the moment pp_entersub is huge, and has code to deal with entering both
-perl and XS subroutines. Subroutine implementations rarely change between
-perl and XS at run time, so investigate using 2 ops to enter subs (one for
-XS, one for perl) and swap between if a sub is redefined.
-
-=head2 Self-ties
-
-Self-ties are currently illegal because they caused too many segfaults. Maybe
-the causes of these could be tracked down and self-ties on all types
-reinstated.
-
-=head2 Optimize away @_
-
-The old perltodo notes "Look at the "reification" code in C<av.c>".
-
-=head2 Virtualize operating system access
-
-Implement a set of "vtables" that virtualizes operating system access
-(open(), mkdir(), unlink(), readdir(), getenv(), etc.) At the very
-least these interfaces should take SVs as "name" arguments instead of
-bare char pointers; probably the most flexible and extensible way
-would be for the Perl-facing interfaces to accept HVs. The system
-needs to be per-operating-system and per-file-system
-hookable/filterable, preferably both from XS and Perl level
-(L<perlport/"Files and Filesystems"> is good reading at this point,
-in fact, all of L<perlport> is.)
-
-This has actually already been implemented (but only for Win32),
-take a look at F<iperlsys.h> and F<win32/perlhost.h>. While all Win32
-variants go through a set of "vtables" for operating system access,
-non-Win32 systems currently go straight for the POSIX/Unix-style
-system/library call. Similar system as for Win32 should be
-implemented for all platforms. The existing Win32 implementation
-probably does not need to survive alongside this proposed new
-implementation, the approaches could be merged.
-
-What would this give us? One often-asked-for feature this would
-enable is using Unicode for filenames, and other "names" like %ENV,
-usernames, hostnames, and so forth.
-(See L<perlunicode/"When Unicode Does Not Happen">.)
-
-But this kind of virtualization would also allow for things like
-virtual filesystems, virtual networks, and "sandboxes" (though as long
-as dynamic loading of random object code is allowed, not very safe
-sandboxes since external code of course know not of Perl's vtables).
-An example of a smaller "sandbox" is that this feature can be used to
-implement per-thread working directories: Win32 already does this.
-
-See also L</"Extend PerlIO and PerlIO::Scalar">.
-
-=head2 Investigate PADTMP hash pessimisation
-
-The peephole optimiser converts constants used for hash key lookups to shared
-hash key scalars. Under ithreads, something is undoing this work.
-See
-L<http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2007-09/msg00793.html>
-
-=head2 Store the current pad in the OP slab allocator
-
-=for clarification
-I hope that I got that "current pad" part correct
-
-Currently we leak ops in various cases of parse failure. I suggested that we
-could solve this by always using the op slab allocator, and walking it to
-free ops. Dave comments that as some ops are already freed during optree
-creation one would have to mark which ops are freed, and not double free them
-when walking the slab. He notes that one problem with this is that for some ops
-you have to know which pad was current at the time of allocation, which does
-change. I suggested storing a pointer to the current pad in the memory allocated
-for the slab, and swapping to a new slab each time the pad changes. Dave thinks
-that this would work.
-
-=head2 repack the optree
-
-Repacking the optree after execution order is determined could allow
-removal of NULL ops, and optimal ordering of OPs with respect to cache-line
-filling. The slab allocator could be reused for this purpose. I think that
-the best way to do this is to make it an optional step just before the
-completed optree is attached to anything else, and to use the slab allocator
-unchanged, so that freeing ops is identical whether or not this step runs.
-Note that the slab allocator allocates ops downwards in memory, so one would
-have to actually "allocate" the ops in reverse-execution order to get them
-contiguous in memory in execution order.
-
-See
-L<http://www.nntp.perl.org/group/perl.perl5.porters/2007/12/msg131975.html>
-
-Note that running this copy, and then freeing all the old location ops would
-cause their slabs to be freed, which would eliminate possible memory wastage if
-the previous suggestion is implemented, and we swap slabs more frequently.
-
-=head2 eliminate incorrect line numbers in warnings
-
-This code
-
- use warnings;
- my $undef;
-
- if ($undef == 3) {
- } elsif ($undef == 0) {
- }
-
-used to produce this output:
-
- Use of uninitialized value in numeric eq (==) at wrong.pl line 4.
- Use of uninitialized value in numeric eq (==) at wrong.pl line 4.
-
-where the line of the second warning was misreported - it should be line 5.
-Rafael fixed this - the problem arose because there was no nextstate OP
-between the execution of the C<if> and the C<elsif>, hence C<PL_curcop> still
-reports that the currently executing line is line 4. The solution was to inject
-a nextstate OPs for each C<elsif>, although it turned out that the nextstate
-OP needed to be a nulled OP, rather than a live nextstate OP, else other line
-numbers became misreported. (Jenga!)
-
-The problem is more general than C<elsif> (although the C<elsif> case is the
-most common and the most confusing). Ideally this code
-
- use warnings;
- my $undef;
-
- my $a = $undef + 1;
- my $b
- = $undef
- + 1;
-
-would produce this output
-
- Use of uninitialized value $undef in addition (+) at wrong.pl line 4.
- Use of uninitialized value $undef in addition (+) at wrong.pl line 7.
-
-(rather than lines 4 and 5), but this would seem to require every OP to carry
-(at least) line number information.
-
-What might work is to have an optional line number in memory just before the
-BASEOP structure, with a flag bit in the op to say whether it's present.
-Initially during compile every OP would carry its line number. Then add a late
-pass to the optimiser (potentially combined with L</repack the optree>) which
-looks at the two ops on every edge of the graph of the execution path. If
-the line number changes, flags the destination OP with this information.
-Once all paths are traced, replace every op with the flag with a
-nextstate-light op (that just updates C<PL_curcop>), which in turn then passes
-control on to the true op. All ops would then be replaced by variants that
-do not store the line number. (Which, logically, why it would work best in
-conjunction with L</repack the optree>, as that is already copying/reallocating
-all the OPs)
-
-(Although I should note that we're not certain that doing this for the general
-case is worth it)
-
-=head2 optimize tail-calls
-
-Tail-calls present an opportunity for broadly applicable optimization;
-anywhere that C<< return foo(...) >> is called, the outer return can
-be replaced by a goto, and foo will return directly to the outer
-caller, saving (conservatively) 25% of perl's call&return cost, which
-is relatively higher than in C. The scheme language is known to do
-this heavily. B::Concise provides good insight into where this
-optimization is possible, ie anywhere entersub,leavesub op-sequence
-occurs.
-
- perl -MO=Concise,-exec,a,b,-main -e 'sub a{ 1 }; sub b {a()}; b(2)'
-
-Bottom line on this is probably a new pp_tailcall function which
-combines the code in pp_entersub, pp_leavesub. This should probably
-be done 1st in XS, and using B::Generate to patch the new OP into the
-optrees.
-
-=head2 Add C<00dddd>
-
-It has been proposed that octal constants be specifiable through the syntax
-C<0oddddd>, parallel to the existing construct to specify hex constants
-C<0xddddd>
-
-=head1 Big projects
-
-Tasks that will get your name mentioned in the description of the "Highlights
-of 5.14"
-
-=head2 make ithreads more robust
-
-Generally make ithreads more robust. See also L</iCOW>
-
-This task is incremental - even a little bit of work on it will help, and
-will be greatly appreciated.
-
-One bit would be to determine how to clone directory handles on systems
-without a C<fchdir> function (in sv.c:Perl_dirp_dup).
-
-Fix Perl_sv_dup, et al so that threads can return objects.
-
-=head2 iCOW
-
-Sarathy and Arthur have a proposal for an improved Copy On Write which
-specifically will be able to COW new ithreads. If this can be implemented
-it would be a good thing.
-
-=head2 (?{...}) closures in regexps
-
-Fix (or rewrite) the implementation of the C</(?{...})/> closures.
-
-=head2 Add class set operations to regexp engine
-
-Apparently these are quite useful. Anyway, Jeffery Friedl wants them.
-
-demerphq has this on his todo list, but right at the bottom.
-
-
-=head1 Tasks for microperl
-
-
-[ Each and every one of these may be obsolete, but they were listed
- in the old Todo.micro file]
-
-
-=head2 make creating uconfig.sh automatic
-
-=head2 make creating Makefile.micro automatic
-
-=head2 do away with fork/exec/wait?
-
-(system, popen should be enough?)
-
-=head2 some of the uconfig.sh really needs to be probed (using cc) in buildtime:
-
-(uConfigure? :-) native datatype widths and endianness come to mind
-
+We no longer install the Perl 5 to-do list as a manpage, as installing
+snapshot that becomes increasingly out of date isn't that useful to anyone.
+The current Perl 5 to-do list is maintained in the git repository, and can
+be viewed at L<http://perl5.git.perl.org/perl.git/blob/HEAD:/Porting/todo.pod>
Property changes on: trunk/contrib/perl/pod/perltodo.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perltooc.pod
===================================================================
--- trunk/contrib/perl/pod/perltooc.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perltooc.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,1342 +1,12 @@
+=encoding utf8
+
=head1 NAME
-perltooc - Tom's OO Tutorial for Class Data in Perl
+perltooc - This document has been deleted
=head1 DESCRIPTION
-When designing an object class, you are sometimes faced with the situation
-of wanting common state shared by all objects of that class.
-Such I<class attributes> act somewhat like global variables for the entire
-class, but unlike program-wide globals, class attributes have meaning only to
-the class itself.
+For information on OO programming with Perl, please see L<perlootut>
+and L<perlobj>.
-Here are a few examples where class attributes might come in handy:
-
-=over 4
-
-=item *
-
-to keep a count of the objects you've created, or how many are
-still extant.
-
-=item *
-
-to extract the name or file descriptor for a logfile used by a debugging
-method.
-
-=item *
-
-to access collective data, like the total amount of cash dispensed by
-all ATMs in a network in a given day.
-
-=item *
-
-to access the last object created by a class, or the most accessed object,
-or to retrieve a list of all objects.
-
-=back
-
-Unlike a true global, class attributes should not be accessed directly.
-Instead, their state should be inspected, and perhaps altered, only
-through the mediated access of I<class methods>. These class attributes
-accessor methods are similar in spirit and function to accessors used
-to manipulate the state of instance attributes on an object. They provide a
-clear firewall between interface and implementation.
-
-You should allow access to class attributes through either the class
-name or any object of that class. If we assume that $an_object is of
-type Some_Class, and the &Some_Class::population_count method accesses
-class attributes, then these two invocations should both be possible,
-and almost certainly equivalent.
-
- Some_Class->population_count()
- $an_object->population_count()
-
-The question is, where do you store the state which that method accesses?
-Unlike more restrictive languages like C++, where these are called
-static data members, Perl provides no syntactic mechanism to declare
-class attributes, any more than it provides a syntactic mechanism to
-declare instance attributes. Perl provides the developer with a broad
-set of powerful but flexible features that can be uniquely crafted to
-the particular demands of the situation.
-
-A class in Perl is typically implemented in a module. A module consists
-of two complementary feature sets: a package for interfacing with the
-outside world, and a lexical file scope for privacy. Either of these
-two mechanisms can be used to implement class attributes. That means you
-get to decide whether to put your class attributes in package variables
-or to put them in lexical variables.
-
-And those aren't the only decisions to make. If you choose to use package
-variables, you can make your class attribute accessor methods either ignorant
-of inheritance or sensitive to it. If you choose lexical variables,
-you can elect to permit access to them from anywhere in the entire file
-scope, or you can limit direct data access exclusively to the methods
-implementing those attributes.
-
-=head1 Class Data in a Can
-
-One of the easiest ways to solve a hard problem is to let someone else
-do it for you! In this case, Class::Data::Inheritable (available on a
-CPAN near you) offers a canned solution to the class data problem
-using closures. So before you wade into this document, consider
-having a look at that module.
-
-
-=head1 Class Data as Package Variables
-
-Because a class in Perl is really just a package, using package variables
-to hold class attributes is the most natural choice. This makes it simple
-for each class to have its own class attributes. Let's say you have a class
-called Some_Class that needs a couple of different attributes that you'd
-like to be global to the entire class. The simplest thing to do is to
-use package variables like $Some_Class::CData1 and $Some_Class::CData2
-to hold these attributes. But we certainly don't want to encourage
-outsiders to touch those data directly, so we provide methods
-to mediate access.
-
-In the accessor methods below, we'll for now just ignore the first
-argument--that part to the left of the arrow on method invocation, which
-is either a class name or an object reference.
-
- package Some_Class;
- sub CData1 {
- shift; # XXX: ignore calling class/object
- $Some_Class::CData1 = shift if @_;
- return $Some_Class::CData1;
- }
- sub CData2 {
- shift; # XXX: ignore calling class/object
- $Some_Class::CData2 = shift if @_;
- return $Some_Class::CData2;
- }
-
-This technique is highly legible and should be completely straightforward
-to even the novice Perl programmer. By fully qualifying the package
-variables, they stand out clearly when reading the code. Unfortunately,
-if you misspell one of these, you've introduced an error that's hard
-to catch. It's also somewhat disconcerting to see the class name itself
-hard-coded in so many places.
-
-Both these problems can be easily fixed. Just add the C<use strict>
-pragma, then pre-declare your package variables. (The C<our> operator
-will be new in 5.6, and will work for package globals just like C<my>
-works for scoped lexicals.)
-
- package Some_Class;
- use strict;
- our($CData1, $CData2); # our() is new to perl5.6
- sub CData1 {
- shift; # XXX: ignore calling class/object
- $CData1 = shift if @_;
- return $CData1;
- }
- sub CData2 {
- shift; # XXX: ignore calling class/object
- $CData2 = shift if @_;
- return $CData2;
- }
-
-
-As with any other global variable, some programmers prefer to start their
-package variables with capital letters. This helps clarity somewhat, but
-by no longer fully qualifying the package variables, their significance
-can be lost when reading the code. You can fix this easily enough by
-choosing better names than were used here.
-
-=head2 Putting All Your Eggs in One Basket
-
-Just as the mindless enumeration of accessor methods for instance attributes
-grows tedious after the first few (see L<perltoot>), so too does the
-repetition begin to grate when listing out accessor methods for class
-data. Repetition runs counter to the primary virtue of a programmer:
-Laziness, here manifesting as that innate urge every programmer feels
-to factor out duplicate code whenever possible.
-
-Here's what to do. First, make just one hash to hold all class attributes.
-
- package Some_Class;
- use strict;
- our %ClassData = ( # our() is new to perl5.6
- CData1 => "",
- CData2 => "",
- );
-
-Using closures (see L<perlref>) and direct access to the package symbol
-table (see L<perlmod>), now clone an accessor method for each key in
-the %ClassData hash. Each of these methods is used to fetch or store
-values to the specific, named class attribute.
-
- for my $datum (keys %ClassData) {
- no strict "refs"; # to register new methods in package
- *$datum = sub {
- shift; # XXX: ignore calling class/object
- $ClassData{$datum} = shift if @_;
- return $ClassData{$datum};
- }
- }
-
-It's true that you could work out a solution employing an &AUTOLOAD
-method, but this approach is unlikely to prove satisfactory. Your
-function would have to distinguish between class attributes and object
-attributes; it could interfere with inheritance; and it would have to
-careful about DESTROY. Such complexity is uncalled for in most cases,
-and certainly in this one.
-
-You may wonder why we're rescinding strict refs for the loop. We're
-manipulating the package's symbol table to introduce new function names
-using symbolic references (indirect naming), which the strict pragma
-would otherwise forbid. Normally, symbolic references are a dodgy
-notion at best. This isn't just because they can be used accidentally
-when you aren't meaning to. It's also because for most uses
-to which beginning Perl programmers attempt to put symbolic references,
-we have much better approaches, like nested hashes or hashes of arrays.
-But there's nothing wrong with using symbolic references to manipulate
-something that is meaningful only from the perspective of the package
-symbol table, like method names or package variables. In other
-words, when you want to refer to the symbol table, use symbol references.
-
-Clustering all the class attributes in one place has several advantages.
-They're easy to spot, initialize, and change. The aggregation also
-makes them convenient to access externally, such as from a debugger
-or a persistence package. The only possible problem is that we don't
-automatically know the name of each class's class object, should it have
-one. This issue is addressed below in L<"The Eponymous Meta-Object">.
-
-=head2 Inheritance Concerns
-
-Suppose you have an instance of a derived class, and you access class
-data using an inherited method call. Should that end up referring
-to the base class's attributes, or to those in the derived class?
-How would it work in the earlier examples? The derived class inherits
-all the base class's methods, including those that access class attributes.
-But what package are the class attributes stored in?
-
-The answer is that, as written, class attributes are stored in the package into
-which those methods were compiled. When you invoke the &CData1 method
-on the name of the derived class or on one of that class's objects, the
-version shown above is still run, so you'll access $Some_Class::CData1--or
-in the method cloning version, C<$Some_Class::ClassData{CData1}>.
-
-Think of these class methods as executing in the context of their base
-class, not in that of their derived class. Sometimes this is exactly
-what you want. If Feline subclasses Carnivore, then the population of
-Carnivores in the world should go up when a new Feline is born.
-But what if you wanted to figure out how many Felines you have apart
-from Carnivores? The current approach doesn't support that.
-
-You'll have to decide on a case-by-case basis whether it makes any sense
-for class attributes to be package-relative. If you want it to be so,
-then stop ignoring the first argument to the function. Either it will
-be a package name if the method was invoked directly on a class name,
-or else it will be an object reference if the method was invoked on an
-object reference. In the latter case, the ref() function provides the
-class of that object.
-
- package Some_Class;
- sub CData1 {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- my $varname = $class . "::CData1";
- no strict "refs"; # to access package data symbolically
- $$varname = shift if @_;
- return $$varname;
- }
-
-And then do likewise for all other class attributes (such as CData2,
-etc.) that you wish to access as package variables in the invoking package
-instead of the compiling package as we had previously.
-
-Once again we temporarily disable the strict references ban, because
-otherwise we couldn't use the fully-qualified symbolic name for
-the package global. This is perfectly reasonable: since all package
-variables by definition live in a package, there's nothing wrong with
-accessing them via that package's symbol table. That's what it's there
-for (well, somewhat).
-
-What about just using a single hash for everything and then cloning
-methods? What would that look like? The only difference would be the
-closure used to produce new method entries for the class's symbol table.
-
- no strict "refs";
- *$datum = sub {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- my $varname = $class . "::ClassData";
- $varname->{$datum} = shift if @_;
- return $varname->{$datum};
- }
-
-=head2 The Eponymous Meta-Object
-
-It could be argued that the %ClassData hash in the previous example is
-neither the most imaginative nor the most intuitive of names. Is there
-something else that might make more sense, be more useful, or both?
-
-As it happens, yes, there is. For the "class meta-object", we'll use
-a package variable of the same name as the package itself. Within the
-scope of a package Some_Class declaration, we'll use the eponymously
-named hash %Some_Class as that class's meta-object. (Using an eponymously
-named hash is somewhat reminiscent of classes that name their constructors
-eponymously in the Python or C++ fashion. That is, class Some_Class would
-use &Some_Class::Some_Class as a constructor, probably even exporting that
-name as well. The StrNum class in Recipe 13.14 in I<The Perl Cookbook>
-does this, if you're looking for an example.)
-
-This predictable approach has many benefits, including having a well-known
-identifier to aid in debugging, transparent persistence,
-or checkpointing. It's also the obvious name for monadic classes and
-translucent attributes, discussed later.
-
-Here's an example of such a class. Notice how the name of the
-hash storing the meta-object is the same as the name of the package
-used to implement the class.
-
- package Some_Class;
- use strict;
-
- # create class meta-object using that most perfect of names
- our %Some_Class = ( # our() is new to perl5.6
- CData1 => "",
- CData2 => "",
- );
-
- # this accessor is calling-package-relative
- sub CData1 {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- no strict "refs"; # to access eponymous meta-object
- $class->{CData1} = shift if @_;
- return $class->{CData1};
- }
-
- # but this accessor is not
- sub CData2 {
- shift; # XXX: ignore calling class/object
- no strict "refs"; # to access eponymous meta-object
- __PACKAGE__ -> {CData2} = shift if @_;
- return __PACKAGE__ -> {CData2};
- }
-
-In the second accessor method, the __PACKAGE__ notation was used for
-two reasons. First, to avoid hardcoding the literal package name
-in the code in case we later want to change that name. Second, to
-clarify to the reader that what matters here is the package currently
-being compiled into, not the package of the invoking object or class.
-If the long sequence of non-alphabetic characters bothers you, you can
-always put the __PACKAGE__ in a variable first.
-
- sub CData2 {
- shift; # XXX: ignore calling class/object
- no strict "refs"; # to access eponymous meta-object
- my $class = __PACKAGE__;
- $class->{CData2} = shift if @_;
- return $class->{CData2};
- }
-
-Even though we're using symbolic references for good not evil, some
-folks tend to become unnerved when they see so many places with strict
-ref checking disabled. Given a symbolic reference, you can always
-produce a real reference (the reverse is not true, though). So we'll
-create a subroutine that does this conversion for us. If invoked as a
-function of no arguments, it returns a reference to the compiling class's
-eponymous hash. Invoked as a class method, it returns a reference to
-the eponymous hash of its caller. And when invoked as an object method,
-this function returns a reference to the eponymous hash for whatever
-class the object belongs to.
-
- package Some_Class;
- use strict;
-
- our %Some_Class = ( # our() is new to perl5.6
- CData1 => "",
- CData2 => "",
- );
-
- # tri-natured: function, class method, or object method
- sub _classobj {
- my $obclass = shift || __PACKAGE__;
- my $class = ref($obclass) || $obclass;
- no strict "refs"; # to convert sym ref to real one
- return \%$class;
- }
-
- for my $datum (keys %{ _classobj() } ) {
- # turn off strict refs so that we can
- # register a method in the symbol table
- no strict "refs";
- *$datum = sub {
- use strict "refs";
- my $self = shift->_classobj();
- $self->{$datum} = shift if @_;
- return $self->{$datum};
- }
- }
-
-=head2 Indirect References to Class Data
-
-A reasonably common strategy for handling class attributes is to store
-a reference to each package variable on the object itself. This is
-a strategy you've probably seen before, such as in L<perltoot> and
-L<perlbot>, but there may be variations in the example below that you
-haven't thought of before.
-
- package Some_Class;
- our($CData1, $CData2); # our() is new to perl5.6
-
- sub new {
- my $obclass = shift;
- return bless my $self = {
- ObData1 => "",
- ObData2 => "",
- CData1 => \$CData1,
- CData2 => \$CData2,
- } => (ref $obclass || $obclass);
- }
-
- sub ObData1 {
- my $self = shift;
- $self->{ObData1} = shift if @_;
- return $self->{ObData1};
- }
-
- sub ObData2 {
- my $self = shift;
- $self->{ObData2} = shift if @_;
- return $self->{ObData2};
- }
-
- sub CData1 {
- my $self = shift;
- my $dataref = ref $self
- ? $self->{CData1}
- : \$CData1;
- $$dataref = shift if @_;
- return $$dataref;
- }
-
- sub CData2 {
- my $self = shift;
- my $dataref = ref $self
- ? $self->{CData2}
- : \$CData2;
- $$dataref = shift if @_;
- return $$dataref;
- }
-
-As written above, a derived class will inherit these methods, which
-will consequently access package variables in the base class's package.
-This is not necessarily expected behavior in all circumstances. Here's an
-example that uses a variable meta-object, taking care to access the
-proper package's data.
-
- package Some_Class;
- use strict;
-
- our %Some_Class = ( # our() is new to perl5.6
- CData1 => "",
- CData2 => "",
- );
-
- sub _classobj {
- my $self = shift;
- my $class = ref($self) || $self;
- no strict "refs";
- # get (hard) ref to eponymous meta-object
- return \%$class;
- }
-
- sub new {
- my $obclass = shift;
- my $classobj = $obclass->_classobj();
- bless my $self = {
- ObData1 => "",
- ObData2 => "",
- CData1 => \$classobj->{CData1},
- CData2 => \$classobj->{CData2},
- } => (ref $obclass || $obclass);
- return $self;
- }
-
- sub ObData1 {
- my $self = shift;
- $self->{ObData1} = shift if @_;
- return $self->{ObData1};
- }
-
- sub ObData2 {
- my $self = shift;
- $self->{ObData2} = shift if @_;
- return $self->{ObData2};
- }
-
- sub CData1 {
- my $self = shift;
- $self = $self->_classobj() unless ref $self;
- my $dataref = $self->{CData1};
- $$dataref = shift if @_;
- return $$dataref;
- }
-
- sub CData2 {
- my $self = shift;
- $self = $self->_classobj() unless ref $self;
- my $dataref = $self->{CData2};
- $$dataref = shift if @_;
- return $$dataref;
- }
-
-Not only are we now strict refs clean, using an eponymous meta-object
-seems to make the code cleaner. Unlike the previous version, this one
-does something interesting in the face of inheritance: it accesses the
-class meta-object in the invoking class instead of the one into which
-the method was initially compiled.
-
-You can easily access data in the class meta-object, making
-it easy to dump the complete class state using an external mechanism such
-as when debugging or implementing a persistent class. This works because
-the class meta-object is a package variable, has a well-known name, and
-clusters all its data together. (Transparent persistence
-is not always feasible, but it's certainly an appealing idea.)
-
-There's still no check that object accessor methods have not been
-invoked on a class name. If strict ref checking is enabled, you'd
-blow up. If not, then you get the eponymous meta-object. What you do
-with--or about--this is up to you. The next two sections demonstrate
-innovative uses for this powerful feature.
-
-=head2 Monadic Classes
-
-Some of the standard modules shipped with Perl provide class interfaces
-without any attribute methods whatsoever. The most commonly used module
-not numbered amongst the pragmata, the Exporter module, is a class with
-neither constructors nor attributes. Its job is simply to provide a
-standard interface for modules wishing to export part of their namespace
-into that of their caller. Modules use the Exporter's &import method by
-setting their inheritance list in their package's @ISA array to mention
-"Exporter". But class Exporter provides no constructor, so you can't
-have several instances of the class. In fact, you can't have any--it
-just doesn't make any sense. All you get is its methods. Its interface
-contains no statefulness, so state data is wholly superfluous.
-
-Another sort of class that pops up from time to time is one that supports
-a unique instance. Such classes are called I<monadic classes>, or less
-formally, I<singletons> or I<highlander classes>.
-
-If a class is monadic, where do you store its state, that is,
-its attributes? How do you make sure that there's never more than
-one instance? While you could merely use a slew of package variables,
-it's a lot cleaner to use the eponymously named hash. Here's a complete
-example of a monadic class:
-
- package Cosmos;
- %Cosmos = ();
-
- # accessor method for "name" attribute
- sub name {
- my $self = shift;
- $self->{name} = shift if @_;
- return $self->{name};
- }
-
- # read-only accessor method for "birthday" attribute
- sub birthday {
- my $self = shift;
- die "can't reset birthday" if @_; # XXX: croak() is better
- return $self->{birthday};
- }
-
- # accessor method for "stars" attribute
- sub stars {
- my $self = shift;
- $self->{stars} = shift if @_;
- return $self->{stars};
- }
-
- # oh my - one of our stars just went out!
- sub supernova {
- my $self = shift;
- my $count = $self->stars();
- $self->stars($count - 1) if $count > 0;
- }
-
- # constructor/initializer method - fix by reboot
- sub bigbang {
- my $self = shift;
- %$self = (
- name => "the world according to tchrist",
- birthday => time(),
- stars => 0,
- );
- return $self; # yes, it's probably a class. SURPRISE!
- }
-
- # After the class is compiled, but before any use or require
- # returns, we start off the universe with a bang.
- __PACKAGE__ -> bigbang();
-
-Hold on, that doesn't look like anything special. Those attribute
-accessors look no different than they would if this were a regular class
-instead of a monadic one. The crux of the matter is there's nothing
-that says that $self must hold a reference to a blessed object. It merely
-has to be something you can invoke methods on. Here the package name
-itself, Cosmos, works as an object. Look at the &supernova method. Is that
-a class method or an object method? The answer is that static analysis
-cannot reveal the answer. Perl doesn't care, and neither should you.
-In the three attribute methods, C<%$self> is really accessing the %Cosmos
-package variable.
-
-If like Stephen Hawking, you posit the existence of multiple, sequential,
-and unrelated universes, then you can invoke the &bigbang method yourself
-at any time to start everything all over again. You might think of
-&bigbang as more of an initializer than a constructor, since the function
-doesn't allocate new memory; it only initializes what's already there.
-But like any other constructor, it does return a scalar value to use
-for later method invocations.
-
-Imagine that some day in the future, you decide that one universe just
-isn't enough. You could write a new class from scratch, but you already
-have an existing class that does what you want--except that it's monadic,
-and you want more than just one cosmos.
-
-That's what code reuse via subclassing is all about. Look how short
-the new code is:
-
- package Multiverse;
- use Cosmos;
- @ISA = qw(Cosmos);
-
- sub new {
- my $protoverse = shift;
- my $class = ref($protoverse) || $protoverse;
- my $self = {};
- return bless($self, $class)->bigbang();
- }
- 1;
-
-Because we were careful to be good little creators when we designed our
-Cosmos class, we can now reuse it without touching a single line of code
-when it comes time to write our Multiverse class. The same code that
-worked when invoked as a class method continues to work perfectly well
-when invoked against separate instances of a derived class.
-
-The astonishing thing about the Cosmos class above is that the value
-returned by the &bigbang "constructor" is not a reference to a blessed
-object at all. It's just the class's own name. A class name is, for
-virtually all intents and purposes, a perfectly acceptable object.
-It has state, behavior, and identity, the three crucial components
-of an object system. It even manifests inheritance, polymorphism,
-and encapsulation. And what more can you ask of an object?
-
-To understand object orientation in Perl, it's important to recognize the
-unification of what other programming languages might think of as class
-methods and object methods into just plain methods. "Class methods"
-and "object methods" are distinct only in the compartmentalizing mind
-of the Perl programmer, not in the Perl language itself.
-
-Along those same lines, a constructor is nothing special either, which
-is one reason why Perl has no pre-ordained name for them. "Constructor"
-is just an informal term loosely used to describe a method that returns
-a scalar value that you can make further method calls against. So long
-as it's either a class name or an object reference, that's good enough.
-It doesn't even have to be a reference to a brand new object.
-
-You can have as many--or as few--constructors as you want, and you can
-name them whatever you care to. Blindly and obediently using new()
-for each and every constructor you ever write is to speak Perl with
-such a severe C++ accent that you do a disservice to both languages.
-There's no reason to insist that each class have but one constructor,
-or that a constructor be named new(), or that a constructor be
-used solely as a class method and not an object method.
-
-The next section shows how useful it can be to further distance ourselves
-from any formal distinction between class method calls and object method
-calls, both in constructors and in accessor methods.
-
-=head2 Translucent Attributes
-
-A package's eponymous hash can be used for more than just containing
-per-class, global state data. It can also serve as a sort of template
-containing default settings for object attributes. These default
-settings can then be used in constructors for initialization of a
-particular object. The class's eponymous hash can also be used to
-implement I<translucent attributes>. A translucent attribute is one
-that has a class-wide default. Each object can set its own value for the
-attribute, in which case C<< $object->attribute() >> returns that value.
-But if no value has been set, then C<< $object->attribute() >> returns
-the class-wide default.
-
-We'll apply something of a copy-on-write approach to these translucent
-attributes. If you're just fetching values from them, you get
-translucency. But if you store a new value to them, that new value is
-set on the current object. On the other hand, if you use the class as
-an object and store the attribute value directly on the class, then the
-meta-object's value changes, and later fetch operations on objects with
-uninitialized values for those attributes will retrieve the meta-object's
-new values. Objects with their own initialized values, however, won't
-see any change.
-
-Let's look at some concrete examples of using these properties before we
-show how to implement them. Suppose that a class named Some_Class
-had a translucent data attribute called "color". First you set the color
-in the meta-object, then you create three objects using a constructor
-that happens to be named &spawn.
-
- use Vermin;
- Vermin->color("vermilion");
-
- $ob1 = Vermin->spawn(); # so that's where Jedi come from
- $ob2 = Vermin->spawn();
- $ob3 = Vermin->spawn();
-
- print $obj3->color(); # prints "vermilion"
-
-Each of these objects' colors is now "vermilion", because that's the
-meta-object's value for that attribute, and these objects do not have
-individual color values set.
-
-Changing the attribute on one object has no effect on other objects
-previously created.
-
- $ob3->color("chartreuse");
- print $ob3->color(); # prints "chartreuse"
- print $ob1->color(); # prints "vermilion", translucently
-
-If you now use $ob3 to spawn off another object, the new object will
-take the color its parent held, which now happens to be "chartreuse".
-That's because the constructor uses the invoking object as its template
-for initializing attributes. When that invoking object is the
-class name, the object used as a template is the eponymous meta-object.
-When the invoking object is a reference to an instantiated object, the
-&spawn constructor uses that existing object as a template.
-
- $ob4 = $ob3->spawn(); # $ob3 now template, not %Vermin
- print $ob4->color(); # prints "chartreuse"
-
-Any actual values set on the template object will be copied to the
-new object. But attributes undefined in the template object, being
-translucent, will remain undefined and consequently translucent in the
-new one as well.
-
-Now let's change the color attribute on the entire class:
-
- Vermin->color("azure");
- print $ob1->color(); # prints "azure"
- print $ob2->color(); # prints "azure"
- print $ob3->color(); # prints "chartreuse"
- print $ob4->color(); # prints "chartreuse"
-
-That color change took effect only in the first pair of objects, which
-were still translucently accessing the meta-object's values. The second
-pair had per-object initialized colors, and so didn't change.
-
-One important question remains. Changes to the meta-object are reflected
-in translucent attributes in the entire class, but what about
-changes to discrete objects? If you change the color of $ob3, does the
-value of $ob4 see that change? Or vice-versa. If you change the color
-of $ob4, does then the value of $ob3 shift?
-
- $ob3->color("amethyst");
- print $ob3->color(); # prints "amethyst"
- print $ob4->color(); # hmm: "chartreuse" or "amethyst"?
-
-While one could argue that in certain rare cases it should, let's not
-do that. Good taste aside, we want the answer to the question posed in
-the comment above to be "chartreuse", not "amethyst". So we'll treat
-these attributes similar to the way process attributes like environment
-variables, user and group IDs, or the current working directory are
-treated across a fork(). You can change only yourself, but you will see
-those changes reflected in your unspawned children. Changes to one object
-will propagate neither up to the parent nor down to any existing child objects.
-Those objects made later, however, will see the changes.
-
-If you have an object with an actual attribute value, and you want to
-make that object's attribute value translucent again, what do you do?
-Let's design the class so that when you invoke an accessor method with
-C<undef> as its argument, that attribute returns to translucency.
-
- $ob4->color(undef); # back to "azure"
-
-Here's a complete implementation of Vermin as described above.
-
- package Vermin;
-
- # here's the class meta-object, eponymously named.
- # it holds all class attributes, and also all instance attributes
- # so the latter can be used for both initialization
- # and translucency.
-
- our %Vermin = ( # our() is new to perl5.6
- PopCount => 0, # capital for class attributes
- color => "beige", # small for instance attributes
- );
-
- # constructor method
- # invoked as class method or object method
- sub spawn {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- my $self = {};
- bless($self, $class);
- $class->{PopCount}++;
- # init fields from invoking object, or omit if
- # invoking object is the class to provide translucency
- %$self = %$obclass if ref $obclass;
- return $self;
- }
-
- # translucent accessor for "color" attribute
- # invoked as class method or object method
- sub color {
- my $self = shift;
- my $class = ref($self) || $self;
-
- # handle class invocation
- unless (ref $self) {
- $class->{color} = shift if @_;
- return $class->{color}
- }
-
- # handle object invocation
- $self->{color} = shift if @_;
- if (defined $self->{color}) { # not exists!
- return $self->{color};
- } else {
- return $class->{color};
- }
- }
-
- # accessor for "PopCount" class attribute
- # invoked as class method or object method
- # but uses object solely to locate meta-object
- sub population {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- return $class->{PopCount};
- }
-
- # instance destructor
- # invoked only as object method
- sub DESTROY {
- my $self = shift;
- my $class = ref $self;
- $class->{PopCount}--;
- }
-
-Here are a couple of helper methods that might be convenient. They aren't
-accessor methods at all. They're used to detect accessibility of data
-attributes. The &is_translucent method determines whether a particular
-object attribute is coming from the meta-object. The &has_attribute
-method detects whether a class implements a particular property at all.
-It could also be used to distinguish undefined properties from non-existent
-ones.
-
- # detect whether an object attribute is translucent
- # (typically?) invoked only as object method
- sub is_translucent {
- my($self, $attr) = @_;
- return !defined $self->{$attr};
- }
-
- # test for presence of attribute in class
- # invoked as class method or object method
- sub has_attribute {
- my($self, $attr) = @_;
- my $class = ref($self) || $self;
- return exists $class->{$attr};
- }
-
-If you prefer to install your accessors more generically, you can make
-use of the upper-case versus lower-case convention to register into the
-package appropriate methods cloned from generic closures.
-
- for my $datum (keys %{ +__PACKAGE__ }) {
- *$datum = ($datum =~ /^[A-Z]/)
- ? sub { # install class accessor
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- return $class->{$datum};
- }
- : sub { # install translucent accessor
- my $self = shift;
- my $class = ref($self) || $self;
- unless (ref $self) {
- $class->{$datum} = shift if @_;
- return $class->{$datum}
- }
- $self->{$datum} = shift if @_;
- return defined $self->{$datum}
- ? $self -> {$datum}
- : $class -> {$datum}
- }
- }
-
-Translations of this closure-based approach into C++, Java, and Python
-have been left as exercises for the reader. Be sure to send us mail as
-soon as you're done.
-
-=head1 Class Data as Lexical Variables
-
-=head2 Privacy and Responsibility
-
-Unlike conventions used by some Perl programmers, in the previous
-examples, we didn't prefix the package variables used for class attributes
-with an underscore, nor did we do so for the names of the hash keys used
-for instance attributes. You don't need little markers on data names to
-suggest nominal privacy on attribute variables or hash keys, because these
-are B<already> notionally private! Outsiders have no business whatsoever
-playing with anything within a class save through the mediated access of
-its documented interface; in other words, through method invocations.
-And not even through just any method, either. Methods that begin with
-an underscore are traditionally considered off-limits outside the class.
-If outsiders skip the documented method interface to poke around the
-internals of your class and end up breaking something, that's not your
-fault--it's theirs.
-
-Perl believes in individual responsibility rather than mandated control.
-Perl respects you enough to let you choose your own preferred level of
-pain, or of pleasure. Perl believes that you are creative, intelligent,
-and capable of making your own decisions--and fully expects you to
-take complete responsibility for your own actions. In a perfect world,
-these admonitions alone would suffice, and everyone would be intelligent,
-responsible, happy, and creative. And careful. One probably shouldn't
-forget careful, and that's a good bit harder to expect. Even Einstein
-would take wrong turns by accident and end up lost in the wrong part
-of town.
-
-Some folks get the heebie-jeebies when they see package variables
-hanging out there for anyone to reach over and alter them. Some folks
-live in constant fear that someone somewhere might do something wicked.
-The solution to that problem is simply to fire the wicked, of course.
-But unfortunately, it's not as simple as all that. These cautious
-types are also afraid that they or others will do something not so
-much wicked as careless, whether by accident or out of desperation.
-If we fire everyone who ever gets careless, pretty soon there won't be
-anybody left to get any work done.
-
-Whether it's needless paranoia or sensible caution, this uneasiness can
-be a problem for some people. We can take the edge off their discomfort
-by providing the option of storing class attributes as lexical variables
-instead of as package variables. The my() operator is the source of
-all privacy in Perl, and it is a powerful form of privacy indeed.
-
-It is widely perceived, and indeed has often been written, that Perl
-provides no data hiding, that it affords the class designer no privacy
-nor isolation, merely a rag-tag assortment of weak and unenforceable
-social conventions instead. This perception is demonstrably false and
-easily disproven. In the next section, we show how to implement forms
-of privacy that are far stronger than those provided in nearly any
-other object-oriented language.
-
-=head2 File-Scoped Lexicals
-
-A lexical variable is visible only through the end of its static scope.
-That means that the only code able to access that variable is code
-residing textually below the my() operator through the end of its block
-if it has one, or through the end of the current file if it doesn't.
-
-Starting again with our simplest example given at the start of this
-document, we replace our() variables with my() versions.
-
- package Some_Class;
- my($CData1, $CData2); # file scope, not in any package
- sub CData1 {
- shift; # XXX: ignore calling class/object
- $CData1 = shift if @_;
- return $CData1;
- }
- sub CData2 {
- shift; # XXX: ignore calling class/object
- $CData2 = shift if @_;
- return $CData2;
- }
-
-So much for that old $Some_Class::CData1 package variable and its brethren!
-Those are gone now, replaced with lexicals. No one outside the
-scope can reach in and alter the class state without resorting to the
-documented interface. Not even subclasses or superclasses of
-this one have unmediated access to $CData1. They have to invoke the &CData1
-method against Some_Class or an instance thereof, just like anybody else.
-
-To be scrupulously honest, that last statement assumes you haven't packed
-several classes together into the same file scope, nor strewn your class
-implementation across several different files. Accessibility of those
-variables is based uniquely on the static file scope. It has nothing to
-do with the package. That means that code in a different file but
-the same package (class) could not access those variables, yet code in the
-same file but a different package (class) could. There are sound reasons
-why we usually suggest a one-to-one mapping between files and packages
-and modules and classes. You don't have to stick to this suggestion if
-you really know what you're doing, but you're apt to confuse yourself
-otherwise, especially at first.
-
-If you'd like to aggregate your class attributes into one lexically scoped,
-composite structure, you're perfectly free to do so.
-
- package Some_Class;
- my %ClassData = (
- CData1 => "",
- CData2 => "",
- );
- sub CData1 {
- shift; # XXX: ignore calling class/object
- $ClassData{CData1} = shift if @_;
- return $ClassData{CData1};
- }
- sub CData2 {
- shift; # XXX: ignore calling class/object
- $ClassData{CData2} = shift if @_;
- return $ClassData{CData2};
- }
-
-To make this more scalable as other class attributes are added, we can
-again register closures into the package symbol table to create accessor
-methods for them.
-
- package Some_Class;
- my %ClassData = (
- CData1 => "",
- CData2 => "",
- );
- for my $datum (keys %ClassData) {
- no strict "refs";
- *$datum = sub {
- shift; # XXX: ignore calling class/object
- $ClassData{$datum} = shift if @_;
- return $ClassData{$datum};
- };
- }
-
-Requiring even your own class to use accessor methods like anybody else is
-probably a good thing. But demanding and expecting that everyone else,
-be they subclass or superclass, friend or foe, will all come to your
-object through mediation is more than just a good idea. It's absolutely
-critical to the model. Let there be in your mind no such thing as
-"public" data, nor even "protected" data, which is a seductive but
-ultimately destructive notion. Both will come back to bite at you.
-That's because as soon as you take that first step out of the solid
-position in which all state is considered completely private, save from the
-perspective of its own accessor methods, you have violated the envelope.
-And, having pierced that encapsulating envelope, you shall doubtless
-someday pay the price when future changes in the implementation break
-unrelated code. Considering that avoiding this infelicitous outcome was
-precisely why you consented to suffer the slings and arrows of obsequious
-abstraction by turning to object orientation in the first place, such
-breakage seems unfortunate in the extreme.
-
-=head2 More Inheritance Concerns
-
-Suppose that Some_Class were used as a base class from which to derive
-Another_Class. If you invoke a &CData method on the derived class or
-on an object of that class, what do you get? Would the derived class
-have its own state, or would it piggyback on its base class's versions
-of the class attributes?
-
-The answer is that under the scheme outlined above, the derived class
-would B<not> have its own state data. As before, whether you consider
-this a good thing or a bad one depends on the semantics of the classes
-involved.
-
-The cleanest, sanest, simplest way to address per-class state in a
-lexical is for the derived class to override its base class's version
-of the method that accesses the class attributes. Since the actual method
-called is the one in the object's derived class if this exists, you
-automatically get per-class state this way. Any urge to provide an
-unadvertised method to sneak out a reference to the %ClassData hash
-should be strenuously resisted.
-
-As with any other overridden method, the implementation in the
-derived class always has the option of invoking its base class's
-version of the method in addition to its own. Here's an example:
-
- package Another_Class;
- @ISA = qw(Some_Class);
-
- my %ClassData = (
- CData1 => "",
- );
-
- sub CData1 {
- my($self, $newvalue) = @_;
- if (@_ > 1) {
- # set locally first
- $ClassData{CData1} = $newvalue;
-
- # then pass the buck up to the first
- # overridden version, if there is one
- if ($self->can("SUPER::CData1")) {
- $self->SUPER::CData1($newvalue);
- }
- }
- return $ClassData{CData1};
- }
-
-Those dabbling in multiple inheritance might be concerned
-about there being more than one override.
-
- for my $parent (@ISA) {
- my $methname = $parent . "::CData1";
- if ($self->can($methname)) {
- $self->$methname($newvalue);
- }
- }
-
-Because the &UNIVERSAL::can method returns a reference
-to the function directly, you can use this directly
-for a significant performance improvement:
-
- for my $parent (@ISA) {
- if (my $coderef = $self->can($parent . "::CData1")) {
- $self->$coderef($newvalue);
- }
- }
-
-If you override C<UNIVERSAL::can> in your own classes, be sure to return the
-reference appropriately.
-
-=head2 Locking the Door and Throwing Away the Key
-
-As currently implemented, any code within the same scope as the
-file-scoped lexical %ClassData can alter that hash directly. Is that
-ok? Is it acceptable or even desirable to allow other parts of the
-implementation of this class to access class attributes directly?
-
-That depends on how careful you want to be. Think back to the Cosmos
-class. If the &supernova method had directly altered $Cosmos::Stars or
-C<$Cosmos::Cosmos{stars}>, then we wouldn't have been able to reuse the
-class when it came to inventing a Multiverse. So letting even the class
-itself access its own class attributes without the mediating intervention of
-properly designed accessor methods is probably not a good idea after all.
-
-Restricting access to class attributes from the class itself is usually
-not enforceable even in strongly object-oriented languages. But in Perl,
-you can.
-
-Here's one way:
-
- package Some_Class;
-
- { # scope for hiding $CData1
- my $CData1;
- sub CData1 {
- shift; # XXX: unused
- $CData1 = shift if @_;
- return $CData1;
- }
- }
-
- { # scope for hiding $CData2
- my $CData2;
- sub CData2 {
- shift; # XXX: unused
- $CData2 = shift if @_;
- return $CData2;
- }
- }
-
-No one--absolutely no one--is allowed to read or write the class
-attributes without the mediation of the managing accessor method, since
-only that method has access to the lexical variable it's managing.
-This use of mediated access to class attributes is a form of privacy far
-stronger than most OO languages provide.
-
-The repetition of code used to create per-datum accessor methods chafes
-at our Laziness, so we'll again use closures to create similar
-methods.
-
- package Some_Class;
-
- { # scope for ultra-private meta-object for class attributes
- my %ClassData = (
- CData1 => "",
- CData2 => "",
- );
-
- for my $datum (keys %ClassData ) {
- no strict "refs";
- *$datum = sub {
- use strict "refs";
- my ($self, $newvalue) = @_;
- $ClassData{$datum} = $newvalue if @_ > 1;
- return $ClassData{$datum};
- }
- }
-
- }
-
-The closure above can be modified to take inheritance into account using
-the &UNIVERSAL::can method and SUPER as shown previously.
-
-=head2 Translucency Revisited
-
-The Vermin class demonstrates translucency using a package variable,
-eponymously named %Vermin, as its meta-object. If you prefer to
-use absolutely no package variables beyond those necessary to appease
-inheritance or possibly the Exporter, this strategy is closed to you.
-That's too bad, because translucent attributes are an appealing
-technique, so it would be valuable to devise an implementation using
-only lexicals.
-
-There's a second reason why you might wish to avoid the eponymous
-package hash. If you use class names with double-colons in them, you
-would end up poking around somewhere you might not have meant to poke.
-
- package Vermin;
- $class = "Vermin";
- $class->{PopCount}++;
- # accesses $Vermin::Vermin{PopCount}
-
- package Vermin::Noxious;
- $class = "Vermin::Noxious";
- $class->{PopCount}++;
- # accesses $Vermin::Noxious{PopCount}
-
-In the first case, because the class name had no double-colons, we got
-the hash in the current package. But in the second case, instead of
-getting some hash in the current package, we got the hash %Noxious in
-the Vermin package. (The noxious vermin just invaded another package and
-sprayed their data around it. :-) Perl doesn't support relative packages
-in its naming conventions, so any double-colons trigger a fully-qualified
-lookup instead of just looking in the current package.
-
-In practice, it is unlikely that the Vermin class had an existing
-package variable named %Noxious that you just blew away. If you're
-still mistrustful, you could always stake out your own territory
-where you know the rules, such as using Eponymous::Vermin::Noxious or
-Hieronymus::Vermin::Boschious or Leave_Me_Alone::Vermin::Noxious as class
-names instead. Sure, it's in theory possible that someone else has
-a class named Eponymous::Vermin with its own %Noxious hash, but this
-kind of thing is always true. There's no arbiter of package names.
-It's always the case that globals like @Cwd::ISA would collide if more
-than one class uses the same Cwd package.
-
-If this still leaves you with an uncomfortable twinge of paranoia,
-we have another solution for you. There's nothing that says that you
-have to have a package variable to hold a class meta-object, either for
-monadic classes or for translucent attributes. Just code up the methods
-so that they access a lexical instead.
-
-Here's another implementation of the Vermin class with semantics identical
-to those given previously, but this time using no package variables.
-
- package Vermin;
-
-
- # Here's the class meta-object, eponymously named.
- # It holds all class data, and also all instance data
- # so the latter can be used for both initialization
- # and translucency. it's a template.
- my %ClassData = (
- PopCount => 0, # capital for class attributes
- color => "beige", # small for instance attributes
- );
-
- # constructor method
- # invoked as class method or object method
- sub spawn {
- my $obclass = shift;
- my $class = ref($obclass) || $obclass;
- my $self = {};
- bless($self, $class);
- $ClassData{PopCount}++;
- # init fields from invoking object, or omit if
- # invoking object is the class to provide translucency
- %$self = %$obclass if ref $obclass;
- return $self;
- }
-
- # translucent accessor for "color" attribute
- # invoked as class method or object method
- sub color {
- my $self = shift;
-
- # handle class invocation
- unless (ref $self) {
- $ClassData{color} = shift if @_;
- return $ClassData{color}
- }
-
- # handle object invocation
- $self->{color} = shift if @_;
- if (defined $self->{color}) { # not exists!
- return $self->{color};
- } else {
- return $ClassData{color};
- }
- }
-
- # class attribute accessor for "PopCount" attribute
- # invoked as class method or object method
- sub population {
- return $ClassData{PopCount};
- }
-
- # instance destructor; invoked only as object method
- sub DESTROY {
- $ClassData{PopCount}--;
- }
-
- # detect whether an object attribute is translucent
- # (typically?) invoked only as object method
- sub is_translucent {
- my($self, $attr) = @_;
- $self = \%ClassData if !ref $self;
- return !defined $self->{$attr};
- }
-
- # test for presence of attribute in class
- # invoked as class method or object method
- sub has_attribute {
- my($self, $attr) = @_;
- return exists $ClassData{$attr};
- }
-
-=head1 NOTES
-
-Inheritance is a powerful but subtle device, best used only after careful
-forethought and design. Aggregation instead of inheritance is often a
-better approach.
-
-You can't use file-scoped lexicals in conjunction with the SelfLoader
-or the AutoLoader, because they alter the lexical scope in which the
-module's methods wind up getting compiled.
-
-The usual mealy-mouthed package-munging doubtless applies to setting
-up names of object attributes. For example, C<< $self->{ObData1} >>
-should probably be C<< $self->{ __PACKAGE__ . "_ObData1" } >>, but that
-would just confuse the examples.
-
-=head1 SEE ALSO
-
-L<perltoot>, L<perlobj>, L<perlmod>, and L<perlbot>.
-
-The Tie::SecureHash and Class::Data::Inheritable modules from CPAN are
-worth checking out.
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1999 Tom Christiansen.
-All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
-
-=head1 ACKNOWLEDGEMENTS
-
-Russ Allbery, Jon Orwant, Randy Ray, Larry Rosler, Nat Torkington,
-and Stephen Warren all contributed suggestions and corrections to this
-piece. Thanks especially to Damian Conway for his ideas and feedback,
-and without whose indirect prodding I might never have taken the time
-to show others how much Perl has to offer in the way of objects once
-you start thinking outside the tiny little box that today's "popular"
-object-oriented languages enforce.
-
-=head1 HISTORY
-
-Last edit: Sun Feb 4 20:50:28 EST 2001
+=cut
Property changes on: trunk/contrib/perl/pod/perltooc.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perltoot.pod
===================================================================
--- trunk/contrib/perl/pod/perltoot.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perltoot.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,1836 +1,12 @@
+=encoding utf8
+
=head1 NAME
-perltoot - Tom's object-oriented tutorial for perl
+perltoot - This document has been deleted
=head1 DESCRIPTION
-Object-oriented programming is a big seller these days. Some managers
-would rather have objects than sliced bread. Why is that? What's so
-special about an object? Just what I<is> an object anyway?
+For information on OO programming with Perl, please see L<perlootut>
+and L<perlobj>.
-An object is nothing but a way of tucking away complex behaviours into
-a neat little easy-to-use bundle. (This is what professors call
-abstraction.) Smart people who have nothing to do but sit around for
-weeks on end figuring out really hard problems make these nifty
-objects that even regular people can use. (This is what professors call
-software reuse.) Users (well, programmers) can play with this little
-bundle all they want, but they aren't to open it up and mess with the
-insides. Just like an expensive piece of hardware, the contract says
-that you void the warranty if you muck with the cover. So don't do that.
-
-The heart of objects is the class, a protected little private namespace
-full of data and functions. A class is a set of related routines that
-addresses some problem area. You can think of it as a user-defined type.
-The Perl package mechanism, also used for more traditional modules,
-is used for class modules as well. Objects "live" in a class, meaning
-that they belong to some package.
-
-More often than not, the class provides the user with little bundles.
-These bundles are objects. They know whose class they belong to,
-and how to behave. Users ask the class to do something, like "give
-me an object." Or they can ask one of these objects to do something.
-Asking a class to do something for you is calling a I<class method>.
-Asking an object to do something for you is calling an I<object method>.
-Asking either a class (usually) or an object (sometimes) to give you
-back an object is calling a I<constructor>, which is just a
-kind of method.
-
-That's all well and good, but how is an object different from any other
-Perl data type? Just what is an object I<really>; that is, what's its
-fundamental type? The answer to the first question is easy. An object
-is different from any other data type in Perl in one and only one way:
-you may dereference it using not merely string or numeric subscripts
-as with simple arrays and hashes, but with named subroutine calls.
-In a word, with I<methods>.
-
-The answer to the second question is that it's a reference, and not just
-any reference, mind you, but one whose referent has been I<bless>()ed
-into a particular class (read: package). What kind of reference? Well,
-the answer to that one is a bit less concrete. That's because in Perl
-the designer of the class can employ any sort of reference they'd like
-as the underlying intrinsic data type. It could be a scalar, an array,
-or a hash reference. It could even be a code reference. But because
-of its inherent flexibility, an object is usually a hash reference.
-
-=head1 Creating a Class
-
-Before you create a class, you need to decide what to name it. That's
-because the class (package) name governs the name of the file used to
-house it, just as with regular modules. Then, that class (package)
-should provide one or more ways to generate objects. Finally, it should
-provide mechanisms to allow users of its objects to indirectly manipulate
-these objects from a distance.
-
-For example, let's make a simple Person class module. It gets stored in
-the file Person.pm. If it were called a Happy::Person class, it would
-be stored in the file Happy/Person.pm, and its package would become
-Happy::Person instead of just Person. (On a personal computer not
-running Unix or Plan 9, but something like Mac OS or VMS, the directory
-separator may be different, but the principle is the same.) Do not assume
-any formal relationship between modules based on their directory names.
-This is merely a grouping convenience, and has no effect on inheritance,
-variable accessibility, or anything else.
-
-For this module we aren't going to use Exporter, because we're
-a well-behaved class module that doesn't export anything at all.
-In order to manufacture objects, a class needs to have a I<constructor
-method>. A constructor gives you back not just a regular data type,
-but a brand-new object in that class. This magic is taken care of by
-the bless() function, whose sole purpose is to enable its referent to
-be used as an object. Remember: being an object really means nothing
-more than that methods may now be called against it.
-
-While a constructor may be named anything you'd like, most Perl
-programmers seem to like to call theirs new(). However, new() is not
-a reserved word, and a class is under no obligation to supply such.
-Some programmers have also been known to use a function with
-the same name as the class as the constructor.
-
-=head2 Object Representation
-
-By far the most common mechanism used in Perl to represent a Pascal
-record, a C struct, or a C++ class is an anonymous hash. That's because a
-hash has an arbitrary number of data fields, each conveniently accessed by
-an arbitrary name of your own devising.
-
-If you were just doing a simple
-struct-like emulation, you would likely go about it something like this:
-
- $rec = {
- name => "Jason",
- age => 23,
- peers => [ "Norbert", "Rhys", "Phineas"],
- };
-
-If you felt like it, you could add a bit of visual distinction
-by up-casing the hash keys:
-
- $rec = {
- NAME => "Jason",
- AGE => 23,
- PEERS => [ "Norbert", "Rhys", "Phineas"],
- };
-
-And so you could get at C<< $rec->{NAME} >> to find "Jason", or
-C<< @{ $rec->{PEERS} } >> to get at "Norbert", "Rhys", and "Phineas".
-(Have you ever noticed how many 23-year-old programmers seem to
-be named "Jason" these days? :-)
-
-This same model is often used for classes, although it is not considered
-the pinnacle of programming propriety for folks from outside the
-class to come waltzing into an object, brazenly accessing its data
-members directly. Generally speaking, an object should be considered
-an opaque cookie that you use I<object methods> to access. Visually,
-methods look like you're dereffing a reference using a function name
-instead of brackets or braces.
-
-=head2 Class Interface
-
-Some languages provide a formal syntactic interface to a class's methods,
-but Perl does not. It relies on you to read the documentation of each
-class. If you try to call an undefined method on an object, Perl won't
-complain, but the program will trigger an exception while it's running.
-Likewise, if you call a method expecting a prime number as its argument
-with a non-prime one instead, you can't expect the compiler to catch this.
-(Well, you can expect it all you like, but it's not going to happen.)
-
-Let's suppose you have a well-educated user of your Person class,
-someone who has read the docs that explain the prescribed
-interface. Here's how they might use the Person class:
-
- use Person;
-
- $him = Person->new();
- $him->name("Jason");
- $him->age(23);
- $him->peers( "Norbert", "Rhys", "Phineas" );
-
- push @All_Recs, $him; # save object in array for later
-
- printf "%s is %d years old.\n", $him->name, $him->age;
- print "His peers are: ", join(", ", $him->peers), "\n";
-
- printf "Last rec's name is %s\n", $All_Recs[-1]->name;
-
-As you can see, the user of the class doesn't know (or at least, has no
-business paying attention to the fact) that the object has one particular
-implementation or another. The interface to the class and its objects
-is exclusively via methods, and that's all the user of the class should
-ever play with.
-
-=head2 Constructors and Instance Methods
-
-Still, I<someone> has to know what's in the object. And that someone is
-the class. It implements methods that the programmer uses to access
-the object. Here's how to implement the Person class using the standard
-hash-ref-as-an-object idiom. We'll make a class method called new() to
-act as the constructor, and three object methods called name(), age(), and
-peers() to get at per-object data hidden away in our anonymous hash.
-
- package Person;
- use strict;
-
- ##################################################
- ## the object constructor (simplistic version) ##
- ##################################################
- sub new {
- my $self = {};
- $self->{NAME} = undef;
- $self->{AGE} = undef;
- $self->{PEERS} = [];
- bless($self); # but see below
- return $self;
- }
-
- ##############################################
- ## methods to access per-object data ##
- ## ##
- ## With args, they set the value. Without ##
- ## any, they only retrieve it/them. ##
- ##############################################
-
- sub name {
- my $self = shift;
- if (@_) { $self->{NAME} = shift }
- return $self->{NAME};
- }
-
- sub age {
- my $self = shift;
- if (@_) { $self->{AGE} = shift }
- return $self->{AGE};
- }
-
- sub peers {
- my $self = shift;
- if (@_) { @{ $self->{PEERS} } = @_ }
- return @{ $self->{PEERS} };
- }
-
- 1; # so the require or use succeeds
-
-We've created three methods to access an object's data, name(), age(),
-and peers(). These are all substantially similar. If called with an
-argument, they set the appropriate field; otherwise they return the
-value held by that field, meaning the value of that hash key.
-
-=head2 Planning for the Future: Better Constructors
-
-Even though at this point you may not even know what it means, someday
-you're going to worry about inheritance. (You can safely ignore this
-for now and worry about it later if you'd like.) To ensure that this
-all works out smoothly, you must use the double-argument form of bless().
-The second argument is the class into which the referent will be blessed.
-By not assuming our own class as the default second argument and instead
-using the class passed into us, we make our constructor inheritable.
-
- sub new {
- my $class = shift;
- my $self = {};
- $self->{NAME} = undef;
- $self->{AGE} = undef;
- $self->{PEERS} = [];
- bless ($self, $class);
- return $self;
- }
-
-That's about all there is for constructors. These methods bring objects
-to life, returning neat little opaque bundles to the user to be used in
-subsequent method calls.
-
-=head2 Destructors
-
-Every story has a beginning and an end. The beginning of the object's
-story is its constructor, explicitly called when the object comes into
-existence. But the ending of its story is the I<destructor>, a method
-implicitly called when an object leaves this life. Any per-object
-clean-up code is placed in the destructor, which must (in Perl) be called
-DESTROY.
-
-If constructors can have arbitrary names, then why not destructors?
-Because while a constructor is explicitly called, a destructor is not.
-Destruction happens automatically via Perl's garbage collection (GC)
-system, which is a quick but somewhat lazy reference-based GC system.
-To know what to call, Perl insists that the destructor be named DESTROY.
-Perl's notion of the right time to call a destructor is not well-defined
-currently, which is why your destructors should not rely on when they are
-called.
-
-Why is DESTROY in all caps? Perl on occasion uses purely uppercase
-function names as a convention to indicate that the function will
-be automatically called by Perl in some way. Others that are called
-implicitly include BEGIN, END, AUTOLOAD, plus all methods used by
-tied objects, described in L<perltie>.
-
-In really good object-oriented programming languages, the user doesn't
-care when the destructor is called. It just happens when it's supposed
-to. In low-level languages without any GC at all, there's no way to
-depend on this happening at the right time, so the programmer must
-explicitly call the destructor to clean up memory and state, crossing
-their fingers that it's the right time to do so. Unlike C++, an
-object destructor is nearly never needed in Perl, and even when it is,
-explicit invocation is uncalled for. In the case of our Person class,
-we don't need a destructor because Perl takes care of simple matters
-like memory deallocation.
-
-The only situation where Perl's reference-based GC won't work is
-when there's a circularity in the data structure, such as:
-
- $this->{WHATEVER} = $this;
-
-In that case, you must delete the self-reference manually if you expect
-your program not to leak memory. While admittedly error-prone, this is
-the best we can do right now. Nonetheless, rest assured that when your
-program is finished, its objects' destructors are all duly called.
-So you are guaranteed that an object I<eventually> gets properly
-destroyed, except in the unique case of a program that never exits.
-(If you're running Perl embedded in another application, this full GC
-pass happens a bit more frequently--whenever a thread shuts down.)
-
-=head2 Other Object Methods
-
-The methods we've talked about so far have either been constructors or
-else simple "data methods", interfaces to data stored in the object.
-These are a bit like an object's data members in the C++ world, except
-that strangers don't access them as data. Instead, they should only
-access the object's data indirectly via its methods. This is an
-important rule: in Perl, access to an object's data should I<only>
-be made through methods.
-
-Perl doesn't impose restrictions on who gets to use which methods.
-The public-versus-private distinction is by convention, not syntax.
-(Well, unless you use the Alias module described below in
-L<Data Members as Variables>.) Occasionally you'll see method names beginning or ending
-with an underscore or two. This marking is a convention indicating
-that the methods are private to that class alone and sometimes to its
-closest acquaintances, its immediate subclasses. But this distinction
-is not enforced by Perl itself. It's up to the programmer to behave.
-
-There's no reason to limit methods to those that simply access data.
-Methods can do anything at all. The key point is that they're invoked
-against an object or a class. Let's say we'd like object methods that
-do more than fetch or set one particular field.
-
- sub exclaim {
- my $self = shift;
- return sprintf "Hi, I'm %s, age %d, working with %s",
- $self->{NAME}, $self->{AGE}, join(", ", @{$self->{PEERS}});
- }
-
-Or maybe even one like this:
-
- sub happy_birthday {
- my $self = shift;
- return ++$self->{AGE};
- }
-
-Some might argue that one should go at these this way:
-
- sub exclaim {
- my $self = shift;
- return sprintf "Hi, I'm %s, age %d, working with %s",
- $self->name, $self->age, join(", ", $self->peers);
- }
-
- sub happy_birthday {
- my $self = shift;
- return $self->age( $self->age() + 1 );
- }
-
-But since these methods are all executing in the class itself, this
-may not be critical. There are tradeoffs to be made. Using direct
-hash access is faster (about an order of magnitude faster, in fact), and
-it's more convenient when you want to interpolate in strings. But using
-methods (the external interface) internally shields not just the users of
-your class but even you yourself from changes in your data representation.
-
-=head1 Class Data
-
-What about "class data", data items common to each object in a class?
-What would you want that for? Well, in your Person class, you might
-like to keep track of the total people alive. How do you implement that?
-
-You I<could> make it a global variable called $Person::Census. But about
-only reason you'd do that would be if you I<wanted> people to be able to
-get at your class data directly. They could just say $Person::Census
-and play around with it. Maybe this is ok in your design scheme.
-You might even conceivably want to make it an exported variable. To be
-exportable, a variable must be a (package) global. If this were a
-traditional module rather than an object-oriented one, you might do that.
-
-While this approach is expected in most traditional modules, it's
-generally considered rather poor form in most object modules. In an
-object module, you should set up a protective veil to separate interface
-from implementation. So provide a class method to access class data
-just as you provide object methods to access object data.
-
-So, you I<could> still keep $Census as a package global and rely upon
-others to honor the contract of the module and therefore not play around
-with its implementation. You could even be supertricky and make $Census a
-tied object as described in L<perltie>, thereby intercepting all accesses.
-
-But more often than not, you just want to make your class data a
-file-scoped lexical. To do so, simply put this at the top of the file:
-
- my $Census = 0;
-
-Even though the scope of a my() normally expires when the block in which
-it was declared is done (in this case the whole file being required or
-used), Perl's deep binding of lexical variables guarantees that the
-variable will not be deallocated, remaining accessible to functions
-declared within that scope. This doesn't work with global variables
-given temporary values via local(), though.
-
-Irrespective of whether you leave $Census a package global or make
-it instead a file-scoped lexical, you should make these
-changes to your Person::new() constructor:
-
- sub new {
- my $class = shift;
- my $self = {};
- $Census++;
- $self->{NAME} = undef;
- $self->{AGE} = undef;
- $self->{PEERS} = [];
- bless ($self, $class);
- return $self;
- }
-
- sub population {
- return $Census;
- }
-
-Now that we've done this, we certainly do need a destructor so that
-when Person is destroyed, the $Census goes down. Here's how
-this could be done:
-
- sub DESTROY { --$Census }
-
-Notice how there's no memory to deallocate in the destructor? That's
-something that Perl takes care of for you all by itself.
-
-Alternatively, you could use the Class::Data::Inheritable module from
-CPAN.
-
-
-=head2 Accessing Class Data
-
-It turns out that this is not really a good way to go about handling
-class data. A good scalable rule is that I<you must never reference class
-data directly from an object method>. Otherwise you aren't building a
-scalable, inheritable class. The object must be the rendezvous point
-for all operations, especially from an object method. The globals
-(class data) would in some sense be in the "wrong" package in your
-derived classes. In Perl, methods execute in the context of the class
-they were defined in, I<not> that of the object that triggered them.
-Therefore, namespace visibility of package globals in methods is unrelated
-to inheritance.
-
-Got that? Maybe not. Ok, let's say that some other class "borrowed"
-(well, inherited) the DESTROY method as it was defined above. When those
-objects are destroyed, the original $Census variable will be altered,
-not the one in the new class's package namespace. Perhaps this is what
-you want, but probably it isn't.
-
-Here's how to fix this. We'll store a reference to the data in the
-value accessed by the hash key "_CENSUS". Why the underscore? Well,
-mostly because an initial underscore already conveys strong feelings
-of magicalness to a C programmer. It's really just a mnemonic device
-to remind ourselves that this field is special and not to be used as
-a public data member in the same way that NAME, AGE, and PEERS are.
-(Because we've been developing this code under the strict pragma, prior
-to perl version 5.004 we'll have to quote the field name.)
-
- sub new {
- my $class = shift;
- my $self = {};
- $self->{NAME} = undef;
- $self->{AGE} = undef;
- $self->{PEERS} = [];
- # "private" data
- $self->{"_CENSUS"} = \$Census;
- bless ($self, $class);
- ++ ${ $self->{"_CENSUS"} };
- return $self;
- }
-
- sub population {
- my $self = shift;
- if (ref $self) {
- return ${ $self->{"_CENSUS"} };
- } else {
- return $Census;
- }
- }
-
- sub DESTROY {
- my $self = shift;
- -- ${ $self->{"_CENSUS"} };
- }
-
-=head2 Debugging Methods
-
-It's common for a class to have a debugging mechanism. For example,
-you might want to see when objects are created or destroyed. To do that,
-add a debugging variable as a file-scoped lexical. For this, we'll pull
-in the standard Carp module to emit our warnings and fatal messages.
-That way messages will come out with the caller's filename and
-line number instead of our own; if we wanted them to be from our own
-perspective, we'd just use die() and warn() directly instead of croak()
-and carp() respectively.
-
- use Carp;
- my $Debugging = 0;
-
-Now add a new class method to access the variable.
-
- sub debug {
- my $class = shift;
- if (ref $class) { confess "Class method called as object method" }
- unless (@_ == 1) { confess "usage: CLASSNAME->debug(level)" }
- $Debugging = shift;
- }
-
-Now fix up DESTROY to murmur a bit as the moribund object expires:
-
- sub DESTROY {
- my $self = shift;
- if ($Debugging) { carp "Destroying $self " . $self->name }
- -- ${ $self->{"_CENSUS"} };
- }
-
-One could conceivably make a per-object debug state. That
-way you could call both of these:
-
- Person->debug(1); # entire class
- $him->debug(1); # just this object
-
-To do so, we need our debugging method to be a "bimodal" one, one that
-works on both classes I<and> objects. Therefore, adjust the debug()
-and DESTROY methods as follows:
-
- sub debug {
- my $self = shift;
- confess "usage: thing->debug(level)" unless @_ == 1;
- my $level = shift;
- if (ref($self)) {
- $self->{"_DEBUG"} = $level; # just myself
- } else {
- $Debugging = $level; # whole class
- }
- }
-
- sub DESTROY {
- my $self = shift;
- if ($Debugging || $self->{"_DEBUG"}) {
- carp "Destroying $self " . $self->name;
- }
- -- ${ $self->{"_CENSUS"} };
- }
-
-What happens if a derived class (which we'll call Employee) inherits
-methods from this Person base class? Then C<< Employee->debug() >>, when called
-as a class method, manipulates $Person::Debugging not $Employee::Debugging.
-
-=head2 Class Destructors
-
-The object destructor handles the death of each distinct object. But sometimes
-you want a bit of cleanup when the entire class is shut down, which
-currently only happens when the program exits. To make such a
-I<class destructor>, create a function in that class's package named
-END. This works just like the END function in traditional modules,
-meaning that it gets called whenever your program exits unless it execs
-or dies of an uncaught signal. For example,
-
- sub END {
- if ($Debugging) {
- print "All persons are going away now.\n";
- }
- }
-
-When the program exits, all the class destructors (END functions) are
-be called in the opposite order that they were loaded in (LIFO order).
-
-=head2 Documenting the Interface
-
-And there you have it: we've just shown you the I<implementation> of this
-Person class. Its I<interface> would be its documentation. Usually this
-means putting it in pod ("plain old documentation") format right there
-in the same file. In our Person example, we would place the following
-docs anywhere in the Person.pm file. Even though it looks mostly like
-code, it's not. It's embedded documentation such as would be used by
-the pod2man, pod2html, or pod2text programs. The Perl compiler ignores
-pods entirely, just as the translators ignore code. Here's an example of
-some pods describing the informal interface:
-
- =head1 NAME
-
- Person - class to implement people
-
- =head1 SYNOPSIS
-
- use Person;
-
- #################
- # class methods #
- #################
- $ob = Person->new;
- $count = Person->population;
-
- #######################
- # object data methods #
- #######################
-
- ### get versions ###
- $who = $ob->name;
- $years = $ob->age;
- @pals = $ob->peers;
-
- ### set versions ###
- $ob->name("Jason");
- $ob->age(23);
- $ob->peers( "Norbert", "Rhys", "Phineas" );
-
- ########################
- # other object methods #
- ########################
-
- $phrase = $ob->exclaim;
- $ob->happy_birthday;
-
- =head1 DESCRIPTION
-
- The Person class implements dah dee dah dee dah....
-
-That's all there is to the matter of interface versus implementation.
-A programmer who opens up the module and plays around with all the private
-little shiny bits that were safely locked up behind the interface contract
-has voided the warranty, and you shouldn't worry about their fate.
-
-=head1 Aggregation
-
-Suppose you later want to change the class to implement better names.
-Perhaps you'd like to support both given names (called Christian names,
-irrespective of one's religion) and family names (called surnames), plus
-nicknames and titles. If users of your Person class have been properly
-accessing it through its documented interface, then you can easily change
-the underlying implementation. If they haven't, then they lose and
-it's their fault for breaking the contract and voiding their warranty.
-
-To do this, we'll make another class, this one called Fullname. What's
-the Fullname class look like? To answer that question, you have to
-first figure out how you want to use it. How about we use it this way:
-
- $him = Person->new();
- $him->fullname->title("St");
- $him->fullname->christian("Thomas");
- $him->fullname->surname("Aquinas");
- $him->fullname->nickname("Tommy");
- printf "His normal name is %s\n", $him->name;
- printf "But his real name is %s\n", $him->fullname->as_string;
-
-Ok. To do this, we'll change Person::new() so that it supports
-a full name field this way:
-
- sub new {
- my $class = shift;
- my $self = {};
- $self->{FULLNAME} = Fullname->new();
- $self->{AGE} = undef;
- $self->{PEERS} = [];
- $self->{"_CENSUS"} = \$Census;
- bless ($self, $class);
- ++ ${ $self->{"_CENSUS"} };
- return $self;
- }
-
- sub fullname {
- my $self = shift;
- return $self->{FULLNAME};
- }
-
-Then to support old code, define Person::name() this way:
-
- sub name {
- my $self = shift;
- return $self->{FULLNAME}->nickname(@_)
- || $self->{FULLNAME}->christian(@_);
- }
-
-Here's the Fullname class. We'll use the same technique
-of using a hash reference to hold data fields, and methods
-by the appropriate name to access them:
-
- package Fullname;
- use strict;
-
- sub new {
- my $class = shift;
- my $self = {
- TITLE => undef,
- CHRISTIAN => undef,
- SURNAME => undef,
- NICK => undef,
- };
- bless ($self, $class);
- return $self;
- }
-
- sub christian {
- my $self = shift;
- if (@_) { $self->{CHRISTIAN} = shift }
- return $self->{CHRISTIAN};
- }
-
- sub surname {
- my $self = shift;
- if (@_) { $self->{SURNAME} = shift }
- return $self->{SURNAME};
- }
-
- sub nickname {
- my $self = shift;
- if (@_) { $self->{NICK} = shift }
- return $self->{NICK};
- }
-
- sub title {
- my $self = shift;
- if (@_) { $self->{TITLE} = shift }
- return $self->{TITLE};
- }
-
- sub as_string {
- my $self = shift;
- my $name = join(" ", @$self{'CHRISTIAN', 'SURNAME'});
- if ($self->{TITLE}) {
- $name = $self->{TITLE} . " " . $name;
- }
- return $name;
- }
-
- 1;
-
-Finally, here's the test program:
-
- #!/usr/bin/perl -w
- use strict;
- use Person;
- sub END { show_census() }
-
- sub show_census () {
- printf "Current population: %d\n", Person->population;
- }
-
- Person->debug(1);
-
- show_census();
-
- my $him = Person->new();
-
- $him->fullname->christian("Thomas");
- $him->fullname->surname("Aquinas");
- $him->fullname->nickname("Tommy");
- $him->fullname->title("St");
- $him->age(1);
-
- printf "%s is really %s.\n", $him->name, $him->fullname->as_string;
- printf "%s's age: %d.\n", $him->name, $him->age;
- $him->happy_birthday;
- printf "%s's age: %d.\n", $him->name, $him->age;
-
- show_census();
-
-=head1 Inheritance
-
-Object-oriented programming systems all support some notion of
-inheritance. Inheritance means allowing one class to piggy-back on
-top of another one so you don't have to write the same code again and
-again. It's about software reuse, and therefore related to Laziness,
-the principal virtue of a programmer. (The import/export mechanisms in
-traditional modules are also a form of code reuse, but a simpler one than
-the true inheritance that you find in object modules.)
-
-Sometimes the syntax of inheritance is built into the core of the
-language, and sometimes it's not. Perl has no special syntax for
-specifying the class (or classes) to inherit from. Instead, it's all
-strictly in the semantics. Each package can have a variable called @ISA,
-which governs (method) inheritance. If you try to call a method on an
-object or class, and that method is not found in that object's package,
-Perl then looks to @ISA for other packages to go looking through in
-search of the missing method.
-
-Like the special per-package variables recognized by Exporter (such as
- at EXPORT, @EXPORT_OK, @EXPORT_FAIL, %EXPORT_TAGS, and $VERSION), the @ISA
-array I<must> be a package-scoped global and not a file-scoped lexical
-created via my(). Most classes have just one item in their @ISA array.
-In this case, we have what's called "single inheritance", or SI for short.
-
-Consider this class:
-
- package Employee;
- use Person;
- @ISA = ("Person");
- 1;
-
-Not a lot to it, eh? All it's doing so far is loading in another
-class and stating that this one will inherit methods from that
-other class if need be. We have given it none of its own methods.
-We rely upon an Employee to behave just like a Person.
-
-Setting up an empty class like this is called the "empty subclass test";
-that is, making a derived class that does nothing but inherit from a
-base class. If the original base class has been designed properly,
-then the new derived class can be used as a drop-in replacement for the
-old one. This means you should be able to write a program like this:
-
- use Employee;
- my $empl = Employee->new();
- $empl->name("Jason");
- $empl->age(23);
- printf "%s is age %d.\n", $empl->name, $empl->age;
-
-By proper design, we mean always using the two-argument form of bless(),
-avoiding direct access of global data, and not exporting anything. If you
-look back at the Person::new() function we defined above, we were careful
-to do that. There's a bit of package data used in the constructor,
-but the reference to this is stored on the object itself and all other
-methods access package data via that reference, so we should be ok.
-
-What do we mean by the Person::new() function? Isn't that actually
-a method? Well, in principle, yes. A method is just a function that
-expects as its first argument a class name (package) or object
-(blessed reference). Person::new() is the function that both the
-C<< Person->new() >> method and the C<< Employee->new() >> method end
-up calling. Understand that while a method call looks a lot like a
-function call, they aren't really quite the same, and if you treat them
-as the same, you'll very soon be left with nothing but broken programs.
-First, the actual underlying calling conventions are different: method
-calls get an extra argument. Second, function calls don't do inheritance,
-but methods do.
-
- Method Call Resulting Function Call
- ----------- ------------------------
- Person->new() Person::new("Person")
- Employee->new() Person::new("Employee")
-
-So don't use function calls when you mean to call a method.
-
-If an employee is just a Person, that's not all too very interesting.
-So let's add some other methods. We'll give our employee
-data fields to access their salary, their employee ID, and their
-start date.
-
-If you're getting a little tired of creating all these nearly identical
-methods just to get at the object's data, do not despair. Later,
-we'll describe several different convenience mechanisms for shortening
-this up. Meanwhile, here's the straight-forward way:
-
- sub salary {
- my $self = shift;
- if (@_) { $self->{SALARY} = shift }
- return $self->{SALARY};
- }
-
- sub id_number {
- my $self = shift;
- if (@_) { $self->{ID} = shift }
- return $self->{ID};
- }
-
- sub start_date {
- my $self = shift;
- if (@_) { $self->{START_DATE} = shift }
- return $self->{START_DATE};
- }
-
-=head2 Overridden Methods
-
-What happens when both a derived class and its base class have the same
-method defined? Well, then you get the derived class's version of that
-method. For example, let's say that we want the peers() method called on
-an employee to act a bit differently. Instead of just returning the list
-of peer names, let's return slightly different strings. So doing this:
-
- $empl->peers("Peter", "Paul", "Mary");
- printf "His peers are: %s\n", join(", ", $empl->peers);
-
-will produce:
-
- His peers are: PEON=PETER, PEON=PAUL, PEON=MARY
-
-To do this, merely add this definition into the Employee.pm file:
-
- sub peers {
- my $self = shift;
- if (@_) { @{ $self->{PEERS} } = @_ }
- return map { "PEON=\U$_" } @{ $self->{PEERS} };
- }
-
-There, we've just demonstrated the high-falutin' concept known in certain
-circles as I<polymorphism>. We've taken on the form and behaviour of
-an existing object, and then we've altered it to suit our own purposes.
-This is a form of Laziness. (Getting polymorphed is also what happens
-when the wizard decides you'd look better as a frog.)
-
-Every now and then you'll want to have a method call trigger both its
-derived class (also known as "subclass") version as well as its base class
-(also known as "superclass") version. In practice, constructors and
-destructors are likely to want to do this, and it probably also makes
-sense in the debug() method we showed previously.
-
-To do this, add this to Employee.pm:
-
- use Carp;
- my $Debugging = 0;
-
- sub debug {
- my $self = shift;
- confess "usage: thing->debug(level)" unless @_ == 1;
- my $level = shift;
- if (ref($self)) {
- $self->{"_DEBUG"} = $level;
- } else {
- $Debugging = $level; # whole class
- }
- Person::debug($self, $Debugging); # don't really do this
- }
-
-As you see, we turn around and call the Person package's debug() function.
-But this is far too fragile for good design. What if Person doesn't
-have a debug() function, but is inheriting I<its> debug() method
-from elsewhere? It would have been slightly better to say
-
- Person->debug($Debugging);
-
-But even that's got too much hard-coded. It's somewhat better to say
-
- $self->Person::debug($Debugging);
-
-Which is a funny way to say to start looking for a debug() method up
-in Person. This strategy is more often seen on overridden object methods
-than on overridden class methods.
-
-There is still something a bit off here. We've hard-coded our
-superclass's name. This in particular is bad if you change which classes
-you inherit from, or add others. Fortunately, the pseudoclass SUPER
-comes to the rescue here.
-
- $self->SUPER::debug($Debugging);
-
-This way it starts looking in my class's @ISA. This only makes sense
-from I<within> a method call, though. Don't try to access anything
-in SUPER:: from anywhere else, because it doesn't exist outside
-an overridden method call. Note that C<SUPER> refers to the superclass of
-the current package, I<not> to the superclass of C<$self>.
-
-Things are getting a bit complicated here. Have we done anything
-we shouldn't? As before, one way to test whether we're designing
-a decent class is via the empty subclass test. Since we already have
-an Employee class that we're trying to check, we'd better get a new
-empty subclass that can derive from Employee. Here's one:
-
- package Boss;
- use Employee; # :-)
- @ISA = qw(Employee);
-
-And here's the test program:
-
- #!/usr/bin/perl -w
- use strict;
- use Boss;
- Boss->debug(1);
-
- my $boss = Boss->new();
-
- $boss->fullname->title("Don");
- $boss->fullname->surname("Pichon Alvarez");
- $boss->fullname->christian("Federico Jesus");
- $boss->fullname->nickname("Fred");
-
- $boss->age(47);
- $boss->peers("Frank", "Felipe", "Faust");
-
- printf "%s is age %d.\n", $boss->fullname->as_string, $boss->age;
- printf "His peers are: %s\n", join(", ", $boss->peers);
-
-Running it, we see that we're still ok. If you'd like to dump out your
-object in a nice format, somewhat like the way the 'x' command works in
-the debugger, you could use the Data::Dumper module from CPAN this way:
-
- use Data::Dumper;
- print "Here's the boss:\n";
- print Dumper($boss);
-
-Which shows us something like this:
-
- Here's the boss:
- $VAR1 = bless( {
- _CENSUS => \1,
- FULLNAME => bless( {
- TITLE => 'Don',
- SURNAME => 'Pichon Alvarez',
- NICK => 'Fred',
- CHRISTIAN => 'Federico Jesus'
- }, 'Fullname' ),
- AGE => 47,
- PEERS => [
- 'Frank',
- 'Felipe',
- 'Faust'
- ]
- }, 'Boss' );
-
-Hm.... something's missing there. What about the salary, start date,
-and ID fields? Well, we never set them to anything, even undef, so they
-don't show up in the hash's keys. The Employee class has no new() method
-of its own, and the new() method in Person doesn't know about Employees.
-(Nor should it: proper OO design dictates that a subclass be allowed to
-know about its immediate superclass, but never vice-versa.) So let's
-fix up Employee::new() this way:
-
- sub new {
- my $class = shift;
- my $self = $class->SUPER::new();
- $self->{SALARY} = undef;
- $self->{ID} = undef;
- $self->{START_DATE} = undef;
- bless ($self, $class); # reconsecrate
- return $self;
- }
-
-Now if you dump out an Employee or Boss object, you'll find
-that new fields show up there now.
-
-=head2 Multiple Inheritance
-
-Ok, at the risk of confusing beginners and annoying OO gurus, it's
-time to confess that Perl's object system includes that controversial
-notion known as multiple inheritance, or MI for short. All this means
-is that rather than having just one parent class who in turn might
-itself have a parent class, etc., that you can directly inherit from
-two or more parents. It's true that some uses of MI can get you into
-trouble, although hopefully not quite so much trouble with Perl as with
-dubiously-OO languages like C++.
-
-The way it works is actually pretty simple: just put more than one package
-name in your @ISA array. When it comes time for Perl to go finding
-methods for your object, it looks at each of these packages in order.
-Well, kinda. It's actually a fully recursive, depth-first order by
-default (see L<mro> for alternate method resolution orders).
-Consider a bunch of @ISA arrays like this:
-
- @First::ISA = qw( Alpha );
- @Second::ISA = qw( Beta );
- @Third::ISA = qw( First Second );
-
-If you have an object of class Third:
-
- my $ob = Third->new();
- $ob->spin();
-
-How do we find a spin() method (or a new() method for that matter)?
-Because the search is depth-first, classes will be looked up
-in the following order: Third, First, Alpha, Second, and Beta.
-
-In practice, few class modules have been seen that actually
-make use of MI. One nearly always chooses simple containership of
-one class within another over MI. That's why our Person
-object I<contained> a Fullname object. That doesn't mean
-it I<was> one.
-
-However, there is one particular area where MI in Perl is rampant:
-borrowing another class's class methods. This is rather common,
-especially with some bundled "objectless" classes,
-like Exporter, DynaLoader, AutoLoader, and SelfLoader. These classes
-do not provide constructors; they exist only so you may inherit their
-class methods. (It's not entirely clear why inheritance was done
-here rather than traditional module importation.)
-
-For example, here is the POSIX module's @ISA:
-
- package POSIX;
- @ISA = qw(Exporter DynaLoader);
-
-The POSIX module isn't really an object module, but then,
-neither are Exporter or DynaLoader. They're just lending their
-classes' behaviours to POSIX.
-
-Why don't people use MI for object methods much? One reason is that
-it can have complicated side-effects. For one thing, your inheritance
-graph (no longer a tree) might converge back to the same base class.
-Although Perl guards against recursive inheritance, merely having parents
-who are related to each other via a common ancestor, incestuous though
-it sounds, is not forbidden. What if in our Third class shown above we
-wanted its new() method to also call both overridden constructors in its
-two parent classes? The SUPER notation would only find the first one.
-Also, what about if the Alpha and Beta classes both had a common ancestor,
-like Nought? If you kept climbing up the inheritance tree calling
-overridden methods, you'd end up calling Nought::new() twice,
-which might well be a bad idea.
-
-=head2 UNIVERSAL: The Root of All Objects
-
-Wouldn't it be convenient if all objects were rooted at some ultimate
-base class? That way you could give every object common methods without
-having to go and add it to each and every @ISA. Well, it turns out that
-you can. You don't see it, but Perl tacitly and irrevocably assumes
-that there's an extra element at the end of @ISA: the class UNIVERSAL.
-In version 5.003, there were no predefined methods there, but you could put
-whatever you felt like into it.
-
-However, as of version 5.004 (or some subversive releases, like 5.003_08),
-UNIVERSAL has some methods in it already. These are builtin to your Perl
-binary, so they don't take any extra time to load. Predefined methods
-include isa(), can(), and VERSION(). isa() tells you whether an object or
-class "is" another one without having to traverse the hierarchy yourself:
-
- $has_io = $fd->isa("IO::Handle");
- $itza_handle = IO::Socket->isa("IO::Handle");
-
-The can() method, called against that object or class, reports back
-whether its string argument is a callable method name in that class.
-In fact, it gives you back a function reference to that method:
-
- $his_print_method = $obj->can('as_string');
-
-Finally, the VERSION method checks whether the class (or the object's
-class) has a package global called $VERSION that's high enough, as in:
-
- Some_Module->VERSION(3.0);
- $his_vers = $ob->VERSION();
-
-However, we don't usually call VERSION ourselves. (Remember that an all
-uppercase function name is a Perl convention that indicates that the
-function will be automatically used by Perl in some way.) In this case,
-it happens when you say
-
- use Some_Module 3.0;
-
-If you wanted to add version checking to your Person class explained
-above, just add this to Person.pm:
-
- our $VERSION = '1.1';
-
-and then in Employee.pm you can say
-
- use Person 1.1;
-
-And it would make sure that you have at least that version number or
-higher available. This is not the same as loading in that exact version
-number. No mechanism currently exists for concurrent installation of
-multiple versions of a module. Lamentably.
-
-=head2 Deeper UNIVERSAL details
-
-It is also valid (though perhaps unwise in most cases) to put other
-packages' names in @UNIVERSAL::ISA. These packages will also be
-implicitly inherited by all classes, just as UNIVERSAL itself is.
-However, neither UNIVERSAL nor any of its parents from the @ISA tree
-are explicit base classes of all objects. To clarify, given the
-following:
-
- @UNIVERSAL::ISA = ('REALLYUNIVERSAL');
-
- package REALLYUNIVERSAL;
- sub special_method { return "123" }
-
- package Foo;
- sub normal_method { return "321" }
-
-Calling Foo->special_method() will return "123", but calling
-Foo->isa('REALLYUNIVERSAL') or Foo->isa('UNIVERSAL') will return
-false.
-
-If your class is using an alternate mro like C3 (see
-L<mro>), method resolution within UNIVERSAL / @UNIVERSAL::ISA will
-still occur in the default depth-first left-to-right manner,
-after the class's C3 mro is exhausted.
-
-All of the above is made more intuitive by realizing what really
-happens during method lookup, which is roughly like this
-ugly pseudo-code:
-
- get_mro(class) {
- # recurses down the @ISA's starting at class,
- # builds a single linear array of all
- # classes to search in the appropriate order.
- # The method resolution order (mro) to use
- # for the ordering is whichever mro "class"
- # has set on it (either default (depth first
- # l-to-r) or C3 ordering).
- # The first entry in the list is the class
- # itself.
- }
-
- find_method(class, methname) {
- foreach $class (get_mro(class)) {
- if($class->has_method(methname)) {
- return ref_to($class->$methname);
- }
- }
- foreach $class (get_mro(UNIVERSAL)) {
- if($class->has_method(methname)) {
- return ref_to($class->$methname);
- }
- }
- return undef;
- }
-
-However the code that implements UNIVERSAL::isa does not
-search in UNIVERSAL itself, only in the package's actual
- at ISA.
-
-=head1 Alternate Object Representations
-
-Nothing requires objects to be implemented as hash references. An object
-can be any sort of reference so long as its referent has been suitably
-blessed. That means scalar, array, and code references are also fair
-game.
-
-A scalar would work if the object has only one datum to hold. An array
-would work for most cases, but makes inheritance a bit dodgy because
-you have to invent new indices for the derived classes.
-
-=head2 Arrays as Objects
-
-If the user of your class honors the contract and sticks to the advertised
-interface, then you can change its underlying interface if you feel
-like it. Here's another implementation that conforms to the same
-interface specification. This time we'll use an array reference
-instead of a hash reference to represent the object.
-
- package Person;
- use strict;
-
- my($NAME, $AGE, $PEERS) = ( 0 .. 2 );
-
- ############################################
- ## the object constructor (array version) ##
- ############################################
- sub new {
- my $self = [];
- $self->[$NAME] = undef; # this is unnecessary
- $self->[$AGE] = undef; # as is this
- $self->[$PEERS] = []; # but this isn't, really
- bless($self);
- return $self;
- }
-
- sub name {
- my $self = shift;
- if (@_) { $self->[$NAME] = shift }
- return $self->[$NAME];
- }
-
- sub age {
- my $self = shift;
- if (@_) { $self->[$AGE] = shift }
- return $self->[$AGE];
- }
-
- sub peers {
- my $self = shift;
- if (@_) { @{ $self->[$PEERS] } = @_ }
- return @{ $self->[$PEERS] };
- }
-
- 1; # so the require or use succeeds
-
-You might guess that the array access would be a lot faster than the
-hash access, but they're actually comparable. The array is a I<little>
-bit faster, but not more than ten or fifteen percent, even when you
-replace the variables above like $AGE with literal numbers, like 1.
-A bigger difference between the two approaches can be found in memory use.
-A hash representation takes up more memory than an array representation
-because you have to allocate memory for the keys as well as for the values.
-However, it really isn't that bad, especially since as of version 5.004,
-memory is only allocated once for a given hash key, no matter how many
-hashes have that key. It's expected that sometime in the future, even
-these differences will fade into obscurity as more efficient underlying
-representations are devised.
-
-Still, the tiny edge in speed (and somewhat larger one in memory)
-is enough to make some programmers choose an array representation
-for simple classes. There's still a little problem with
-scalability, though, because later in life when you feel
-like creating subclasses, you'll find that hashes just work
-out better.
-
-=head2 Closures as Objects
-
-Using a code reference to represent an object offers some fascinating
-possibilities. We can create a new anonymous function (closure) who
-alone in all the world can see the object's data. This is because we
-put the data into an anonymous hash that's lexically visible only to
-the closure we create, bless, and return as the object. This object's
-methods turn around and call the closure as a regular subroutine call,
-passing it the field we want to affect. (Yes,
-the double-function call is slow, but if you wanted fast, you wouldn't
-be using objects at all, eh? :-)
-
-Use would be similar to before:
-
- use Person;
- $him = Person->new();
- $him->name("Jason");
- $him->age(23);
- $him->peers( [ "Norbert", "Rhys", "Phineas" ] );
- printf "%s is %d years old.\n", $him->name, $him->age;
- print "His peers are: ", join(", ", @{$him->peers}), "\n";
-
-but the implementation would be radically, perhaps even sublimely
-different:
-
- package Person;
-
- sub new {
- my $class = shift;
- my $self = {
- NAME => undef,
- AGE => undef,
- PEERS => [],
- };
- my $closure = sub {
- my $field = shift;
- if (@_) { $self->{$field} = shift }
- return $self->{$field};
- };
- bless($closure, $class);
- return $closure;
- }
-
- sub name { &{ $_[0] }("NAME", @_[ 1 .. $#_ ] ) }
- sub age { &{ $_[0] }("AGE", @_[ 1 .. $#_ ] ) }
- sub peers { &{ $_[0] }("PEERS", @_[ 1 .. $#_ ] ) }
-
- 1;
-
-Because this object is hidden behind a code reference, it's probably a bit
-mysterious to those whose background is more firmly rooted in standard
-procedural or object-based programming languages than in functional
-programming languages whence closures derive. The object
-created and returned by the new() method is itself not a data reference
-as we've seen before. It's an anonymous code reference that has within
-it access to a specific version (lexical binding and instantiation)
-of the object's data, which are stored in the private variable $self.
-Although this is the same function each time, it contains a different
-version of $self.
-
-When a method like C<$him-E<gt>name("Jason")> is called, its implicit
-zeroth argument is the invoking object--just as it is with all method
-calls. But in this case, it's our code reference (something like a
-function pointer in C++, but with deep binding of lexical variables).
-There's not a lot to be done with a code reference beyond calling it, so
-that's just what we do when we say C<&{$_[0]}>. This is just a regular
-function call, not a method call. The initial argument is the string
-"NAME", and any remaining arguments are whatever had been passed to the
-method itself.
-
-Once we're executing inside the closure that had been created in new(),
-the $self hash reference suddenly becomes visible. The closure grabs
-its first argument ("NAME" in this case because that's what the name()
-method passed it), and uses that string to subscript into the private
-hash hidden in its unique version of $self.
-
-Nothing under the sun will allow anyone outside the executing method to
-be able to get at this hidden data. Well, nearly nothing. You I<could>
-single step through the program using the debugger and find out the
-pieces while you're in the method, but everyone else is out of luck.
-
-There, if that doesn't excite the Scheme folks, then I just don't know
-what will. Translation of this technique into C++, Java, or any other
-braindead-static language is left as a futile exercise for aficionados
-of those camps.
-
-You could even add a bit of nosiness via the caller() function and
-make the closure refuse to operate unless called via its own package.
-This would no doubt satisfy certain fastidious concerns of programming
-police and related puritans.
-
-If you were wondering when Hubris, the third principle virtue of a
-programmer, would come into play, here you have it. (More seriously,
-Hubris is just the pride in craftsmanship that comes from having written
-a sound bit of well-designed code.)
-
-=head1 AUTOLOAD: Proxy Methods
-
-Autoloading is a way to intercept calls to undefined methods. An autoload
-routine may choose to create a new function on the fly, either loaded
-from disk or perhaps just eval()ed right there. This define-on-the-fly
-strategy is why it's called autoloading.
-
-But that's only one possible approach. Another one is to just
-have the autoloaded method itself directly provide the
-requested service. When used in this way, you may think
-of autoloaded methods as "proxy" methods.
-
-When Perl tries to call an undefined function in a particular package
-and that function is not defined, it looks for a function in
-that same package called AUTOLOAD. If one exists, it's called
-with the same arguments as the original function would have had.
-The fully-qualified name of the function is stored in that package's
-global variable $AUTOLOAD. Once called, the function can do anything
-it would like, including defining a new function by the right name, and
-then doing a really fancy kind of C<goto> right to it, erasing itself
-from the call stack.
-
-What does this have to do with objects? After all, we keep talking about
-functions, not methods. Well, since a method is just a function with
-an extra argument and some fancier semantics about where it's found,
-we can use autoloading for methods, too. Perl doesn't start looking
-for an AUTOLOAD method until it has exhausted the recursive hunt up
-through @ISA, though. Some programmers have even been known to define
-a UNIVERSAL::AUTOLOAD method to trap unresolved method calls to any
-kind of object.
-
-=head2 Autoloaded Data Methods
-
-You probably began to get a little suspicious about the duplicated
-code way back earlier when we first showed you the Person class, and
-then later the Employee class. Each method used to access the
-hash fields looked virtually identical. This should have tickled
-that great programming virtue, Impatience, but for the time,
-we let Laziness win out, and so did nothing. Proxy methods can cure
-this.
-
-Instead of writing a new function every time we want a new data field,
-we'll use the autoload mechanism to generate (actually, mimic) methods on
-the fly. To verify that we're accessing a valid member, we will check
-against an C<_permitted> (pronounced "under-permitted") field, which
-is a reference to a file-scoped lexical (like a C file static) hash of permitted fields in this record
-called %fields. Why the underscore? For the same reason as the _CENSUS
-field we once used: as a marker that means "for internal use only".
-
-Here's what the module initialization code and class
-constructor will look like when taking this approach:
-
- package Person;
- use Carp;
- our $AUTOLOAD; # it's a package global
-
- my %fields = (
- name => undef,
- age => undef,
- peers => undef,
- );
-
- sub new {
- my $class = shift;
- my $self = {
- _permitted => \%fields,
- %fields,
- };
- bless $self, $class;
- return $self;
- }
-
-If we wanted our record to have default values, we could fill those in
-where current we have C<undef> in the %fields hash.
-
-Notice how we saved a reference to our class data on the object itself?
-Remember that it's important to access class data through the object
-itself instead of having any method reference %fields directly, or else
-you won't have a decent inheritance.
-
-The real magic, though, is going to reside in our proxy method, which
-will handle all calls to undefined methods for objects of class Person
-(or subclasses of Person). It has to be called AUTOLOAD. Again, it's
-all caps because it's called for us implicitly by Perl itself, not by
-a user directly.
-
- sub AUTOLOAD {
- my $self = shift;
- my $type = ref($self)
- or croak "$self is not an object";
-
- my $name = $AUTOLOAD;
- $name =~ s/.*://; # strip fully-qualified portion
-
- unless (exists $self->{_permitted}->{$name} ) {
- croak "Can't access `$name' field in class $type";
- }
-
- if (@_) {
- return $self->{$name} = shift;
- } else {
- return $self->{$name};
- }
- }
-
-Pretty nifty, eh? All we have to do to add new data fields
-is modify %fields. No new functions need be written.
-
-I could have avoided the C<_permitted> field entirely, but I
-wanted to demonstrate how to store a reference to class data on the
-object so you wouldn't have to access that class data
-directly from an object method.
-
-=head2 Inherited Autoloaded Data Methods
-
-But what about inheritance? Can we define our Employee
-class similarly? Yes, so long as we're careful enough.
-
-Here's how to be careful:
-
- package Employee;
- use Person;
- use strict;
- our @ISA = qw(Person);
-
- my %fields = (
- id => undef,
- salary => undef,
- );
-
- sub new {
- my $class = shift;
- my $self = $class->SUPER::new();
- my($element);
- foreach $element (keys %fields) {
- $self->{_permitted}->{$element} = $fields{$element};
- }
- @{$self}{keys %fields} = values %fields;
- return $self;
- }
-
-Once we've done this, we don't even need to have an
-AUTOLOAD function in the Employee package, because
-we'll grab Person's version of that via inheritance,
-and it will all work out just fine.
-
-=head1 Metaclassical Tools
-
-Even though proxy methods can provide a more convenient approach to making
-more struct-like classes than tediously coding up data methods as
-functions, it still leaves a bit to be desired. For one thing, it means
-you have to handle bogus calls that you don't mean to trap via your proxy.
-It also means you have to be quite careful when dealing with inheritance,
-as detailed above.
-
-Perl programmers have responded to this by creating several different
-class construction classes. These metaclasses are classes
-that create other classes. A couple worth looking at are
-Class::Struct and Alias. These and other related metaclasses can be
-found in the modules directory on CPAN.
-
-=head2 Class::Struct
-
-One of the older ones is Class::Struct. In fact, its syntax and
-interface were sketched out long before perl5 even solidified into a
-real thing. What it does is provide you a way to "declare" a class
-as having objects whose fields are of a specific type. The function
-that does this is called, not surprisingly enough, struct(). Because
-structures or records are not base types in Perl, each time you want to
-create a class to provide a record-like data object, you yourself have
-to define a new() method, plus separate data-access methods for each of
-that record's fields. You'll quickly become bored with this process.
-The Class::Struct::struct() function alleviates this tedium.
-
-Here's a simple example of using it:
-
- use Class::Struct qw(struct);
- use Jobbie; # user-defined; see below
-
- struct 'Fred' => {
- one => '$',
- many => '@',
- profession => 'Jobbie', # does not call Jobbie->new()
- };
-
- $ob = Fred->new(profession => Jobbie->new());
- $ob->one("hmmmm");
-
- $ob->many(0, "here");
- $ob->many(1, "you");
- $ob->many(2, "go");
- print "Just set: ", $ob->many(2), "\n";
-
- $ob->profession->salary(10_000);
-
-You can declare types in the struct to be basic Perl types, or
-user-defined types (classes). User types will be initialized by calling
-that class's new() method.
-
-Take care that the C<Jobbie> object is not created automatically by the
-C<Fred> class's new() method, so you should specify a C<Jobbie> object
-when you create an instance of C<Fred>.
-
-Here's a real-world example of using struct generation. Let's say you
-wanted to override Perl's idea of gethostbyname() and gethostbyaddr() so
-that they would return objects that acted like C structures. We don't
-care about high-falutin' OO gunk. All we want is for these objects to
-act like structs in the C sense.
-
- use Socket;
- use Net::hostent;
- $h = gethostbyname("perl.com"); # object return
- printf "perl.com's real name is %s, address %s\n",
- $h->name, inet_ntoa($h->addr);
-
-Here's how to do this using the Class::Struct module.
-The crux is going to be this call:
-
- struct 'Net::hostent' => [ # note bracket
- name => '$',
- aliases => '@',
- addrtype => '$',
- 'length' => '$',
- addr_list => '@',
- ];
-
-Which creates object methods of those names and types.
-It even creates a new() method for us.
-
-We could also have implemented our object this way:
-
- struct 'Net::hostent' => { # note brace
- name => '$',
- aliases => '@',
- addrtype => '$',
- 'length' => '$',
- addr_list => '@',
- };
-
-and then Class::Struct would have used an anonymous hash as the object
-type, instead of an anonymous array. The array is faster and smaller,
-but the hash works out better if you eventually want to do inheritance.
-Since for this struct-like object we aren't planning on inheritance,
-this time we'll opt for better speed and size over better flexibility.
-
-Here's the whole implementation:
-
- package Net::hostent;
- use strict;
-
- BEGIN {
- use Exporter ();
- our @EXPORT = qw(gethostbyname gethostbyaddr gethost);
- our @EXPORT_OK = qw(
- $h_name @h_aliases
- $h_addrtype $h_length
- @h_addr_list $h_addr
- );
- our %EXPORT_TAGS = ( FIELDS => [ @EXPORT_OK, @EXPORT ] );
- }
- our @EXPORT_OK;
-
- # Class::Struct forbids use of @ISA
- sub import { goto &Exporter::import }
-
- use Class::Struct qw(struct);
- struct 'Net::hostent' => [
- name => '$',
- aliases => '@',
- addrtype => '$',
- 'length' => '$',
- addr_list => '@',
- ];
-
- sub addr { shift->addr_list->[0] }
-
- sub populate (@) {
- return unless @_;
- my $hob = new(); # Class::Struct made this!
- $h_name = $hob->[0] = $_[0];
- @h_aliases = @{ $hob->[1] } = split ' ', $_[1];
- $h_addrtype = $hob->[2] = $_[2];
- $h_length = $hob->[3] = $_[3];
- $h_addr = $_[4];
- @h_addr_list = @{ $hob->[4] } = @_[ (4 .. $#_) ];
- return $hob;
- }
-
- sub gethostbyname ($) { populate(CORE::gethostbyname(shift)) }
-
- sub gethostbyaddr ($;$) {
- my ($addr, $addrtype);
- $addr = shift;
- require Socket unless @_;
- $addrtype = @_ ? shift : Socket::AF_INET();
- populate(CORE::gethostbyaddr($addr, $addrtype))
- }
-
- sub gethost($) {
- if ($_[0] =~ /^\d+(?:\.\d+(?:\.\d+(?:\.\d+)?)?)?$/) {
- require Socket;
- &gethostbyaddr(Socket::inet_aton(shift));
- } else {
- &gethostbyname;
- }
- }
-
- 1;
-
-We've snuck in quite a fair bit of other concepts besides just dynamic
-class creation, like overriding core functions, import/export bits,
-function prototyping, short-cut function call via C<&whatever>, and
-function replacement with C<goto &whatever>. These all mostly make
-sense from the perspective of a traditional module, but as you can see,
-we can also use them in an object module.
-
-You can look at other object-based, struct-like overrides of core
-functions in the 5.004 release of Perl in File::stat, Net::hostent,
-Net::netent, Net::protoent, Net::servent, Time::gmtime, Time::localtime,
-User::grent, and User::pwent. These modules have a final component
-that's all lowercase, by convention reserved for compiler pragmas,
-because they affect the compilation and change a builtin function.
-They also have the type names that a C programmer would most expect.
-
-=head2 Data Members as Variables
-
-If you're used to C++ objects, then you're accustomed to being able to
-get at an object's data members as simple variables from within a method.
-The Alias module provides for this, as well as a good bit more, such
-as the possibility of private methods that the object can call but folks
-outside the class cannot.
-
-Here's an example of creating a Person using the Alias module.
-When you update these magical instance variables, you automatically
-update value fields in the hash. Convenient, eh?
-
- package Person;
-
- # this is the same as before...
- sub new {
- my $class = shift;
- my $self = {
- NAME => undef,
- AGE => undef,
- PEERS => [],
- };
- bless($self, $class);
- return $self;
- }
-
- use Alias qw(attr);
- our ($NAME, $AGE, $PEERS);
-
- sub name {
- my $self = attr shift;
- if (@_) { $NAME = shift; }
- return $NAME;
- }
-
- sub age {
- my $self = attr shift;
- if (@_) { $AGE = shift; }
- return $AGE;
- }
-
- sub peers {
- my $self = attr shift;
- if (@_) { @PEERS = @_; }
- return @PEERS;
- }
-
- sub exclaim {
- my $self = attr shift;
- return sprintf "Hi, I'm %s, age %d, working with %s",
- $NAME, $AGE, join(", ", @PEERS);
- }
-
- sub happy_birthday {
- my $self = attr shift;
- return ++$AGE;
- }
-
-The need for the C<our> declaration is because what Alias does
-is play with package globals with the same name as the fields. To use
-globals while C<use strict> is in effect, you have to predeclare them.
-These package variables are localized to the block enclosing the attr()
-call just as if you'd used a local() on them. However, that means that
-they're still considered global variables with temporary values, just
-as with any other local().
-
-It would be nice to combine Alias with
-something like Class::Struct or Class::MethodMaker.
-
-=head1 NOTES
-
-=head2 Object Terminology
-
-In the various OO literature, it seems that a lot of different words
-are used to describe only a few different concepts. If you're not
-already an object programmer, then you don't need to worry about all
-these fancy words. But if you are, then you might like to know how to
-get at the same concepts in Perl.
-
-For example, it's common to call an object an I<instance> of a class
-and to call those objects' methods I<instance methods>. Data fields
-peculiar to each object are often called I<instance data> or I<object
-attributes>, and data fields common to all members of that class are
-I<class data>, I<class attributes>, or I<static data members>.
-
-Also, I<base class>, I<generic class>, and I<superclass> all describe
-the same notion, whereas I<derived class>, I<specific class>, and
-I<subclass> describe the other related one.
-
-C++ programmers have I<static methods> and I<virtual methods>,
-but Perl only has I<class methods> and I<object methods>.
-Actually, Perl only has methods. Whether a method gets used
-as a class or object method is by usage only. You could accidentally
-call a class method (one expecting a string argument) on an
-object (one expecting a reference), or vice versa.
-
-From the C++ perspective, all methods in Perl are virtual.
-This, by the way, is why they are never checked for function
-prototypes in the argument list as regular builtin and user-defined
-functions can be.
-
-Because a class is itself something of an object, Perl's classes can be
-taken as describing both a "class as meta-object" (also called I<object
-factory>) philosophy and the "class as type definition" (I<declaring>
-behaviour, not I<defining> mechanism) idea. C++ supports the latter
-notion, but not the former.
-
-=head1 SEE ALSO
-
-The following manpages will doubtless provide more
-background for this one:
-L<perlmod>,
-L<perlref>,
-L<perlobj>,
-L<perlbot>,
-L<perltie>,
-and
-L<overload>.
-
-L<perlboot> is a kinder, gentler introduction to object-oriented
-programming.
-
-L<perltooc> provides more detail on class data.
-
-Some modules which might prove interesting are Class::Accessor,
-Class::Class, Class::Contract, Class::Data::Inheritable,
-Class::MethodMaker and Tie::SecureHash
-
-
-=head1 AUTHOR AND COPYRIGHT
-
-Copyright (c) 1997, 1998 Tom Christiansen
-All rights reserved.
-
-This documentation is free; you can redistribute it and/or modify it
-under the same terms as Perl itself.
-
-Irrespective of its distribution, all code examples in this file
-are hereby placed into the public domain. You are permitted and
-encouraged to use this code in your own programs for fun
-or for profit as you see fit. A simple comment in the code giving
-credit would be courteous but is not required.
-
-=head1 COPYRIGHT
-
-=head2 Acknowledgments
-
-Thanks to
-Larry Wall,
-Roderick Schertler,
-Gurusamy Sarathy,
-Dean Roehrich,
-Raphael Manfredi,
-Brent Halsey,
-Greg Bacon,
-Brad Appleton,
-and many others for their helpful comments.
+=cut
Property changes on: trunk/contrib/perl/pod/perltoot.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perltrap.pod
===================================================================
--- trunk/contrib/perl/pod/perltrap.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perltrap.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -171,7 +171,7 @@
=item *
The switch statement is called C<given/when> and only available in
-perl 5.10 or newer. See L<perlsyn/"Switch statements">.
+perl 5.10 or newer. See L<perlsyn/"Switch Statements">.
=item *
@@ -347,1245 +347,6 @@
=back
-=head2 Perl4 to Perl5 Traps
-
-Practicing Perl4 Programmers should take note of the following
-Perl4-to-Perl5 specific traps.
-
-They're crudely ordered according to the following list:
-
-=over 4
-
-=item Discontinuance, Deprecation, and BugFix traps
-
-Anything that's been fixed as a perl4 bug, removed as a perl4 feature
-or deprecated as a perl4 feature with the intent to encourage usage of
-some other perl5 feature.
-
-=item Parsing Traps
-
-Traps that appear to stem from the new parser.
-
-=item Numerical Traps
-
-Traps having to do with numerical or mathematical operators.
-
-=item General data type traps
-
-Traps involving perl standard data types.
-
-=item Context Traps - scalar, list contexts
-
-Traps related to context within lists, scalar statements/declarations.
-
-=item Precedence Traps
-
-Traps related to the precedence of parsing, evaluation, and execution of
-code.
-
-=item General Regular Expression Traps using s///, etc.
-
-Traps related to the use of pattern matching.
-
-=item Subroutine, Signal, Sorting Traps
-
-Traps related to the use of signals and signal handlers, general subroutines,
-and sorting, along with sorting subroutines.
-
-=item OS Traps
-
-OS-specific traps.
-
-=item DBM Traps
-
-Traps specific to the use of C<dbmopen()>, and specific dbm implementations.
-
-=item Unclassified Traps
-
-Everything else.
-
-=back
-
-If you find an example of a conversion trap that is not listed here,
-please submit it to <F<perlbug at perl.org>> for inclusion.
-Also note that at least some of these can be caught with the
-C<use warnings> pragma or the B<-w> switch.
-
-=head2 Discontinuance, Deprecation, and BugFix traps
-
-Anything that has been discontinued, deprecated, or fixed as
-a bug from perl4.
-
-=over 4
-
-=item * Symbols starting with "_" no longer forced into main
-
-Symbols starting with "_" are no longer forced into package main, except
-for C<$_> itself (and C<@_>, etc.).
-
- package test;
- $_legacy = 1;
-
- package main;
- print "\$_legacy is ",$_legacy,"\n";
-
- # perl4 prints: $_legacy is 1
- # perl5 prints: $_legacy is
-
-=item * Double-colon valid package separator in variable name
-
-Double-colon is now a valid package separator in a variable name. Thus these
-behave differently in perl4 vs. perl5, because the packages don't exist.
-
- $a=1;$b=2;$c=3;$var=4;
- print "$a::$b::$c ";
- print "$var::abc::xyz\n";
-
- # perl4 prints: 1::2::3 4::abc::xyz
- # perl5 prints: 3
-
-Given that C<::> is now the preferred package delimiter, it is debatable
-whether this should be classed as a bug or not.
-(The older package delimiter, ' ,is used here)
-
- $x = 10;
- print "x=${'x}\n";
-
- # perl4 prints: x=10
- # perl5 prints: Can't find string terminator "'" anywhere before EOF
-
-You can avoid this problem, and remain compatible with perl4, if you
-always explicitly include the package name:
-
- $x = 10;
- print "x=${main'x}\n";
-
-Also see precedence traps, for parsing C<$:>.
-
-=item * 2nd and 3rd args to C<splice()> are now in scalar context
-
-The second and third arguments of C<splice()> are now evaluated in scalar
-context (as the Camel says) rather than list context.
-
- sub sub1{return(0,2) } # return a 2-element list
- sub sub2{ return(1,2,3)} # return a 3-element list
- @a1 = ("a","b","c","d","e");
- @a2 = splice(@a1,&sub1,&sub2);
- print join(' ', at a2),"\n";
-
- # perl4 prints: a b
- # perl5 prints: c d e
-
-=item * Can't do C<goto> into a block that is optimized away
-
-You can't do a C<goto> into a block that is optimized away. Darn.
-
- goto marker1;
-
- for(1){
- marker1:
- print "Here I is!\n";
- }
-
- # perl4 prints: Here I is!
- # perl5 errors: Can't "goto" into the middle of a foreach loop
-
-=item * Can't use whitespace as variable name or quote delimiter
-
-It is no longer syntactically legal to use whitespace as the name
-of a variable, or as a delimiter for any kind of quote construct.
-Double darn.
-
- $a = ("foo bar");
- $b = q baz ;
- print "a is $a, b is $b\n";
-
- # perl4 prints: a is foo bar, b is baz
- # perl5 errors: Bareword found where operator expected
-
-=item * C<while/if BLOCK BLOCK> gone
-
-The archaic while/if BLOCK BLOCK syntax is no longer supported.
-
- if { 1 } {
- print "True!";
- }
- else {
- print "False!";
- }
-
- # perl4 prints: True!
- # perl5 errors: syntax error at test.pl line 1, near "if {"
-
-=item * C<**> binds tighter than unary minus
-
-The C<**> operator now binds more tightly than unary minus.
-It was documented to work this way before, but didn't.
-
- print -4**2,"\n";
-
- # perl4 prints: 16
- # perl5 prints: -16
-
-=item * C<foreach> changed when iterating over a list
-
-The meaning of C<foreach{}> has changed slightly when it is iterating over a
-list which is not an array. This used to assign the list to a
-temporary array, but no longer does so (for efficiency). This means
-that you'll now be iterating over the actual values, not over copies of
-the values. Modifications to the loop variable can change the original
-values.
-
- @list = ('ab','abc','bcd','def');
- foreach $var (grep(/ab/, at list)){
- $var = 1;
- }
- print (join(':', at list));
-
- # perl4 prints: ab:abc:bcd:def
- # perl5 prints: 1:1:bcd:def
-
-To retain Perl4 semantics you need to assign your list
-explicitly to a temporary array and then iterate over that. For
-example, you might need to change
-
- foreach $var (grep(/ab/, at list)){
-
-to
-
- foreach $var (@tmp = grep(/ab/, at list)){
-
-Otherwise changing $var will clobber the values of @list. (This most often
-happens when you use C<$_> for the loop variable, and call subroutines in
-the loop that don't properly localize C<$_>.)
-
-=item * C<split> with no args behavior changed
-
-C<split> with no arguments now behaves like C<split ' '> (which doesn't
-return an initial null field if $_ starts with whitespace), it used to
-behave like C<split /\s+/> (which does).
-
- $_ = ' hi mom';
- print join(':', split);
-
- # perl4 prints: :hi:mom
- # perl5 prints: hi:mom
-
-=item * B<-e> behavior fixed
-
-Perl 4 would ignore any text which was attached to an B<-e> switch,
-always taking the code snippet from the following arg. Additionally, it
-would silently accept an B<-e> switch without a following arg. Both of
-these behaviors have been fixed.
-
- perl -e'print "attached to -e"' 'print "separate arg"'
-
- # perl4 prints: separate arg
- # perl5 prints: attached to -e
-
- perl -e
-
- # perl4 prints:
- # perl5 dies: No code specified for -e.
-
-=item * C<push> returns number of elements in resulting list
-
-In Perl 4 the return value of C<push> was undocumented, but it was
-actually the last value being pushed onto the target list. In Perl 5
-the return value of C<push> is documented, but has changed, it is the
-number of elements in the resulting list.
-
- @x = ('existing');
- print push(@x, 'first new', 'second new');
-
- # perl4 prints: second new
- # perl5 prints: 3
-
-=item * Some error messages differ
-
-Some error messages will be different.
-
-=item * C<split()> honors subroutine args
-
-In Perl 4, if in list context the delimiters to the first argument of
-C<split()> were C<??>, the result would be placed in C<@_> as well as
-being returned. Perl 5 has more respect for your subroutine arguments.
-
-=item * Bugs removed
-
-Some bugs may have been inadvertently removed. :-)
-
-=back
-
-=head2 Parsing Traps
-
-Perl4-to-Perl5 traps from having to do with parsing.
-
-=over 4
-
-=item * Space between . and = triggers syntax error
-
-Note the space between . and =
-
- $string . = "more string";
- print $string;
-
- # perl4 prints: more string
- # perl5 prints: syntax error at - line 1, near ". ="
-
-=item * Better parsing in perl 5
-
-Better parsing in perl 5
-
- sub foo {}
- &foo
- print("hello, world\n");
-
- # perl4 prints: hello, world
- # perl5 prints: syntax error
-
-=item * Function parsing
-
-"if it looks like a function, it is a function" rule.
-
- print
- ($foo == 1) ? "is one\n" : "is zero\n";
-
- # perl4 prints: is zero
- # perl5 warns: "Useless use of a constant in void context" if using -w
-
-=item * String interpolation of C<$#array> differs
-
-String interpolation of the C<$#array> construct differs when braces
-are to used around the name.
-
- @a = (1..3);
- print "${#a}";
-
- # perl4 prints: 2
- # perl5 fails with syntax error
-
- @a = (1..3);
- print "$#{a}";
-
- # perl4 prints: {a}
- # perl5 prints: 2
-
-=item * Perl guesses on C<map>, C<grep> followed by C<{> if it starts BLOCK or hash ref
-
-When perl sees C<map {> (or C<grep {>), it has to guess whether the C<{>
-starts a BLOCK or a hash reference. If it guesses wrong, it will report
-a syntax error near the C<}> and the missing (or unexpected) comma.
-
-Use unary C<+> before C<{> on a hash reference, and unary C<+> applied
-to the first thing in a BLOCK (after C<{>), for perl to guess right all
-the time. (See L<perlfunc/map>.)
-
-=back
-
-=head2 Numerical Traps
-
-Perl4-to-Perl5 traps having to do with numerical operators,
-operands, or output from same.
-
-=over 5
-
-=item * Formatted output and significant digits
-
-Formatted output and significant digits. In general, Perl 5
-tries to be more precise. For example, on a Solaris Sparc:
-
- print 7.373504 - 0, "\n";
- printf "%20.18f\n", 7.373504 - 0;
-
- # Perl4 prints:
- 7.3750399999999996141
- 7.375039999999999614
-
- # Perl5 prints:
- 7.373504
- 7.373503999999999614
-
-Notice how the first result looks better in Perl 5.
-
-Your results may vary, since your floating point formatting routines
-and even floating point format may be slightly different.
-
-=item * Auto-increment operator over signed int limit deleted
-
-This specific item has been deleted. It demonstrated how the auto-increment
-operator would not catch when a number went over the signed int limit. Fixed
-in version 5.003_04. But always be wary when using large integers.
-If in doubt:
-
- use Math::BigInt;
-
-=item * Assignment of return values from numeric equality tests doesn't work
-
-Assignment of return values from numeric equality tests
-does not work in perl5 when the test evaluates to false (0).
-Logical tests now return a null, instead of 0
-
- $p = ($test == 1);
- print $p,"\n";
-
- # perl4 prints: 0
- # perl5 prints:
-
-Also see L<"General Regular Expression Traps using s///, etc.">
-for another example of this new feature...
-
-=item * Bitwise string ops
-
-When bitwise operators which can operate upon either numbers or
-strings (C<& | ^ ~>) are given only strings as arguments, perl4 would
-treat the operands as bitstrings so long as the program contained a call
-to the C<vec()> function. perl5 treats the string operands as bitstrings.
-(See L<perlop/Bitwise String Operators> for more details.)
-
- $fred = "10";
- $barney = "12";
- $betty = $fred & $barney;
- print "$betty\n";
- # Uncomment the next line to change perl4's behavior
- # ($dummy) = vec("dummy", 0, 0);
-
- # Perl4 prints:
- 8
-
- # Perl5 prints:
- 10
-
- # If vec() is used anywhere in the program, both print:
- 10
-
-=back
-
-=head2 General data type traps
-
-Perl4-to-Perl5 traps involving most data-types, and their usage
-within certain expressions and/or context.
-
-=over 5
-
-=item * Negative array subscripts now count from the end of array
-
-Negative array subscripts now count from the end of the array.
-
- @a = (1, 2, 3, 4, 5);
- print "The third element of the array is $a[3] also expressed as $a[-2] \n";
-
- # perl4 prints: The third element of the array is 4 also expressed as
- # perl5 prints: The third element of the array is 4 also expressed as 4
-
-=item * Setting C<$#array> lower now discards array elements
-
-Setting C<$#array> lower now discards array elements, and makes them
-impossible to recover.
-
- @a = (a,b,c,d,e);
- print "Before: ",join('', at a);
- $#a =1;
- print ", After: ",join('', at a);
- $#a =3;
- print ", Recovered: ",join('', at a),"\n";
-
- # perl4 prints: Before: abcde, After: ab, Recovered: abcd
- # perl5 prints: Before: abcde, After: ab, Recovered: ab
-
-=item * Hashes get defined before use
-
-Hashes get defined before use
-
- local($s, at a,%h);
- die "scalar \$s defined" if defined($s);
- die "array \@a defined" if defined(@a);
- die "hash \%h defined" if defined(%h);
-
- # perl4 prints:
- # perl5 dies: hash %h defined
-
-Perl will now generate a warning when it sees defined(@a) and
-defined(%h).
-
-=item * Glob assignment from localized variable to variable
-
-glob assignment from variable to variable will fail if the assigned
-variable is localized subsequent to the assignment
-
- @a = ("This is Perl 4");
- *b = *a;
- local(@a);
- print @b,"\n";
-
- # perl4 prints: This is Perl 4
- # perl5 prints:
-
-=item * Assigning C<undef> to glob
-
-Assigning C<undef> to a glob has no effect in Perl 5. In Perl 4
-it undefines the associated scalar (but may have other side effects
-including SEGVs). Perl 5 will also warn if C<undef> is assigned to a
-typeglob. (Note that assigning C<undef> to a typeglob is different
-than calling the C<undef> function on a typeglob (C<undef *foo>), which
-has quite a few effects.
-
- $foo = "bar";
- *foo = undef;
- print $foo;
-
- # perl4 prints:
- # perl4 warns: "Use of uninitialized variable" if using -w
- # perl5 prints: bar
- # perl5 warns: "Undefined value assigned to typeglob" if using -w
-
-=item * Changes in unary negation (of strings)
-
-Changes in unary negation (of strings)
-This change effects both the return value and what it
-does to auto(magic)increment.
-
- $x = "aaa";
- print ++$x," : ";
- print -$x," : ";
- print ++$x,"\n";
-
- # perl4 prints: aab : -0 : 1
- # perl5 prints: aab : -aab : aac
-
-=item * Modifying of constants prohibited
-
-perl 4 lets you modify constants:
-
- $foo = "x";
- &mod($foo);
- for ($x = 0; $x < 3; $x++) {
- &mod("a");
- }
- sub mod {
- print "before: $_[0]";
- $_[0] = "m";
- print " after: $_[0]\n";
- }
-
- # perl4:
- # before: x after: m
- # before: a after: m
- # before: m after: m
- # before: m after: m
-
- # Perl5:
- # before: x after: m
- # Modification of a read-only value attempted at foo.pl line 12.
- # before: a
-
-=item * C<defined $var> behavior changed
-
-The behavior is slightly different for:
-
- print "$x", defined $x
-
- # perl 4: 1
- # perl 5: <no output, $x is not called into existence>
-
-=item * Variable Suicide
-
-Variable suicide behavior is more consistent under Perl 5.
-Perl5 exhibits the same behavior for hashes and scalars,
-that perl4 exhibits for only scalars.
-
- $aGlobal{ "aKey" } = "global value";
- print "MAIN:", $aGlobal{"aKey"}, "\n";
- $GlobalLevel = 0;
- &test( *aGlobal );
-
- sub test {
- local( *theArgument ) = @_;
- local( %aNewLocal ); # perl 4 != 5.001l,m
- $aNewLocal{"aKey"} = "this should never appear";
- print "SUB: ", $theArgument{"aKey"}, "\n";
- $aNewLocal{"aKey"} = "level $GlobalLevel"; # what should print
- $GlobalLevel++;
- if( $GlobalLevel<4 ) {
- &test( *aNewLocal );
- }
- }
-
- # Perl4:
- # MAIN:global value
- # SUB: global value
- # SUB: level 0
- # SUB: level 1
- # SUB: level 2
-
- # Perl5:
- # MAIN:global value
- # SUB: global value
- # SUB: this should never appear
- # SUB: this should never appear
- # SUB: this should never appear
-
-=back
-
-=head2 Context Traps - scalar, list contexts
-
-=over 5
-
-=item * Elements of argument lists for formats evaluated in list context
-
-The elements of argument lists for formats are now evaluated in list
-context. This means you can interpolate list values now.
-
- @fmt = ("foo","bar","baz");
- format STDOUT=
- @<<<<< @||||| @>>>>>
- @fmt;
- .
- write;
-
- # perl4 errors: Please use commas to separate fields in file
- # perl5 prints: foo bar baz
-
-=item * C<caller()> returns false value in scalar context if no caller present
-
-The C<caller()> function now returns a false value in a scalar context
-if there is no caller. This lets library files determine if they're
-being required.
-
- caller() ? (print "You rang?\n") : (print "Got a 0\n");
-
- # perl4 errors: There is no caller
- # perl5 prints: Got a 0
-
-=item * Comma operator in scalar context gives scalar context to args
-
-The comma operator in a scalar context is now guaranteed to give a
-scalar context to its last argument. It gives scalar or void context
-to any preceding arguments, depending on circumstances.
-
- @y= ('a','b','c');
- $x = (1, 2, @y);
- print "x = $x\n";
-
- # Perl4 prints: x = c # Interpolates array @y into the list
- # Perl5 prints: x = 3 # Evaluates array @y in scalar context
-
-=item * C<sprintf()> prototyped as C<($;@)>
-
-C<sprintf()> is prototyped as ($;@), so its first argument is given scalar
-context. Thus, if passed an array, it will probably not do what you want,
-unlike Perl 4:
-
- @z = ('%s%s', 'foo', 'bar');
- $x = sprintf(@z);
- print $x;
-
- # perl4 prints: foobar
- # perl5 prints: 3
-
-C<printf()> works the same as it did in Perl 4, though:
-
- @z = ('%s%s', 'foo', 'bar');
- printf STDOUT (@z);
-
- # perl4 prints: foobar
- # perl5 prints: foobar
-
-=back
-
-=head2 Precedence Traps
-
-Perl4-to-Perl5 traps involving precedence order.
-
-Perl 4 has almost the same precedence rules as Perl 5 for the operators
-that they both have. Perl 4 however, seems to have had some
-inconsistencies that made the behavior differ from what was documented.
-
-=over 5
-
-=item * LHS vs. RHS of any assignment operator
-
-LHS vs. RHS of any assignment operator. LHS is evaluated first
-in perl4, second in perl5; this can affect the relationship
-between side-effects in sub-expressions.
-
- @arr = ( 'left', 'right' );
- $a{shift @arr} = shift @arr;
- print join( ' ', keys %a );
-
- # perl4 prints: left
- # perl5 prints: right
-
-=item * Semantic errors introduced due to precedence
-
-These are now semantic errors because of precedence:
-
- @list = (1,2,3,4,5);
- %map = ("a",1,"b",2,"c",3,"d",4);
- $n = shift @list + 2; # first item in list plus 2
- print "n is $n, ";
- $m = keys %map + 2; # number of items in hash plus 2
- print "m is $m\n";
-
- # perl4 prints: n is 3, m is 6
- # perl5 errors and fails to compile
-
-=item * Precedence of assignment operators same as the precedence of assignment
-
-The precedence of assignment operators is now the same as the precedence
-of assignment. Perl 4 mistakenly gave them the precedence of the associated
-operator. So you now must parenthesize them in expressions like
-
- /foo/ ? ($a += 2) : ($a -= 2);
-
-Otherwise
-
- /foo/ ? $a += 2 : $a -= 2
-
-would be erroneously parsed as
-
- (/foo/ ? $a += 2 : $a) -= 2;
-
-On the other hand,
-
- $a += /foo/ ? 1 : 2;
-
-now works as a C programmer would expect.
-
-=item * C<open> requires parentheses around filehandle
-
- open FOO || die;
-
-is now incorrect. You need parentheses around the filehandle.
-Otherwise, perl5 leaves the statement as its default precedence:
-
- open(FOO || die);
-
- # perl4 opens or dies
- # perl5 opens FOO, dying only if 'FOO' is false, i.e. never
-
-=item * C<$:> precedence over C<$::> gone
-
-perl4 gives the special variable, C<$:> precedence, where perl5
-treats C<$::> as main C<package>
-
- $a = "x"; print "$::a";
-
- # perl 4 prints: -:a
- # perl 5 prints: x
-
-=item * Precedence of file test operators documented
-
-perl4 had buggy precedence for the file test operators vis-a-vis
-the assignment operators. Thus, although the precedence table
-for perl4 leads one to believe C<-e $foo .= "q"> should parse as
-C<((-e $foo) .= "q")>, it actually parses as C<(-e ($foo .= "q"))>.
-In perl5, the precedence is as documented.
-
- -e $foo .= "q"
-
- # perl4 prints: no output
- # perl5 prints: Can't modify -e in concatenation
-
-=item * C<keys>, C<each>, C<values> are regular named unary operators
-
-In perl4, keys(), each() and values() were special high-precedence operators
-that operated on a single hash, but in perl5, they are regular named unary
-operators. As documented, named unary operators have lower precedence
-than the arithmetic and concatenation operators C<+ - .>, but the perl4
-variants of these operators actually bind tighter than C<+ - .>.
-Thus, for:
-
- %foo = 1..10;
- print keys %foo - 1
-
- # perl4 prints: 4
- # perl5 prints: Type of arg 1 to keys must be hash (not subtraction)
-
-The perl4 behavior was probably more useful, if less consistent.
-
-=back
-
-=head2 General Regular Expression Traps using s///, etc.
-
-All types of RE traps.
-
-=over 5
-
-=item * C<s'$lhs'$rhs'> interpolates on either side
-
-C<s'$lhs'$rhs'> now does no interpolation on either side. It used to
-interpolate $lhs but not $rhs. (And still does not match a literal
-'$' in string)
-
- $a=1;$b=2;
- $string = '1 2 $a $b';
- $string =~ s'$a'$b';
- print $string,"\n";
-
- # perl4 prints: $b 2 $a $b
- # perl5 prints: 1 2 $a $b
-
-=item * C<m//g> attaches its state to the searched string
-
-C<m//g> now attaches its state to the searched string rather than the
-regular expression. (Once the scope of a block is left for the sub, the
-state of the searched string is lost)
-
- $_ = "ababab";
- while(m/ab/g){
- &doit("blah");
- }
- sub doit{local($_) = shift; print "Got $_ "}
-
- # perl4 prints: Got blah Got blah Got blah Got blah
- # perl5 prints: infinite loop blah...
-
-=item * C<m//o> used within an anonymous sub
-
-Currently, if you use the C<m//o> qualifier on a regular expression
-within an anonymous sub, I<all> closures generated from that anonymous
-sub will use the regular expression as it was compiled when it was used
-the very first time in any such closure. For instance, if you say
-
- sub build_match {
- my($left,$right) = @_;
- return sub { $_[0] =~ /$left stuff $right/o; };
- }
- $good = build_match('foo','bar');
- $bad = build_match('baz','blarch');
- print $good->('foo stuff bar') ? "ok\n" : "not ok\n";
- print $bad->('baz stuff blarch') ? "ok\n" : "not ok\n";
- print $bad->('foo stuff bar') ? "not ok\n" : "ok\n";
-
-For most builds of Perl5, this will print:
-ok
-not ok
-not ok
-
-build_match() will always return a sub which matches the contents of
-$left and $right as they were the I<first> time that build_match()
-was called, not as they are in the current call.
-
-=item * C<$+> isn't set to whole match
-
-If no parentheses are used in a match, Perl4 sets C<$+> to
-the whole match, just like C<$&>. Perl5 does not.
-
- "abcdef" =~ /b.*e/;
- print "\$+ = $+\n";
-
- # perl4 prints: bcde
- # perl5 prints:
-
-=item * Substitution now returns null string if it fails
-
-substitution now returns the null string if it fails
-
- $string = "test";
- $value = ($string =~ s/foo//);
- print $value, "\n";
-
- # perl4 prints: 0
- # perl5 prints:
-
-Also see L<Numerical Traps> for another example of this new feature.
-
-=item * C<s`lhs`rhs`> is now a normal substitution
-
-C<s`lhs`rhs`> (using backticks) is now a normal substitution, with no
-backtick expansion
-
- $string = "";
- $string =~ s`^`hostname`;
- print $string, "\n";
-
- # perl4 prints: <the local hostname>
- # perl5 prints: hostname
-
-=item * Stricter parsing of variables in regular expressions
-
-Stricter parsing of variables used in regular expressions
-
- s/^([^$grpc]*$grpc[$opt$plus$rep]?)//o;
-
- # perl4: compiles w/o error
- # perl5: with Scalar found where operator expected ..., near "$opt$plus"
-
-an added component of this example, apparently from the same script, is
-the actual value of the s'd string after the substitution.
-C<[$opt]> is a character class in perl4 and an array subscript in perl5
-
- $grpc = 'a';
- $opt = 'r';
- $_ = 'bar';
- s/^([^$grpc]*$grpc[$opt]?)/foo/;
- print;
-
- # perl4 prints: foo
- # perl5 prints: foobar
-
-=item * C<m?x?> matches only once
-
-Under perl5, C<m?x?> matches only once, like C<?x?>. Under perl4, it matched
-repeatedly, like C</x/> or C<m!x!>.
-
- $test = "once";
- sub match { $test =~ m?once?; }
- &match();
- if( &match() ) {
- # m?x? matches more then once
- print "perl4\n";
- } else {
- # m?x? matches only once
- print "perl5\n";
- }
-
- # perl4 prints: perl4
- # perl5 prints: perl5
-
-=item * Failed matches don't reset the match variables
-
-Unlike in Ruby, failed matches in Perl do not reset the match variables
-($1, $2, ..., C<$`>, ...).
-
-=back
-
-=head2 Subroutine, Signal, Sorting Traps
-
-The general group of Perl4-to-Perl5 traps having to do with
-Signals, Sorting, and their related subroutines, as well as
-general subroutine traps. Includes some OS-Specific traps.
-
-=over 5
-
-=item * Barewords that used to look like strings look like subroutine calls
-
-Barewords that used to look like strings to Perl will now look like subroutine
-calls if a subroutine by that name is defined before the compiler sees them.
-
- sub SeeYa { warn"Hasta la vista, baby!" }
- $SIG{'TERM'} = SeeYa;
- print "SIGTERM is now $SIG{'TERM'}\n";
-
- # perl4 prints: SIGTERM is now main'SeeYa
- # perl5 prints: SIGTERM is now main::1 (and warns "Hasta la vista, baby!")
-
-Use B<-w> to catch this one
-
-=item * Reverse is no longer allowed as the name of a sort subroutine
-
-reverse is no longer allowed as the name of a sort subroutine.
-
- sub reverse{ print "yup "; $a <=> $b }
- print sort reverse (2,1,3);
-
- # perl4 prints: yup yup 123
- # perl5 prints: 123
- # perl5 warns (if using -w): Ambiguous call resolved as CORE::reverse()
-
-=item * C<warn()> won't let you specify a filehandle.
-
-Although it _always_ printed to STDERR, warn() would let you specify a
-filehandle in perl4. With perl5 it does not.
-
- warn STDERR "Foo!";
-
- # perl4 prints: Foo!
- # perl5 prints: String found where operator expected
-
-=back
-
-=head2 OS Traps
-
-=over 5
-
-=item * SysV resets signal handler correctly
-
-Under HPUX, and some other SysV OSes, one had to reset any signal handler,
-within the signal handler function, each time a signal was handled with
-perl4. With perl5, the reset is now done correctly. Any code relying
-on the handler _not_ being reset will have to be reworked.
-
-Since version 5.002, Perl uses sigaction() under SysV.
-
- sub gotit {
- print "Got @_... ";
- }
- $SIG{'INT'} = 'gotit';
-
- $| = 1;
- $pid = fork;
- if ($pid) {
- kill('INT', $pid);
- sleep(1);
- kill('INT', $pid);
- } else {
- while (1) {sleep(10);}
- }
-
- # perl4 (HPUX) prints: Got INT...
- # perl5 (HPUX) prints: Got INT... Got INT...
-
-=item * SysV C<seek()> appends correctly
-
-Under SysV OSes, C<seek()> on a file opened to append C<<< >> >>> now does
-the right thing w.r.t. the fopen() manpage. e.g., - When a file is opened
-for append, it is impossible to overwrite information already in
-the file.
-
- open(TEST,">>seek.test");
- $start = tell TEST;
- foreach(1 .. 9){
- print TEST "$_ ";
- }
- $end = tell TEST;
- seek(TEST,$start,0);
- print TEST "18 characters here";
-
- # perl4 (solaris) seek.test has: 18 characters here
- # perl5 (solaris) seek.test has: 1 2 3 4 5 6 7 8 9 18 characters here
-
-
-
-=back
-
-=head2 Interpolation Traps
-
-Perl4-to-Perl5 traps having to do with how things get interpolated
-within certain expressions, statements, contexts, or whatever.
-
-=over 5
-
-=item * C<@> always interpolates an array in double-quotish strings
-
-@ now always interpolates an array in double-quotish strings.
-
- print "To: someone at somewhere.com\n";
-
- # perl4 prints: To:someone at somewhere.com
- # perl < 5.6.1, error : In string, @somewhere now must be written as \@somewhere
- # perl >= 5.6.1, warning : Possible unintended interpolation of @somewhere in string
-
-=item * Double-quoted strings may no longer end with an unescaped $
-
-Double-quoted strings may no longer end with an unescaped $.
-
- $foo = "foo$";
- print "foo is $foo\n";
-
- # perl4 prints: foo is foo$
- # perl5 errors: Final $ should be \$ or $name
-
-Note: perl5 DOES NOT error on the terminating @ in $bar
-
-=item * Arbitrary expressions are evaluated inside braces within double quotes
-
-Perl now sometimes evaluates arbitrary expressions inside braces that occur
-within double quotes (usually when the opening brace is preceded by C<$>
-or C<@>).
-
- @www = "buz";
- $foo = "foo";
- $bar = "bar";
- sub foo { return "bar" };
- print "|@{w.w.w}|${main'foo}|";
-
- # perl4 prints: |@{w.w.w}|foo|
- # perl5 prints: |buz|bar|
-
-Note that you can C<use strict;> to ward off such trappiness under perl5.
-
-=item * C<$$x> now tries to dereference $x
-
-The construct "this is $$x" used to interpolate the pid at that point, but
-now tries to dereference $x. C<$$> by itself still works fine, however.
-
- $s = "a reference";
- $x = *s;
- print "this is $$x\n";
-
- # perl4 prints: this is XXXx (XXX is the current pid)
- # perl5 prints: this is a reference
-
-=item * Creation of hashes on the fly with C<eval "EXPR"> requires protection
-
-Creation of hashes on the fly with C<eval "EXPR"> now requires either both
-C<$>'s to be protected in the specification of the hash name, or both curlies
-to be protected. If both curlies are protected, the result will be compatible
-with perl4 and perl5. This is a very common practice, and should be changed
-to use the block form of C<eval{}> if possible.
-
- $hashname = "foobar";
- $key = "baz";
- $value = 1234;
- eval "\$$hashname{'$key'} = q|$value|";
- (defined($foobar{'baz'})) ? (print "Yup") : (print "Nope");
-
- # perl4 prints: Yup
- # perl5 prints: Nope
-
-Changing
-
- eval "\$$hashname{'$key'} = q|$value|";
-
-to
-
- eval "\$\$hashname{'$key'} = q|$value|";
-
-causes the following result:
-
- # perl4 prints: Nope
- # perl5 prints: Yup
-
-or, changing to
-
- eval "\$$hashname\{'$key'\} = q|$value|";
-
-causes the following result:
-
- # perl4 prints: Yup
- # perl5 prints: Yup
- # and is compatible for both versions
-
-
-=item * Bugs in earlier perl versions
-
-perl4 programs which unconsciously rely on the bugs in earlier perl versions.
-
- perl -e '$bar=q/not/; print "This is $foo{$bar} perl5"'
-
- # perl4 prints: This is not perl5
- # perl5 prints: This is perl5
-
-=item * Array and hash brackets during interpolation
-
-You also have to be careful about array and hash brackets during
-interpolation.
-
- print "$foo["
-
- perl 4 prints: [
- perl 5 prints: syntax error
-
- print "$foo{"
-
- perl 4 prints: {
- perl 5 prints: syntax error
-
-Perl 5 is expecting to find an index or key name following the respective
-brackets, as well as an ending bracket of the appropriate type. In order
-to mimic the behavior of Perl 4, you must escape the bracket like so.
-
- print "$foo\[";
- print "$foo\{";
-
-=item * Interpolation of C<\$$foo{bar}>
-
-Similarly, watch out for: C<\$$foo{bar}>
-
- $foo = "baz";
- print "\$$foo{bar}\n";
-
- # perl4 prints: $baz{bar}
- # perl5 prints: $
-
-Perl 5 is looking for C<$foo{bar}> which doesn't exist, but perl 4 is
-happy just to expand $foo to "baz" by itself. Watch out for this
-especially in C<eval>'s.
-
-=item * C<qq()> string passed to C<eval> will not find string terminator
-
-C<qq()> string passed to C<eval>
-
- eval qq(
- foreach \$y (keys %\$x\) {
- \$count++;
- }
- );
-
- # perl4 runs this ok
- # perl5 prints: Can't find string terminator ")"
-
-=back
-
-=head2 DBM Traps
-
-General DBM traps.
-
-=over 5
-
-=item * Perl5 must have been linked with same dbm/ndbm as the default for C<dbmopen()>
-
-Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
-may cause the same script, run under perl5, to fail. The build of perl5
-must have been linked with the same dbm/ndbm as the default for C<dbmopen()>
-to function properly without C<tie>'ing to an extension dbm implementation.
-
- dbmopen (%dbm, "file", undef);
- print "ok\n";
-
- # perl4 prints: ok
- # perl5 prints: ok (IFF linked with -ldbm or -lndbm)
-
-
-=item * DBM exceeding limit on the key/value size will cause perl5 to exit immediately
-
-Existing dbm databases created under perl4 (or any other dbm/ndbm tool)
-may cause the same script, run under perl5, to fail. The error generated
-when exceeding the limit on the key/value size will cause perl5 to exit
-immediately.
-
- dbmopen(DB, "testdb",0600) || die "couldn't open db! $!";
- $DB{'trap'} = "x" x 1024; # value too large for most dbm/ndbm
- print "YUP\n";
-
- # perl4 prints:
- dbm store returned -1, errno 28, key "trap" at - line 3.
- YUP
-
- # perl5 prints:
- dbm store returned -1, errno 28, key "trap" at - line 3.
-
-=back
-
-=head2 Unclassified Traps
-
-Everything else.
-
-=over 5
-
-=item * C<require>/C<do> trap using returned value
-
-If the file doit.pl has:
-
- sub foo {
- $rc = do "./do.pl";
- return 8;
- }
- print &foo, "\n";
-
-And the do.pl file has the following single line:
-
- return 3;
-
-Running doit.pl gives the following:
-
- # perl 4 prints: 3 (aborts the subroutine early)
- # perl 5 prints: 8
-
-Same behavior if you replace C<do> with C<require>.
-
-=item * C<split> on empty string with LIMIT specified
-
- $string = '';
- @list = split(/foo/, $string, 2)
-
-Perl4 returns a one element list containing the empty string but Perl5
-returns an empty list.
-
-=back
-
As always, if any of these are ever officially declared as bugs,
they'll be fixed and removed.
Property changes on: trunk/contrib/perl/pod/perltrap.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlunicode.pod
===================================================================
--- trunk/contrib/perl/pod/perlunicode.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlunicode.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -28,8 +28,10 @@
selected if you use C<use 5.012> or higher.) Failure to do this can
trigger unexpected surprises. See L</The "Unicode Bug"> below.
-This pragma doesn't affect I/O, and there are still several places
-where Unicode isn't fully supported, such as in filenames.
+This pragma doesn't affect I/O. Nor does it change the internal
+representation of strings, only their interpretation. There are still
+several places where Unicode isn't fully supported, such as in
+filenames.
=item Input and Output Layers
@@ -72,8 +74,7 @@
=head2 Byte and Character Semantics
-Beginning with version 5.6, Perl uses logically-wide characters to
-represent strings internally.
+Perl uses logically-wide characters to represent strings internally.
Starting in Perl 5.14, Perl-level operations work with
characters rather than bytes within the scope of a
@@ -90,18 +91,15 @@
without additional information from the user, Perl decides in favor of
compatibility and chooses to use byte semantics.
-When C<use locale> is in effect (which overrides
-C<use feature 'unicode_strings'> in the same scope), Perl uses the
-semantics associated
-with the current locale. Otherwise, Perl uses the platform's native
+When C<use locale> (but not C<use locale ':not_characters'>) is in
+effect, Perl uses the semantics associated with the current locale.
+(C<use locale> overrides C<use feature 'unicode_strings'> in the same scope;
+while C<use locale ':not_characters'> effectively also selects
+C<use feature 'unicode_strings'> in its scope; see L<perllocale>.)
+Otherwise, Perl uses the platform's native
byte semantics for characters whose code points are less than 256, and
-Unicode semantics for those greater than 255. On EBCDIC platforms, this
-is almost seamless, as the EBCDIC code pages that Perl handles are
-equivalent to Unicode's first 256 code points. (The exception is that
-EBCDIC regular expression case-insensitive matching rules are not as
-as robust as Unicode's.) But on ASCII platforms, Perl uses US-ASCII
-(or Basic Latin in Unicode terminology) byte semantics, meaning that characters
-whose ordinal numbers are in the range 128 - 255 are undefined except for their
+Unicode semantics for those greater than 255. That means that non-ASCII
+characters are undefined except for their
ordinal numbers. This means that none have case (upper and lower), nor are any
a member of character classes, like C<[:alpha:]> or C<\w>. (But all do belong
to the C<\W> class or the Perl regular expression extension C<[:^alpha:]>.)
@@ -155,16 +153,18 @@
above. For characters below 0x100 you may get byte semantics instead of
character semantics; see L</The "Unicode Bug">. On EBCDIC machines there is
the additional problem that the value for such characters gives the EBCDIC
-character rather than the Unicode one.
+character rather than the Unicode one, thus it is more portable to use
+C<\N{U+...}> instead.
-Additionally, if you
+Additionally, you can use the C<\N{...}> notation and put the official
+Unicode character name within the braces, such as
+C<\N{WHITE SMILING FACE}>. This automatically loads the L<charnames>
+module with the C<:full> and C<:short> options. If you prefer different
+options for this module, you can instead, before the C<\N{...}>,
+explicitly load it with your desired options; for example,
- use charnames ':full';
+ use charnames ':loose';
-you can use the C<\N{...}> notation and put the official Unicode
-character name within the braces, such as C<\N{WHITE SMILING FACE}>.
-See L<charnames>.
-
=item *
If an appropriate L<encoding> is specified, identifiers within the
@@ -260,11 +260,13 @@
=item *
-You can define your own mappings to be used in C<lc()>,
-C<lcfirst()>, C<uc()>, and C<ucfirst()> (or their double-quoted string inlined
-versions such as C<\U>). See
-L<User-Defined Case-Mappings|/"User-Defined Case Mappings (for serious hackers only)">
-for more details.
+There is a CPAN module, L<Unicode::Casing>, which allows you to define
+your own mappings to be used in C<lc()>, C<lcfirst()>, C<uc()>,
+C<ucfirst()>, and C<fc> (or their double-quoted string inlined
+versions such as C<\U>).
+(Prior to Perl 5.16, this functionality was partially provided
+in the Perl core, but suffered from a number of insurmountable
+drawbacks, so the CPAN module was written instead.)
=back
@@ -301,7 +303,8 @@
take on more values than just True and False. For example, the Bidi_Class (see
L</"Bidirectional Character Types"> below), can take on several different
values, such as Left, Right, Whitespace, and others. To match these, one needs
-to specify the property name (Bidi_Class), AND the value being matched against
+to specify both the property name (Bidi_Class), AND the value being
+matched against
(Left, Right, etc.). This is done, as in the examples above, by having the
two components separated by an equal sign (or interchangeably, a colon), like
C<\p{Bidi_Class: Left}>.
@@ -364,6 +367,14 @@
numerals, come in both upper and lower case so they are C<Cased>, but aren't considered
letters, so they aren't C<Cased_Letter>s.)
+The result is undefined if you try to match a non-Unicode code point
+(that is, one above 0x10FFFF) against a Unicode property. Currently, a
+warning is raised, and the match will fail. In some cases, this is
+counterintuitive, as both these fail:
+
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=True} # Fails.
+ chr(0x110000) =~ \p{ASCII_Hex_Digit=False} # Fails!
+
=head3 B<General_Category>
Every Unicode character is assigned a general category, which is the "most
@@ -469,12 +480,64 @@
written in Cyrillic, and Greek is written in, well, Greek; Japanese mainly in
Hiragana or Katakana. There are many more.
-The Unicode Script property gives what script a given character is in,
-and the property can be specified with the compound form like
-C<\p{Script=Hebrew}> (short: C<\p{sc=hebr}>). Perl furnishes shortcuts for all
-script names. You can omit everything up through the equals (or colon), and
-simply write C<\p{Latin}> or C<\P{Cyrillic}>.
+The Unicode Script and Script_Extensions properties give what script a
+given character is in. Either property can be specified with the
+compound form like
+C<\p{Script=Hebrew}> (short: C<\p{sc=hebr}>), or
+C<\p{Script_Extensions=Javanese}> (short: C<\p{scx=java}>).
+In addition, Perl furnishes shortcuts for all
+C<Script> property names. You can omit everything up through the equals
+(or colon), and simply write C<\p{Latin}> or C<\P{Cyrillic}>.
+(This is not true for C<Script_Extensions>, which is required to be
+written in the compound form.)
+The difference between these two properties involves characters that are
+used in multiple scripts. For example the digits '0' through '9' are
+used in many parts of the world. These are placed in a script named
+C<Common>. Other characters are used in just a few scripts. For
+example, the "KATAKANA-HIRAGANA DOUBLE HYPHEN" is used in both Japanese
+scripts, Katakana and Hiragana, but nowhere else. The C<Script>
+property places all characters that are used in multiple scripts in the
+C<Common> script, while the C<Script_Extensions> property places those
+that are used in only a few scripts into each of those scripts; while
+still using C<Common> for those used in many scripts. Thus both these
+match:
+
+ "0" =~ /\p{sc=Common}/ # Matches
+ "0" =~ /\p{scx=Common}/ # Matches
+
+and only the first of these match:
+
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Common} # Matches
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Common} # No match
+
+And only the last two of these match:
+
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Hiragana} # No match
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{sc=Katakana} # No match
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Hiragana} # Matches
+ "\N{KATAKANA-HIRAGANA DOUBLE HYPHEN}" =~ /\p{scx=Katakana} # Matches
+
+C<Script_Extensions> is thus an improved C<Script>, in which there are
+fewer characters in the C<Common> script, and correspondingly more in
+other scripts. It is new in Unicode version 6.0, and its data are likely
+to change significantly in later releases, as things get sorted out.
+
+(Actually, besides C<Common>, the C<Inherited> script, contains
+characters that are used in multiple scripts. These are modifier
+characters which modify other characters, and inherit the script value
+of the controlling character. Some of these are used in many scripts,
+and so go into C<Inherited> in both C<Script> and C<Script_Extensions>.
+Others are used in just a few scripts, so are in C<Inherited> in
+C<Script>, but not in C<Script_Extensions>.)
+
+It is worth stressing that there are several different sets of digits in
+Unicode that are equivalent to 0-9 and are matchable by C<\d> in a
+regular expression. If they are used in a single language only, they
+are in that language's C<Script> and C<Script_Extension>. If they are
+used in more than one script, they will be in C<sc=Common>, but only
+if they are used in many scripts should they be in C<scx=Common>.
+
A complete list of scripts and their shortcuts is in L<perluniprops>.
=head3 B<Use of "Is" Prefix>
@@ -496,20 +559,14 @@
from this as well as several other blocks, like "Latin-1 Supplement",
"Latin Extended-A", etc., but it does not contain all the characters from
those blocks. It does not, for example, contain the digits 0-9, because
-those digits are shared across many scripts. The digits 0-9 and similar groups,
-like punctuation, are in the script called C<Common>. There is also a
-script called C<Inherited> for characters that modify other characters,
-and inherit the script value of the controlling character. (Note that
-there are several different sets of digits in Unicode that are
-equivalent to 0-9 and are matchable by C<\d> in a regular expression.
-If they are used in a single language only, they are in that language's
-script. Only sets are used across several languages are in the
-C<Common> script.)
+those digits are shared across many scripts, and hence are in the
+C<Common> script.
For more about scripts versus blocks, see UAX#24 "Unicode Script Property":
L<http://www.unicode.org/reports/tr24>
-The Script property is likely to be the one you want to use when processing
+The C<Script> or C<Script_Extensions> properties are likely to be the
+ones you want to use when processing
natural language; the Block property may occasionally be useful in working
with the nuts and bolts of Unicode.
@@ -557,8 +614,9 @@
the compound form. And quite a few of these are actually recommended by Unicode
(in L<http://www.unicode.org/reports/tr18>).
-This section gives some details on all extensions that aren't synonyms for
-compound-form Unicode properties (for those, you'll have to refer to the
+This section gives some details on all extensions that aren't just
+synonyms for compound-form Unicode properties
+(for those properties, you'll have to refer to the
L<Unicode Standard|http://www.unicode.org/reports/tr44>.
=over
@@ -658,7 +716,8 @@
=item B<C<\p{PerlSpace}>>
-This is the same as C<\s>, restricted to ASCII, namely C<S<[ \f\n\r\t]>>.
+This is the same as C<\s>, restricted to ASCII, namely C<S<[ \f\n\r\t]>>
+and starting in Perl v5.18, experimentally, a vertical tab.
Mnemonic: Perl's (original) space
@@ -719,6 +778,13 @@
Mnemonic: Space, as modified by Perl. (It doesn't include the vertical tab
which both the Posix standard and Unicode consider white space.)
+=item B<C<\p{Title}>> and B<C<\p{Titlecase}>>
+
+Under case-sensitive matching, these both match the same code points as
+C<\p{General Category=Titlecase_Letter}> (C<\p{gc=lt}>). The difference
+is that under C</i> caseless matching, these match the same as
+C<\p{Cased}>, whereas C<\p{gc=lt}> matches C<\p{Cased_Letter>).
+
=item B<C<\p{VertSpace}>>
This is the same as C<\v>: A character that changes the spacing vertically.
@@ -738,7 +804,9 @@
=head2 User-Defined Character Properties
You can define your own binary character properties by defining subroutines
-whose names begin with "In" or "Is". The subroutines can be defined in any
+whose names begin with "In" or "Is". (The experimental feature
+L<perlre/(?[ ])> provides an alternative which allows more complex
+definitions.) The subroutines can be defined in any
package. The user-defined properties can be used in the regular expression
C<\p> and C<\P> constructs; if you are using a user-defined property from a
package other than the one you are in, you must specify its package in the
@@ -781,7 +849,8 @@
=item *
Something to include, prefixed by "+": a built-in character
-property (prefixed by "utf8::") or a user-defined character property,
+property (prefixed by "utf8::") or a fully qualified (including package
+name) user-defined character property,
to represent all the characters in that property; two hexadecimal code
points for a range; or a single hexadecimal code point.
@@ -788,7 +857,8 @@
=item *
Something to exclude, prefixed by "-": an existing character
-property (prefixed by "utf8::") or a user-defined character property,
+property (prefixed by "utf8::") or a fully qualified (including package
+name) user-defined character property,
to represent all the characters in that property; two hexadecimal code
points for a range; or a single hexadecimal code point.
@@ -795,7 +865,8 @@
=item *
Something to negate, prefixed "!": an existing character
-property (prefixed by "utf8::") or a user-defined character property,
+property (prefixed by "utf8::") or a fully qualified (including package
+name) user-defined character property,
to represent all the characters in that property; two hexadecimal code
points for a range; or a single hexadecimal code point.
@@ -802,7 +873,8 @@
=item *
Something to intersect with, prefixed by "&": an existing character
-property (prefixed by "utf8::") or a user-defined character property,
+property (prefixed by "utf8::") or a fully qualified (including package
+name) user-defined character property,
for all the characters except the characters in the property; two
hexadecimal code points for a range; or a single hexadecimal code point.
@@ -852,326 +924,188 @@
END
}
-Intersection is useful for getting the common characters matched by
-two (or more) classes.
+This will match all non-Unicode code points, since every one of them is
+not in Kana. You can use intersection to exclude these, if desired, as
+this modified example shows:
- sub InFooAndBar {
+ sub InNotKana {
return <<'END';
- +main::Foo
- &main::Bar
+ !utf8::InHiragana
+ -utf8::InKatakana
+ +utf8::IsCn
+ &utf8::Any
END
}
-It's important to remember not to use "&" for the first set; that
-would be intersecting with nothing, resulting in an empty set.
+C<&utf8::Any> must be the last line in the definition.
-=head2 User-Defined Case Mappings (for serious hackers only)
+Intersection is used generally for getting the common characters matched
+by two (or more) classes. It's important to remember not to use "&" for
+the first set; that would be intersecting with nothing, resulting in an
+empty set.
-B<This featured is deprecated and is scheduled to be removed in Perl
-5.16.>
-The CPAN module L<Unicode::Casing> provides better functionality
-without the drawbacks described below.
+(Note that official Unicode properties differ from these in that they
+automatically exclude non-Unicode code points and a warning is raised if
+a match is attempted on one of those.)
-You can define your own mappings to be used in C<lc()>,
-C<lcfirst()>, C<uc()>, and C<ucfirst()> (or their string-inlined versions,
-C<\L>, C<\l>, C<\U>, and C<\u>). The mappings are currently only valid
-on strings encoded in UTF-8, but see below for a partial workaround for
-this restriction.
+=head2 User-Defined Case Mappings (for serious hackers only)
-The principle is similar to that of user-defined character
-properties: define subroutines that do the mappings.
-C<ToLower> is used for C<lc()>, C<\L>, C<lcfirst()>, and C<\l>; C<ToTitle> for
-C<ucfirst()> and C<\u>; and C<ToUpper> for C<uc()> and C<\U>.
+B<This feature has been removed as of Perl 5.16.>
+The CPAN module L<Unicode::Casing> provides better functionality without
+the drawbacks that this feature had. If you are using a Perl earlier
+than 5.16, this feature was most fully documented in the 5.14 version of
+this pod:
+L<http://perldoc.perl.org/5.14.0/perlunicode.html#User-Defined-Case-Mappings-%28for-serious-hackers-only%29>
-C<ToUpper()> should look something like this:
+=head2 Character Encodings for Input and Output
- sub ToUpper {
- return <<END;
- 0061\t007A\t0041
- 0101\t\t0100
- END
- }
+See L<Encode>.
-This sample C<ToUpper()> has the effect of mapping "a-z" to "A-Z", 0x101
-to 0x100, and all other characters map to themselves. The first
-returned line means to map the code point at 0x61 ("a") to 0x41 ("A"),
-the code point at 0x62 ("b") to 0x42 ("B"), ..., 0x7A ("z") to 0x5A
-("Z"). The second line maps just the code point 0x101 to 0x100. Since
-there are no other mappings defined, all other code points map to
-themselves.
+=head2 Unicode Regular Expression Support Level
-This mechanism is not well behaved as far as affecting other packages
-and scopes. All non-threaded programs have exactly one uppercasing
-behavior, one lowercasing behavior, and one titlecasing behavior in
-effect for utf8-encoded strings for the duration of the program. Each
-of these behaviors is irrevocably determined the first time the
-corresponding function is called to change a utf8-encoded string's case.
-If a corresponding C<To-> function has been defined in the package that
-makes that first call, the mapping defined by that function will be the
-mapping used for the duration of the program's execution across all
-packages and scopes. If no corresponding C<To-> function has been
-defined in that package, the standard official mapping will be used for
-all packages and scopes, and any corresponding C<To-> function anywhere
-will be ignored. Threaded programs have similar behavior. If the
-program's casing behavior has been decided at the time of a thread's
-creation, the thread will inherit that behavior. But, if the behavior
-hasn't been decided, the thread gets to decide for itself, and its
-decision does not affect other threads nor its creator.
+The following list of Unicode supported features for regular expressions describes
+all features currently directly supported by core Perl. The references to "Level N"
+and the section numbers refer to the Unicode Technical Standard #18,
+"Unicode Regular Expressions", version 13, from August 2008.
-As shown by the example above, you have to furnish a complete mapping;
-you can't just override a couple of characters and leave the rest
-unchanged. You can find all the official mappings in the directory
-C<$Config{privlib}>F</unicore/To/>. The mapping data is returned as the
-here-document. The C<utf8::ToSpecI<Foo>> hashes in those files are special
-exception mappings derived from
-C<$Config{privlib}>F</unicore/SpecialCasing.txt>. (The "Digit" and
-"Fold" mappings that one can see in the directory are not directly
-user-accessible, one can use either the L<Unicode::UCD> module, or just match
-case-insensitively, which is what uses the "Fold" mapping. Neither are user
-overridable.)
+=over 4
-If you have many mappings to change, you can take the official mapping data,
-change by hand the affected code points, and place the whole thing into your
-subroutine. But this will only be valid on Perls that use the same Unicode
-version. Another option would be to have your subroutine read the official
-mapping files and overwrite the affected code points.
+=item *
-If you have only a few mappings to change, starting in 5.14 you can use the
-following trick, here illustrated for Turkish.
+Level 1 - Basic Unicode Support
- use Config;
- use charnames ":full";
+ RL1.1 Hex Notation - done [1]
+ RL1.2 Properties - done [2][3]
+ RL1.2a Compatibility Properties - done [4]
+ RL1.3 Subtraction and Intersection - experimental [5]
+ RL1.4 Simple Word Boundaries - done [6]
+ RL1.5 Simple Loose Matches - done [7]
+ RL1.6 Line Boundaries - MISSING [8][9]
+ RL1.7 Supplementary Code Points - done [10]
- sub ToUpper {
- my $official = do "$Config{privlib}/unicore/To/Upper.pl";
- $utf8::ToSpecUpper{'i'} =
- "\N{LATIN CAPITAL LETTER I WITH DOT ABOVE}";
- return $official;
- }
+=over 4
-This takes the official mappings and overrides just one, for "LATIN SMALL
-LETTER I". The keys to the hash must be the bytes that form the UTF-8
-(on EBCDIC platforms, UTF-EBCDIC) of the character, as illustrated by
-the inverse function.
+=item [1]
- sub ToLower {
- my $official = do $lower;
- $utf8::ToSpecLower{"\xc4\xb0"} = "i";
- return $official;
- }
+\x{...}
-This example is for an ASCII platform, and C<\xc4\xb0> is the string of
-bytes that together form the UTF-8 that represents C<\N{LATIN CAPITAL
-LETTER I WITH DOT ABOVE}>, C<U+0130>. You can avoid having to figure out
-these bytes, and at the same time make it work on all platforms by
-instead writing:
+=item [2]
- sub ToLower {
- my $official = do $lower;
- my $sequence = "\N{LATIN CAPITAL LETTER I WITH DOT ABOVE}";
- utf8::encode($sequence);
- $utf8::ToSpecLower{$sequence} = "i";
- return $official;
- }
+\p{...} \P{...}
-This works because C<utf8::encode()> takes the single character and
-converts it to the sequence of bytes that constitute it. Note that we took
-advantage of the fact that C<"i"> is the same in UTF-8 or UTF_EBCIDIC as not;
-otherwise we would have had to write
+=item [3]
- $utf8::ToSpecLower{$sequence} = "\N{LATIN SMALL LETTER I}";
+supports not only minimal list, but all Unicode character properties (see Unicode Character Properties above)
-in the ToLower example, and in the ToUpper example, use
+=item [4]
- my $sequence = "\N{LATIN SMALL LETTER I}";
- utf8::encode($sequence);
+\d \D \s \S \w \W \X [:prop:] [:^prop:]
-A big caveat to the above trick and to this whole mechanism in general,
-is that they work only on strings encoded in UTF-8. You can partially
-get around this by using C<use subs>. (But better to just convert to
-use L<Unicode::Casing>.) For example:
-(The trick illustrated here does work in earlier releases, but only if all the
-characters you want to override have ordinal values of 256 or higher, or
-if you use the other tricks given just below.)
+=item [5]
-The mappings are in effect only for the package they are defined in, and only
-on scalars that have been marked as having Unicode characters, for example by
-using C<utf8::upgrade()>. Although probably not advisable, you can
-cause the mappings to be used globally by importing into C<CORE::GLOBAL>
-(see L<CORE>).
+The experimental feature in v5.18 "(?[...])" accomplishes this. See
+L<perlre/(?[ ])>. If you don't want to use an experimental feature,
+you can use one of the following:
-You can partially get around the restriction that the source strings
-must be in utf8 by using C<use subs> (or by importing into C<CORE::GLOBAL>) by:
+=over 4
- use subs qw(uc ucfirst lc lcfirst);
+=item * Regular expression look-ahead
- sub uc($) {
- my $string = shift;
- utf8::upgrade($string);
- return CORE::uc($string);
- }
+You can mimic class subtraction using lookahead.
+For example, what UTS#18 might write as
- sub lc($) {
- my $string = shift;
- utf8::upgrade($string);
+ [{Block=Greek}-[{UNASSIGNED}]]
- # Unless an I is before a dot_above, it turns into a dotless i.
- # (The character class with the combining classes matches non-above
- # marks following the I. Any number of these may be between the 'I' and
- # the dot_above, and the dot_above will still apply to the 'I'.
- use charnames ":full";
- $string =~
- s/I
- (?! [^\p{ccc=0}\p{ccc=Above}]* \N{COMBINING DOT ABOVE} )
- /\N{LATIN SMALL LETTER DOTLESS I}/gx;
+in Perl can be written as:
- # But when the I is followed by a dot_above, remove the
- # dot_above so the end result will be i.
- $string =~ s/I
- ([^\p{ccc=0}\p{ccc=Above}]* )
- \N{COMBINING DOT ABOVE}
- /i$1/gx;
- return CORE::lc($string);
- }
+ (?!\p{Unassigned})\p{Block=Greek}
+ (?=\p{Assigned})\p{Block=Greek}
-These examples (also for Turkish) make sure the input is in UTF-8, and then
-call the corresponding official function, which will use the C<ToUpper()> and
-C<ToLower()> functions you have defined.
-(For Turkish, there are other required functions: C<ucfirst>, C<lcfirst>,
-and C<ToTitle>. These are very similar to the ones given above.)
+But in this particular example, you probably really want
-The reason this is only a partial fix is that it doesn't affect the C<\l>,
-C<\L>, C<\u>, and C<\U> case-change operations in regular expressions,
-which still require the source to be encoded in utf8 (see L</The "Unicode
-Bug">). (Again, use L<Unicode::Casing> instead.)
+ \p{Greek}
-The C<lc()> example shows how you can add context-dependent casing. Note
-that context-dependent casing suffers from the problem that the string
-passed to the casing function may not have sufficient context to make
-the proper choice. Also, it will not be called for C<\l>, C<\L>, C<\u>,
-and C<\U>.
+which will match assigned characters known to be part of the Greek script.
-=head2 Character Encodings for Input and Output
+=item * CPAN module L<Unicode::Regex::Set>
-See L<Encode>.
+It does implement the full UTS#18 grouping, intersection, union, and
+removal (subtraction) syntax.
-=head2 Unicode Regular Expression Support Level
+=item * L</"User-Defined Character Properties">
-The following list of Unicode supported features for regular expressions describes
-all features currently directly supported by core Perl. The references to "Level N"
-and the section numbers refer to the Unicode Technical Standard #18,
-"Unicode Regular Expressions", version 13, from August 2008.
+'+' for union, '-' for removal (set-difference), '&' for intersection
-=over 4
+=back
-=item *
+=item [6]
-Level 1 - Basic Unicode Support
+\b \B
- RL1.1 Hex Notation - done [1]
- RL1.2 Properties - done [2][3]
- RL1.2a Compatibility Properties - done [4]
- RL1.3 Subtraction and Intersection - MISSING [5]
- RL1.4 Simple Word Boundaries - done [6]
- RL1.5 Simple Loose Matches - done [7]
- RL1.6 Line Boundaries - MISSING [8][9]
- RL1.7 Supplementary Code Points - done [10]
+=item [7]
- [1] \x{...}
- [2] \p{...} \P{...}
- [3] supports not only minimal list, but all Unicode character
- properties (see L</Unicode Character Properties>)
- [4] \d \D \s \S \w \W \X [:prop:] [:^prop:]
- [5] can use regular expression look-ahead [a] or
- user-defined character properties [b] to emulate set
- operations
- [6] \b \B
- [7] note that Perl does Full case-folding in matching (but with
- bugs), not Simple: for example U+1F88 is equivalent to
- U+1F00 U+03B9, not with 1F80. This difference matters
- mainly for certain Greek capital letters with certain
- modifiers: the Full case-folding decomposes the letter,
- while the Simple case-folding would map it to a single
- character.
- [8] should do ^ and $ also on U+000B (\v in C), FF (\f), CR
- (\r), CRLF (\r\n), NEL (U+0085), LS (U+2028), and PS
- (U+2029); should also affect <>, $., and script line
- numbers; should not split lines within CRLF [c] (i.e. there
- is no empty line between \r and \n)
- [9] Linebreaking conformant with UAX#14 "Unicode Line Breaking
- Algorithm" is available through the Unicode::LineBreaking
- module.
- [10] UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to
- U+10FFFF but also beyond U+10FFFF
+Note that Perl does Full case-folding in matching (but with bugs), not Simple: for example U+1F88 is equivalent to U+1F00 U+03B9, instead of just U+1F80. This difference matters mainly for certain Greek capital letters with certain modifiers: the Full case-folding decomposes the letter, while the Simple case-folding would map it to a single character.
-[a] You can mimic class subtraction using lookahead.
-For example, what UTS#18 might write as
+=item [8]
- [{Greek}-[{UNASSIGNED}]]
+Should do ^ and $ also on U+000B (\v in C), FF (\f), CR (\r), CRLF
+(\r\n), NEL (U+0085), LS (U+2028), and PS (U+2029); should also affect
+<>, $., and script line numbers; should not split lines within CRLF
+(i.e. there is no empty line between \r and \n). For CRLF, try the
+C<:crlf> layer (see L<PerlIO>).
-in Perl can be written as:
+=item [9]
- (?!\p{Unassigned})\p{InGreekAndCoptic}
- (?=\p{Assigned})\p{InGreekAndCoptic}
+Linebreaking conformant with UAX#14 "Unicode Line Breaking Algorithm" is available through the Unicode::LineBreaking module.
-But in this particular example, you probably really want
+=item [10]
- \p{GreekAndCoptic}
+UTF-8/UTF-EBDDIC used in Perl allows not only U+10000 to
+U+10FFFF but also beyond U+10FFFF
-which will match assigned characters known to be part of the Greek script.
+=back
-Also see the Unicode::Regex::Set module, it does implement the full
-UTS#18 grouping, intersection, union, and removal (subtraction) syntax.
-
-[b] '+' for union, '-' for removal (set-difference), '&' for intersection
-(see L</"User-Defined Character Properties">)
-
-[c] Try the C<:crlf> layer (see L<PerlIO>).
-
=item *
Level 2 - Extended Unicode Support
- RL2.1 Canonical Equivalents - MISSING [10][11]
- RL2.2 Default Grapheme Clusters - MISSING [12]
- RL2.3 Default Word Boundaries - MISSING [14]
- RL2.4 Default Loose Matches - MISSING [15]
- RL2.5 Name Properties - MISSING [16]
- RL2.6 Wildcard Properties - MISSING
+ RL2.1 Canonical Equivalents - MISSING [10][11]
+ RL2.2 Default Grapheme Clusters - MISSING [12]
+ RL2.3 Default Word Boundaries - MISSING [14]
+ RL2.4 Default Loose Matches - MISSING [15]
+ RL2.5 Name Properties - DONE
+ RL2.6 Wildcard Properties - MISSING
- [10] see UAX#15 "Unicode Normalization Forms"
- [11] have Unicode::Normalize but not integrated to regexes
- [12] have \X but we don't have a "Grapheme Cluster Mode"
- [14] see UAX#29, Word Boundaries
- [15] see UAX#21 "Case Mappings"
- [16] missing loose match [e]
+ [10] see UAX#15 "Unicode Normalization Forms"
+ [11] have Unicode::Normalize but not integrated to regexes
+ [12] have \X but we don't have a "Grapheme Cluster Mode"
+ [14] see UAX#29, Word Boundaries
+ [15] This is covered in Chapter 3.13 (in Unicode 6.0)
-[e] C<\N{...}> allows namespaces (see L<charnames>).
-
=item *
Level 3 - Tailored Support
- RL3.1 Tailored Punctuation - MISSING
- RL3.2 Tailored Grapheme Clusters - MISSING [17][18]
- RL3.3 Tailored Word Boundaries - MISSING
- RL3.4 Tailored Loose Matches - MISSING
- RL3.5 Tailored Ranges - MISSING
- RL3.6 Context Matching - MISSING [19]
- RL3.7 Incremental Matches - MISSING
+ RL3.1 Tailored Punctuation - MISSING
+ RL3.2 Tailored Grapheme Clusters - MISSING [17][18]
+ RL3.3 Tailored Word Boundaries - MISSING
+ RL3.4 Tailored Loose Matches - MISSING
+ RL3.5 Tailored Ranges - MISSING
+ RL3.6 Context Matching - MISSING [19]
+ RL3.7 Incremental Matches - MISSING
( RL3.8 Unicode Set Sharing )
- RL3.9 Possible Match Sets - MISSING
- RL3.10 Folded Matching - MISSING [20]
- RL3.11 Submatchers - MISSING
+ RL3.9 Possible Match Sets - MISSING
+ RL3.10 Folded Matching - MISSING [20]
+ RL3.11 Submatchers - MISSING
- [17] see UAX#10 "Unicode Collation Algorithms"
- [18] have Unicode::Collate but not integrated to regexes
- [19] have (?<=x) and (?=x), but look-aheads or look-behinds
- should see outside of the target substring
- [20] need insensitive matching for linguistic features other
- than case; for example, hiragana to katakana, wide and
- narrow, simplified Han to traditional Han (see UTR#30
- "Character Foldings")
+ [17] see UAX#10 "Unicode Collation Algorithms"
+ [18] have Unicode::Collate but not integrated to regexes
+ [19] have (?<=x) and (?=x), but look-aheads or look-behinds
+ should see outside of the target substring
+ [20] need insensitive matching for linguistic features other
+ than case; for example, hiragana to katakana, wide and
+ narrow, simplified Han to traditional Han (see UTR#30
+ "Character Foldings")
=back
@@ -1192,7 +1126,7 @@
The following table is from Unicode 3.2.
- Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
+ Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
U+0000..U+007F 00..7F
U+0080..U+07FF * C2..DF 80..BF
@@ -1199,7 +1133,7 @@
U+0800..U+0FFF E0 * A0..BF 80..BF
U+1000..U+CFFF E1..EC 80..BF 80..BF
U+D000..U+D7FF ED 80..9F 80..BF
- U+D800..U+DFFF +++++++ utf16 surrogates, not legal utf8 +++++++
+ U+D800..U+DFFF +++++ utf16 surrogates, not legal utf8 +++++
U+E000..U+FFFF EE..EF 80..BF 80..BF
U+10000..U+3FFFF F0 * 90..BF 80..BF 80..BF
U+40000..U+FFFFF F1..F3 80..BF 80..BF 80..BF
@@ -1213,12 +1147,12 @@
Another way to look at it is via bits:
- Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
+ Code Points 1st Byte 2nd Byte 3rd Byte 4th Byte
- 0aaaaaaa 0aaaaaaa
- 00000bbbbbaaaaaa 110bbbbb 10aaaaaa
- ccccbbbbbbaaaaaa 1110cccc 10bbbbbb 10aaaaaa
- 00000dddccccccbbbbbbaaaaaa 11110ddd 10cccccc 10bbbbbb 10aaaaaa
+ 0aaaaaaa 0aaaaaaa
+ 00000bbbbbaaaaaa 110bbbbb 10aaaaaa
+ ccccbbbbbbaaaaaa 1110cccc 10bbbbbb 10aaaaaa
+ 00000dddccccccbbbbbbaaaaaa 11110ddd 10cccccc 10bbbbbb 10aaaaaa
As you can see, the continuation bytes all begin with "10", and the
leading bits of the start byte tell how many bytes there are in the
@@ -1426,7 +1360,7 @@
The following are such interfaces. Also, see L</The "Unicode Bug">.
For all of these interfaces Perl
-currently (as of 5.8.3) simply assumes byte strings both as arguments
+currently (as of v5.16.0) simply assumes byte strings both as arguments
and results, or UTF-8 strings if the (problematic) C<encoding> pragma has been used.
One reason that Perl does not attempt to resolve the role of Unicode in
@@ -1467,37 +1401,51 @@
=head2 The "Unicode Bug"
-The term, the "Unicode bug" has been applied to an inconsistency
+The term, "Unicode bug" has been applied to an inconsistency
on ASCII platforms with the
Unicode code points in the Latin-1 Supplement block, that
is, between 128 and 255. Without a locale specified, unlike all other
characters or code points, these characters have very different semantics in
byte semantics versus character semantics, unless
-C<use feature 'unicode_strings'> is specified.
-(The lesson here is to specify C<unicode_strings> to avoid the
-headaches.)
+C<use feature 'unicode_strings'> is specified, directly or indirectly.
+(It is indirectly specified by a C<use v5.12> or higher.)
-In character semantics they are interpreted as Unicode code points, which means
+In character semantics these upper-Latin1 characters are interpreted as
+Unicode code points, which means
they have the same semantics as Latin-1 (ISO-8859-1).
-In byte semantics, they are considered to be unassigned characters, meaning
-that the only semantics they have is their ordinal numbers, and that they are
+In byte semantics (without C<unicode_strings>), they are considered to
+be unassigned characters, meaning that the only semantics they have is
+their ordinal numbers, and that they are
not members of various character classes. None are considered to match C<\w>
for example, but all match C<\W>.
-The behavior is known to have effects on these areas:
+Perl 5.12.0 added C<unicode_strings> to force character semantics on
+these code points in some circumstances, which fixed portions of the
+bug; Perl 5.14.0 fixed almost all of it; and Perl 5.16.0 fixed the
+remainder (so far as we know, anyway). The lesson here is to enable
+C<unicode_strings> to avoid the headaches described below.
+The old, problematic behavior affects these areas:
+
=over 4
=item *
Changing the case of a scalar, that is, using C<uc()>, C<ucfirst()>, C<lc()>,
-and C<lcfirst()>, or C<\L>, C<\U>, C<\u> and C<\l> in regular expression
-substitutions.
+and C<lcfirst()>, or C<\L>, C<\U>, C<\u> and C<\l> in double-quotish
+contexts, such as regular expression substitutions.
+Under C<unicode_strings> starting in Perl 5.12.0, character semantics are
+generally used. See L<perlfunc/lc> for details on how this works
+in combination with various other pragmas.
=item *
-Using caseless (C</i>) regular expression matching
+Using caseless (C</i>) regular expression matching.
+Starting in Perl 5.14.0, regular expressions compiled within
+the scope of C<unicode_strings> use character semantics
+even when executed or compiled into larger
+regular expressions outside the scope.
=item *
@@ -1504,19 +1452,19 @@
Matching any of several properties in regular expressions, namely C<\b>,
C<\B>, C<\s>, C<\S>, C<\w>, C<\W>, and all the Posix character classes
I<except> C<[[:ascii:]]>.
+Starting in Perl 5.14.0, regular expressions compiled within
+the scope of C<unicode_strings> use character semantics
+even when executed or compiled into larger
+regular expressions outside the scope.
=item *
-In C<quotemeta> or its inline equivalent C<\Q>, no characters
-code points above 127 are quoted in UTF-8 encoded strings, but in
-byte encoded strings, code points between 128-255 are always quoted.
+In C<quotemeta> or its inline equivalent C<\Q>, no code points above 127
+are quoted in UTF-8 encoded strings, but in byte encoded strings, code
+points between 128-255 are always quoted.
+Starting in Perl 5.16.0, consistent quoting rules are used within the
+scope of C<unicode_strings>, as described in L<perlfunc/quotemeta>.
-=item *
-
-User-defined case change mappings. You can create a C<ToUpper()> function, for
-example, which overrides Perl's built-in case mappings. The scalar must be
-encoded in utf8 for your function to actually be invoked.
-
=back
This behavior can lead to unexpected results in which a string's semantics
@@ -1544,21 +1492,9 @@
support seamlessly. The result wasn't seamless: these characters were
orphaned.
-Starting in Perl 5.14, C<use feature 'unicode_strings'> can be used to
-cause Perl to use Unicode semantics on all string operations within the
-scope of the feature subpragma. Regular expressions compiled in its
-scope retain that behavior even when executed or compiled into larger
-regular expressions outside the scope. (The pragma does not, however,
-affect the C<quotemeta> behavior. Nor does it affect the deprecated
-user-defined case changing operations--these still require a UTF-8
-encoded string to operate.)
-
-In Perl 5.12, the subpragma affected casing changes, but not regular
-expressions. See L<perlfunc/lc> for details on how this pragma works in
-combination with various others for casing.
-
-For earlier Perls, or when a string is passed to a function outside the
-subpragma's scope, a workaround is to always call C<utf8::upgrade($string)>,
+For Perls earlier than those described above, or when a string is passed
+to a function outside the subpragma's scope, a workaround is to always
+call C<utf8::upgrade($string)>,
or to use the standard module L<Encode>. Also, a scalar that has any characters
whose ordinal is above 0x100, or which were specified using either of the
C<\N{...}> notations, will automatically have character semantics.
@@ -1608,7 +1544,8 @@
=item *
-C<utf8_to_uvchr(buf, lenp)> reads UTF-8 encoded bytes from a buffer and
+C<utf8_to_uvchr_buf(buf, bufend, lenp)> reads UTF-8 encoded bytes from a
+buffer and
returns the Unicode character code point and, optionally, the length of
the UTF-8 byte sequence. It works appropriately on EBCDIC machines.
@@ -1632,13 +1569,13 @@
=item *
-C<is_utf8_char(s)> returns true if the pointer points to a valid UTF-8
-character.
+C<is_utf8_string(buf, len)> returns true if C<len> bytes of the buffer
+are valid UTF-8.
=item *
-C<is_utf8_string(buf, len)> returns true if C<len> bytes of the buffer
-are valid UTF-8.
+C<is_utf8_char_buf(buf, buf_end)> returns true if the pointer points to
+a valid UTF-8 character.
=item *
@@ -1693,15 +1630,8 @@
site L<http://www.unicode.org>). These should replace the existing files in
F<lib/unicore> in the Perl source tree. Follow the instructions in
F<README.perl> in that directory to change some of their names, and then build
-perl (see F<INSTALL>).
+perl (see L<INSTALL>).
-It is even possible to copy the built files to a different directory, and then
-change F<utf8_heavy.pl> in the directory C<$Config{privlib}> to point to the
-new directory, or maybe make a copy of that directory before making the change,
-and using C<@INC> or the C<-I> run-time flag to switch between versions at will
-(but because of caching, not in the middle of a process), but all this is
-beyond the scope of these instructions.
-
=head1 BUGS
=head2 Interaction with Locales
@@ -1815,13 +1745,13 @@
your code. The examples are written such that the code will continue
to work under 5.6, so you should be safe to try them out.
-=over 4
+=over 3
=item *
A filehandle that should read or write UTF-8
- if ($] > 5.007) {
+ if ($] > 5.008) {
binmode $fh, ":encoding(utf8)";
}
@@ -1832,10 +1762,10 @@
Be it Compress::Zlib, Apache::Request or any extension that has no
mention of Unicode in the manpage, you need to make sure that the
UTF8 flag is stripped off. Note that at the time of this writing
-(October 2002) the mentioned modules are not UTF-8-aware. Please
+(January 2012) the mentioned modules are not UTF-8-aware. Please
check the documentation to verify if this is still true.
- if ($] > 5.007) {
+ if ($] > 5.008) {
require Encode;
$val = Encode::encode_utf8($val); # make octets
}
@@ -1847,7 +1777,7 @@
If you believe the scalar comes back as UTF-8, you will most likely
want the UTF8 flag restored:
- if ($] > 5.007) {
+ if ($] > 5.008) {
require Encode;
$val = Encode::decode_utf8($val);
}
@@ -1856,7 +1786,7 @@
Same thing, if you are really sure it is UTF-8
- if ($] > 5.007) {
+ if ($] > 5.008) {
require Encode;
Encode::_utf8_on($val);
}
@@ -1869,7 +1799,7 @@
a convenient way to replace all your fetchrow_array and
fetchrow_hashref calls. A wrapper function will also make it easier to
adapt to future enhancements in your database driver. Note that at the
-time of this writing (October 2002), the DBI has no standardized way
+time of this writing (January 2012), the DBI has no standardized way
to deal with UTF-8 data. Please check the documentation to verify if
that is still true.
@@ -1876,7 +1806,7 @@
sub fetchrow {
# $what is one of fetchrow_{array,hashref}
my($self, $sth, $what) = @_;
- if ($] < 5.007) {
+ if ($] < 5.008) {
return $sth->$what;
} else {
require Encode;
@@ -1912,7 +1842,7 @@
a drag to your program. If you recognize such a situation, just remove
the UTF8 flag:
- utf8::downgrade($val) if $] > 5.007;
+ utf8::downgrade($val) if $] > 5.008;
=back
Property changes on: trunk/contrib/perl/pod/perlunicode.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlunifaq.pod
===================================================================
--- trunk/contrib/perl/pod/perlunifaq.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlunifaq.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -141,8 +141,8 @@
Starting in Perl 5.14 (and partially in Perl 5.12), just put a
C<use feature 'unicode_strings'> near the beginning of your program.
Within its lexical scope you shouldn't have this problem. It also is
-automatically enabled under C<use feature ':5.12'> or using C<-E> on the
-command line for Perl 5.12 or higher.
+automatically enabled under C<use feature ':5.12'> or C<use v5.12> or
+using C<-E> on the command line for Perl 5.12 or higher.
The rationale for requiring this is to not break older programs that
rely on the way things worked before Unicode came along. Those older
@@ -149,8 +149,8 @@
programs knew only about the ASCII character set, and so may not work
properly for additional characters. When a string is encoded in UTF-8,
Perl assumes that the program is prepared to deal with Unicode, but when
-the string isn't, Perl assumes that only ASCII (unless it is an EBCDIC
-platform) is wanted, and so those characters that are not ASCII
+the string isn't, Perl assumes that only ASCII
+is wanted, and so those characters that are not ASCII
characters aren't recognized as to what they would be in Unicode.
C<use feature 'unicode_strings'> tells Perl to treat all characters as
Unicode, whether the string is encoded in UTF-8 or not, thus avoiding
@@ -274,7 +274,8 @@
but this is considered bad style. Especially C<_utf8_on> can be dangerous, for
the same reason that C<:utf8> can.
-There are some shortcuts for oneliners; see C<-C> in L<perlrun>.
+There are some shortcuts for oneliners;
+see L<-C|perlrun/-C [numberE<sol>list]> in L<perlrun>.
=head2 What's the difference between C<UTF-8> and C<utf8>?
Property changes on: trunk/contrib/perl/pod/perlunifaq.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perluniintro.pod
===================================================================
--- trunk/contrib/perl/pod/perluniintro.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perluniintro.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -93,25 +93,42 @@
otherwise used blocks. Secondly, there are special Unicode control
characters that do not represent true characters.
-A common myth about Unicode is that it is "16-bit", that is,
-Unicode is only represented as C<0x10000> (or 65536) characters from
-C<0x0000> to C<0xFFFF>. B<This is untrue.> Since Unicode 2.0 (July
+When Unicode was first conceived, it was thought that all the world's
+characters could be represented using a 16-bit word; that is a maximum of
+C<0x10000> (or 65536) characters from C<0x0000> to C<0xFFFF> would be
+needed. This soon proved to be false, and since Unicode 2.0 (July
1996), Unicode has been defined all the way up to 21 bits (C<0x10FFFF>),
-and since Unicode 3.1 (March 2001), characters have been defined
-beyond C<0xFFFF>. The first C<0x10000> characters are called the
-I<Plane 0>, or the I<Basic Multilingual Plane> (BMP). With Unicode
-3.1, 17 (yes, seventeen) planes in all were defined--but they are
-nowhere near full of defined characters, yet.
+and Unicode 3.1 (March 2001) defined the first characters above C<0xFFFF>.
+The first C<0x10000> characters are called the I<Plane 0>, or the
+I<Basic Multilingual Plane> (BMP). With Unicode 3.1, 17 (yes,
+seventeen) planes in all were defined--but they are nowhere near full of
+defined characters, yet.
-Another myth is about Unicode blocks--that they have something to
-do with languages--that each block would define the characters used
-by a language or a set of languages. B<This is also untrue.>
+When a new language is being encoded, Unicode generally will choose a
+C<block> of consecutive unallocated code points for its characters. So
+far, the number of code points in these blocks has always been evenly
+divisible by 16. Extras in a block, not currently needed, are left
+unallocated, for future growth. But there have been occasions when
+a later relase needed more code points than the available extras, and a
+new block had to allocated somewhere else, not contiguous to the initial
+one, to handle the overflow. Thus, it became apparent early on that
+"block" wasn't an adequate organizing principal, and so the C<Script>
+property was created. (Later an improved script property was added as
+well, the C<Script_Extensions> property.) Those code points that are in
+overflow blocks can still
+have the same script as the original ones. The script concept fits more
+closely with natural language: there is C<Latin> script, C<Greek>
+script, and so on; and there are several artificial scripts, like
+C<Common> for characters that are used in multiple scripts, such as
+mathematical symbols. Scripts usually span varied parts of several
+blocks. For more information about scripts, see L<perlunicode/Scripts>.
The division into blocks exists, but it is almost completely
-accidental--an artifact of how the characters have been and
-still are allocated. Instead, there is a concept called I<scripts>, which is
-more useful: there is C<Latin> script, C<Greek> script, and so on. Scripts
-usually span varied parts of several blocks. For more information about
-scripts, see L<perlunicode/Scripts>.
+accidental--an artifact of how the characters have been and still are
+allocated. (Note that this paragraph has oversimplified things for the
+sake of this being an introduction. Unicode doesn't really encode
+languages, but the writing systems for them--their scripts; and one
+script can be used by many languages. Unicode also encodes things that
+aren't really about languages, such as symbols like C<BAGGAGE CLAIM>.)
The Unicode code points are just abstract numbers. To input and
output these abstract numbers, the numbers must be I<encoded> or
@@ -120,7 +137,7 @@
variable length encoding that encodes Unicode characters as 1 to 6
bytes. Other encodings
include UTF-16 and UTF-32 and their big- and little-endian variants
-(UTF-8 is byte-order independent) The ISO/IEC 10646 defines the UCS-2
+(UTF-8 is byte-order independent). The ISO/IEC 10646 defines the UCS-2
and UCS-4 encoding forms.
For more information about encodings--for instance, to learn what
@@ -128,25 +145,26 @@
=head2 Perl's Unicode Support
-Starting from Perl 5.6.0, Perl has had the capacity to handle Unicode
-natively. Perl 5.8.0, however, is the first recommended release for
+Starting from Perl v5.6.0, Perl has had the capacity to handle Unicode
+natively. Perl v5.8.0, however, is the first recommended release for
serious Unicode work. The maintenance release 5.6.1 fixed many of the
problems of the initial Unicode implementation, but for example
regular expressions still do not work with Unicode in 5.6.1.
-Perl 5.14.0 is the first release where Unicode support is
+Perl v5.14.0 is the first release where Unicode support is
(almost) seamlessly integrable without some gotchas (the exception being
-some differences in L<quotemeta|perlfunc/quotemeta>). To enable this
+some differences in L<quotemeta|perlfunc/quotemeta>, which is fixed
+starting in Perl 5.16.0). To enable this
seamless support, you should C<use feature 'unicode_strings'> (which is
automatically selected if you C<use 5.012> or higher). See L<feature>.
(5.14 also fixes a number of bugs and departures from the Unicode
standard.)
-Before Perl 5.8.0, the use of C<use utf8> was used to declare
+Before Perl v5.8.0, the use of C<use utf8> was used to declare
that operations in the current block or file would be Unicode-aware.
This model was found to be wrong, or at least clumsy: the "Unicodeness"
is now carried with the data, instead of being attached to the
operations.
-Starting with Perl 5.8.0, only one case remains where an explicit C<use
+Starting with Perl v5.8.0, only one case remains where an explicit C<use
utf8> is needed: if your Perl script itself is encoded in UTF-8, you can
use UTF-8 in your identifier names, and in string and regular expression
literals, by saying C<use utf8>. This is not the default because
@@ -158,7 +176,7 @@
strings of Unicode characters. The general principle is that Perl tries
to keep its data as eight-bit bytes for as long as possible, but as soon
as Unicodeness cannot be avoided, the data is transparently upgraded
-to Unicode. Prior to Perl 5.14, the upgrade was not completely
+to Unicode. Prior to Perl v5.14.0, the upgrade was not completely
transparent (see L<perlunicode/The "Unicode Bug">), and for backwards
compatibility, full transparency is not gained unless C<use feature
'unicode_strings'> (see L<feature>) or C<use 5.012> (or higher) is
@@ -253,10 +271,9 @@
characters regardless of the numeric value, use C<pack("U", ...)>
instead of C<\x..>, C<\x{...}>, or C<chr()>.
-You can also use the C<charnames> pragma to invoke characters
+You can invoke characters
by name in double-quoted strings:
- use charnames ':full';
my $arabic_alef = "\N{ARABIC LETTER ALEF}";
And, as mentioned above, you can also C<pack()> numbers into Unicode
@@ -287,8 +304,8 @@
Note that Perl considers grapheme clusters to be separate characters, so for
example
- use charnames ':full';
- print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"), "\n";
+ print length("\N{LATIN CAPITAL LETTER A}\N{COMBINING ACUTE ACCENT}"),
+ "\n";
will print 2, not 1. The only exception is that regular expressions
have C<\X> for matching an extended grapheme cluster. (Thus C<\X> in a
@@ -398,7 +415,7 @@
You can switch encodings on an already opened stream by using
C<binmode()>; see L<perlfunc/binmode>.
-The C<:locale> does not currently (as of Perl 5.8.0) work with
+The C<:locale> does not currently work with
C<open()> and C<binmode()>, only with the C<open> pragma. The
C<:utf8> and C<:encoding(...)> methods do work with all of C<open()>,
C<binmode()>, and the C<open> pragma.
@@ -459,7 +476,7 @@
join("",
map { $_ > 255 ? # if wide character...
sprintf("\\x{%04X}", $_) : # \x{...}
- chr($_) =~ /[[:cntrl:]]/ ? # else if control character ...
+ chr($_) =~ /[[:cntrl:]]/ ? # else if control character...
sprintf("\\x%02X", $_) : # \x..
quotemeta(chr($_)) # else quoted or as themselves
} unpack("W*", $_[0])); # unpack Unicode characters
@@ -675,7 +692,7 @@
my $unicode = chr(0x100);
print length($unicode), "\n"; # will print 1
require Encode;
- print length(Encode::encode_utf8($unicode)), "\n"; # will print 2
+ print length(Encode::encode_utf8($unicode)),"\n"; # will print 2
use bytes;
print length($unicode), "\n"; # will also print 2
# (the 0xC4 0x80 of the UTF-8)
@@ -785,18 +802,20 @@
How Does Unicode Work With Traditional Locales?
-Perl tries to keep the two separated. Code points that are above 255
-are treated as Unicode; those below 256, generally as locale. This
-works reasonably well except in some case-insensitive regular expression
-pattern matches that in Unicode would cross the 255/256 boundary. These
-are disallowed.
-Also, the C<\p{}> and C<\N{}> constructs silently assume Unicode values
-even for code points below 256.
-See also L<perlrun> for the
-description of the C<-C> switch and its environment counterpart,
-C<$ENV{PERL_UNICODE}> to see how to enable various Unicode features,
-for example by using locale settings.
+Starting in Perl 5.16, you can specify
+ use locale ':not_characters';
+
+to get Perl to work well with tradtional locales. The catch is that you
+have to translate from the locale character set to/from Unicode
+yourself. See L</Unicode IE<sol>O> above for how to
+
+ use open ':locale';
+
+to accomplish this, but full details are in L<perllocale/Unicode and
+UTF-8>, including gotchas that happen if you don't specifiy
+C<:not_characters>.
+
=back
=head2 Hexadecimal Notation
Property changes on: trunk/contrib/perl/pod/perluniintro.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlunitut.pod
===================================================================
--- trunk/contrib/perl/pod/perlunitut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlunitut.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlunitut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlutil.pod
===================================================================
--- trunk/contrib/perl/pod/perlutil.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlutil.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -66,7 +66,7 @@
F<splain> is an interface to L<perldiag> - paste in your error message
to it, and it'll explain it for you.
-=item L<roffitall|roffitall>
+=item C<roffitall>
The C<roffitall> utility is not installed on your system but lives in
the F<pod/> directory of your Perl source kit; it converts all the
@@ -164,7 +164,7 @@
please read through the documentation for F<perlbug> thoroughly before
using it to submit a bug report.
-=item L<perlthanks|perlthanks>
+=item L<perlthanks|perlbug>
This program provides an easy way to send a thank-you message back to the
authors and maintainers of perl. It's just F<perlbug> installed under
@@ -209,13 +209,6 @@
necessary to let C functions manipulate Perl values and creates the glue
necessary to let Perl access those functions.
-=item L<dprofpp|dprofpp>
-
-Perl comes with a profiler, the F<Devel::DProf> module. The
-F<dprofpp> utility analyzes the output of this profiler and tells you
-which subroutines are taking up the most run time. See L<Devel::DProf>
-for more information.
-
=item L<prove>
F<prove> is a command-line interface to the test-running functionality
@@ -239,7 +232,7 @@
B<piconv> is a Perl version of B<iconv>, a character encoding converter
widely available for various Unixen today. This script was primarily a
-technology demonstrator for Perl 5.8.0, but you can use piconv in the
+technology demonstrator for Perl v5.8.0, but you can use piconv in the
place of iconv for virtually any case.
=item L<ptar>
@@ -263,6 +256,11 @@
This utility, that comes with the C<Digest::SHA> module, is used to print
or verify SHA checksums.
+=item L<zipdetails>
+
+L<zipdetails> displays information about the internal record structure of the zip file.
+It is not concerned with displaying any details of the compressed data stored in the zip file.
+
=back
=head2 Installation
@@ -304,11 +302,10 @@
L<perldoc|perldoc>, L<pod2man|pod2man>, L<perlpod>,
L<pod2html|pod2html>, L<pod2usage|pod2usage>, L<podselect|podselect>,
L<podchecker|podchecker>, L<splain|splain>, L<perldiag>,
-L<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
+C<roffitall|roffitall>, L<a2p|a2p>, L<s2p|s2p>, L<find2perl|find2perl>,
L<File::Find|File::Find>, L<pl2pm|pl2pm>, L<perlbug|perlbug>,
-L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<dprofpp|dprofpp>,
-L<Devel::DProf>, L<enc2xs>, L<xsubpp>, L<cpan>, L<cpanp>, L<cpan2dist>,
-L<instmodsh>, L<piconv>, L<prove>, L<corelist>, L<ptar>, L<ptardiff>,
-L<shasum>
+L<h2ph|h2ph>, L<c2ph|c2ph>, L<h2xs|h2xs>, L<enc2xs>, L<xsubpp>,
+L<cpan>, L<cpanp>, L<cpan2dist>, L<instmodsh>, L<piconv>, L<prove>,
+L<corelist>, L<ptar>, L<ptardiff>, L<shasum>, L<zipdetails>
=cut
Property changes on: trunk/contrib/perl/pod/perlutil.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlvar.pod
===================================================================
--- trunk/contrib/perl/pod/perlvar.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlvar.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -6,46 +6,46 @@
=head2 The Syntax of Variable Names
-Variable names in Perl can have several formats. Usually, they
+Variable names in Perl can have several formats. Usually, they
must begin with a letter or underscore, in which case they can be
arbitrarily long (up to an internal limit of 251 characters) and
may contain letters, digits, underscores, or the special sequence
-C<::> or C<'>. In this case, the part before the last C<::> or
+C<::> or C<'>. In this case, the part before the last C<::> or
C<'> is taken to be a I<package qualifier>; see L<perlmod>.
Perl variable names may also be a sequence of digits or a single
-punctuation or control character. These names are all reserved for
+punctuation or control character. These names are all reserved for
special uses by Perl; for example, the all-digits names are used
to hold data captured by backreferences after a regular expression
-match. Perl has a special syntax for the single-control-character
+match. Perl has a special syntax for the single-control-character
names: It understands C<^X> (caret C<X>) to mean the control-C<X>
-character. For example, the notation C<$^W> (dollar-sign caret
+character. For example, the notation C<$^W> (dollar-sign caret
C<W>) is the scalar variable whose name is the single character
-control-C<W>. This is better than typing a literal control-C<W>
+control-C<W>. This is better than typing a literal control-C<W>
into your program.
-Since Perl 5.6, Perl variable names may be alphanumeric
+Since Perl v5.6.0, Perl variable names may be alphanumeric
strings that begin with control characters (or better yet, a caret).
These variables must be written in the form C<${^Foo}>; the braces
-are not optional. C<${^Foo}> denotes the scalar variable whose
-name is a control-C<F> followed by two C<o>'s. These variables are
+are not optional. C<${^Foo}> denotes the scalar variable whose
+name is a control-C<F> followed by two C<o>'s. These variables are
reserved for future special uses by Perl, except for the ones that
-begin with C<^_> (control-underscore or caret-underscore). No
+begin with C<^_> (control-underscore or caret-underscore). No
control-character name that begins with C<^_> will acquire a special
meaning in any future version of Perl; such names may therefore be
-used safely in programs. C<$^_> itself, however, I<is> reserved.
+used safely in programs. C<$^_> itself, however, I<is> reserved.
Perl identifiers that begin with digits, control characters, or
punctuation characters are exempt from the effects of the C<package>
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
+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
@@ -53,21 +53,21 @@
=head1 SPECIAL VARIABLES
-The following names have special meaning to Perl. Most punctuation
+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
-borrowed from B<awk>. To avoid a performance hit, if you don't need the
+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
+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
+Before you continue, note the sort order for variables. In general, we
first list the variables in case-insensitive, almost-lexigraphical
order (ignoring the C<{> or C<^> preceding words, as in C<${^UNICODE}>
or C<$^T>), although C<$_> and C<@_> move up to the top of the pile.
@@ -83,20 +83,20 @@
=item $_
X<$_> X<$ARG>
-The default input and pattern-searching space. The following pairs are
+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:
@@ -106,10 +106,12 @@
The following functions use C<$_> as a default argument:
-abs, alarm, chomp, chop, chr, chroot, cos, defined, eval, exp, glob,
-hex, int, lc, lcfirst, length, log, lstat, mkdir, oct, ord, pos, print,
+abs, alarm, chomp, chop, chr, chroot,
+cos, defined, eval, evalbytes, exp, fc, glob, hex, int, lc,
+lcfirst, length, log, lstat, mkdir, oct, ord, pos, print, printf,
quotemeta, readlink, readpipe, ref, require, reverse (in scalar context only),
-rmdir, sin, split (on its second argument), sqrt, stat, study, uc, ucfirst,
+rmdir, say, sin, split (for its second
+argument), sqrt, stat, study, uc, ucfirst,
unlink, unpack.
=item *
@@ -137,16 +139,26 @@
=item *
-The default place to put an input record when a C<< <FH> >>
+The default place to put the next value or input record
+when a C<< <FH> >>, C<readline>, C<readdir> or C<each>
operation's result is tested by itself as the sole criterion of a C<while>
-test. Outside a C<while> test, this will not happen.
+test. Outside a C<while> test, this will not happen.
=back
-As C<$_> is a global variable, this may lead in some cases to unwanted
-side-effects. As of perl 5.9.1, you can now use a lexical version of
-C<$_> by declaring it in a file or in a block with C<my>. Moreover,
-declaring C<our $_> restores the global C<$_> in the current scope.
+C<$_> is by default a global variable. However, as
+of perl v5.10.0, you can use a lexical version of
+C<$_> by declaring it in a file or in a block with C<my>. Moreover,
+declaring C<our $_> restores the global C<$_> in the current scope. Though
+this seemed like a good idea at the time it was introduced, lexical C<$_>
+actually causes more problems than it solves. If you call a function that
+expects to be passed information via C<$_>, it may or may not work,
+depending on how the function is written, there not being any easy way to
+solve this. Just avoid lexical C<$_>, unless you are feeling particularly
+masochistic. For this reason lexical C<$_> is still experimental and will
+produce a warning unless warnings have been disabled. As with other
+experimental features, the behavior of lexical C<$_> is subject to change
+without notice, including change into a fatal error.
Mnemonic: underline is understood in certain operations.
@@ -156,7 +168,7 @@
X<@_> X<@ARG>
Within a subroutine the array C<@_> contains the parameters passed to
-that subroutine. Inside a subroutine, C<@_> is the default array for
+that subroutine. Inside a subroutine, C<@_> is the default array for
the array operators C<push>, C<pop>, C<shift>, and C<unshift>.
See L<perlsub>.
@@ -168,13 +180,13 @@
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:
+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.
@@ -185,76 +197,31 @@
=item $$
X<$$> X<$PID> X<$PROCESS_ID>
-The process number of the Perl running this script. You should
-consider this variable read-only, although it will be altered
+The process number of the Perl running this script. Though you I<can> set
+this variable, doing so is generally discouraged, although it can be
+invaluable for some testing purposes. It will be reset automatically
across C<fork()> calls.
-Note for Linux users: on Linux, the C functions C<getpid()> and
-C<getppid()> return different values from different threads. In order to
-be portable, this behavior is not reflected by C<$$>, whose value remains
-consistent across threads. If you want to call the underlying C<getpid()>,
-you may use the CPAN module C<Linux::Pid>.
+Note for Linux and Debian GNU/kFreeBSD users: Before Perl v5.16.0 perl
+would emulate POSIX semantics on Linux systems using LinuxThreads, a
+partial implementation of POSIX Threads that has since been superseded
+by the Native POSIX Thread Library (NPTL).
-Mnemonic: same as shells.
+LinuxThreads is now obsolete on Linux, and caching C<getpid()>
+like this made embedding perl unnecessarily complex (since you'd have
+to manually update the value of $$), so now C<$$> and C<getppid()>
+will always return the same values as the underlying C library.
-=item $REAL_GROUP_ID
+Debian GNU/kFreeBSD systems also used LinuxThreads up until and
+including the 6.0 release, but after that moved to FreeBSD thread
+semantics, which are POSIX-like.
-=item $GID
+To see if your system is affected by this discrepancy check if
+C<getconf GNU_LIBPTHREAD_VERSION | grep -q NPTL> returns a false
+value. NTPL threads preserve the POSIX semantics.
-=item $(
-X<$(> X<$GID> X<$REAL_GROUP_ID>
+Mnemonic: same as shells.
-The real gid of this process. If you are on a machine that supports
-membership in multiple groups simultaneously, gives a space separated
-list of groups you are in. The first number is the one returned by
-C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
-the same as the first number.
-
-However, a value assigned to C<$(> must be a single number used to
-set the real gid. So the value given by C<$(> should I<not> be assigned
-back to C<$(> without being forced numeric, such as by adding zero. Note
-that this is different to the effective gid (C<$)>) which does take a
-list.
-
-You can change both the real gid and the effective gid at the same
-time by using C<POSIX::setgid()>. Changes to C<$(> require a check to C<$!>
-to detect any possible errors after an attempted change.
-
-Mnemonic: parentheses are used to I<group> things. The real gid is the
-group you I<left>, if you're running setgid.
-
-=item $EFFECTIVE_GROUP_ID
-
-=item $EGID
-
-=item $)
-X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
-
-The effective gid of this process. If you are on a machine that
-supports membership in multiple groups simultaneously, gives a space
-separated list of groups you are in. The first number is the one
-returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
-one of which may be the same as the first number.
-
-Similarly, a value assigned to C<$)> must also be a space-separated
-list of numbers. The first number sets the effective gid, and
-the rest (if any) are passed to C<setgroups()>. To get the effect of an
-empty list for C<setgroups()>, just repeat the new effective gid; that is,
-to force an effective gid of 5 and an effectively empty C<setgroups()>
-list, say C< $) = "5 5" >.
-
-You can change both the effective gid and the real gid at the same
-time by using C<POSIX::setgid()> (use only a single numeric argument).
-Changes to C<$)> require a check to C<$!> to detect any possible errors
-after an attempted change.
-
-C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
-machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
-and C<$)> can be swapped only on machines supporting C<setregid()>.
-
-Mnemonic: parentheses are used to I<group> things. The effective gid
-is the group that's I<right> for you, if you're running setgid.
-
=item $PROGRAM_NAME
=item $0
@@ -263,14 +230,14 @@
Contains the name of the program being executed.
On some (but not all) operating systems assigning to C<$0> modifies
-the argument area that the C<ps> program sees. On some platforms you
+the argument area that the C<ps> program sees. On some platforms you
may have to use special C<ps> options or a different C<ps> to see the
-changes. Modifying the C<$0> is more useful as a way of indicating the
+changes. Modifying the C<$0> is more useful as a way of indicating the
current program state than it is for hiding the program you're
running.
Note that there are platform-specific limitations on the maximum
-length of C<$0>. In the most extreme case it may be limited to the
+length of C<$0>. In the most extreme case it may be limited to the
space occupied by the original C<$0>.
In some platforms there may be arbitrary amount of padding, for
@@ -280,14 +247,14 @@
for example with Linux 2.2).
Note for BSD users: setting C<$0> does not completely remove "perl"
-from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
+from the ps(1) output. For example, setting C<$0> to C<"foobar"> may
result in C<"perl: foobar (perl)"> (whether both the C<"perl: "> prefix
and the " (perl)" suffix are shown depends on your exact BSD variant
-and version). This is an operating system feature, Perl cannot help it.
+and version). This is an operating system feature, Perl cannot help it.
In multithreaded scripts Perl coordinates the threads so that any
thread may modify its copy of the C<$0> and the change becomes visible
-to ps(1) (assuming the operating system plays along). Note that
+to ps(1) (assuming the operating system plays along). Note that
the view of C<$0> the other threads have will not change since they
have their own copies of it.
@@ -294,47 +261,74 @@
If the program has been given to perl via the switches C<-e> or C<-E>,
C<$0> will contain the string C<"-e">.
-On Linux as of perl 5.14 the legacy process name will be set with
+On Linux as of perl v5.14.0 the legacy process name will be set with
C<prctl(2)>, in addition to altering the POSIX name via C<argv[0]> as
-perl has done since version 4.000. Now system utilities that read the
+perl has done since version 4.000. Now system utilities that read the
legacy process name such as ps, top and killall will recognize the
-name you set when assigning to C<$0>. The string you supply will be
+name you set when assigning to C<$0>. The string you supply will be
cut off at 16 bytes, this is a limitation imposed by Linux.
Mnemonic: same as B<sh> and B<ksh>.
-=item $SUBSCRIPT_SEPARATOR
+=item $REAL_GROUP_ID
-=item $SUBSEP
+=item $GID
-=item $;
-X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
+=item $(
+X<$(> X<$GID> X<$REAL_GROUP_ID>
-The subscript separator for multidimensional array emulation. If you
-refer to a hash element as
+The real gid of this process. If you are on a machine that supports
+membership in multiple groups simultaneously, gives a space separated
+list of groups you are in. The first number is the one returned by
+C<getgid()>, and the subsequent ones by C<getgroups()>, one of which may be
+the same as the first number.
- $foo{$a,$b,$c}
+However, a value assigned to C<$(> must be a single number used to
+set the real gid. So the value given by C<$(> should I<not> be assigned
+back to C<$(> without being forced numeric, such as by adding zero. Note
+that this is different to the effective gid (C<$)>) which does take a
+list.
-it really means
+You can change both the real gid and the effective gid at the same
+time by using C<POSIX::setgid()>. Changes
+to C<$(> require a check to C<$!>
+to detect any possible errors after an attempted change.
- $foo{join($;, $a, $b, $c)}
+Mnemonic: parentheses are used to I<group> things. The real gid is the
+group you I<left>, if you're running setgid.
-But don't put
+=item $EFFECTIVE_GROUP_ID
- @foo{$a,$b,$c} # a slice--note the @
+=item $EGID
-which means
+=item $)
+X<$)> X<$EGID> X<$EFFECTIVE_GROUP_ID>
- ($foo{$a},$foo{$b},$foo{$c})
+The effective gid of this process. If you are on a machine that
+supports membership in multiple groups simultaneously, gives a space
+separated list of groups you are in. The first number is the one
+returned by C<getegid()>, and the subsequent ones by C<getgroups()>,
+one of which may be the same as the first number.
-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<$;>.
+Similarly, a value assigned to C<$)> must also be a space-separated
+list of numbers. The first number sets the effective gid, and
+the rest (if any) are passed to C<setgroups()>. To get the effect of an
+empty list for C<setgroups()>, just repeat the new effective gid; that is,
+to force an effective gid of 5 and an effectively empty C<setgroups()>
+list, say C< $) = "5 5" >.
-Consider using "real" multidimensional arrays as described
-in L<perllol>.
+You can change both the effective gid and the real gid at the same
+time by using C<POSIX::setgid()> (use only a single numeric argument).
+Changes to C<$)> require a check to C<$!> to detect any possible errors
+after an attempted change.
-Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
+C<< $< >>, C<< $> >>, C<$(> and C<$)> can be set only on
+machines that support the corresponding I<set[re][ug]id()> routine. C<$(>
+and C<$)> can be swapped only on machines supporting C<setregid()>.
+Mnemonic: parentheses are used to I<group> things. The effective gid
+is the group that's I<right> for you, if you're running setgid.
+
=item $REAL_USER_ID
=item $UID
@@ -342,8 +336,8 @@
=item $<
X<< $< >> X<$UID> X<$REAL_USER_ID>
-The real uid of this process. You can change both the real uid and the
-effective uid at the same time by using C<POSIX::setuid()>. Since
+The real uid of this process. You can change both the real uid and the
+effective uid at the same time by using C<POSIX::setuid()>. Since
changes to C<< $< >> require a system call, check C<$!> after a change
attempt to detect any possible errors.
@@ -356,13 +350,13 @@
=item $>
X<< $> >> X<$EUID> X<$EFFECTIVE_USER_ID>
-The effective uid of this process. For example:
+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
+time by using C<POSIX::setuid()>. Changes to C<< $> >> require a check
to C<$!> to detect any possible errors after an attempted change.
C<< $< >> and C<< $> >> can be swapped only on machines
@@ -370,55 +364,53 @@
Mnemonic: it's the uid you went I<to>, if you're running setuid.
-=item $a
+=item $SUBSCRIPT_SEPARATOR
-=item $b
-X<$a> X<$b>
+=item $SUBSEP
-Special package variables when using C<sort()>, see L<perlfunc/sort>.
-Because of this specialness C<$a> and C<$b> don't need to be declared
-(using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
-pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
-be able to use them in the C<sort()> comparison block or function.
+=item $;
+X<$;> X<$SUBSEP> X<SUBSCRIPT_SEPARATOR>
-=item $COMPILING
+The subscript separator for multidimensional array emulation. If you
+refer to a hash element as
-=item $^C
-X<$^C> X<$COMPILING>
+ $foo{$a,$b,$c}
-The current value of the flag associated with the B<-c> switch.
-Mainly of use with B<-MO=...> to allow code to alter its behavior
-when being compiled, such as for example to C<AUTOLOAD> at compile
-time rather than normal, deferred loading. Setting
-C<$^C = 1> is similar to calling C<B::minus_c>.
+it really means
-This variable was added in Perl 5.6.
+ $foo{join($;, $a, $b, $c)}
-=item $DEBUGGING
+But don't put
-=item $^D
-X<$^D> X<$DEBUGGING>
+ @foo{$a,$b,$c} # a slice--note the @
-The current value of the debugging flags. May be read or set. Like its
-command-line equivalent, you can use numeric or symbolic values, eg
-C<$^D = 10> or C<$^D = "st">.
+which means
-Mnemonic: value of B<-D> switch.
+ ($foo{$a},$foo{$b},$foo{$c})
-=item ${^ENCODING}
-X<${^ENCODING}>
+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<$;>.
-The I<object reference> to the C<Encode> object that is used to convert
-the source code to Unicode. Thanks to this variable your Perl script
-does not have to be written in UTF-8. Default is I<undef>. The direct
-manipulation of this variable is highly discouraged.
+Consider using "real" multidimensional arrays as described
+in L<perllol>.
-This variable was added in Perl 5.8.2.
+Mnemonic: comma (the syntactic subscript separator) is a semi-semicolon.
+=item $a
+
+=item $b
+X<$a> X<$b>
+
+Special package variables when using C<sort()>, see L<perlfunc/sort>.
+Because of this specialness C<$a> and C<$b> don't need to be declared
+(using C<use vars>, or C<our()>) even when using the C<strict 'vars'>
+pragma. Don't lexicalize them with C<my $a> or C<my $b> if you want to
+be able to use them in the C<sort()> comparison block or function.
+
=item %ENV
X<%ENV>
-The hash C<%ENV> contains your current environment. Setting a
+The hash C<%ENV> contains your current environment. Setting a
value in C<ENV> changes the environment for any child processes
you subsequently C<fork()> off.
@@ -427,11 +419,12 @@
=item $^F
X<$^F> X<$SYSTEM_FD_MAX>
-The maximum system file descriptor, ordinarily 2. System file
+The maximum system file descriptor, ordinarily 2. System file
descriptors are passed to C<exec()>ed processes, while higher file
-descriptors are not. Also, during an C<open()>, system file descriptors are
+descriptors are not. Also, during an
+C<open()>, system file descriptors are
preserved even if the C<open()> fails (ordinary file descriptors are
-closed before the C<open()> is attempted). The close-on-exec
+closed before the C<open()> is attempted). The close-on-exec
status of a file descriptor will be decided according to the value of
C<$^F> when the corresponding file, pipe, or socket was opened, not the
time of the C<exec()>.
@@ -440,203 +433,43 @@
X<@F>
The array C<@F> contains the fields of each line read in when autosplit
-mode is turned on. See L<perlrun> for the B<-a> switch. This array
+mode is turned on. See L<perlrun> for the B<-a> switch. This array
is package-specific, and must be declared or given a full package name
if not in package main when running under C<strict 'vars'>.
-=item ${^GLOBAL_PHASE}
-X<${^GLOBAL_PHASE}>
-
-The current phase of the perl interpreter.
-
-Possible values are:
-
-=over 8
-
-=item CONSTRUCT
-
-The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
-value is mostly there for completeness and for use via the
-underlying C variable C<PL_phase>. It's not really possible for Perl
-code to be executed unless construction of the interpreter is
-finished.
-
-=item START
-
-This is the global compile-time. That includes, basically, every
-C<BEGIN> block executed directly or indirectly from during the
-compile-time of the top-level program.
-
-This phase is not called "BEGIN" to avoid confusion with
-C<BEGIN>-blocks, as those are executed during compile-time of any
-compilation unit, not just the top-level program. A new, localised
-compile-time entered at run-time, for example by constructs as
-C<eval "use SomeModule"> are not global interpreter phases, and
-therefore aren't reflected by C<${^GLOBAL_PHASE}>.
-
-=item CHECK
-
-Execution of any C<CHECK> blocks.
-
-=item INIT
-
-Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
-
-=item RUN
-
-The main run-time, i.e. the execution of C<PL_main_root>.
-
-=item END
-
-Execution of any C<END> blocks.
-
-=item DESTRUCT
-
-Global destruction.
-
-=back
-
-Also note that there's no value for UNITCHECK-blocks. That's because
-those are run for each compilation unit individually, and therefore is
-not a global interpreter phase.
-
-Not every program has to go through each of the possible phases, but
-transition from one phase to another can only happen in the order
-described in the above list.
-
-An example of all of the phases Perl code can see:
-
- BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
-
- INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
-
- CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
-
- {
- package Print::Phase;
-
- sub new {
- my ($class, $time) = @_;
- return bless \$time, $class;
- }
-
- sub DESTROY {
- my $self = shift;
- print "$$self: ${^GLOBAL_PHASE}\n";
- }
- }
-
- print "run-time: ${^GLOBAL_PHASE}\n";
-
- my $runtime = Print::Phase->new(
- "lexical variables are garbage collected before END"
- );
-
- END { print "end-time: ${^GLOBAL_PHASE}\n" }
-
- our $destruct = Print::Phase->new(
- "package variables are garbage collected after END"
- );
-
-This will print out
-
- compile-time: START
- check-time: CHECK
- init-time: INIT
- run-time: RUN
- lexical variables are garbage collected before END: RUN
- end-time: END
- package variables are garbage collected after END: DESTRUCT
-
-This variable was added in Perl 5.14.0.
-
-=item $^H
-X<$^H>
-
-WARNING: This variable is strictly for internal use only. Its availability,
-behavior, and contents are subject to change without notice.
-
-This variable contains compile-time hints for the Perl interpreter. At the
-end of compilation of a BLOCK the value of this variable is restored to the
-value when the interpreter started to compile the BLOCK.
-
-When perl begins to parse any block construct that provides a lexical scope
-(e.g., eval body, required file, subroutine body, loop body, or conditional
-block), the existing value of C<$^H> is saved, but its value is left unchanged.
-When the compilation of the block is completed, it regains the saved value.
-Between the points where its value is saved and restored, code that
-executes within BEGIN blocks is free to change the value of C<$^H>.
-
-This behavior provides the semantic of lexical scoping, and is used in,
-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 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
-being compiled. The new value of C<$^H> will therefore be visible only while
-the body of C<foo()> is being compiled.
-
-Substitution of C<BEGIN { add_100() }> block with:
-
- 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 }
-
-This variable was added in Perl 5.003.
-
-=item %^H
-X<%^H>
-
-The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes it
-useful for implementation of lexically scoped pragmas. See L<perlpragma>.
-
-This variable was added in Perl 5.6.
-
=item @INC
X<@INC>
The array C<@INC> contains the list of places that the C<do EXPR>,
-C<require>, or C<use> constructs look for their library files. It
+C<require>, or C<use> constructs look for their library files. It
initially consists of the arguments to any B<-I> command-line
switches, followed by the default Perl library, probably
F</usr/local/lib/perl>, followed by ".", to represent the current
-directory. ("." will not be appended if taint checks are enabled,
+directory. ("." will not be appended if taint checks are enabled,
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, array
-references or blessed objects. See L<perlfunc/require> for details.
+code directly into C<@INC>. Those hooks may be subroutine references,
+array references or blessed objects. See L<perlfunc/require> for details.
=item %INC
X<%INC>
The hash C<%INC> contains entries for each filename included via the
-C<do>, C<require>, or C<use> operators. The key is the filename
+C<do>, C<require>, or C<use> operators. The key is the filename
you specified (with module names converted to pathnames), and the
-value is the location of the file found. The C<require>
+value is the location of the file found. The C<require>
operator uses this hash to determine whether a particular file has
already been included.
If the file was loaded via a hook (e.g. a subroutine reference, see
L<perlfunc/require> for a description of these hooks), this hook is
-by default inserted into C<%INC> in place of a filename. Note, however,
+by default inserted into C<%INC> in place of a filename. Note, however,
that the hook may have set the C<%INC> entry by itself to provide some more
specific info.
@@ -645,7 +478,7 @@
=item $^I
X<$^I> X<$INPLACE_EDIT>
-The current value of the inplace-edit extension. Use C<undef> to disable
+The current value of the inplace-edit extension. Use C<undef> to disable
inplace editing.
Mnemonic: value of B<-i> switch.
@@ -655,15 +488,15 @@
By default, running out of memory is an untrappable, fatal error.
However, if suitably built, Perl can use the contents of C<$^M>
-as an emergency memory pool after C<die()>ing. Suppose that your Perl
+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
+would allocate a 64K buffer for use in an emergency. See the
F<INSTALL> file in the Perl distribution for information on how to
-add custom C compilation flags when compiling perl. To discourage casual
+add custom C compilation flags when compiling perl. To discourage casual
use of this advanced feature, there is no L<English|English> long name for
this variable.
@@ -675,183 +508,116 @@
X<$^O> X<$OSNAME>
The name of the operating system under which this copy of Perl was
-built, as determined during the configuration process. For examples
+built, as determined during the configuration process. For examples
see L<perlport/PLATFORMS>.
-The value is identical to C<$Config{'osname'}>. See also L<Config>
+The value is identical to C<$Config{'osname'}>. See also L<Config>
and the B<-V> command-line switch documented in L<perlrun>.
In Windows platforms, C<$^O> is not very helpful: since it is always
C<MSWin32>, it doesn't tell the difference between
-95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
+95/98/ME/NT/2000/XP/CE/.NET. Use C<Win32::GetOSName()> or
Win32::GetOSVersion() (see L<Win32> and L<perlport>) to distinguish
between the variants.
This variable was added in Perl 5.003.
-=item ${^OPEN}
-X<${^OPEN}>
-
-An internal variable used by PerlIO. A string in two parts, separated
-by a C<\0> byte, the first part describes the input layers, the second
-part describes the output layers.
-
-This variable was added in Perl 5.8.2.
-
-=item $PERLDB
-
-=item $^P
-X<$^P> X<$PERLDB>
-
-The internal variable for debugging support. The meanings of the
-various bits are subject to change, but currently indicate:
-
-=over 6
-
-=item 0x01
-
-Debug subroutine enter/exit.
-
-=item 0x02
-
-Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for each
-statement executed. Also causes saving source code lines (like 0x400).
-
-=item 0x04
-
-Switch off optimizations.
-
-=item 0x08
-
-Preserve more data for future interactive inspections.
-
-=item 0x10
-
-Keep info about source lines on which a subroutine is defined.
-
-=item 0x20
-
-Start with single-step on.
-
-=item 0x40
-
-Use subroutine address instead of name when reporting.
-
-=item 0x80
-
-Report C<goto &subroutine> as well.
-
-=item 0x100
-
-Provide informative "file" names for evals based on the place they were compiled.
-
-=item 0x200
-
-Provide informative names to anonymous subroutines based on the place they
-were compiled.
-
-=item 0x400
-
-Save source code lines into C<@{"_<$filename"}>.
-
-=back
-
-Some bits may be relevant at compile-time only, some at
-run-time only. This is a new mechanism and the details may change.
-See also L<perldebguts>.
-
=item %SIG
X<%SIG>
-The hash C<%SIG> contains signal handlers for signals. For example:
+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
+signal, except for the C<CHLD> signal. See L<perlipc> for more about
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.
If your system has the C<sigaction()> function then signal handlers
-are installed using it. This means you get reliable signal handling.
+are installed using it. This means you get reliable signal handling.
-The default delivery policy of signals changed in Perl 5.8.0 from
+The default delivery policy of signals changed in Perl v5.8.0 from
immediate (also known as "unsafe") to deferred, also known as "safe
-signals". See L<perlipc> for more information.
+signals". See L<perlipc> for more information.
-Certain internal hooks can be also set using the C<%SIG> hash. The
+Certain internal hooks can be also set using the C<%SIG> hash. The
routine indicated by C<$SIG{__WARN__}> is called when a warning
-message is about to be printed. The warning message is passed as the
-first argument. The presence of a C<__WARN__> hook causes the
-ordinary printing of warnings to C<STDERR> to be suppressed. You can
+message is about to be printed. The warning message is passed as the
+first argument. The presence of a C<__WARN__> hook causes the
+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
-first argument. When a C<__DIE__> hook routine returns, the exception
+exception is about to be thrown. The error message is passed as the
+first argument. When a C<__DIE__> hook routine returns, the exception
processing continues as it would have in the absence of the hook,
-unless the hook routine itself exits via a C<goto>, a loop exit, or a
-C<die()>. The C<__DIE__> handler is explicitly disabled during the
-call, so that you can die from a C<__DIE__> handler. Similarly for
-C<__WARN__>.
+unless the hook routine itself exits via a C<goto &sub>, a loop exit,
+or a C<die()>. The C<__DIE__> handler is explicitly disabled during
+the call, so that you can die from a C<__DIE__> handler. Similarly
+for C<__WARN__>.
Due to an implementation glitch, the C<$SIG{__DIE__}> hook is called
-even inside an C<eval()>. Do not use this to rewrite a pending
+even inside an C<eval()>. Do not use this to rewrite a pending
exception in C<$@>, or as a bizarre substitute for overriding
-C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed
+C<CORE::GLOBAL::die()>. This strange action at a distance may be fixed
in a future release so that C<$SIG{__DIE__}> is only called if your
-program is about to exit, as was the original intent. Any other use is
+program is about to exit, as was the original intent. Any other use is
deprecated.
C<__DIE__>/C<__WARN__> handlers are very special in one respect: they
-may be called to report (probable) errors found by the parser. In such
+may be called to report (probable) errors found by the parser. In such
a case the parser may be in inconsistent state, so any attempt to
evaluate Perl code from such a handler will probably result in a
-segfault. This means that warnings or errors that result from parsing
+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
-C<Carp> was available. The third line will be executed only if C<Carp> was
+called the handler. The second line will print backtrace and die if
+C<Carp> was available. The third line will be executed only if C<Carp> was
not available.
Having to even think about the C<$^S> variable in your exception
-handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
-invites grievous and difficult to track down errors. Avoid it
+handlers is simply wrong. C<$SIG{__DIE__}> as currently implemented
+invites grievous and difficult to track down errors. Avoid it
and use an C<END{}> or CORE::GLOBAL::die override instead.
See L<perlfunc/die>, L<perlfunc/warn>, L<perlfunc/eval>, and
@@ -863,50 +629,9 @@
X<$^T> X<$BASETIME>
The time at which the program began running, in seconds since the
-epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
+epoch (beginning of 1970). The values returned by the B<-M>, B<-A>,
and B<-C> filetests are based on this value.
-=item ${^TAINT}
-X<${^TAINT}>
-
-Reflects if taint mode is on or off. 1 for on (the program was run with
-B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
-B<-t> or B<-TU>).
-
-This variable is read-only.
-
-This variable was added in Perl 5.8.
-
-=item ${^UNICODE}
-X<${^UNICODE}>
-
-Reflects certain Unicode settings of Perl. See L<perlrun>
-documentation for the C<-C> switch for more information about
-the possible values.
-
-This variable is set during Perl startup and is thereafter read-only.
-
-This variable was added in Perl 5.8.2.
-
-=item ${^UTF8CACHE}
-X<${^UTF8CACHE}>
-
-This variable controls the state of the internal UTF-8 offset caching code.
-1 for on (the default), 0 for off, -1 to debug the caching code by checking
-all its results against linear scans, and panicking on any discrepancy.
-
-This variable was added in Perl 5.8.9.
-
-=item ${^UTF8LOCALE}
-X<${^UTF8LOCALE}>
-
-This variable indicates whether a UTF-8 locale was detected by perl at
-startup. This information is used by perl when it's in
-adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
-switch); see L<perlrun> for more info on this.
-
-This variable was added in Perl 5.8.8.
-
=item $PERL_VERSION
=item $^V
@@ -915,19 +640,19 @@
The revision, version, and subversion of the Perl interpreter,
represented as a C<version> object.
-This variable first appeared in perl 5.6.0; earlier versions of perl
-will see an undefined value. Before perl 5.10.0 C<$^V> was represented
+This variable first appeared in perl v5.6.0; earlier versions of perl
+will see an undefined value. Before perl v5.10.0 C<$^V> was represented
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:
+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.
@@ -934,7 +659,7 @@
See also C<$]> for an older representation of the Perl version.
-This variable was added in Perl 5.6.
+This variable was added in Perl v5.6.0.
Mnemonic: use ^V for Version Control.
@@ -942,18 +667,18 @@
X<${^WIN32_SLOPPY_STAT}> X<sitecustomize> X<sitecustomize.pl>
If this variable is set to a true value, then C<stat()> on Windows will
-not try to open the file. This means that the link count cannot be
+not try to open the file. This means that the link count cannot be
determined and file attributes may be out of date if additional
-hardlinks to the file exist. On the other hand, not opening the file
+hardlinks to the file exist. On the other hand, not opening the file
is considerably faster, especially for files on network drives.
This variable could be set in the F<sitecustomize.pl> file to
configure the local Perl installation to use "sloppy" C<stat()> by
-default. See the documentation for B<-f> in
+default. See the documentation for B<-f> in
L<perlrun|perlrun/"Command Switches"> for more information about site
customization.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
=item $EXECUTABLE_NAME
@@ -966,15 +691,15 @@
Depending on the host operating system, the value of C<$^X> may be
a relative or absolute pathname of the perl program file, or may
be the string used to invoke perl but not the pathname of the
-perl program file. Also, most operating systems permit invoking
+perl program file. Also, most operating systems permit invoking
programs that are not in the PATH environment variable, so there
-is no guarantee that the value of C<$^X> is in PATH. For VMS, the
+is no guarantee that the value of C<$^X> is in PATH. For VMS, the
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
@@ -983,31 +708,31 @@
It is not safe to use the value of C<$^X> as a path name of a file,
as some operating systems that have a mandatory suffix on
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
+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
then execute the copy, the security-conscious Perl programmer
should take care to invoke the installed copy of perl, not the
-copy referenced by C<$^X>. The following statements accomplish
+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
@@ -1014,12 +739,12 @@
=head2 Variables related to regular expressions
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:
+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.
@@ -1028,50 +753,50 @@
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>
+and C<$2> are from the match against C<$outer>. Inside the C<INNER>
block, the values of C<$1> and C<$2> are from the match against
C<$inner>, but only until the end of the block (i.e. the dynamic
-scope). After the C<INNER> block completes, the values of C<$1> and
+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
expression matches in a program because it uses the C<$`>, C<$&>, and
C<$'>, regardless of whether they occur in the scope of C<use
-English>. For that reason, saying C<use English> in libraries is
+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
problematic match variables in your code.
-Since Perl 5.10, you can use the C</p> match operator flag and the
+Since Perl v5.10.0, you can use the C</p> match operator flag and the
C<${^PREMATCH}>, C<${^MATCH}>, and C<${^POSTMATCH}> variables instead
so you only suffer the performance penalties.
@@ -1098,9 +823,9 @@
BLOCK).
The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L</@->. Starting
-with Perl 5.10, you can use the </p> match flag and the C<${^MATCH}>
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L</@->. Starting
+with Perl v5.10.0, you can use the C</p> match flag and the C<${^MATCH}>
variable to do the same thing for particular match operations.
This variable is read-only and dynamically-scoped.
@@ -1115,7 +840,7 @@
to return a defined value when the pattern was compiled or executed with
the C</p> modifier.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
@@ -1129,9 +854,9 @@
enclosed by the current BLOCK.
The use of this variable anywhere in a program imposes a considerable
-performance penalty on all regular expression matches. To avoid this
-penalty, you can extract the same substring by using L</@->. Starting
-with Perl 5.10, you can use the </p> match flag and the
+performance penalty on all regular expression matches. To avoid this
+penalty, you can extract the same substring by using L</@->. Starting
+with Perl v5.10.0, you can use the C</p> match flag and the
C<${^PREMATCH}> variable to do the same thing for particular match
operations.
@@ -1147,7 +872,7 @@
to return a defined value when the pattern was compiled or executed with
the C</p> modifier.
-This variable was added in Perl 5.10
+This variable was added in Perl v5.10.0
This variable is read-only and dynamically-scoped.
@@ -1158,16 +883,16 @@
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:
+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.
To avoid this penalty, you can extract the same substring by
-using L</@->. Starting with Perl 5.10, you can use the </p> match flag
+using L</@->. Starting with Perl v5.10.0, you can use the C</p> match flag
and the C<${^POSTMATCH}> variable to do the same thing for particular
match operations.
@@ -1183,7 +908,7 @@
to return a defined value when the pattern was compiled or executed with
the C</p> modifier.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
@@ -1194,9 +919,9 @@
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:
+matched. For example:
- /Version: (.*)|Revision: (.*)/ && ($rev = $+);
+ /Version: (.*)|Revision: (.*)/ && ($rev = $+);
This variable is read-only and dynamically-scoped.
@@ -1212,15 +937,15 @@
pattern.
This is primarily used inside C<(?{...})> blocks for examining text
-recently matched. For example, to effectively capture text to a variable
+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.
-This variable was added in Perl 5.8.
+This variable was added in Perl v5.8.0.
Mnemonic: the (possibly) Nested parenthesis that most recently closed.
@@ -1230,17 +955,17 @@
X<@+> X<@LAST_MATCH_END>
This array holds the offsets of the ends of the last successful
-submatches in the currently active dynamic scope. C<$+[0]> is
-the offset into the string of the end of the entire match. This
+submatches in the currently active dynamic scope. C<$+[0]> is
+the offset into the string of the end of the entire match. This
is the same value as what the C<pos> function returns when called
-on the variable that was matched against. The I<n>th element
+on the variable that was matched against. The I<n>th element
of this array holds the offset of the I<n>th submatch, so
C<$+[1]> is the offset past where C<$1> ends, C<$+[2]> the offset
-past where C<$2> ends, and so on. You can use C<$#+> to determine
-how many subgroups were in the last successful match. See the
+past where C<$2> ends, and so on. You can use C<$#+> to determine
+how many subgroups were in the last successful match. See the
examples given for the C<@-> variable.
-This variable was added in Perl 5.6.
+This variable was added in Perl v5.6.0.
=item %LAST_PAREN_MATCH
@@ -1253,7 +978,7 @@
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).
@@ -1262,12 +987,12 @@
L<Tie::Hash::NamedCapture> module.
B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
+associated with the last successful regular expression. Therefore mixing
iterative access to them via C<each> may have unpredictable results.
Likewise, if the last successful match changes, then the results may be
surprising.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
@@ -1281,17 +1006,17 @@
I<n>-th subpattern, or undef if the subpattern did not match.
Thus, after a match against C<$_>, C<$&> coincides with C<substr $_, $-[0],
-$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
+$+[0] - $-[0]>. Similarly, $I<n> coincides with C<substr $_, $-[n],
$+[n] - $-[n]> if C<$-[n]> is defined, and $+ coincides with
-C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the last
-matched subgroup in the last successful match. Contrast with
-C<$#+>, the number of subgroups in the regular expression. Compare
+C<substr $_, $-[$#-], $+[$#-] - $-[$#-]>. One can use C<$#-> to find the
+last matched subgroup in the last successful match. Contrast with
+C<$#+>, the number of subgroups in the regular expression. Compare
with C<@+>.
This array holds the offsets of the beginnings of the last
successful submatches in the currently active dynamic scope.
C<$-[0]> is the offset into the string of the beginning of the
-entire match. The I<n>th element of this array holds the offset
+entire match. The I<n>th element of this array holds the offset
of the I<n>th submatch, so C<$-[1]> is the offset where C<$1>
begins, C<$-[2]> the offset where C<$2> begins, and so on.
@@ -1313,7 +1038,7 @@
=back
-This variable was added in Perl 5.6.
+This variable was added in Perl v5.6.0.
=item %LAST_MATCH_START
@@ -1321,7 +1046,7 @@
X<%-> X<%LAST_MATCH_START>
Similar to C<%+>, this variable allows access to the named capture groups
-in the last successful match in the currently active dynamic scope. To
+in the last successful match in the currently active dynamic scope. To
each capture group name found in the regular expression, it associates a
reference to an array containing the list of values captured by all
buffers with that name (should there be several of them), in the order
@@ -1334,7 +1059,9 @@
my $ary = $-{$bufname};
foreach my $idx (0..$#$ary) {
print "\$-{$bufname}[$idx] : ",
- (defined($ary->[$idx]) ? "'$ary->[$idx]'" : "undef"),
+ (defined($ary->[$idx])
+ ? "'$ary->[$idx]'"
+ : "undef"),
"\n";
}
}
@@ -1342,10 +1069,10 @@
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.
@@ -1354,12 +1081,12 @@
L<Tie::Hash::NamedCapture> module.
B<Note:> C<%-> and C<%+> are tied views into a common internal hash
-associated with the last successful regular expression. Therefore mixing
+associated with the last successful regular expression. Therefore mixing
iterative access to them via C<each> may have unpredictable results.
Likewise, if the last successful match changes, then the results may be
surprising.
-This variable was added in Perl 5.10
+This variable was added in Perl v5.10.0.
This variable is read-only and dynamically-scoped.
@@ -1369,7 +1096,7 @@
X<$^R> X<$LAST_REGEXP_CODE_RESULT>
The result of evaluation of the last successful C<(?{ code })>
-regular expression assertion (see L<perlre>). May be written to.
+regular expression assertion (see L<perlre>). May be written to.
This variable was added in Perl 5.005.
@@ -1376,23 +1103,24 @@
=item ${^RE_DEBUG_FLAGS}
X<${^RE_DEBUG_FLAGS}>
-The current value of the regex debugging flags. Set to 0 for no debug output
-even when the C<re 'debug'> module is loaded. See L<re> for details.
+The current value of the regex debugging flags. Set to 0 for no debug output
+even when the C<re 'debug'> module is loaded. See L<re> for details.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
=item ${^RE_TRIE_MAXBUF}
X<${^RE_TRIE_MAXBUF}>
Controls how certain regex optimisations are applied and how much memory they
-utilize. This value by default is 65536 which corresponds to a 512kB temporary
-cache. Set this to a higher value to trade memory for speed when matching
-large alternations. Set it to a lower value if you want the optimisations to
+utilize. This value by default is 65536 which corresponds to a 512kB
+temporary cache. Set this to a higher value to trade
+memory for speed when matching large alternations. Set
+it to a lower value if you want the optimisations to
be as conservative of memory as possible but still occur, and set it to a
negative value to prevent the optimisation and conserve the most memory.
Under normal situations this variable should be of no interest to you.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.10.0.
=back
@@ -1401,22 +1129,22 @@
Variables that depend on the currently selected filehandle may be set
by calling an appropriate object method on the C<IO::Handle> object,
although this is less efficient than using the regular built-in
-variables. (Summary lines below for this contain the word HANDLE.)
+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
+Each method returns the old value of the C<IO::Handle> attribute. The
methods each take an optional EXPR, which, if supplied, specifies the
-new value for the C<IO::Handle> attribute in question. If not
+new value for the C<IO::Handle> attribute in question. If not
supplied, most methods do nothing to the current value--except for
C<autoflush()>, which will assume a 1 for you, just to be different.
@@ -1423,28 +1151,28 @@
Because loading in the C<IO::Handle> class is an expensive operation,
you should learn how to use the regular built-in variables.
-A few of these variables are considered "read-only". This means that
+A few of these variables are considered "read-only". This means that
if you try to assign to this variable, either directly or indirectly
through a reference, you'll raise a run-time exception.
You should be very careful when modifying the default values of most
-special variables described in this document. In most cases you want
+special variables described in this document. In most cases you want
to localize these variables before changing them, since if you don't,
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
+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
@@ -1452,30 +1180,30 @@
running inside the same Perl interpreter.
Usually when a variable is localized you want to make sure that this
-change affects the shortest scope possible. So unless you are already
-inside some short C<{}> block, you should create one yourself. For
+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
@@ -1486,11 +1214,11 @@
"1\f2\f3\f"
Why? Because C<nasty_break()> modifies C<$\> without localizing it
-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
+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,18 +1235,18 @@
X<@ARGV>
The array C<@ARGV> contains the command-line arguments intended for
-the script. C<$#ARGV> is generally the number of arguments minus
+the script. C<$#ARGV> is generally the number of arguments minus
one, because C<$ARGV[0]> is the first argument, I<not> the program's
-command name itself. See C<$0> for the command name.
+command name itself. See L</$0> for the command name.
=item ARGV
X<ARGV>
The special filehandle that iterates over command-line filenames in
-C<@ARGV>. Usually written as the null filehandle in the angle operator
-C<< <> >>. Note that currently C<ARGV> only has its magical effect
+C<@ARGV>. Usually written as the null filehandle in the angle operator
+C<< <> >>. Note that currently C<ARGV> only has its magical effect
within the C<< <> >> operator; elsewhere it is just a plain filehandle
-corresponding to the last file opened by C<< <> >>. In particular,
+corresponding to the last file opened by C<< <> >>. In particular,
passing C<\*ARGV> as a parameter to a function that expects a filehandle
may not cause your function to automatically read the contents of all the
files in C<@ARGV>.
@@ -1527,11 +1255,11 @@
X<ARGVOUT>
The special filehandle that points to the currently open output file
-when doing edit-in-place processing with B<-i>. Useful when you have
-to do a lot of inserting and don't want to keep modifying C<$_>. See
+when doing edit-in-place processing with B<-i>. Useful when you have
+to do a lot of inserting and don't want to keep modifying C<$_>. See
L<perlrun> for the B<-i> switch.
-=item Handle->output_field_separator( EXPR )
+=item IO::Handle->output_field_separator( EXPR )
=item $OUTPUT_FIELD_SEPARATOR
@@ -1540,9 +1268,12 @@
=item $,
X<$,> X<$OFS> X<$OUTPUT_FIELD_SEPARATOR>
-The output field separator for the print operator. If defined, this
-value is printed between each of print's arguments. Default is C<undef>.
+The output field separator for the print operator. If defined, this
+value is printed between each of print's arguments. Default is C<undef>.
+You cannot call C<output_field_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
+
Mnemonic: what is printed when there is a "," in your print statement.
=item HANDLE->input_line_number( EXPR )
@@ -1557,7 +1288,7 @@
Current line number for the last filehandle accessed.
Each filehandle in Perl counts the number of lines that have been read
-from it. (Depending on the value of C<$/>, Perl's idea of what
+from it. (Depending on the value of C<$/>, Perl's idea of what
constitutes a line may not match yours.) When a line is read from a
filehandle (via C<readline()> or C<< <> >>), or when C<tell()> or
C<seek()> is called on it, C<$.> becomes an alias to the line counter
@@ -1564,13 +1295,13 @@
for that filehandle.
You can adjust the counter by assigning to C<$.>, but this will not
-actually move the seek pointer. I<Localizing C<$.> will not localize
-the filehandle's line count>. Instead, it will localize perl's notion
+actually move the seek pointer. I<Localizing C<$.> will not localize
+the filehandle's line count>. Instead, it will localize perl's notion
of which filehandle C<$.> is currently aliased to.
C<$.> is reset when the filehandle is closed, but B<not> when an open
-filehandle is reopened without an intervening C<close()>. For more
-details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
+filehandle is reopened without an intervening C<close()>. For more
+details, see L<perlop/"IE<sol>O Operators">. Because C<< <> >> never does
an explicit close, line numbers increase across C<ARGV> files (but see
examples in L<perlfunc/eof>).
@@ -1580,7 +1311,7 @@
Mnemonic: many programs use "." to mean the current line number.
-=item HANDLE->input_record_separator( EXPR )
+=item IO::Handle->input_record_separator( EXPR )
=item $INPUT_RECORD_SEPARATOR
@@ -1589,15 +1320,15 @@
=item $/
X<$/> X<$RS> X<$INPUT_RECORD_SEPARATOR>
-The input record separator, newline by default. This influences Perl's
-idea of what a "line" is. Works like B<awk>'s RS variable, including
+The input record separator, newline by default. This influences Perl's
+idea of what a "line" is. Works like B<awk>'s RS variable, including
treating empty lines as a terminator if set to the null string (an
-empty line cannot contain any spaces or tabs). You may set it to a
+empty line cannot contain any spaces or tabs). You may set it to a
multi-character string to match a multi-character terminator, or to
-C<undef> to read through the end of file. Setting it to C<"\n\n">
+C<undef> to read through the end of file. Setting it to C<"\n\n">
means something slightly different than setting to C<"">, if the file
-contains consecutive empty lines. Setting to C<""> will treat two or
-more consecutive empty lines as a single empty line. Setting to
+contains consecutive empty lines. Setting to C<""> will treat two or
+more consecutive empty lines as a single empty line. Setting to
C<"\n\n"> will blindly assume that the next input character belongs to
the next paragraph, even if it's a newline.
@@ -1605,37 +1336,38 @@
local $_ = <FH>; # whole file now here
s/\n[ \t]+/ /g;
-Remember: the value of C<$/> is a string, not a regex. B<awk> has to
+Remember: the value of C<$/> is a string, not a regex. B<awk> has to
be better for something. :-)
Setting C<$/> to a reference to an integer, scalar containing an
integer, or scalar that's convertible to an integer will attempt to
read records instead of lines, with the maximum record size being the
-referenced integer. So this:
+referenced integer number of characters. So this:
local $/ = \32768; # or \"32768", or \$var_containing_32768
open my $fh, "<", $myfile or die $!;
local $_ = <$fh>;
-will read a record of no more than 32768 bytes from FILE. If you're
+will read a record of no more than 32768 characters from $fh. If you're
not reading from a record-oriented file (or your OS doesn't have
record-oriented files), then you'll likely get a full chunk of data
-with every read. If a record is larger than the record size you've
-set, you'll get the record back in pieces. Trying to set the record
+with every read. If a record is larger than the record size you've
+set, you'll get the record back in pieces. Trying to set the record
size to zero or less will cause reading in the (rest of the) whole file.
-On VMS, record reads are done with the equivalent of C<sysread>,
-so it's best not to mix record and non-record reads on the same
-file. (This is unlikely to be a problem, because any file you'd
-want to read in record mode is probably unusable in line mode.)
-Non-VMS systems do normal I/O, so it's safe to mix record and
-non-record reads of a file.
+On VMS only, record reads bypass PerlIO layers and any associated
+buffering, so you must not mix record and non-record reads on the
+same filehandle. Record mode mixes with line mode only when the
+same buffering layer is in use for both modes.
-See also L<perlport/"Newlines">. Also see C<$.>.
+You cannot call C<input_record_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
+See also L<perlport/"Newlines">. Also see L</$.>.
+
Mnemonic: / delimits line boundaries when quoting poetry.
-=item Handle->output_record_separator( EXPR )
+=item IO::Handle->output_record_separator( EXPR )
=item $OUTPUT_RECORD_SEPARATOR
@@ -1644,9 +1376,12 @@
=item $\
X<$\> X<$ORS> X<$OUTPUT_RECORD_SEPARATOR>
-The output record separator for the print operator. If defined, this
-value is printed after the last of print's arguments. Default is C<undef>.
+The output record separator for the print operator. If defined, this
+value is printed after the last of print's arguments. Default is C<undef>.
+You cannot call C<output_record_separator()> on a handle, only as a
+static method. See L<IO::Handle|IO::Handle>.
+
Mnemonic: you set C<$\> instead of adding "\n" at the end of the print.
Also, it's just like C<$/>, but it's what you get "back" from Perl.
@@ -1658,25 +1393,36 @@
X<$|> X<autoflush> X<flush> X<$OUTPUT_AUTOFLUSH>
If set to nonzero, forces a flush right away and after every write or
-print on the currently selected output channel. Default is 0
+print on the currently selected output channel. Default is 0
(regardless of whether the channel is really buffered by the system or
not; C<$|> tells you only whether you've asked Perl explicitly to
-flush after each write). STDOUT will typically be line buffered if
-output is to the terminal and block buffered otherwise. Setting this
+flush after each write). STDOUT will typically be line buffered if
+output is to the terminal and block buffered otherwise. Setting this
variable is useful primarily when you are outputting to a pipe or
socket, such as when you are running a Perl program under B<rsh> and
-want to see the output as it's happening. This has no effect on input
-buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
-how to select the output channel. See also L<IO::Handle>.
+want to see the output as it's happening. This has no effect on input
+buffering. See L<perlfunc/getc> for that. See L<perlfunc/select> on
+how to select the output channel. See also L<IO::Handle>.
Mnemonic: when you want your pipes to be piping hot.
+=item ${^LAST_FH}
+X<${^LAST_FH}>
+
+This read-only variable contains a reference to the last-read filehandle.
+This is set by C<< <HANDLE> >>, C<readline>, C<tell>, C<eof> and C<seek>.
+This is the same handle that C<$.> and C<tell> and C<eof> without arguments
+use. It is also the handle used when Perl appends ", <STDIN> line 1" to
+an error or warning message.
+
+This variable was added in Perl v5.18.0.
+
=back
=head3 Variables related to formats
The special variables for formats are a subset of those for
-filehandles. See L<perlform> for more information about Perl's
+filehandles. See L<perlform> for more information about Perl's
formats.
=over 8
@@ -1688,12 +1434,12 @@
The current value of the C<write()> accumulator for C<format()> lines.
A format contains C<formline()> calls that put their result into
-C<$^A>. After calling its format, C<write()> prints out the contents
-of C<$^A> and empties. So you never really see the contents of C<$^A>
-unless you call C<formline()> yourself and then look at it. See
+C<$^A>. After calling its format, C<write()> prints out the contents
+of C<$^A> and empties. So you never really see the contents of C<$^A>
+unless you call C<formline()> yourself and then look at it. See
L<perlform> and L<perlfunc/"formline PICTURE,LIST">.
-=item HANDLE->format_formfeed(EXPR)
+=item IO::Handle->format_formfeed(EXPR)
=item $FORMAT_FORMFEED
@@ -1700,8 +1446,11 @@
=item $^L
X<$^L> X<$FORMAT_FORMFEED>
-What formats output as a form feed. The default is C<\f>.
+What formats output as a form feed. The default is C<\f>.
+You cannot call C<format_formfeed()> on a handle, only as a static
+method. See L<IO::Handle|IO::Handle>.
+
=item HANDLE->format_page_number(EXPR)
=item $FORMAT_PAGE_NUMBER
@@ -1725,7 +1474,7 @@
Mnemonic: lines_on_page - lines_printed.
-=item Handle->format_line_break_characters EXPR
+=item IO::Handle->format_line_break_characters EXPR
=item $FORMAT_LINE_BREAK_CHARACTERS
@@ -1733,9 +1482,12 @@
X<$:> X<FORMAT_LINE_BREAK_CHARACTERS>
The current set of characters after which a string may be broken to
-fill continuation fields (starting with C<^>) in a format. The default is
+fill continuation fields (starting with C<^>) in a format. The default is
S<" \n-">, to break on a space, newline, or a hyphen.
+You cannot call C<format_line_break_characters()> on a handle, only as
+a static method. See L<IO::Handle|IO::Handle>.
+
Mnemonic: a "colon" in poetry is a part of a line.
=item HANDLE->format_lines_per_page(EXPR)
@@ -1746,7 +1498,7 @@
X<$=> X<$FORMAT_LINES_PER_PAGE>
The current page length (printable lines) of the currently selected
-output channel. The default is 60.
+output channel. The default is 60.
Mnemonic: = has horizontal lines.
@@ -1758,9 +1510,9 @@
X<$^> X<$FORMAT_TOP_NAME>
The name of the current top-of-page format for the currently selected
-output channel. The default is the name of the filehandle with C<_TOP>
-appended. For example, the default format top name for the C<STDOUT>
-filehanlde is C<STDOUT_TOP>.
+output channel. The default is the name of the filehandle with C<_TOP>
+appended. For example, the default format top name for the C<STDOUT>
+filehandle is C<STDOUT_TOP>.
Mnemonic: points to top of page.
@@ -1772,8 +1524,8 @@
X<$~> X<$FORMAT_NAME>
The name of the current report format for the currently selected
-output channel. The default format name is the same as the filehandle
-name. For example, the default format name for the C<STDOUT>
+output channel. The default format name is the same as the filehandle
+name. For example, the default format name for the C<STDOUT>
filehandle is just C<STDOUT>.
Mnemonic: brother to C<$^>.
@@ -1785,46 +1537,46 @@
The variables C<$@>, C<$!>, C<$^E>, and C<$?> contain information
about different types of error conditions that may appear during
-execution of a Perl program. The variables are shown ordered by
+execution of a Perl program. The variables are shown ordered by
the "distance" between the subsystem which reported the error and
-the Perl process. They correspond to errors detected by the Perl
+the Perl process. They correspond to errors detected by the Perl
interpreter, C library, operating system, or an external program,
respectively.
To illustrate the differences between these variables, consider the
-following Perl expression, which uses a single-quoted string. After
+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
-and thence to the operating system kernel. perl sets C<$!> to
+and thence to the operating system kernel. perl sets C<$!> to
the C library's C<errno> if one of these calls fails.
C<$@> is set if the string to be C<eval>-ed did not compile (this may
happen if C<open> or C<close> were imported with bad prototypes), or
-if Perl code executed during evaluation C<die()>d. In these cases the
+if Perl code executed during evaluation C<die()>d. In these cases the
value of C<$@> is the compile error, or the argument to C<die> (which
-will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
+will interpolate C<$!> and C<$?>). (See also L<Fatal>, though.)
Under a few operating systems, C<$^E> may contain a more verbose error
-indicator, such as in this case, "CDROM tray not closed." Systems that
+indicator, such as in this case, "CDROM tray not closed." Systems that
do not support extended error messages leave C<$^E> the same as C<$!>.
Finally, C<$?> may be set to non-0 value if the external program
-F</cdrom/install> fails. The upper eight bits reflect specific error
+F</cdrom/install> fails. The upper eight bits reflect specific error
conditions encountered by the program (the program's C<exit()> value).
The lower eight bits reflect mode of failure, like signal death and
-core dump information. See C<wait(2)> for details. In contrast to
+core dump information. See L<wait(2)> for details. In contrast to
C<$!> and C<$^E>, which are set only if error condition is detected,
the variable C<$?> is set on each C<wait> or pipe C<close>,
-overwriting the old value. This is more like C<$@>, which on every
+overwriting the old value. This is more like C<$@>, which on every
C<eval()> is always set on failure and cleared on success.
For more details, see the individual descriptions at C<$@>, C<$!>,
@@ -1837,7 +1589,7 @@
The native status returned by the last pipe close, backtick (C<``>)
command, successful call to C<wait()> or C<waitpid()>, or from the
-C<system()> operator. On POSIX-like systems this value can be decoded
+C<system()> operator. On POSIX-like systems this value can be decoded
with the WIFEXITED, WEXITSTATUS, WIFSIGNALED, WTERMSIG, WIFSTOPPED,
WSTOPSIG and WIFCONTINUED functions provided by the L<POSIX> module.
@@ -1844,7 +1596,7 @@
Under VMS this reflects the actual VMS exit status; i.e. it is the
same as C<$?> when the pragma C<use vmsish 'status'> is in effect.
-This variable was added in Perl 5.8.9.
+This variable was added in Perl v5.10.0.
=item $EXTENDED_OS_ERROR
@@ -1851,14 +1603,14 @@
=item $^E
X<$^E> X<$EXTENDED_OS_ERROR>
-Error information specific to the current operating system. At the
+Error information specific to the current operating system. At the
moment, this differs from C<$!> under only VMS, OS/2, and Win32 (and
-for MacPerl). On all other platforms, C<$^E> is always just the same
+for MacPerl). On all other platforms, C<$^E> is always just the same
as C<$!>.
Under VMS, C<$^E> provides the VMS status value from the last system
-error. This is more specific information about the last system error
-than that provided by C<$!>. This is particularly important when C<$!>
+error. This is more specific information about the last system error
+than that provided by C<$!>. This is particularly important when C<$!>
is set to B<EVMSERR>.
Under OS/2, C<$^E> is set to the error code of the last call to OS/2
@@ -1866,8 +1618,8 @@
Under Win32, C<$^E> always returns the last error information reported
by the Win32 call C<GetLastError()> which describes the last error
-from within the Win32 API. Most Win32-specific code will report errors
-via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
+from within the Win32 API. Most Win32-specific code will report errors
+via C<$^E>. ANSI C and Unix-like calls set C<errno> and so most
portable Perl code will report errors via C<$!>.
Caveats mentioned in the description of C<$!> generally apply to
@@ -1885,8 +1637,8 @@
Current state of the interpreter.
$^S State
- --------- -------------------
- undef Parsing module/eval
+ --------- -------------------------------------
+ undef Parsing module, eval, or main program
true (1) Executing an eval
false (0) Otherwise
@@ -1893,6 +1645,10 @@
The first state may happen in C<$SIG{__DIE__}> and C<$SIG{__WARN__}>
handlers.
+The English name $EXCEPTIONS_BEING_CAUGHT is slightly misleading, because
+the C<undef> value does not indicate whether exceptions are being caught,
+since compilation of the main program does not catch exceptions.
+
This variable was added in Perl 5.004.
=item $WARNING
@@ -1911,9 +1667,11 @@
X<${^WARNING_BITS}>
The current set of warning checks enabled by the C<use warnings> pragma.
-See the documentation of C<warnings> for more details.
+It has the same scoping as the C<$^H> and C<%^H> variables. The exact
+values are considered internal to the L<warnings> pragma and may change
+between versions of Perl.
-This variable was added in Perl 5.10.
+This variable was added in Perl v5.6.0.
=item $OS_ERROR
@@ -1922,12 +1680,18 @@
=item $!
X<$!> X<$ERRNO> X<$OS_ERROR>
-If used numerically, yields the current value of the C C<errno>
-variable, or in other words, if a system or library call fails, it
-sets this variable. This means that the value of C<$!> is meaningful
-only I<immediately> after a B<failure>:
+When referenced, C<$!> retrieves the current value
+of the C C<errno> integer variable.
+If C<$!> is assigned a numerical value, that value is stored in C<errno>.
+When referenced as a string, C<$!> yields the system error string
+corresponding to C<errno>.
- if (open my $fh, "<", $filename) {
+Many system or library calls set C<errno> if they fail,
+to indicate the cause of failure. They usually do B<not>
+set C<errno> to zero if they succeed. This means C<errno>,
+hence C<$!>, is meaningful only I<immediately> after a B<failure>:
+
+ if (open my $fh, "<", $filename) {
# Here $! is meaningless.
...
}
@@ -1937,17 +1701,14 @@
# Already here $! might be meaningless.
}
# Since here we might have either success or failure,
- # here $! is meaningless.
+ # $! is meaningless.
-The I<meaningless> stands for anything: zero, non-zero,
-C<undef>. A successful system or library call does B<not> set the
-variable to zero.
+Here, I<meaningless> means that C<$!> may be unrelated to the outcome
+of the C<open()> operator. Assignment to C<$!> is similarly ephemeral.
+It can be used immediately before invoking the C<die()> operator,
+to set the exit value, or to inspect the system error string
+corresponding to error I<n>, or to restore C<$!> to a meaningful state.
-If used as a string, yields the corresponding system error string. You
-can assign a number to C<$!> to set I<errno> if, for instance, you
-want C<"$!"> to return the string for error I<n>, or you want to set
-the exit value for the C<die()> operator.
-
Mnemonic: What just went bang?
=item %OS_ERROR
@@ -1958,12 +1719,12 @@
X<%!> X<%OS_ERROR> X<%ERRNO>
Each element of C<%!> has a true value only if C<$!> is set to that
-value. For example, C<$!{ENOENT}> is true if and only if the current
+value. For example, C<$!{ENOENT}> is true if and only if the current
value of C<$!> is C<ENOENT>; that is, if the most recent error was "No
such file or directory" (or its moral equivalent: not all operating
-systems give that exact error, and certainly not all languages). To
+systems give that exact error, and certainly not all languages). To
check if a particular key is meaningful on your system, use C<exists
-$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
+$!{the_key}>; for a list of legal keys, use C<keys %!>. See L<Errno>
for more information, and also see L</$!>.
This variable was added in Perl 5.005.
@@ -1975,9 +1736,9 @@
The status returned by the last pipe close, backtick (C<``>) command,
successful call to C<wait()> or C<waitpid()>, or from the C<system()>
-operator. This is just the 16-bit status word returned by the
+operator. This is just the 16-bit status word returned by the
traditional Unix C<wait()> system call (or else is made up to look
-like it). Thus, the exit value of the subprocess is really (C<<< $? >>
+like it). Thus, the exit value of the subprocess is really (C<<< $? >>
8 >>>), and C<$? & 127> gives which signal, if any, the process died
from, and C<$? & 128> reports whether there was a core dump.
@@ -1988,8 +1749,8 @@
value of C<$?> will usually be wrong outside that handler.
Inside an C<END> subroutine C<$?> contains the value that is going to be
-given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
-change the exit status of your program. For example:
+given to C<exit()>. You can modify C<$?> in an C<END> subroutine to
+change the exit status of your program. For example:
END {
$? = 1 if $? == 255; # die would make it 255
@@ -2006,12 +1767,13 @@
=item $@
X<$@> X<$EVAL_ERROR>
-The Perl syntax error message from the last C<eval()> operator. If C<$@> is
+The Perl syntax error message from the
+last C<eval()> operator. If C<$@> is
the null string, the last C<eval()> parsed and executed correctly
(although the operations you invoked may have failed in the normal
fashion).
-Warning messages are not collected in this variable. You can, however,
+Warning messages are not collected in this variable. You can, however,
set up a routine to process warnings by setting C<$SIG{__WARN__}> as
described in L</%SIG>.
@@ -2019,11 +1781,339 @@
=back
+=head2 Variables related to the interpreter state
+
+These variables provide information about the current interpreter state.
+
+=over 8
+
+=item $COMPILING
+
+=item $^C
+X<$^C> X<$COMPILING>
+
+The current value of the flag associated with the B<-c> switch.
+Mainly of use with B<-MO=...> to allow code to alter its behavior
+when being compiled, such as for example to C<AUTOLOAD> at compile
+time rather than normal, deferred loading. Setting
+C<$^C = 1> is similar to calling C<B::minus_c>.
+
+This variable was added in Perl v5.6.0.
+
+=item $DEBUGGING
+
+=item $^D
+X<$^D> X<$DEBUGGING>
+
+The current value of the debugging flags. May be read or set. Like its
+command-line equivalent, you can use numeric or symbolic values, eg
+C<$^D = 10> or C<$^D = "st">.
+
+Mnemonic: value of B<-D> switch.
+
+=item ${^ENCODING}
+X<${^ENCODING}>
+
+The I<object reference> to the C<Encode> object that is used to convert
+the source code to Unicode. Thanks to this variable your Perl script
+does not have to be written in UTF-8. Default is I<undef>. The direct
+manipulation of this variable is highly discouraged.
+
+This variable was added in Perl 5.8.2.
+
+=item ${^GLOBAL_PHASE}
+X<${^GLOBAL_PHASE}>
+
+The current phase of the perl interpreter.
+
+Possible values are:
+
+=over 8
+
+=item CONSTRUCT
+
+The C<PerlInterpreter*> is being constructed via C<perl_construct>. This
+value is mostly there for completeness and for use via the
+underlying C variable C<PL_phase>. It's not really possible for Perl
+code to be executed unless construction of the interpreter is
+finished.
+
+=item START
+
+This is the global compile-time. That includes, basically, every
+C<BEGIN> block executed directly or indirectly from during the
+compile-time of the top-level program.
+
+This phase is not called "BEGIN" to avoid confusion with
+C<BEGIN>-blocks, as those are executed during compile-time of any
+compilation unit, not just the top-level program. A new, localised
+compile-time entered at run-time, for example by constructs as
+C<eval "use SomeModule"> are not global interpreter phases, and
+therefore aren't reflected by C<${^GLOBAL_PHASE}>.
+
+=item CHECK
+
+Execution of any C<CHECK> blocks.
+
+=item INIT
+
+Similar to "CHECK", but for C<INIT>-blocks, not C<CHECK> blocks.
+
+=item RUN
+
+The main run-time, i.e. the execution of C<PL_main_root>.
+
+=item END
+
+Execution of any C<END> blocks.
+
+=item DESTRUCT
+
+Global destruction.
+
+=back
+
+Also note that there's no value for UNITCHECK-blocks. That's because
+those are run for each compilation unit individually, and therefore is
+not a global interpreter phase.
+
+Not every program has to go through each of the possible phases, but
+transition from one phase to another can only happen in the order
+described in the above list.
+
+An example of all of the phases Perl code can see:
+
+ BEGIN { print "compile-time: ${^GLOBAL_PHASE}\n" }
+
+ INIT { print "init-time: ${^GLOBAL_PHASE}\n" }
+
+ CHECK { print "check-time: ${^GLOBAL_PHASE}\n" }
+
+ {
+ package Print::Phase;
+
+ sub new {
+ my ($class, $time) = @_;
+ return bless \$time, $class;
+ }
+
+ sub DESTROY {
+ my $self = shift;
+ print "$$self: ${^GLOBAL_PHASE}\n";
+ }
+ }
+
+ print "run-time: ${^GLOBAL_PHASE}\n";
+
+ my $runtime = Print::Phase->new(
+ "lexical variables are garbage collected before END"
+ );
+
+ END { print "end-time: ${^GLOBAL_PHASE}\n" }
+
+ our $destruct = Print::Phase->new(
+ "package variables are garbage collected after END"
+ );
+
+This will print out
+
+ compile-time: START
+ check-time: CHECK
+ init-time: INIT
+ run-time: RUN
+ lexical variables are garbage collected before END: RUN
+ end-time: END
+ package variables are garbage collected after END: DESTRUCT
+
+This variable was added in Perl 5.14.0.
+
+=item $^H
+X<$^H>
+
+WARNING: This variable is strictly for
+internal use only. Its availability,
+behavior, and contents are subject to change without notice.
+
+This variable contains compile-time hints for the Perl interpreter. At the
+end of compilation of a BLOCK the value of this variable is restored to the
+value when the interpreter started to compile the BLOCK.
+
+When perl begins to parse any block construct that provides a lexical scope
+(e.g., eval body, required file, subroutine body, loop body, or conditional
+block), the existing value of C<$^H> is saved, but its value is left unchanged.
+When the compilation of the block is completed, it regains the saved value.
+Between the points where its value is saved and restored, code that
+executes within BEGIN blocks is free to change the value of C<$^H>.
+
+This behavior provides the semantic of lexical scoping, and is used in,
+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 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
+being compiled. The new value of C<$^H>
+will therefore be visible only while
+the body of C<foo()> is being compiled.
+
+Substitution of C<BEGIN { add_100() }> block with:
+
+ 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
+ }
+
+This variable was added in Perl 5.003.
+
+=item %^H
+X<%^H>
+
+The C<%^H> hash provides the same scoping semantic as C<$^H>. This makes
+it useful for implementation of lexically scoped pragmas. See
+L<perlpragma>.
+
+When putting items into C<%^H>, in order to avoid conflicting with other
+users of the hash there is a convention regarding which keys to use.
+A module should use only keys that begin with the module's name (the
+name of its main package) and a "/" character. For example, a module
+C<Foo::Bar> should use keys such as C<Foo::Bar/baz>.
+
+This variable was added in Perl v5.6.0.
+
+=item ${^OPEN}
+X<${^OPEN}>
+
+An internal variable used by PerlIO. A string in two parts, separated
+by a C<\0> byte, the first part describes the input layers, the second
+part describes the output layers.
+
+This variable was added in Perl v5.8.0.
+
+=item $PERLDB
+
+=item $^P
+X<$^P> X<$PERLDB>
+
+The internal variable for debugging support. The meanings of the
+various bits are subject to change, but currently indicate:
+
+=over 6
+
+=item 0x01
+
+Debug subroutine enter/exit.
+
+=item 0x02
+
+Line-by-line debugging. Causes C<DB::DB()> subroutine to be called for
+each statement executed. Also causes saving source code lines (like
+0x400).
+
+=item 0x04
+
+Switch off optimizations.
+
+=item 0x08
+
+Preserve more data for future interactive inspections.
+
+=item 0x10
+
+Keep info about source lines on which a subroutine is defined.
+
+=item 0x20
+
+Start with single-step on.
+
+=item 0x40
+
+Use subroutine address instead of name when reporting.
+
+=item 0x80
+
+Report C<goto &subroutine> as well.
+
+=item 0x100
+
+Provide informative "file" names for evals based on the place they were compiled.
+
+=item 0x200
+
+Provide informative names to anonymous subroutines based on the place they
+were compiled.
+
+=item 0x400
+
+Save source code lines into C<@{"_<$filename"}>.
+
+=back
+
+Some bits may be relevant at compile-time only, some at
+run-time only. This is a new mechanism and the details may change.
+See also L<perldebguts>.
+
+=item ${^TAINT}
+X<${^TAINT}>
+
+Reflects if taint mode is on or off. 1 for on (the program was run with
+B<-T>), 0 for off, -1 when only taint warnings are enabled (i.e. with
+B<-t> or B<-TU>).
+
+This variable is read-only.
+
+This variable was added in Perl v5.8.0.
+
+=item ${^UNICODE}
+X<${^UNICODE}>
+
+Reflects certain Unicode settings of Perl. See L<perlrun>
+documentation for the C<-C> switch for more information about
+the possible values.
+
+This variable is set during Perl startup and is thereafter read-only.
+
+This variable was added in Perl v5.8.2.
+
+=item ${^UTF8CACHE}
+X<${^UTF8CACHE}>
+
+This variable controls the state of the internal UTF-8 offset caching code.
+1 for on (the default), 0 for off, -1 to debug the caching code by checking
+all its results against linear scans, and panicking on any discrepancy.
+
+This variable was added in Perl v5.8.9. It is subject to change or
+removal without notice, but is currently used to avoid recalculating the
+boundaries of multi-byte UTF-8-encoded characters.
+
+=item ${^UTF8LOCALE}
+X<${^UTF8LOCALE}>
+
+This variable indicates whether a UTF-8 locale was detected by perl at
+startup. This information is used by perl when it's in
+adjust-utf8ness-to-locale mode (as when run with the C<-CL> command-line
+switch); see L<perlrun> for more info on this.
+
+This variable was added in Perl v5.8.8.
+
+=back
+
=head2 Deprecated and removed variables
Deprecating a variable announces the intent of the perl maintainers to
-eventually remove the variable from the langauge. It may still be
-available despite its status. Using a deprecated variable triggers
+eventually remove the variable from the language. It may still be
+available despite its status. Using a deprecated variable triggers
a warning.
Once a variable is removed, its use triggers an error telling you
@@ -2038,29 +2128,29 @@
=item $#
X<$#> X<$OFMT>
-C<$#> was a variable that you could be use to format printed numbers.
-After a deprecation cycle, its magic was removed in Perl 5.10 and
+C<$#> was a variable that could be used to format printed numbers.
+After a deprecation cycle, its magic was removed in Perl v5.10.0 and
using it now triggers a warning: C<$# is no longer supported>.
This is not the sigil you use in front of an array name to get the
-last index, like C<$#array>. That's still how you get the last index
-of an array in Perl. The two have nothing to do with each other.
+last index, like C<$#array>. That's still how you get the last index
+of an array in Perl. The two have nothing to do with each other.
Deprecated in Perl 5.
-Removed in Perl 5.10.
+Removed in Perl v5.10.0.
=item $*
X<$*>
C<$*> was a variable that you could use to enable multiline matching.
-After a deprecation cycle, its magic was removed in Perl 5.10.
+After a deprecation cycle, its magic was removed in Perl v5.10.0.
Using it now triggers a warning: C<$* is no longer supported>.
You should use the C</s> and C</m> regexp modifiers instead.
Deprecated in Perl 5.
-Removed in Perl 5.10.
+Removed in Perl v5.10.0.
=item $ARRAY_BASE
@@ -2068,7 +2158,7 @@
X<$[> X<$ARRAY_BASE>
This variable stores the index of the first element in an array, and
-of the first character in a substring. The default is 0, but you could
+of the first character in a substring. The default is 0, but you could
theoretically set it to 1 to make Perl behave more like B<awk> (or Fortran)
when subscripting and when evaluating the index() and substr() functions.
@@ -2077,14 +2167,21 @@
(That's why you can only assign compile-time constants to it.)
Its use is highly discouraged.
-Prior to Perl 5.10, assignment to C<$[> could be seen from outer lexical
+Prior to Perl v5.10.0, assignment to C<$[> could be seen from outer lexical
scopes in the same file, unlike other compile-time directives (such as
-L<strict>). Using local() on it would bind its value strictly to a lexical
-block. Now it is always lexically scoped.
+L<strict>). Using local() on it would bind its value strictly to a lexical
+block. Now it is always lexically scoped.
+As of Perl v5.16.0, it is implemented by the L<arybase> module. See
+L<arybase> for more details on its behaviour.
+
+Under C<use v5.16>, or C<no feature "array_base">, C<$[> no longer has any
+effect, and always contains 0. Assigning 0 to it is permitted, but any
+other value will produce an error.
+
Mnemonic: [ begins subscripts.
-Deprecated in Perl 5.12.
+Deprecated in Perl v5.12.0.
=item $OLD_PERL_VERSION
@@ -2091,10 +2188,10 @@
=item $]
X<$]> X<$OLD_PERL_VERSION>
-See C<$^V> for a more modern representation of the Perl version that allows
+See L</$^V> for a more modern representation of the Perl version that allows
accurate string comparisons.
-The version + patchlevel / 1000 of the Perl interpreter. This variable
+The version + patchlevel / 1000 of the Perl interpreter. This variable
can be used to determine whether the Perl interpreter executing a
script is in the right range of versions:
@@ -2108,8 +2205,6 @@
Mnemonic: Is this version of perl in the right bracket?
-Deprecated in Perl 5.6.
-
=back
=cut
Property changes on: trunk/contrib/perl/pod/perlvar.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Modified: trunk/contrib/perl/pod/perlvms.pod
===================================================================
--- trunk/contrib/perl/pod/perlvms.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlvms.pod 2013-12-02 21:27:48 UTC (rev 6441)
@@ -409,7 +409,7 @@
This allows the programmer to look at the execution stack and variables to
find out the cause of the exception. As the debugger is being invoked as
the Perl interpreter is about to do a fatal exit, continuing the execution
-in debug mode is usally not practical.
+in debug mode is usually not practical.
Starting Perl in the VMS debugger may change the program execution
profile in a way that such problems are not reproduced.
@@ -704,7 +704,6 @@
See L</"$?"> for a description of the encoding of the Unix value to
produce a native VMS status containing it.
-
=item dump
Rather than causing Perl to abort and dump core, the C<dump>
Property changes on: trunk/contrib/perl/pod/perlvms.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlxs.pod
===================================================================
--- trunk/contrib/perl/pod/perlxs.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlxs.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlxs.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Index: trunk/contrib/perl/pod/perlxstut.pod
===================================================================
--- trunk/contrib/perl/pod/perlxstut.pod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/perlxstut.pod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/perlxstut.pod
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.3
\ No newline at end of property
Copied: trunk/contrib/perl/pod/pod2html.PL (from rev 6437, vendor/perl/5.18.1/pod/pod2html.PL)
===================================================================
--- trunk/contrib/perl/pod/pod2html.PL (rev 0)
+++ trunk/contrib/perl/pod/pod2html.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,183 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+ eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+ if \$running_under_some_shell;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+=pod
+
+=head1 NAME
+
+pod2html - convert .pod files to .html files
+
+=head1 SYNOPSIS
+
+ pod2html --help --htmlroot=<name> --infile=<name> --outfile=<name>
+ --podpath=<name>:...:<name> --podroot=<name>
+ --libpods=<name>:...:<name> --recurse --norecurse --verbose
+ --index --noindex --title=<name>
+
+=head1 DESCRIPTION
+
+Converts files from pod format (see L<perlpod>) to HTML format.
+
+=head1 ARGUMENTS
+
+pod2html takes the following arguments:
+
+=over 4
+
+=item help
+
+ --help
+
+Displays the usage message.
+
+=item htmlroot
+
+ --htmlroot=name
+
+Sets the base URL for the HTML files. When cross-references are made,
+the HTML root is prepended to the URL.
+
+=item infile
+
+ --infile=name
+
+Specify the pod file to convert. Input is taken from STDIN if no
+infile is specified.
+
+=item outfile
+
+ --outfile=name
+
+Specify the HTML file to create. Output goes to STDOUT if no outfile
+is specified.
+
+=item podroot
+
+ --podroot=name
+
+Specify the base directory for finding library pods.
+
+=item podpath
+
+ --podpath=name:...:name
+
+Specify which subdirectories of the podroot contain pod files whose
+HTML converted forms can be linked-to in cross-references.
+
+=item libpods
+
+ --libpods=name:...:name
+
+List of page names (eg, "perlfunc") which contain linkable C<=item>s.
+
+=item netscape
+
+ --netscape
+
+Use Netscape HTML directives when applicable.
+
+=item nonetscape
+
+ --nonetscape
+
+Do not use Netscape HTML directives (default).
+
+=item index
+
+ --index
+
+Generate an index at the top of the HTML file (default behaviour).
+
+=item noindex
+
+ --noindex
+
+Do not generate an index at the top of the HTML file.
+
+
+=item recurse
+
+ --recurse
+
+Recurse into subdirectories specified in podpath (default behaviour).
+
+=item norecurse
+
+ --norecurse
+
+Do not recurse into subdirectories specified in podpath.
+
+=item title
+
+ --title=title
+
+Specify the title of the resulting HTML file.
+
+=item verbose
+
+ --verbose
+
+Display progress messages.
+
+=back
+
+=head1 AUTHOR
+
+Tom Christiansen, E<lt>tchrist at perl.comE<gt>.
+
+=head1 BUGS
+
+See L<Pod::Html> for a list of known bugs in the translator.
+
+=head1 SEE ALSO
+
+L<perlpod>, L<Pod::Html>
+
+=head1 COPYRIGHT
+
+This program is distributed under the Artistic License.
+
+=cut
+
+use Pod::Html;
+
+pod2html @ARGV;
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/pod2latex.PL (from rev 6437, vendor/perl/5.18.1/pod/pod2latex.PL)
===================================================================
--- trunk/contrib/perl/pod/pod2latex.PL (rev 0)
+++ trunk/contrib/perl/pod/pod2latex.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,421 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+ eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+ if \$running_under_some_shell;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+
+# pod2latex conversion program
+
+use strict;
+use Pod::LaTeX;
+use Pod::Find qw/ pod_find /;
+use Pod::Usage;
+use Getopt::Long;
+use File::Basename;
+use Symbol;
+
+my $VERSION = "1.01";
+
+# return the entire contents of a text file
+# whose name is given as argument
+sub _get {
+ my $fn = shift;
+ my $infh = gensym;
+ open $infh, $fn
+ or die "Could not open file $fn: $!\n";
+ local $/;
+ return <$infh>;
+}
+
+# Read command line arguments
+
+my %options = (
+ "help" => 0,
+ "man" => 0,
+ "sections" => [],
+ "full" => 0,
+ "out" => undef,
+ "verbose" => 0,
+ "modify" => 0,
+ "h1level" => 1, # section is equivalent to H1
+ "preamble" => [],
+ "postamble" => [],
+ );
+# "prefile" is just like "preamble", but the argument
+# comes from the file named by the argument
+$options{"prefile"} = sub { shift; push @{$options{"preamble"}}, _get(shift) };
+# the same between "postfile" and "postamble"
+$options{"postfile"} = sub { shift; push @{$options{"postamble"}}, _get(shift) };
+
+GetOptions(\%options,
+ "help",
+ "man",
+ "verbose",
+ "full",
+ "sections=s@",
+ "out=s",
+ "modify",
+ "h1level=i",
+ "preamble=s@",
+ "postamble=s@",
+ "prefile=s",
+ "postfile=s"
+ ) || pod2usage(2);
+
+pod2usage(1) if ($options{help});
+pod2usage(-verbose => 2) if ($options{man});
+
+
+# Read all the files from the command line
+my @files = @ARGV;
+
+# Now find which ones are real pods and convert
+# directories to their contents.
+
+# Extract the pods from each arg since some of them might
+# be directories
+# This is not as efficient as using pod_find to search through
+# everything at once but it allows us to preserve the order
+# supplied by the user
+
+my @pods;
+foreach my $arg (@files) {
+ my %pods = pod_find($arg);
+ push(@pods, sort keys %pods);
+}
+
+# Abort if nothing to do
+if ($#pods == -1) {
+ warn "None of the supplied Pod files actually exist\n";
+ exit;
+}
+
+# Only want to override the preamble and postamble if we have
+# been given values.
+my %User;
+$User{UserPreamble} = join("\n", @{$options{'preamble'}})
+ if ($options{preamble} && @{$options{preamble}});
+$User{UserPostamble} = join("\n", @{$options{'postamble'}})
+ if ($options{postamble} && @{$options{postamble}});
+
+
+
+# If $options{'out'} is set we are processing to a single output file
+my $multi_documents;
+if (exists $options{'out'} && defined $options{'out'}) {
+ $multi_documents = 0;
+} else {
+ $multi_documents = 1;
+}
+
+# If the output file is not specified it is assumed that
+# a single output file is required per input file using
+# a .tex extension rather than any exisiting extension
+
+if ($multi_documents) {
+
+ # Case where we just generate one input per output
+
+ foreach my $pod (@pods) {
+
+ if (-f $pod) {
+
+ my $output = $pod;
+ $output = basename($output, '.pm', '.pod','.pl') . '.tex';
+
+ # Create a new parser object
+ my $parser = new Pod::LaTeX(
+ AddPreamble => $options{'full'},
+ AddPostamble => $options{'full'},
+ MakeIndex => $options{'full'},
+ TableOfContents => $options{'full'},
+ ReplaceNAMEwithSection => $options{'modify'},
+ UniqueLabels => $options{'modify'},
+ Head1Level => $options{'h1level'},
+ LevelNoNum => $options{'h1level'} + 1,
+ %User,
+ );
+
+ # Select sections if supplied
+ $parser->select(@{ $options{'sections'}})
+ if @{$options{'sections'}};
+
+ # Derive the input file from the output file
+ $parser->parse_from_file($pod, $output);
+
+ print "Written output to $output\n" if $options{'verbose'};
+
+ } else {
+ warn "File $pod not found\n";
+ }
+
+ }
+} else {
+
+ # Case where we want everything to be in a single document
+
+ # Need to open the output file ourselves
+ my $output = $options{'out'};
+ $output .= '.tex' unless $output =~ /\.tex$/;
+
+ # Use auto-vivified file handle in perl 5.6
+ my $outfh = gensym;
+ open ($outfh, ">$output") || die "Could not open output file: $!\n";
+
+ # Flag to indicate whether we have converted at least one file
+ # indicates how many files have been converted
+ my $converted = 0;
+
+ # Loop over the input files
+ foreach my $pod (@pods) {
+
+ if (-f $pod) {
+
+ warn "Converting $pod\n" if $options{'verbose'};
+
+ # Open the file (need the handle)
+ # Use auto-vivified handle in perl 5.6
+ my $podfh = gensym;
+ open ($podfh, "<$pod") || die "Could not open pod file $pod: $!\n";
+
+ # if this is the first file to be converted we may want to add
+ # a preamble (controlled by command line option)
+ my $preamble = 0;
+ $preamble = 1 if ($converted == 0 && $options{'full'});
+
+ # if this is the last file to be converted may want to add
+ # a postamble (controlled by command line option)
+ # relies on a previous pass to check existence of all pods we
+ # are converting.
+ my $postamble = ( ($converted == $#pods && $options{'full'}) ? 1 : 0 );
+
+ # Open parser object
+ # May want to start with a preamble for the first one and
+ # end with an index for the last
+ my $parser = new Pod::LaTeX(
+ MakeIndex => $options{'full'},
+ TableOfContents => $preamble,
+ ReplaceNAMEwithSection => $options{'modify'},
+ UniqueLabels => $options{'modify'},
+ StartWithNewPage => $options{'full'},
+ AddPreamble => $preamble,
+ AddPostamble => $postamble,
+ Head1Level => $options{'h1level'},
+ LevelNoNum => $options{'h1level'} + 1,
+ %User
+ );
+
+ # Store the file name for error messages
+ # This is a kluge that breaks the data hiding of the object
+ $parser->{_INFILE} = $pod;
+
+ # Select sections if supplied
+ $parser->select(@{ $options{'sections'}})
+ if @{$options{'sections'}};
+
+ # Parse it
+ $parser->parse_from_filehandle($podfh, $outfh);
+
+ # We have converted at least one file
+ $converted++;
+
+ } else {
+ warn "File $pod not found\n";
+ }
+
+ }
+
+ # Should unlink the file if we didn't convert anything!
+ # dont check for return status of unlink
+ # since there is not a lot to be done if the unlink failed
+ # and the program does not rely upon it.
+ unlink "$output" unless $converted;
+
+ # If verbose
+ warn "Converted $converted files\n" if $options{'verbose'};
+
+}
+
+exit;
+
+__END__
+
+=head1 NAME
+
+pod2latex - convert pod documentation to latex format
+
+=head1 SYNOPSIS
+
+ pod2latex *.pm
+
+ pod2latex -out mytex.tex *.pod
+
+ pod2latex -full -sections 'DESCRIPTION|NAME' SomeDir
+
+ pod2latex -prefile h.tex -postfile t.tex my.pod
+
+=head1 DESCRIPTION
+
+C<pod2latex> is a program to convert POD format documentation
+(L<perlpod>) into latex. It can process multiple input documents at a
+time and either generate a latex file per input document or a single
+combined output file.
+
+=head1 OPTIONS AND ARGUMENTS
+
+This section describes the supported command line options. Minimum
+matching is supported.
+
+=over 4
+
+=item B<-out>
+
+Name of the output file to be used. If there are multiple input pods
+it is assumed that the intention is to write all translated output
+into a single file. C<.tex> is appended if not present. If the
+argument is not supplied, a single document will be created for each
+input file.
+
+=item B<-full>
+
+Creates a complete C<latex> file that can be processed immediately
+(unless C<=for/=begin> directives are used that rely on extra packages).
+Table of contents and index generation commands are included in the
+wrapper C<latex> code.
+
+=item B<-sections>
+
+Specify pod sections to include (or remove if negated) in the
+translation. See L<Pod::Select/"SECTION SPECIFICATIONS"> for the
+format to use for I<section-spec>. This option may be given multiple
+times on the command line.This is identical to the similar option in
+the C<podselect()> command.
+
+=item B<-modify>
+
+This option causes the output C<latex> to be slightly
+modified from the input pod such that when a C<=head1 NAME>
+is encountered a section is created containing the actual
+pod name (rather than B<NAME>) and all subsequent C<=head1>
+directives are treated as subsections. This has the advantage
+that the description of a module will be in its own section
+which is helpful for including module descriptions in documentation.
+Also forces C<latex> label and index entries to be prefixed by the
+name of the module.
+
+=item B<-h1level>
+
+Specifies the C<latex> section that is equivalent to a C<H1> pod
+directive. This is an integer between 0 and 5 with 0 equivalent to a
+C<latex> chapter, 1 equivalent to a C<latex> section etc. The default
+is 1 (C<H1> equivalent to a latex section).
+
+=item B<-help>
+
+Print a brief help message and exit.
+
+=item B<-man>
+
+Print the manual page and exit.
+
+=item B<-verbose>
+
+Print information messages as each document is processed.
+
+=item B<-preamble>
+
+A user-supplied preamble for the LaTeX code. Multiple values
+are supported and appended in order separated by "\n".
+See B<-prefile> for reading the preamble from a file.
+
+=item B<-postamble>
+
+A user supplied postamble for the LaTeX code. Multiple values
+are supported and appended in order separated by "\n".
+See B<-postfile> for reading the postamble from a file.
+
+=item B<-prefile>
+
+A user-supplied preamble for the LaTeX code to be read from the
+named file. Multiple values are supported and appended in
+order. See B<-preamble>.
+
+=item B<-postfile>
+
+A user-supplied postamble for the LaTeX code to be read from the
+named file. Multiple values are supported and appended in
+order. See B<-postamble>.
+
+=back
+
+=head1 BUGS
+
+Known bugs are:
+
+=over 4
+
+=item *
+
+Cross references between documents are not resolved when multiple
+pod documents are converted into a single output C<latex> file.
+
+=item *
+
+Functions and variables are not automatically recognized
+and they will therefore not be marked up in any special way
+unless instructed by an explicit pod command.
+
+=back
+
+=head1 SEE ALSO
+
+L<Pod::LaTeX>
+
+=head1 AUTHOR
+
+Tim Jenness E<lt>tjenness at cpan.orgE<gt>
+
+This program is free software; you can redistribute it
+and/or modify it under the same terms as Perl itself.
+
+Copyright (C) 2000, 2003, 2004 Tim Jenness. All Rights Reserved.
+
+=cut
+
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/pod2man.PL (from rev 6437, vendor/perl/5.18.1/pod/pod2man.PL)
===================================================================
--- trunk/contrib/perl/pod/pod2man.PL (rev 0)
+++ trunk/contrib/perl/pod/pod2man.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,588 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+ eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+ if \$running_under_some_shell;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+
+# pod2man -- Convert POD data to formatted *roff input.
+#
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra at stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+
+require 5.004;
+
+use Getopt::Long qw(GetOptions);
+use Pod::Man ();
+use Pod::Usage qw(pod2usage);
+
+use strict;
+
+# Silence -w warnings.
+use vars qw($running_under_some_shell);
+
+# Insert -- into @ARGV before any single dash argument to hide it from
+# Getopt::Long; we want to interpret it as meaning stdin.
+my $stdin;
+ at ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
+
+# Parse our options, trying to retain backward compatibility with pod2man but
+# allowing short forms as well. --lax is currently ignored.
+my %options;
+$options{errors} = 'pod';
+Getopt::Long::config ('bundling_override');
+GetOptions (\%options, 'center|c=s', 'date|d=s', 'fixed=s', 'fixedbold=s',
+ 'fixeditalic=s', 'fixedbolditalic=s', 'help|h', 'lax|l',
+ 'name|n=s', 'official|o', 'quotes|q=s', 'release|r:s',
+ 'section|s=s', 'stderr', 'verbose|v', 'utf8|u') or exit 1;
+pod2usage (0) if $options{help};
+
+# Official sets --center, but don't override things explicitly set.
+if ($options{official} && !defined $options{center}) {
+ $options{center} = 'Perl Programmers Reference Guide';
+}
+
+# Verbose is only our flag, not a Pod::Man flag.
+my $verbose = $options{verbose};
+delete $options{verbose};
+
+# This isn't a valid Pod::Man option and is only accepted for backward
+# compatibility.
+delete $options{lax};
+
+# Initialize and run the formatter, pulling a pair of input and output off at
+# a time.
+my $parser = Pod::Man->new (%options);
+my @files;
+do {
+ @files = splice (@ARGV, 0, 2);
+ print " $files[1]\n" if $verbose;
+ $parser->parse_from_file (@files);
+} while (@ARGV);
+
+__END__
+
+=head1 NAME
+
+pod2man - Convert POD data to formatted *roff input
+
+=for stopwords
+en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris
+URL troff troff-specific formatters uppercased Christiansen
+
+=head1 SYNOPSIS
+
+pod2man [B<--center>=I<string>] [B<--date>=I<string>]
+ [B<--fixed>=I<font>] [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>]
+ [B<--fixedbolditalic>=I<font>] [B<--name>=I<name>] [B<--official>]
+ [B<--quotes>=I<quotes>] [B<--release>[=I<version>]]
+ [B<--section>=I<manext>] [B<--stderr>] [B<--utf8>] [B<--verbose>]
+ [I<input> [I<output>] ...]
+
+pod2man B<--help>
+
+=head1 DESCRIPTION
+
+B<pod2man> is a front-end for Pod::Man, using it to generate *roff input
+from POD source. The resulting *roff code is suitable for display on a
+terminal using nroff(1), normally via man(1), or printing using troff(1).
+
+I<input> is the file to read for POD source (the POD can be embedded in
+code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
+given, is the file to which to write the formatted output. If I<output>
+isn't given, the formatted output is written to C<STDOUT>. Several POD
+files can be processed in the same B<pod2man> invocation (saving module
+load and compile times) by providing multiple pairs of I<input> and
+I<output> files on the command line.
+
+B<--section>, B<--release>, B<--center>, B<--date>, and B<--official> can
+be used to set the headers and footers to use; if not given, Pod::Man will
+assume various defaults. See below or L<Pod::Man> for details.
+
+B<pod2man> assumes that your *roff formatters have a fixed-width font
+named C<CW>. If yours is called something else (like C<CR>), use
+B<--fixed> to specify it. This generally only matters for troff output
+for printing. Similarly, you can set the fonts used for bold, italic, and
+bold italic fixed-width output.
+
+Besides the obvious pod conversions, Pod::Man, and therefore pod2man also
+takes care of formatting func(), func(n), and simple variable references
+like $foo or @bar so you don't have to use code escapes for them; complex
+expressions like C<$fred{'stuff'}> will still need to be escaped, though.
+It also translates dashes that aren't used as hyphens into en dashes, makes
+long dashes--like this--into proper em dashes, fixes "paired quotes," and
+takes care of several other troff-specific tweaks. See L<Pod::Man> for
+complete information.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-c> I<string>, B<--center>=I<string>
+
+Sets the centered page header to I<string>. The default is "User
+Contributed Perl Documentation", but also see B<--official> below.
+
+=item B<-d> I<string>, B<--date>=I<string>
+
+Set the left-hand footer string to this value. By default, the modification
+date of the input file will be used, or the current date if input comes from
+C<STDIN>.
+
+=item B<--fixed>=I<font>
+
+The fixed-width font to use for verbatim text and code. Defaults to
+C<CW>. Some systems may want C<CR> instead. Only matters for troff(1)
+output.
+
+=item B<--fixedbold>=I<font>
+
+Bold version of the fixed-width font. Defaults to C<CB>. Only matters
+for troff(1) output.
+
+=item B<--fixeditalic>=I<font>
+
+Italic version of the fixed-width font (actually, something of a misnomer,
+since most fixed-width fonts only have an oblique version, not an italic
+version). Defaults to C<CI>. Only matters for troff(1) output.
+
+=item B<--fixedbolditalic>=I<font>
+
+Bold italic (probably actually oblique) version of the fixed-width font.
+Pod::Man doesn't assume you have this, and defaults to C<CB>. Some
+systems (such as Solaris) have this font available as C<CX>. Only matters
+for troff(1) output.
+
+=item B<-h>, B<--help>
+
+Print out usage information.
+
+=item B<-l>, B<--lax>
+
+No longer used. B<pod2man> used to check its input for validity as a
+manual page, but this should now be done by L<podchecker(1)> instead.
+Accepted for backward compatibility; this option no longer does anything.
+
+=item B<-n> I<name>, B<--name>=I<name>
+
+Set the name of the manual page to I<name>. Without this option, the manual
+name is set to the uppercased base name of the file being converted unless
+the manual section is 3, in which case the path is parsed to see if it is a
+Perl module path. If it is, a path like C<.../lib/Pod/Man.pm> is converted
+into a name like C<Pod::Man>. This option, if given, overrides any
+automatic determination of the name.
+
+Note that this option is probably not useful when converting multiple POD
+files at once. The convention for Unix man pages for commands is for the
+man page title to be in all-uppercase even if the command isn't.
+
+=item B<-o>, B<--official>
+
+Set the default header to indicate that this page is part of the standard
+Perl release, if B<--center> is not also given.
+
+=item B<-q> I<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> text (but the font is still changed for
+troff output).
+
+=item B<-r>, B<--release>
+
+Set the centered footer. By default, this is the version of Perl you run
+B<pod2man> under. Note that some system an macro sets assume that the
+centered footer will be a modification date and will prepend something like
+"Last modified: "; if this is the case, you may want to set B<--release> to
+the last modified date and B<--date> to the version number.
+
+=item B<-s>, B<--section>
+
+Set the section for the C<.TH> macro. The standard section numbering
+convention is to use 1 for user commands, 2 for system calls, 3 for
+functions, 4 for devices, 5 for file formats, 6 for games, 7 for
+miscellaneous information, and 8 for administrator commands. There is a lot
+of variation here, however; some systems (like Solaris) use 4 for file
+formats, 5 for miscellaneous information, and 7 for devices. Still others
+use 1m instead of 8, or some mix of both. About the only section numbers
+that are reliably consistent are 1, 2, and 3.
+
+By default, section 1 will be used unless the file ends in C<.pm>, in
+which case section 3 will be selected.
+
+=item B<--stderr>
+
+By default, B<pod2man> puts any errors detected in the POD input in a POD
+ERRORS section in the output manual page. If B<--stderr> is given, errors
+are sent to standard error instead and the POD ERRORS section is
+suppressed.
+
+=item B<-u>, B<--utf8>
+
+By default, B<pod2man> produces the most conservative possible *roff
+output to try to ensure that it will work with as many different *roff
+implementations as possible. Many *roff implementations cannot handle
+non-ASCII characters, so this means all non-ASCII characters are converted
+either to a *roff escape sequence that tries to create a properly accented
+character (at least for troff output) or to C<X>.
+
+This option says to instead output literal UTF-8 characters. If your
+*roff implementation can handle it, this is the best output format to use
+and avoids corruption of documents containing non-ASCII characters.
+However, be warned that *roff source with literal UTF-8 characters is not
+supported by many implementations and may even result in segfaults and
+other bad behavior.
+
+Be aware that, when using this option, the input encoding of your POD
+source must be properly declared unless it is US-ASCII or Latin-1. POD
+input without an C<=encoding> command will be assumed to be in Latin-1,
+and if it's actually in UTF-8, the output will be double-encoded. See
+L<perlpod(1)> for more information on the C<=encoding> command.
+
+=item B<-v>, B<--verbose>
+
+Print out the name of each output file as it is being generated.
+
+=back
+
+=head1 DIAGNOSTICS
+
+If B<pod2man> fails with errors, see L<Pod::Man> and L<Pod::Simple> for
+information about what those errors might mean.
+
+=head1 EXAMPLES
+
+ pod2man program > program.1
+ pod2man SomeModule.pm /usr/perl/man/man3/SomeModule.3
+ pod2man --section=7 note.pod > note.7
+
+If you would like to print out a lot of man page continuously, you probably
+want to set the C and D registers to set contiguous page numbering and
+even/odd paging, at least on some versions of man(7).
+
+ troff -man -rC1 -rD1 perl.1 perldata.1 perlsyn.1 ...
+
+To get index entries on C<STDERR>, turn on the F register, as in:
+
+ troff -man -rF1 perl.1
+
+The indexing merely outputs messages via C<.tm> for each major page,
+section, subsection, item, and any C<XE<lt>E<gt>> directives. See
+L<Pod::Man> for more details.
+
+=head1 BUGS
+
+Lots of this documentation is duplicated from L<Pod::Man>.
+
+=head1 NOTES
+
+For those not sure of the proper layout of a man page, here are some notes
+on writing a proper man page.
+
+The name of the program being documented is conventionally written in bold
+(using BE<lt>E<gt>) wherever it occurs, as are all program options.
+Arguments should be written in italics (IE<lt>E<gt>). Functions are
+traditionally written in italics; if you write a function as function(),
+Pod::Man will take care of this for you. Literal code or commands should
+be in CE<lt>E<gt>. References to other man pages should be in the form
+C<manpage(section)>, and Pod::Man will automatically format those
+appropriately. As an exception, it's traditional not to use this form when
+referring to module documentation; use C<LE<lt>Module::NameE<gt>> instead.
+
+References to other programs or functions are normally in the form of man
+page references so that cross-referencing tools can provide the user with
+links and the like. It's possible to overdo this, though, so be careful not
+to clutter your documentation with too much markup.
+
+The major headers should be set out using a C<=head1> directive, and are
+historically written in the rather startling ALL UPPER CASE format, although
+this is not mandatory. Minor headers may be included using C<=head2>, and
+are typically in mixed case.
+
+The standard sections of a manual page are:
+
+=over 4
+
+=item NAME
+
+Mandatory section; should be a comma-separated list of programs or functions
+documented by this POD page, such as:
+
+ foo, bar - programs to do something
+
+Manual page indexers are often extremely picky about the format of this
+section, so don't put anything in it except this line. A single dash, and
+only a single dash, should separate the list of programs or functions from
+the description. Functions should not be qualified with C<()> or the like.
+The description should ideally fit on a single line, even if a man program
+replaces the dash with a few tabs.
+
+=item SYNOPSIS
+
+A short usage summary for programs and functions. This section is mandatory
+for section 3 pages.
+
+=item DESCRIPTION
+
+Extended description and discussion of the program or functions, or the body
+of the documentation for man pages that document something else. If
+particularly long, it's a good idea to break this up into subsections
+C<=head2> directives like:
+
+ =head2 Normal Usage
+
+ =head2 Advanced Features
+
+ =head2 Writing Configuration Files
+
+or whatever is appropriate for your documentation.
+
+=item OPTIONS
+
+Detailed description of each of the command-line options taken by the
+program. This should be separate from the description for the use of things
+like L<Pod::Usage|Pod::Usage>. This is normally presented as a list, with
+each option as a separate C<=item>. The specific option string should be
+enclosed in BE<lt>E<gt>. Any values that the option takes should be
+enclosed in IE<lt>E<gt>. For example, the section for the option
+B<--section>=I<manext> would be introduced with:
+
+ =item B<--section>=I<manext>
+
+Synonymous options (like both the short and long forms) are separated by a
+comma and a space on the same C<=item> line, or optionally listed as their
+own item with a reference to the canonical name. For example, since
+B<--section> can also be written as B<-s>, the above would be:
+
+ =item B<-s> I<manext>, B<--section>=I<manext>
+
+(Writing the short option first is arguably easier to read, since the long
+option is long enough to draw the eye to it anyway and the short option can
+otherwise get lost in visual noise.)
+
+=item RETURN VALUE
+
+What the program or function returns, if successful. This section can be
+omitted for programs whose precise exit codes aren't important, provided
+they return 0 on success as is standard. It should always be present for
+functions.
+
+=item ERRORS
+
+Exceptions, error return codes, exit statuses, and errno settings.
+Typically used for function documentation; program documentation uses
+DIAGNOSTICS instead. The general rule of thumb is that errors printed to
+C<STDOUT> or C<STDERR> and intended for the end user are documented in
+DIAGNOSTICS while errors passed internal to the calling program and
+intended for other programmers are documented in ERRORS. When documenting
+a function that sets errno, a full list of the possible errno values
+should be given here.
+
+=item DIAGNOSTICS
+
+All possible messages the program can print out--and what they mean. You
+may wish to follow the same documentation style as the Perl documentation;
+see perldiag(1) for more details (and look at the POD source as well).
+
+If applicable, please include details on what the user should do to correct
+the error; documenting an error as indicating "the input buffer is too
+small" without telling the user how to increase the size of the input buffer
+(or at least telling them that it isn't possible) aren't very useful.
+
+=item EXAMPLES
+
+Give some example uses of the program or function. Don't skimp; users often
+find this the most useful part of the documentation. The examples are
+generally given as verbatim paragraphs.
+
+Don't just present an example without explaining what it does. Adding a
+short paragraph saying what the example will do can increase the value of
+the example immensely.
+
+=item ENVIRONMENT
+
+Environment variables that the program cares about, normally presented as a
+list using C<=over>, C<=item>, and C<=back>. For example:
+
+ =over 6
+
+ =item HOME
+
+ Used to determine the user's home directory. F<.foorc> in this
+ directory is read for configuration details, if it exists.
+
+ =back
+
+Since environment variables are normally in all uppercase, no additional
+special formatting is generally needed; they're glaring enough as it is.
+
+=item FILES
+
+All files used by the program or function, normally presented as a list, and
+what it uses them for. File names should be enclosed in FE<lt>E<gt>. It's
+particularly important to document files that will be potentially modified.
+
+=item CAVEATS
+
+Things to take special care with, sometimes called WARNINGS.
+
+=item BUGS
+
+Things that are broken or just don't work quite right.
+
+=item RESTRICTIONS
+
+Bugs you don't plan to fix. :-)
+
+=item NOTES
+
+Miscellaneous commentary.
+
+=item AUTHOR
+
+Who wrote it (use AUTHORS for multiple people). Including your current
+e-mail address (or some e-mail address to which bug reports should be sent)
+so that users have a way of contacting you is a good idea. Remember that
+program documentation tends to roam the wild for far longer than you expect
+and pick an e-mail address that's likely to last if possible.
+
+=item HISTORY
+
+Programs derived from other sources sometimes have this, or you might keep
+a modification log here. If the log gets overly long or detailed,
+consider maintaining it in a separate file, though.
+
+=item COPYRIGHT AND LICENSE
+
+For copyright
+
+ Copyright YEAR(s) by YOUR NAME(s)
+
+(No, (C) is not needed. No, "all rights reserved" is not needed.)
+
+For licensing the easiest way is to use the same licensing as Perl itself:
+
+ This library is free software; you may redistribute it and/or modify
+ it under the same terms as Perl itself.
+
+This makes it easy for people to use your module with Perl. Note that
+this licensing is neither an endorsement or a requirement, you are of
+course free to choose any licensing.
+
+=item SEE ALSO
+
+Other man pages to check out, like man(1), man(7), makewhatis(8), or
+catman(8). Normally a simple list of man pages separated by commas, or a
+paragraph giving the name of a reference work. Man page references, if they
+use the standard C<name(section)> form, don't have to be enclosed in
+LE<lt>E<gt> (although it's recommended), but other things in this section
+probably should be when appropriate.
+
+If the package has a mailing list, include a URL or subscription
+instructions here.
+
+If the package has a web site, include a URL here.
+
+=back
+
+In addition, some systems use CONFORMING TO to note conformance to relevant
+standards and MT-LEVEL to note safeness for use in threaded programs or
+signal handlers. These headings are primarily useful when documenting parts
+of a C library. Documentation of object-oriented libraries or modules may
+use CONSTRUCTORS and METHODS sections for detailed documentation of the
+parts of the library and save the DESCRIPTION section for an overview; other
+large modules may use FUNCTIONS for similar reasons. Some people use
+OVERVIEW to summarize the description if it's quite long.
+
+Section ordering varies, although NAME should I<always> be the first section
+(you'll break some man page systems otherwise), and NAME, SYNOPSIS,
+DESCRIPTION, and OPTIONS generally always occur first and in that order if
+present. In general, SEE ALSO, AUTHOR, and similar material should be left
+for last. Some systems also move WARNINGS and NOTES to last. The order
+given above should be reasonable for most purposes.
+
+Finally, as a general note, try not to use an excessive amount of markup.
+As documented here and in L<Pod::Man>, you can safely leave Perl variables,
+function names, man page references, and the like unadorned by markup and
+the POD translators will figure it out for you. This makes it much easier
+to later edit the documentation. Note that many existing translators
+(including this one currently) will do the wrong thing with e-mail addresses
+when wrapped in LE<lt>E<gt>, so don't do that.
+
+For additional information that may be more accurate for your specific
+system, see either L<man(5)> or L<man(7)> depending on your system manual
+section numbering conventions.
+
+=head1 SEE ALSO
+
+L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<perlpod(1)>,
+L<podchecker(1)>, L<troff(1)>, L<man(7)>
+
+The man page documenting the an macro set may be L<man(5)> instead of
+L<man(7)> on your system.
+
+The current version of this script is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
+Perl core distribution as of 5.6.0.
+
+=head1 AUTHOR
+
+Russ Allbery <rra at stanford.edu>, based I<very> heavily on the original
+B<pod2man> by Larry Wall and Tom Christiansen. Large portions of this
+documentation, particularly the sections on the anatomy of a proper man
+page, are taken from the B<pod2man> documentation by Tom.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
+<rra at stanford.edu>.
+
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
+!NO!SUBS!
+#'# (cperl-mode)
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/pod2text.PL (from rev 6437, vendor/perl/5.18.1/pod/pod2text.PL)
===================================================================
--- trunk/contrib/perl/pod/pod2text.PL (rev 0)
+++ trunk/contrib/perl/pod/pod2text.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,312 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{startperl}
+ eval 'exec $Config{perlpath} -S \$0 \${1+"\$@"}'
+ if \$running_under_some_shell;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+
+# pod2text -- Convert POD data to formatted ASCII text.
+#
+# Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery <rra at stanford.edu>
+#
+# This program is free software; you may redistribute it and/or modify it
+# under the same terms as Perl itself.
+#
+# The driver script for Pod::Text, Pod::Text::Termcap, and Pod::Text::Color,
+# invoked by perldoc -t among other things.
+
+require 5.004;
+
+use Getopt::Long qw(GetOptions);
+use Pod::Text ();
+use Pod::Usage qw(pod2usage);
+
+use strict;
+
+# Silence -w warnings.
+use vars qw($running_under_some_shell);
+
+# Take an initial pass through our options, looking for one of the form
+# -<number>. We turn that into -w <number> for compatibility with the
+# original pod2text script.
+for (my $i = 0; $i < @ARGV; $i++) {
+ last if $ARGV[$i] =~ /^--$/;
+ if ($ARGV[$i] =~ /^-(\d+)$/) {
+ splice (@ARGV, $i++, 1, '-w', $1);
+ }
+}
+
+# Insert -- into @ARGV before any single dash argument to hide it from
+# Getopt::Long; we want to interpret it as meaning stdin (which Pod::Simple
+# does correctly).
+my $stdin;
+ at ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV;
+
+# Parse our options. Use the same names as Pod::Text for simplicity, and
+# default to sentence boundaries turned off for compatibility.
+my %options;
+$options{sentence} = 0;
+Getopt::Long::config ('bundling');
+GetOptions (\%options, 'alt|a', 'code', 'color|c', 'help|h', 'indent|i=i',
+ 'loose|l', 'margin|left-margin|m=i', 'overstrike|o',
+ 'quotes|q=s', 'sentence|s', 'stderr', 'termcap|t', 'utf8|u',
+ 'width|w=i')
+ or exit 1;
+pod2usage (1) if $options{help};
+
+# Figure out what formatter we're going to use. -c overrides -t.
+my $formatter = 'Pod::Text';
+if ($options{color}) {
+ $formatter = 'Pod::Text::Color';
+ eval { require Term::ANSIColor };
+ if ($@) { die "-c (--color) requires Term::ANSIColor be installed\n" }
+ require Pod::Text::Color;
+} elsif ($options{termcap}) {
+ $formatter = 'Pod::Text::Termcap';
+ require Pod::Text::Termcap;
+} elsif ($options{overstrike}) {
+ $formatter = 'Pod::Text::Overstrike';
+ require Pod::Text::Overstrike;
+}
+delete @options{'color', 'termcap', 'overstrike'};
+
+# Initialize and run the formatter.
+my $parser = $formatter->new (%options);
+do {
+ my ($input, $output) = splice (@ARGV, 0, 2);
+ $parser->parse_from_file ($input, $output);
+} while (@ARGV);
+
+__END__
+
+=head1 NAME
+
+pod2text - Convert POD data to formatted ASCII text
+
+=for stopwords
+-aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8
+UTF-8
+
+=head1 SYNOPSIS
+
+pod2text [B<-aclostu>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]>
+ [B<--stderr>] S<[B<-w> I<width>]> [I<input> [I<output> ...]]
+
+pod2text B<-h>
+
+=head1 DESCRIPTION
+
+B<pod2text> is a front-end for Pod::Text and its subclasses. It uses them
+to generate formatted ASCII text from POD source. It can optionally use
+either termcap sequences or ANSI color escape sequences to format the text.
+
+I<input> is the file to read for POD source (the POD can be embedded in
+code). If I<input> isn't given, it defaults to C<STDIN>. I<output>, if
+given, is the file to which to write the formatted output. If I<output>
+isn't given, the formatted output is written to C<STDOUT>. Several POD
+files can be processed in the same B<pod2text> invocation (saving module
+load and compile times) by providing multiple pairs of I<input> and
+I<output> files on the command line.
+
+=head1 OPTIONS
+
+=over 4
+
+=item B<-a>, B<--alt>
+
+Use an alternate output format that, among other things, uses a different
+heading style and marks C<=item> entries with a colon in the left margin.
+
+=item B<--code>
+
+Include any non-POD text from the input file in the output as well. Useful
+for viewing code documented with POD blocks with the POD rendered and the
+code left intact.
+
+=item B<-c>, B<--color>
+
+Format the output with ANSI color escape sequences. Using this option
+requires that Term::ANSIColor be installed on your system.
+
+=item B<-i> I<indent>, B<--indent=>I<indent>
+
+Set the number of spaces to indent regular text, and the default indentation
+for C<=over> blocks. Defaults to 4 spaces if this option isn't given.
+
+=item B<-h>, B<--help>
+
+Print out usage information and exit.
+
+=item B<-l>, B<--loose>
+
+Print a blank line after a C<=head1> heading. Normally, no blank line is
+printed after C<=head1>, although one is still printed after C<=head2>,
+because this is the expected formatting for manual pages; if you're
+formatting arbitrary text documents, using this option is recommended.
+
+=item B<-m> I<width>, B<--left-margin>=I<width>, B<--margin>=I<width>
+
+The width of the left margin in spaces. Defaults to 0. This is the margin
+for all text, including headings, not the amount by which regular text is
+indented; for the latter, see B<-i> option.
+
+=item B<-o>, B<--overstrike>
+
+Format the output with overstrike printing. Bold text is rendered as
+character, backspace, character. Italics and file names are rendered as
+underscore, backspace, character. Many pagers, such as B<less>, know how
+to convert this to bold or underlined text.
+
+=item B<-q> I<quotes>, B<--quotes>=I<quotes>
+
+Sets the quote marks used to surround CE<lt>> text to I<quotes>. If
+I<quotes> is a single character, it is used as both the left and right
+quote; if I<quotes> is two characters, the first character is used as the
+left quote and the second as the right quoted; and if I<quotes> is four
+characters, the first two are used as the left quote and the second two as
+the right quote.
+
+I<quotes> may also be set to the special value C<none>, in which case no
+quote marks are added around CE<lt>> text.
+
+=item B<-s>, B<--sentence>
+
+Assume each sentence ends with two spaces and try to preserve that spacing.
+Without this option, all consecutive whitespace in non-verbatim paragraphs
+is compressed into a single space.
+
+=item B<--stderr>
+
+By default, B<pod2text> puts any errors detected in the POD input in a POD
+ERRORS section in the output manual page. If B<--stderr> is given, errors
+are sent to standard error instead and the POD ERRORS section is
+suppressed.
+
+=item B<-t>, B<--termcap>
+
+Try to determine the width of the screen and the bold and underline
+sequences for the terminal from termcap, and use that information in
+formatting the output. Output will be wrapped at two columns less than the
+width of your terminal device. Using this option requires that your system
+have a termcap file somewhere where Term::Cap can find it and requires that
+your system support termios. With this option, the output of B<pod2text>
+will contain terminal control sequences for your current terminal type.
+
+=item B<-u>, B<--utf8>
+
+By default, B<pod2text> tries to use the same output encoding as its input
+encoding (to be backward-compatible with older versions). This option
+says to instead force the output encoding to UTF-8.
+
+Be aware that, when using this option, the input encoding of your POD
+source must be properly declared unless it is US-ASCII or Latin-1. POD
+input without an C<=encoding> command will be assumed to be in Latin-1,
+and if it's actually in UTF-8, the output will be double-encoded. See
+L<perlpod(1)> for more information on the C<=encoding> command.
+
+=item B<-w>, B<--width=>I<width>, B<->I<width>
+
+The column at which to wrap text on the right-hand side. Defaults to 76,
+unless B<-t> is given, in which case it's two columns less than the width of
+your terminal device.
+
+=back
+
+=head1 DIAGNOSTICS
+
+If B<pod2text> fails with errors, see L<Pod::Text> and L<Pod::Simple> for
+information about what those errors might mean. Internally, it can also
+produce the following diagnostics:
+
+=over 4
+
+=item -c (--color) requires Term::ANSIColor be installed
+
+(F) B<-c> or B<--color> were given, but Term::ANSIColor could not be
+loaded.
+
+=item Unknown option: %s
+
+(F) An unknown command line option was given.
+
+=back
+
+In addition, other L<Getopt::Long> error messages may result from invalid
+command-line options.
+
+=head1 ENVIRONMENT
+
+=over 4
+
+=item COLUMNS
+
+If B<-t> is given, B<pod2text> will take the current width of your screen
+from this environment variable, if available. It overrides terminal width
+information in TERMCAP.
+
+=item TERMCAP
+
+If B<-t> is given, B<pod2text> will use the contents of this environment
+variable if available to determine the correct formatting sequences for your
+current terminal device.
+
+=back
+
+=head1 SEE ALSO
+
+L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>,
+L<Pod::Text::Termcap>, L<Pod::Simple>, L<perlpod(1)>
+
+The current version of this script is always available from its web site at
+L<http://www.eyrie.org/~eagle/software/podlators/>. It is also part of the
+Perl core distribution as of 5.6.0.
+
+=head1 AUTHOR
+
+Russ Allbery <rra at stanford.edu>.
+
+=head1 COPYRIGHT AND LICENSE
+
+Copyright 1999, 2000, 2001, 2004, 2006, 2008 Russ Allbery
+<rra at stanford.edu>.
+
+This program is free software; you may redistribute it and/or modify it
+under the same terms as Perl itself.
+
+=cut
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/pod2usage.PL (from rev 6437, vendor/perl/5.18.1/pod/pod2usage.PL)
===================================================================
--- trunk/contrib/perl/pod/pod2usage.PL (rev 0)
+++ trunk/contrib/perl/pod/pod2usage.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,180 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{'startperl'}
+ eval 'exec perl -S \$0 "\$@"'
+ if 0;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+
+#############################################################################
+# pod2usage -- command to print usage messages from embedded pod docs
+#
+# Copyright (c) 1996-2000 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;
+
+=head1 NAME
+
+pod2usage - print usage messages from embedded pod docs in files
+
+=head1 SYNOPSIS
+
+=over 12
+
+=item B<pod2usage>
+
+[B<-help>]
+[B<-man>]
+[B<-exit>S< >I<exitval>]
+[B<-output>S< >I<outfile>]
+[B<-verbose> I<level>]
+[B<-pathlist> I<dirlist>]
+I<file>
+
+=back
+
+=head1 OPTIONS AND ARGUMENTS
+
+=over 8
+
+=item B<-help>
+
+Print a brief help message and exit.
+
+=item B<-man>
+
+Print this command's manual page and exit.
+
+=item B<-exit> I<exitval>
+
+The exit status value to return.
+
+=item B<-output> I<outfile>
+
+The output file to print to. If the special names "-" or ">&1" or ">&STDOUT"
+are used then standard output is used. If ">&2" or ">&STDERR" is used then
+standard error is used.
+
+=item B<-verbose> I<level>
+
+The desired level of verbosity to use:
+
+ 1 : print SYNOPSIS only
+ 2 : print SYNOPSIS sections and any OPTIONS/ARGUMENTS sections
+ 3 : print the entire manpage (similar to running pod2text)
+
+=item B<-pathlist> I<dirlist>
+
+Specifies one or more directories to search for the input file if it
+was not supplied with an absolute path. Each directory path in the given
+list should be separated by a ':' on Unix (';' on MSWin32 and DOS).
+
+=item I<file>
+
+The pathname of a file containing pod documentation to be output in
+usage message format (defaults to standard input).
+
+=back
+
+=head1 DESCRIPTION
+
+B<pod2usage> will read the given input file looking for pod
+documentation and will print the corresponding usage message.
+If no input file is specified then standard input is read.
+
+B<pod2usage> invokes the B<pod2usage()> function in the B<Pod::Usage>
+module. Please see L<Pod::Usage/pod2usage()>.
+
+=head1 SEE ALSO
+
+L<Pod::Usage>, L<pod2text(1)>
+
+=head1 AUTHOR
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Brad Appleton E<lt>bradapp at enteract.comE<gt>
+
+Based on code for B<pod2text(1)> written by
+Tom Christiansen E<lt>tchrist at mox.perl.comE<gt>
+
+=cut
+
+use Pod::Usage;
+use Getopt::Long;
+
+## Define options
+my %options = ();
+my @opt_specs = (
+ 'help',
+ 'man',
+ 'exit=i',
+ 'output=s',
+ 'pathlist=s',
+ 'verbose=i',
+);
+
+## Parse options
+GetOptions(\%options, @opt_specs) || pod2usage(2);
+pod2usage(1) if ($options{help});
+pod2usage(VERBOSE => 2) if ($options{man});
+
+## Dont default to STDIN if connected to a terminal
+pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
+
+ at ARGV = ('-') unless (@ARGV);
+if (@ARGV > 1) {
+ print STDERR "pod2usage: Too many filenames given\n\n";
+ pod2usage(2);
+}
+
+my %usage = ();
+$usage{-input} = shift(@ARGV);
+$usage{-exitval} = $options{'exit'} if (defined $options{'exit'});
+$usage{-output} = $options{'output'} if (defined $options{'output'});
+$usage{-verbose} = $options{'verbose'} if (defined $options{'verbose'});
+$usage{-pathlist} = $options{'pathlist'} if (defined $options{'pathlist'});
+
+pod2usage(\%usage);
+
+
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/podchecker.PL (from rev 6437, vendor/perl/5.18.1/pod/podchecker.PL)
===================================================================
--- trunk/contrib/perl/pod/podchecker.PL (rev 0)
+++ trunk/contrib/perl/pod/podchecker.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,186 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# This is so that make depend always knows where to find PL derivatives.
+$origdir = cwd;
+chdir(dirname($0));
+($file = basename($0)) =~ s/\.PL$//;
+$file =~ s/\.pl$//
+ if ($^O eq 'VMS' or $^O eq 'os2' or $^O eq 'dos'); # "case-forgiving"
+$file .= '.com' if $^O eq 'VMS';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{'startperl'}
+ eval 'exec perl -S \$0 "\$@"'
+ if 0;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+#############################################################################
+# podchecker -- command to invoke the podchecker function in Pod::Checker
+#
+# Copyright (c) 1998-2000 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;
+
+=head1 NAME
+
+podchecker - check the syntax of POD format documentation files
+
+=head1 SYNOPSIS
+
+B<podchecker> [B<-help>] [B<-man>] [B<-(no)warnings>] [I<file>S< >...]
+
+=head1 OPTIONS AND ARGUMENTS
+
+=over 8
+
+=item B<-help>
+
+Print a brief help message and exit.
+
+=item B<-man>
+
+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.
+
+=item I<file>
+
+The pathname of a POD file to syntax-check (defaults to standard input).
+
+=back
+
+=head1 DESCRIPTION
+
+B<podchecker> will read the given input files looking for POD
+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.
+
+=head1 RETURN VALUE
+
+B<podchecker> returns a 0 (zero) exit status if all specified
+POD files are ok.
+
+=head1 ERRORS
+
+B<podchecker> returns the exit status 1 if at least one of
+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
+results, call B<podchecker> with one single argument only.
+
+=head1 SEE ALSO
+
+L<Pod::Parser> and L<Pod::Checker>
+
+=head1 AUTHORS
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Brad Appleton E<lt>bradapp at enteract.comE<gt>,
+Marek Rouchal E<lt>marekr at cpan.orgE<gt>
+
+Based on code for B<Pod::Text::pod2text(1)> written by
+Tom Christiansen E<lt>tchrist at mox.perl.comE<gt>
+
+=cut
+
+
+use Pod::Checker;
+use Pod::Usage;
+use Getopt::Long;
+
+## Define options
+my %options;
+
+## Parse options
+GetOptions(\%options, qw(help man warnings+ nowarnings)) || 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;
+ at 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) {
+ # errors occurred
+ $status = 1;
+ printf STDERR ("%s has %d pod syntax %s.\n",
+ $podfile, $errors,
+ ($errors == 1) ? 'error' : 'errors');
+ }
+ elsif($errors < 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;
+
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Copied: trunk/contrib/perl/pod/podselect.PL (from rev 6437, vendor/perl/5.18.1/pod/podselect.PL)
===================================================================
--- trunk/contrib/perl/pod/podselect.PL (rev 0)
+++ trunk/contrib/perl/pod/podselect.PL 2013-12-02 21:27:48 UTC (rev 6441)
@@ -0,0 +1,143 @@
+#!/usr/local/bin/perl
+
+use Config;
+use File::Basename qw(&basename &dirname);
+use Cwd;
+
+# List explicitly here the variables you want Configure to
+# generate. Metaconfig only looks for shell variables, so you
+# have to mention them as if they were shell variables, not
+# %Config entries. Thus you write
+# $startperl
+# to ensure Configure will look for $Config{startperl}.
+
+# This forces PL files to create target in same directory as PL file.
+# 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';
+
+open OUT,">$file" or die "Can't create $file: $!";
+
+print "Extracting $file (with variable substitutions)\n";
+
+# In this section, perl variables will be expanded during extraction.
+# You can use $Config{...} to use Configure variables.
+
+print OUT <<"!GROK!THIS!";
+$Config{'startperl'}
+ eval 'exec perl -S \$0 "\$@"'
+ if 0;
+!GROK!THIS!
+
+# In the following, perl variables are not expanded during extraction.
+
+print OUT <<'!NO!SUBS!';
+
+#############################################################################
+# podselect -- command to invoke the podselect function in Pod::Select
+#
+# Copyright (c) 1996-2000 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;
+
+=head1 NAME
+
+podselect - print selected sections of pod documentation on standard output
+
+=head1 SYNOPSIS
+
+B<podselect> [B<-help>] [B<-man>] [B<-section>S< >I<section-spec>]
+[I<file>S< >...]
+
+=head1 OPTIONS AND ARGUMENTS
+
+=over 8
+
+=item B<-help>
+
+Print a brief help message and exit.
+
+=item B<-man>
+
+Print the manual page and exit.
+
+=item B<-section>S< >I<section-spec>
+
+Specify a section to include in the output.
+See L<Pod::Parser/"SECTION SPECIFICATIONS">
+for the format to use for I<section-spec>.
+This option may be given multiple times on the command line.
+
+=item I<file>
+
+The pathname of a file from which to select sections of pod
+documentation (defaults to standard input).
+
+=back
+
+=head1 DESCRIPTION
+
+B<podselect> will read the given input files looking for pod
+documentation and will print out (in raw pod format) all sections that
+match one ore more of the given section specifications. If no section
+specifications are given than all pod sections encountered are output.
+
+B<podselect> invokes the B<podselect()> function exported by B<Pod::Select>
+Please see L<Pod::Select/podselect()> for more details.
+
+=head1 SEE ALSO
+
+L<Pod::Parser> and L<Pod::Select>
+
+=head1 AUTHOR
+
+Please report bugs using L<http://rt.cpan.org>.
+
+Brad Appleton E<lt>bradapp at enteract.comE<gt>
+
+Based on code for B<Pod::Text::pod2text(1)> written by
+Tom Christiansen E<lt>tchrist at mox.perl.comE<gt>
+
+=cut
+
+use Pod::Select;
+use Pod::Usage;
+use Getopt::Long;
+
+## Define options
+my %options = (
+ 'help' => 0,
+ 'man' => 0,
+ 'sections' => [],
+);
+
+## Parse options
+GetOptions(\%options, 'help', 'man', 'sections|select=s@') || pod2usage(2);
+pod2usage(1) if ($options{help});
+pod2usage(-verbose => 2) if ($options{man});
+
+## Dont default to STDIN if connected to a terminal
+pod2usage(2) if ((@ARGV == 0) && (-t STDIN));
+
+## Invoke podselect().
+if (@{ $options{'sections'} } > 0) {
+ podselect({ -sections => $options{'sections'} }, @ARGV);
+}
+else {
+ podselect(@ARGV);
+}
+
+
+!NO!SUBS!
+
+close OUT or die "Can't close $file: $!";
+chmod 0755, $file or die "Can't reset permissions for $file: $!\n";
+exec("$Config{'eunicefix'} $file") if $Config{'eunicefix'} ne ':';
+chdir $origdir;
Index: trunk/contrib/perl/pod/roffitall
===================================================================
--- trunk/contrib/perl/pod/roffitall 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/roffitall 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/roffitall
___________________________________________________________________
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.2
\ No newline at end of property
Modified: trunk/contrib/perl/pod/rofftoc
===================================================================
--- trunk/contrib/perl/pod/rofftoc 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/rofftoc 2013-12-02 21:27:48 UTC (rev 6441)
@@ -1,7 +1,3 @@
-# feed this into perl
- eval 'exec perl -S $0 ${1+"$@"}'
- if $running_under_some_shell;
-
# Usage: rofftoc PerlTOC.xxx.raw
#
# Post-processes roffitall output. Called from roffitall to produce
Property changes on: trunk/contrib/perl/pod/rofftoc
___________________________________________________________________
Deleted: svn:executable
## -1 +0,0 ##
-*
\ No newline at end of property
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/splitman
===================================================================
--- trunk/contrib/perl/pod/splitman 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/splitman 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/splitman
___________________________________________________________________
Deleted: svn:executable
## -1 +0,0 ##
-*
\ No newline at end of property
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
Index: trunk/contrib/perl/pod/splitpod
===================================================================
--- trunk/contrib/perl/pod/splitpod 2013-12-02 21:27:05 UTC (rev 6440)
+++ trunk/contrib/perl/pod/splitpod 2013-12-02 21:27:48 UTC (rev 6441)
Property changes on: trunk/contrib/perl/pod/splitpod
___________________________________________________________________
Deleted: svn:executable
## -1 +0,0 ##
-*
\ No newline at end of property
Deleted: cvs2svn:cvs-rev
## -1 +0,0 ##
-1.1.1.1
\ No newline at end of property
More information about the Midnightbsd-cvs
mailing list