diff options
Diffstat (limited to 'pod')
42 files changed, 6976 insertions, 1730 deletions
diff --git a/pod/.gitignore b/pod/.gitignore new file mode 100644 index 0000000000..872cc33e96 --- /dev/null +++ b/pod/.gitignore @@ -0,0 +1,52 @@ +# arch-specific pods +/perlaix.pod +/perlamiga.pod +/perlapollo.pod +/perlbeos.pod +/perlbs2000.pod +/perlce.pod +/perlcn.pod +/perlcygwin.pod +/perldelta.pod +/perldgux.pod +/perldos.pod +/perlepoc.pod +/perlfreebsd.pod +/perlhaiku.pod +/perlhpux.pod +/perlhurd.pod +/perlirix.pod +/perljp.pod +/perlko.pod +/perllinux.pod +/perlmachten.pod +/perlmacos.pod +/perlmacosx.pod +/perlmint.pod +/perlmpeix.pod +/perlnetware.pod +/perlopenbsd.pod +/perlos2.pod +/perlos390.pod +/perlos400.pod +/perlplan9.pod +/perlqnx.pod +/perlriscos.pod +/perlsolaris.pod +/perlsymbian.pod +/perltru64.pod +/perltw.pod +/perluts.pod +/perlvmesa.pod +/perlvms.pod +/perlvos.pod +/perlwin32.pod + +# scripts etc +/pod2html +/pod2latex +/pod2man +/pod2text +/pod2usage +/podchecker +/podselect diff --git a/pod/Makefile.SH b/pod/Makefile.SH index 74d299f7a1..0dd799b108 100644 --- a/pod/Makefile.SH +++ b/pod/Makefile.SH @@ -54,7 +54,7 @@ LDLIBPTH = $ldlibpth ## In the following dollars and backticks do not need the extra backslash. $spitshell >>Makefile <<'!NO!SUBS!' -CONVERTERS = pod2html pod2latex pod2man pod2text checkpods \ +CONVERTERS = pod2html pod2latex pod2man pod2text \ pod2usage podchecker podselect HTMLROOT = / # Change this to fix cross-references in HTML @@ -125,9 +125,9 @@ distclean: realclean veryclean: distclean -rm -f *~ *.orig -check: checkpods +check: podchecker @echo "checking..."; \ - $(PERL) -I../lib checkpods $(POD) + $(PERL) -I../lib podchecker $(POD) # Dependencies. pod2latex: pod2latex.PL ../lib/Config.pm @@ -142,9 +142,6 @@ pod2man: pod2man.PL ../lib/Config.pm pod2text: pod2text.PL ../lib/Config.pm $(LDLIBPTH) $(PERL) -I ../lib pod2text.PL -checkpods: checkpods.PL ../lib/Config.pm - $(LDLIBPTH) $(PERL) -I ../lib checkpods.PL - pod2usage: pod2usage.PL ../lib/Config.pm $(PERL) -I ../lib pod2usage.PL diff --git a/pod/buildtoc b/pod/buildtoc index de88d8d693..4054fdac43 100644 --- a/pod/buildtoc +++ b/pod/buildtoc @@ -611,7 +611,7 @@ sub do_nmake { 1 while $makefile =~ s/\0\tcopy .*\n/\0/gm; $makefile =~ s/\0+/join ("", &generate_nmake_1)/se; - $makefile =~ s{(del /f [^\n]+checkpods[^\n]+).*?(pod2html)} + $makefile =~ s{(del /f [^\n]+podchecker[^\n]+).*?(pod2html)} {"$1\n" . &generate_nmake_2."\n\t $2"}se; $makefile; } diff --git a/pod/checkpods.PL b/pod/checkpods.PL deleted file mode 100644 index 1466fb94d3..0000000000 --- a/pod/checkpods.PL +++ /dev/null @@ -1,85 +0,0 @@ -#!/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@gate.netThu Sep 5 17:19:30 1996 -# Date: Thu, 05 Sep 1996 00:11:22 -0400 -# From: Roderick Schertler <roderick@gate.net> -# To: perl5-porters@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@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@argon.org> -# Check for pod directives following any kind of unempty line, not -# just lines of whitespace. - -@directive = qw(head1 head2 item over back cut pod for begin end); -@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; diff --git a/pod/perl.pod b/pod/perl.pod index c5bbd32e8b..3a10eaa957 100644 --- a/pod/perl.pod +++ b/pod/perl.pod @@ -41,6 +41,8 @@ For ease of access, the Perl manual has been split up into several sections. perltooc Perl OO tutorial, part 2 perlbot Perl OO tricks and examples + perlperf Perl Performance and Optimization Techniques + perlstyle Perl style guide perlcheat Perl cheat sheet @@ -134,6 +136,7 @@ For ease of access, the Perl manual has been split up into several sections. perlapio Perl internal IO abstraction interface perlhack Perl hackers guide + perlrepository Perl source repository =head2 Miscellaneous @@ -193,6 +196,7 @@ For ease of access, the Perl manual has been split up into several sections. 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 perlhurd Perl notes for Hurd perlirix Perl notes for Irix diff --git a/pod/perl5100delta.pod b/pod/perl5100delta.pod index d47df845d2..2026de57af 100644 --- a/pod/perl5100delta.pod +++ b/pod/perl5100delta.pod @@ -396,7 +396,7 @@ details. This variable gives the native status returned by the last pipe close, backtick command, successful call to wait() or waitpid(), or from the -system() operator. See L<perlrun> for details. (Contributed by Gisle Aas.) +system() operator. See L<perlvar> for details. (Contributed by Gisle Aas.) =item C<${^RE_TRIE_MAXBUF}> diff --git a/pod/perl5110delta.pod b/pod/perl5110delta.pod index 65cfb94c44..f42511bf67 100644 --- a/pod/perl5110delta.pod +++ b/pod/perl5110delta.pod @@ -11,8 +11,23 @@ developement releases. =head1 Core Enhancements +=head1 The C<overloading> pragma + +This pragma allows you to lexically disable or enable overloading +for some or all operations. (Yuval Kogman) + =head1 Modules and Pragmata +=head2 Pragmata Changes + +=over 4 + +=item C<overloading> + +See L</"The C<overloading> pragma"> above. + +=back + =head1 Utility Changes =head1 Documentation @@ -23,6 +38,15 @@ developement releases. =head1 Selected Bug Fixes +=over 4 + +=item C<-I> on shebang line now adds directories in front of @INC + +as documented, and as does C<-I> when specified on the command-line. +(Renée Bäcker) + +=back + =head1 New or Changed Diagnostics =head1 Changed Internals diff --git a/pod/perl590delta.pod b/pod/perl590delta.pod index fdc6c314c1..db6f599597 100644 --- a/pod/perl590delta.pod +++ b/pod/perl590delta.pod @@ -485,8 +485,6 @@ of Perl in OS/400 PASE. perlreref has been added: it is a regular expressions quick reference. -=head1 Performance Enhancements - =head1 Installation and Configuration Improvements The UNIX standard Perl location, F</usr/bin/perl>, is no longer diff --git a/pod/perl595delta.pod b/pod/perl595delta.pod index 96d061ac1a..246b2cc747 100644 --- a/pod/perl595delta.pod +++ b/pod/perl595delta.pod @@ -464,8 +464,6 @@ CSS. Some formatting problems were also corrected. (Jari Aalto) A new manual page, L<perlunifaq> (the Perl Unicode FAQ), has been added (Juerd Waalboer). -=head1 Performance Enhancements - =head1 Installation and Configuration Improvements =head2 C++ compatibility @@ -563,10 +561,6 @@ an hash/array when the op is flagged with OPf_SPECIAL (Nicholas Clark). =for p5p XXX new BIND SV type, #29544, #29642 -=head1 Known Problems - -=head2 Platform Specific Problems - =head1 Reporting Bugs If you find what you think is a bug, you might check the articles diff --git a/pod/perlapi.pod b/pod/perlapi.pod index 4cedbc9aa2..8c3e6d6bb6 100644 --- a/pod/perlapi.pod +++ b/pod/perlapi.pod @@ -22,7 +22,30 @@ 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. +Perl was originally written to handle US-ASCII only (that is characters +whose ordinal numbers are in the range 0 - 127). +And documentation and comments may still use the term ASCII, when +sometimes in fact the entire range from 0 - 255 is meant. + +Note that Perl can be compiled and run under EBCDIC (See L<perlebcdic>) +or ASCII. Most of the documentation (and even comments in the code) +ignore the EBCDIC possibility. +For almost all purposes the differences are transparent. +As an example, under EBCDIC, +instead of UTF-8, UTF-EBCDIC is used to encode Unicode strings, and so +whenever this documentation refers to C<utf8> +(and variants of that name, including in function names), +it also (essentially transparently) means C<UTF-EBCDIC>. +But the ordinals of characters differ between ASCII, EBCDIC, and +the UTF- encodings, and a string encoded in UTF-EBCDIC may occupy more bytes +than in UTF-8. + +Also, on some EBCDIC machines, functions that are documented as operating on +US-ASCII (or Basic Latin in Unicode terminology) may in fact operate on all +256 characters in the EBCDIC range, not just the subset corresponding to +US-ASCII. + +The listing below is alphabetical, case insensitive. =head1 "Gimme" Values @@ -237,7 +260,7 @@ 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 *av) + I32 av_len(AV *av) =for hackers Found in file av.c @@ -279,7 +302,8 @@ Found in file av.c =item av_shift X<av_shift> -Shifts an SV off the beginning of the array. +Shifts an SV off the beginning of the array. Returns C<&PL_sv_undef> if the +array is empty. SV* av_shift(AV *av) @@ -509,8 +533,8 @@ Found in file scope.h =item isALNUM X<isALNUM> -Returns a boolean indicating whether the C C<char> is an ASCII alphanumeric -character (including underscore) or digit. +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) +alphanumeric character (including underscore) or digit. bool isALNUM(char ch) @@ -520,8 +544,8 @@ Found in file handy.h =item isALPHA X<isALPHA> -Returns a boolean indicating whether the C C<char> is an ASCII alphabetic -character. +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) +alphabetic character. bool isALPHA(char ch) @@ -531,7 +555,7 @@ Found in file handy.h =item isDIGIT X<isDIGIT> -Returns a boolean indicating whether the C C<char> is an ASCII +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) digit. bool isDIGIT(char ch) @@ -542,8 +566,8 @@ Found in file handy.h =item isLOWER X<isLOWER> -Returns a boolean indicating whether the C C<char> is a lowercase -character. +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) +lowercase character. bool isLOWER(char ch) @@ -553,7 +577,8 @@ Found in file handy.h =item isSPACE X<isSPACE> -Returns a boolean indicating whether the C C<char> is whitespace. +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) +whitespace. bool isSPACE(char ch) @@ -563,8 +588,8 @@ Found in file handy.h =item isUPPER X<isUPPER> -Returns a boolean indicating whether the C C<char> is an uppercase -character. +Returns a boolean indicating whether the C C<char> is a US-ASCII (Basic Latin) +uppercase character. bool isUPPER(char ch) @@ -574,7 +599,8 @@ Found in file handy.h =item toLOWER X<toLOWER> -Converts the specified character to lowercase. +Converts the specified character to lowercase. Characters outside the +US-ASCII (Basic Latin) range are viewed as not having any case. char toLOWER(char ch) @@ -584,7 +610,8 @@ Found in file handy.h =item toUPPER X<toUPPER> -Converts the specified character to uppercase. +Converts the specified character to uppercase. Characters outside the +US-ASCII (Basic Latin) range are viewed as not having any case. char toUPPER(char ch) @@ -815,9 +842,6 @@ Found in file perl.c =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); @@ -835,9 +859,6 @@ 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. @@ -872,8 +893,6 @@ 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 @@ -882,10 +901,6 @@ 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. @@ -905,8 +920,6 @@ 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 @@ -1245,6 +1258,27 @@ Found in file pp_pack.c =back +=head1 Functions in file pp_sys.c + + +=over 8 + +=item setdefout +X<setdefout> + +Sets PL_defoutgv, the default file handle for output, to the passed in +typeglob. As PL_defoutgv "owns" a reference on its typeglob, the reference +count of the passed in typeglob is increased by one, and the reference count +of the typeglob that PL_defoutgv points to is decreased by one. + + void setdefout(GV* gv) + +=for hackers +Found in file pp_sys.c + + +=back + =head1 GV Functions =over 8 @@ -3044,7 +3078,7 @@ 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) + SV* cv_const_sv(const CV *const cv) =for hackers Found in file op.c @@ -4057,7 +4091,7 @@ Found in file sv.h X<SvIOKp> Returns a U32 value indicating whether the SV contains an integer. Checks -the B<private> setting. Use C<SvIOK>. +the B<private> setting. Use C<SvIOK> instead. U32 SvIOKp(SV* sv) @@ -4250,7 +4284,7 @@ Found in file sv.h X<SvNIOKp> Returns a U32 value indicating whether the SV contains a number, integer or -double. Checks the B<private> setting. Use C<SvNIOK>. +double. Checks the B<private> setting. Use C<SvNIOK> instead. U32 SvNIOKp(SV* sv) @@ -4281,7 +4315,7 @@ Found in file sv.h X<SvNOKp> Returns a U32 value indicating whether the SV contains a double. Checks the -B<private> setting. Use C<SvNOK>. +B<private> setting. Use C<SvNOK> instead. U32 SvNOKp(SV* sv) @@ -4417,7 +4451,7 @@ Found in file sv.h X<SvPOKp> Returns a U32 value indicating whether the SV contains a character string. -Checks the B<private> setting. Use C<SvPOK>. +Checks the B<private> setting. Use C<SvPOK> instead. U32 SvPOKp(SV* sv) @@ -5100,6 +5134,16 @@ Like C<sv_setsv> but doesn't process magic. =for hackers Found in file sv.h +=item sv_utf8_upgrade_nomg +X<sv_utf8_upgrade_nomg> + +Like sv_utf8_upgrade, but doesn't do magic on C<sv> + + STRLEN sv_utf8_upgrade_nomg(NN SV *sv) + +=for hackers +Found in file sv.h + =back @@ -6435,7 +6479,8 @@ Found in file sv.c 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; +If the PV contains a character that cannot fit +in a byte, this conversion will fail; in this case, either returns false or, if C<fail_ok> is not true, croaks. @@ -6466,8 +6511,10 @@ 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. +Will C<mg_get> on C<sv> if appropriate. Always sets the SvUTF8 flag to avoid future validity checks even -if all the bytes have hibit clear. +if the whole string is the same in UTF-8 as not. +Returns the number of bytes in the converted string This is not as a general purpose byte encoding to Unicode interface: use the Encode extension for that. @@ -6483,8 +6530,10 @@ 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 +if all the bytes are invariant in UTF-8. If C<flags> has C<SV_GMAGIC> bit set, +will C<mg_get> on C<sv> if appropriate, else not. +Returns the number of bytes in the converted string +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: @@ -6495,6 +6544,16 @@ use the Encode extension for that. =for hackers Found in file sv.c +=item sv_utf8_upgrade_nomg +X<sv_utf8_upgrade_nomg> + +Like sv_utf8_upgrade, but doesn't do magic on C<sv> + + STRLEN sv_utf8_upgrade_nomg(SV *sv) + +=for hackers +Found in file sv.c + =item sv_vcatpvf X<sv_vcatpvf> @@ -6584,12 +6643,13 @@ Found in file sv.c =item bytes_from_utf8 X<bytes_from_utf8> -Converts a string C<s> of length C<len> from UTF-8 into byte encoding. +Converts a string C<s> of length C<len> from UTF-8 into native 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. +0 if C<s> is converted or consisted entirely of characters that are invariant +in utf8 (i.e., US-ASCII on non-EBCDIC machines). NOTE: this function is experimental and may change or be removed without notice. @@ -6602,11 +6662,14 @@ 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. +Converts a string C<s> of length C<len> from the native encoding into UTF-8. 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, +A NUL character will be written after the end of the string. + +If you want to convert to UTF-8 from encodings other than +the native (Latin1 or EBCDIC), see sv_recode_to_utf8(). NOTE: this function is experimental and may change or be @@ -6650,9 +6713,9 @@ Found in file utf8.c 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. +character. Note that an INVARIANT (i.e. ASCII on non-EBCDIC machines) +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 *s) @@ -6957,7 +7020,7 @@ 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. +Converts a string C<s> of length C<len> from UTF-8 into native 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. @@ -6994,7 +7057,7 @@ 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 +This function should only be used when the 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 diff --git a/pod/perldata.pod b/pod/perldata.pod index 4503e9d8bd..b26360917a 100644 --- a/pod/perldata.pod +++ b/pod/perldata.pod @@ -674,7 +674,7 @@ name of the array (without the leading C<@>), then the subscript inside square brackets. For example: @myarray = (5, 50, 500, 5000); - print "Element Number 2 is", $myarray[2], "\n"; + print "The Third Element is", $myarray[2], "\n"; The array indices start with 0. A negative subscript retrieves its value from the end. In our example, C<$myarray[-1]> would have been diff --git a/pod/perldebguts.pod b/pod/perldebguts.pod index 7a9fc485bb..55f237b755 100644 --- a/pod/perldebguts.pod +++ b/pod/perldebguts.pod @@ -154,6 +154,7 @@ contents of this variable are treated as if they were the argument of an C<o ...> debugger command (q.v. in L<perldebug/Options>). =head3 Debugger internal variables + In addition to the file and subroutine-related variables mentioned above, the debugger also maintains various magical internal variables. diff --git a/pod/perldebtut.pod b/pod/perldebtut.pod index a38349bbe7..b10f9b4066 100644 --- a/pod/perldebtut.pod +++ b/pod/perldebtut.pod @@ -708,7 +708,7 @@ L<perlrun> =head1 AUTHOR -Richard Foley <richard@rfi.net> Copyright (c) 2000 +Richard Foley <richard.foley@rfi.net> Copyright (c) 2000 =head1 CONTRIBUTORS diff --git a/pod/perldiag.pod b/pod/perldiag.pod index 775e274ffc..cdfe718670 100644 --- a/pod/perldiag.pod +++ b/pod/perldiag.pod @@ -902,13 +902,6 @@ method, nor does any of its base classes. See L<perlobj>. (W syntax) The @ISA array contained the name of another package that doesn't seem to exist. -=item Can't locate package %s for the parents of %s - -(W syntax) You did not define (or require/use) the first package, -which is named as a (possibly indirect) parent of the second by -C<@ISA> inheritance. Perl will treat this as if the undefined -package had an empty C<@ISA>. - =item Can't locate PerlIO%s (F) You tried to use in open() a PerlIO layer that does not exist, @@ -1597,7 +1590,7 @@ conversion routines don't handle. Drat. 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 run time +=item %s: Eval-group not allowed at runtime, use re 'eval' (F) Perl tried to compile a regular expression containing the C<(?{ ... })> zero-width assertion at run time, as it would when the @@ -2708,6 +2701,11 @@ package has restricted the set of allowed keys using the L<fields> pragma. (F) You provided a class qualifier in a "my", "our" or "state" declaration, but this class doesn't exist at this point in your program. +=item No such hook: %s + +(F) You specified a signal hook that was not recognized by Perl. Currently, Perl +accepts C<__DIE__> and C<__WARN__> as valid signal hooks + =item No such pipe open (P) An error peculiar to VMS. The internal routine my_pclose() tried to @@ -3661,6 +3659,12 @@ earlier. numeric field that will never go blank so that the repetition never 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 +are meaningless. + =item Reversed %s= operator (W syntax) You wrote your assignment operator backwards. The = must @@ -4616,6 +4620,12 @@ must be written as The <-- HERE shows in the regular expression about where 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 +about the /d modifier. + =item Useless use of %s in void context (W void) You did something without a side effect in a context that does @@ -4684,8 +4694,13 @@ returns no useful value. See L<perlmod>. =item Use of bare << to mean <<"" is deprecated -(D deprecated) You are now encouraged to use the explicitly quoted form -if you wish to use an empty line as the terminator of the here-document. +(D deprecated, W syntax) You are now encouraged to use the explicitly quoted +form if you wish to use an empty line as the terminator of the here-document. + +=item Use of comma-less variable list is deprecated + +(D deprecated, W syntax) The values you give to a format should be +separated by commas, not just aligned on a line. =item Use of chdir('') or chdir(undef) as chdir() deprecated @@ -4734,8 +4749,8 @@ repeatedly, the C</g> has no effect. =item Use of implicit split to @_ is deprecated -(D deprecated) It makes a lot of work for the compiler when you clobber -a subroutine's argument list, so it's better if you assign the results +(D deprecated, W syntax) It makes a lot of work for the compiler when you +clobber a subroutine's argument list, so it's better if you assign the results of a split() explicitly to an array (or list). =item Use of inherited AUTOLOAD for non-method %s() is deprecated diff --git a/pod/perldsc.pod b/pod/perldsc.pod index fd6403b7e7..623e367910 100644 --- a/pod/perldsc.pod +++ b/pod/perldsc.pod @@ -71,8 +71,8 @@ these types of data structures. =head1 REFERENCES X<reference> X<dereference> X<dereferencing> X<pointer> -The most important thing to understand about all data structures in Perl --- including multidimensional arrays--is that even though they might +The most important thing to understand about all data structures in +Perl--including multidimensional arrays--is that even though they might appear otherwise, Perl C<@ARRAY>s and C<%HASH>es are all internally one-dimensional. They can hold only scalar values (meaning a string, number, or a reference). They cannot directly contain other arrays or diff --git a/pod/perlebcdic.pod b/pod/perlebcdic.pod index 942526b0e9..f222e3d9df 100644 --- a/pod/perlebcdic.pod +++ b/pod/perlebcdic.pod @@ -15,9 +15,10 @@ Portions that are still incomplete are marked with XXX. =head2 ASCII -The American Standard Code for Information Interchange is a set of +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 system(s) of computers. +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 a "7-bit ASCII". ASCII was described by the American National Standards Institute @@ -69,7 +70,10 @@ identification numbers (CCSID numbers) or code page numbers. Leading zero digits in CCSID numbers within this document are insignificant. E.g. CCSID 0037 may be referred to as 37 in places. -=head2 13 variant characters +Perl can be compiled on platforms that run any of three commonly used EBCDIC +character sets, listed below. + +=head2 The 13 variant characters Among IBM EBCDIC character code sets there are 13 characters that are often mapped to different integer values. Those characters @@ -77,6 +81,13 @@ 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 +accordingly to that platform. If the platform uses a character set that is not +one of the three Perl knows about, Perl will either fail to compile, or +mistakenly and silently choose one of the three. +They are: + =head2 0037 Character code set ID 0037 is a mapping of the ASCII plus Latin-1 @@ -123,10 +134,7 @@ equal I<A with acute> or chr(101), and unpack("U", "A") would equal =item * -Many of the remaining seem to be related to case-insensitive matching: -for example, C<< /[\x{131}]/ >> (LATIN SMALL LETTER DOTLESS I) does -not match "I" case-insensitively, as it should under Unicode. -(The match succeeds in ASCII-derived platforms.) +Many of the remaining problems seem to be related to case-insensitive matching =item * @@ -137,15 +145,38 @@ supported under EBCDIC, likewise for the encoding pragma. =head2 Unicode and UTF -UTF is a Unicode Transformation Format. UTF-8 is a Unicode conforming -representation of the Unicode standard that looks very much like ASCII. -UTF-EBCDIC is an attempt to represent Unicode characters in an EBCDIC -transparent manner. +UTF stands for C<Unicode Transformation Format>. +UTF-8 is an encoding of Unicode into a sequence of 8-bit byte chunks, based on +ASCII and Latin-1. +The length of a sequence required to represent a Unicode code point +depends on the ordinal number of that code point, +with larger numbers requiring more bytes. +UTF-EBCDIC is like UTF-8, but based on EBCDIC. + +You may see the term C<invariant> character or code point. +This simply means that the character has the same numeric +value when encoded as when not. +(Note that this is a very different concept from L</The 13 variant characters> +mentioned above.) +For example, the ordinal value of 'A' is 193 in most EBCDIC code pages, +and also is 193 when encoded in UTF-EBCDIC. +All other code points occupy at least two bytes when encoded. +In UTF-8, the code points corresponding to the lowest 128 +ordinal numbers (0 - 127: the ASCII characters) are invariant. +In UTF-EBCDIC, there are 160 invariant characters. +(If you care, the EBCDIC invariants are those characters +which have ASCII equivalents, plus those that correspond to +the C1 controls (80..9f on ASCII platforms).) + +A string encoded in UTF-EBCDIC may be longer (but never shorter) than +one encoded in UTF-8. =head2 Using Encode Starting from Perl 5.8 you can use the standard new module Encode -to translate from EBCDIC to Latin-1 code points +to translate from EBCDIC to Latin-1 code points. +Encode knows about more EBCDIC character sets than Perl can currently +be compiled to run on. use Encode 'from_to'; @@ -181,9 +212,11 @@ you to use different encodings per IO channel. For example you may use open($f, ">:encoding(utf8)", "test.utf8"); print $f "Hello World!\n"; -to get two files containing "Hello World!\n" in ASCII, CP 37 EBCDIC, -ISO 8859-1 (Latin-1) (in this example identical to ASCII) respective -UTF-EBCDIC (in this example identical to normal EBCDIC). See the +to get four files containing "Hello World!\n" in ASCII, CP 37 EBCDIC, +ISO 8859-1 (Latin-1) (in this example identical to ASCII since only ASCII +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. As the PerlIO layer uses raw IO (bytes) internally, all this totally @@ -618,11 +651,11 @@ However, it would be unwise to write tests such as: $is_ascii = "\r" ne chr(13); # WRONG $is_ascii = "\n" ne chr(10); # ILL ADVISED -Obviously the first of these will fail to distinguish most ASCII machines -from either a CCSID 0037, a 1047, or a POSIX-BC EBCDIC machine since "\r" eq +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 -ASCII machine) the second C<$is_ascii> test will lead to trouble there. +ASCII platform) the second C<$is_ascii> test will lead to trouble there. To determine whether or not perl was built under an EBCDIC code page you can use the Config module like so: @@ -702,15 +735,15 @@ The OS/390 and z/OS C run time libraries provide _atoe() and _etoa() functions. =head1 OPERATOR DIFFERENCES The C<..> range operator treats certain character ranges with -care on EBCDIC machines. For example the following array -will have twenty six elements on either an EBCDIC machine -or an ASCII machine: +care on EBCDIC platforms. For example the following array +will have twenty six elements on either an EBCDIC platform +or an ASCII platform: @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 -on an EBCDIC machine than when run on an ASCII machine. Here is +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 @@ -722,7 +755,7 @@ an example adapted from the one in L<perlop>: An interesting property of the 32 C0 control characters in the ASCII table is that they can "literally" be constructed as control characters in perl, e.g. C<(chr(0) eq "\c@")> -C<(chr(1) eq "\cA")>, and so on. Perl on EBCDIC machines has been +C<(chr(1) eq "\cA")>, and so on. Perl on EBCDIC platforms has been ported to take "\c@" to chr(0) and "\cA" to chr(1) as well, but the thirty three characters that result depend on which code page you are using. The table below uses the character names from the previous table @@ -732,9 +765,9 @@ s/HORIZONTAL/HORIZ./; s/DEVICE CONTROL/D.C./; s/SEPARATOR/SEP./; s/NEGATIVE ACKNOWLEDGE/NEG. ACK./;. The POSIX-BC and 1047 sets are 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 "\cJ" on ASCII machines but by "\cU" on 1047 or POSIX-BC -machines and cannot be generated as a C<"\c.letter."> control character on -0037 machines. Note also that "\c\\" maps to two characters +may be generated by "\cJ" on ASCII platforms but by "\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\\" maps to two characters not one. chr ord 8859-1 0037 1047 && POSIX-BC @@ -781,13 +814,13 @@ not one. =item chr() chr() must be given an EBCDIC code number argument to yield a desired -character return value on an EBCDIC machine. For example: +character return value on an EBCDIC platform. For example: $CAPITAL_LETTER_A = chr(193); =item ord() -ord() will return EBCDIC code number values on an EBCDIC machine. +ord() will return EBCDIC code number values on an EBCDIC platform. For example: $the_number_193 = ord("A"); @@ -830,7 +863,7 @@ further details. The formats that can convert characters to numbers and vice versa will be different from their ASCII counterparts when executed -on an EBCDIC machine. Examples include: +on an EBCDIC platform. Examples include: printf("%c%c%c",193,194,195); # prints ABC @@ -866,7 +899,7 @@ 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 machines to +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 @@ -900,7 +933,7 @@ set of subs: 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 machine it may be desirable for constructs such as +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 @@ -994,7 +1027,7 @@ output. One big difference between ASCII based character sets and EBCDIC ones are the relative positions of upper and lower case letters and the -letters compared to the digits. If sorted on an ASCII based machine the +letters compared to the digits. If sorted on an ASCII based platform the two letter abbreviation for a physician comes before the two letter for drive, that is: @@ -1004,15 +1037,15 @@ for drive, that is: The property of lower case 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 machine, but -the latter (83) comes before the former (115) on an EBCDIC machine. +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 upper case 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 -ASCII machines versus EBCDIC machines. What follows are some suggestions +ASCII platforms versus EBCDIC platforms. What follows are some suggestions on how to deal with these differences. =head2 Ignore ASCII vs. EBCDIC sort differences. @@ -1035,7 +1068,7 @@ and include Latin-1 characters then apply: 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 machines, but 223 on most EBCDIC machines +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: @@ -1049,7 +1082,7 @@ of the data and may not be acceptable for that reason. This is the most expensive proposition that does not employ a network connection. -=head2 Perform sorting on one type of machine only. +=head2 Perform sorting on one type of platform only. This strategy can employ a network connection. As such it would be computationally expensive. @@ -1180,13 +1213,13 @@ that the @e2a array is filled in appropriately: =head2 Quoted-Printable encoding and decoding -On ASCII encoded machines it is possible to strip characters outside of +On ASCII encoded platforms it is possible to strip characters outside of the printable set using: # 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 machines +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): @@ -1211,7 +1244,7 @@ Such QP strings can be decoded with: $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 machines +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): @@ -1229,7 +1262,7 @@ 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 machines: +work on ASCII and EBCDIC platforms: #!/usr/local/bin/perl @@ -1247,13 +1280,13 @@ In one-liner form: 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 machine and hashes stored on an EBCDIC based machine. +on an ASCII based platform and hashes stored on an EBCDIC based platform. XXX =head1 I18N AND L10N Internationalization(I18N) and localization(L10N) are supported at least -in principle even on EBCDIC machines. The details are system dependent +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 @@ -1349,13 +1382,13 @@ L<perllocale>, L<perlfunc>, L<perlunicode>, L<utf8>. =head1 REFERENCES -http://anubis.dkuug.dk/i18n/charmaps +L<http://anubis.dkuug.dk/i18n/charmaps> -http://www.unicode.org/ +L<http://www.unicode.org/> -http://www.unicode.org/unicode/reports/tr16/ +L<http://www.unicode.org/unicode/reports/tr16/> -http://www.wps.com/texts/codes/ +L<http://www.wps.com/texts/codes/> B<ASCII: American Standard Code for Information Infiltration> Tom Jennings, September 1999. @@ -1373,7 +1406,7 @@ B<Codes, Ciphers, and Other Cryptic and Clandestine Communication> Fred B. Wrixon, ISBN 1-57912-040-7, Black Dog & Leventhal Publishers, 1998. -http://www.bobbemer.com/P-BIT.HTM +L<http://www.bobbemer.com/P-BIT.HTM> B<IBM - EBCDIC and the P-bit; The biggest Computer Goof Ever> Robert Bemer. =head1 HISTORY diff --git a/pod/perlform.pod b/pod/perlform.pod index 93d1633b84..3cfa1b768d 100644 --- a/pod/perlform.pod +++ b/pod/perlform.pod @@ -59,12 +59,12 @@ characters for field definitions: X<format, picture line> X<@> X<^> X<< < >> X<< | >> X<< > >> X<#> X<0> X<.> X<...> X<@*> X<^*> X<~> X<~~> - + @ start of regular field ^ start of special field - < pad character for left adjustification + < pad character for left justification | pad character for centering - > pad character for right adjustification + > pad character for right justification # pad character for a right justified numeric field 0 instead of first #: pad number with leading zeroes . decimal point within a numeric field diff --git a/pod/perlfunc.pod b/pod/perlfunc.pod index 2f9a85c8f6..1d3823e574 100644 --- a/pod/perlfunc.pod +++ b/pod/perlfunc.pod @@ -525,7 +525,7 @@ like for example images. If LAYER is present it is a single string, but may contain multiple directives. The directives alter the behaviour of the file handle. -When LAYER is present using binmode on text file makes sense. +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 @@ -1549,7 +1549,8 @@ itself. See L</wantarray> for more on how the evaluation context can be determined. If there is a syntax error or runtime error, or a C<die> statement is -executed, an undefined value is returned by C<eval>, and C<$@> is set to the +executed, C<eval> returns an undefined value in scalar context +or an empty list in list context, and C<$@> is set to the error message. If there was no error, C<$@> is guaranteed to be a null string. Beware that using C<eval> neither silences perl from printing warnings to STDERR, nor does it stuff the text of warning messages into C<$@>. @@ -1935,25 +1936,27 @@ perl. Here's a mailbox appender for BSD systems. - use Fcntl ':flock'; # import LOCK_* constants + use Fcntl qw(:flock SEEK_END); # import LOCK_* and SEEK_END constants sub lock { - flock(MBOX,LOCK_EX); - # and, in case someone appended - # while we were waiting... - seek(MBOX, 0, 2); + my ($fh) = @_; + flock($fh, LOCK_EX) or die "Cannot lock mailbox - $!\n"; + + # and, in case someone appended while we were waiting... + seek($fh, 0, SEEK_END) or die "Cannot seek - $!\n"; } sub unlock { - flock(MBOX,LOCK_UN); + my ($fh) = @_; + flock($fh, LOCK_UN) or die "Cannot unlock mailbox - $!\n"; } open(my $mbox, ">>", "/usr/spool/mail/$ENV{'USER'}") or die "Can't open mailbox: $!"; - lock(); + lock($mbox); print $mbox $msg,"\n\n"; - unlock(); + unlock($mbox); On systems that support a real flock(), locks are inherited across fork() calls, whereas those that must resort to the more capricious fcntl() @@ -2114,7 +2117,7 @@ C<Linux::Pid>. X<getpriority> X<priority> X<nice> Returns the current priority for a process, a process group, or a user. -(See L<getpriority(2)>.) Will raise a fatal exception if used on a +(See C<getpriority(2)>.) Will raise a fatal exception if used on a machine that doesn't implement getpriority(2). =item getpwnam NAME @@ -2853,7 +2856,7 @@ If EXPR is omitted, stats C<$_>. =item m// -The match operator. See L<perlop>. +The match operator. See L<perlop/"Regexp Quote-Like Operators">. =item map BLOCK LIST X<map> @@ -3271,7 +3274,7 @@ See L<perliol> for detailed info on PerlIO. You may also, in the Bourne shell tradition, specify an EXPR beginning with C<< '>&' >>, in which case the rest of the string is interpreted as the name of a filehandle (or file descriptor, if numeric) to be -duped (as L<dup(2)>) and opened. You may use C<&> after C<< > >>, +duped (as C<dup(2)>) and opened. You may use C<&> after C<< > >>, 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 @@ -3302,7 +3305,7 @@ C<STDERR> using various methods: If you specify C<< '<&=X' >>, where C<X> is a file descriptor number or a filehandle, then Perl will do an equivalent of C's C<fdopen> of -that file descriptor (and not call L<dup(2)>); this is more +that file descriptor (and not call C<dup(2)>); this is more parsimonious of file descriptors. For example: # open for input, reusing the fileno of $fd @@ -3415,7 +3418,7 @@ but will not work on a filename which happens to have a trailing space, while will have exactly the opposite restrictions. -If you want a "real" C C<open> (see L<open(2)> on your system), then you +If you want a "real" C C<open> (see C<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 @@ -4774,7 +4777,7 @@ the C<rmtree> function of the L<File::Path> module. =item s/// -The substitution operator. See L<perlop>. +The substitution operator. See L<perlop/"Regexp Quote-Like Operators">. =item say FILEHANDLE LIST X<say> @@ -5519,7 +5522,7 @@ produces the list value 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: - $header =~ s/\n\s+/ /g; # fix continuation lines + $header =~ s/\n(?=\s)//g; # fix continuation lines %hdrs = (UNIX_FROM => split /^(\S*?):\s*/m, $header); The pattern C</PATTERN/> may be replaced with an expression to specify @@ -5558,7 +5561,7 @@ X<sprintf> Returns a string formatted by the usual C<printf> conventions of the C library function C<sprintf>. See below for more details -and see L<sprintf(3)> or L<printf(3)> on your system for an explanation of +and see C<sprintf(3)> or C<printf(3)> on your system for an explanation of the general principles. For example: @@ -6672,7 +6675,8 @@ Note that times for children are included only after they terminate. =item tr/// -The transliteration operator. Same as C<y///>. See L<perlop>. +The transliteration operator. Same as C<y///>. See +L<perlop/"Quote and Quote-like Operators">. =item truncate FILEHANDLE,LENGTH X<truncate> @@ -7305,7 +7309,7 @@ X<wait> Behaves like the wait(2) system call 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<$?> -and C<{^CHILD_ERROR_NATIVE}>. +and C<${^CHILD_ERROR_NATIVE}>. Note that a return value of C<-1> could mean that child processes are being automatically reaped, as described in L<perlipc>. @@ -7315,7 +7319,7 @@ X<waitpid> 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. -The status is returned in C<$?> and C<{^CHILD_ERROR_NATIVE}>. If you say +The status is returned in C<$?> and C<${^CHILD_ERROR_NATIVE}>. If you say use POSIX ":sys_wait_h"; #... @@ -7430,6 +7434,7 @@ Note that write is I<not> the opposite of C<read>. Unfortunately. =item y/// -The transliteration operator. Same as C<tr///>. See L<perlop>. +The transliteration operator. Same as C<tr///>. See +L<perlop/"Quote and Quote-like Operators">. =back diff --git a/pod/perlguts.pod b/pod/perlguts.pod index 33346c6bd3..3ce60d0599 100644 --- a/pod/perlguts.pod +++ b/pod/perlguts.pod @@ -1959,7 +1959,7 @@ sanctioned for use in extensions) begins like this: void Perl_sv_setiv(pTHX_ SV* dsv, IV num) -C<pTHX_> is one of a number of macros (in perl.h) that hide the +C<pTHX_> is one of a number of macros (in F<perl.h>) that hide the details of the interpreter's context. THX stands for "thread", "this", or "thingy", as the case may be. (And no, George Lucas is not involved. :-) The first character could be 'p' for a B<p>rototype, 'a' for B<a>rgument, @@ -2028,7 +2028,7 @@ built with PERL_IMPLICIT_CONTEXT enabled. There are three ways to do this. First, the easy but inefficient way, which is also the default, in order to maintain source compatibility -with extensions: whenever XSUB.h is #included, it redefines the aTHX +with extensions: whenever F<XSUB.h> is #included, it redefines the aTHX and aTHX_ macros to call a function that will return the context. Thus, something like: @@ -2165,7 +2165,7 @@ This allows the ability to provide an extra pointer (called the "host" environment) for all the system calls. This makes it possible for all the system stuff to maintain their own state, broken down into seven C structures. These are thin wrappers around the usual system -calls (see win32/perllib.c) for the default perl executable, but for a +calls (see F<win32/perllib.c>) for the default perl executable, but for a more ambitious host (like the one that would do fork() emulation) all the extra work needed to pretend that different interpreters are actually different "processes", would be done here. @@ -2610,9 +2610,7 @@ you can use C<*s = uv>. =item * Mixing UTF-8 and non-UTF-8 strings is tricky. Use C<bytes_to_utf8> to get -a new string which is UTF-8 encoded. There are tricks you can use to -delay deciding whether you need to use a UTF-8 string until you get to a -high character - C<HALF_UPGRADE> is one of those. +a new string which is UTF-8 encoded, and then combine them. =back diff --git a/pod/perlhack.pod b/pod/perlhack.pod index cf38f03980..c5f249e4a5 100644 --- a/pod/perlhack.pod +++ b/pod/perlhack.pod @@ -207,23 +207,22 @@ interpreter. "A core module" is one that ships with Perl. =head2 Keeping in sync The source code to the Perl interpreter, in its different versions, is -kept in a repository managed by a revision control system ( which is -currently the Perforce program, see http://perforce.com/ ). The -pumpkings and a few others have access to the repository to check in -changes. Periodically the pumpking for the development version of Perl -will release a new version, so the rest of the porters can see what's -changed. The current state of the main trunk of repository, and patches -that describe the individual changes that have happened since the last -public release are available at this location: +kept in a repository managed by the git revision control system. The +pumpkings and a few others have write access to the repository to check in +changes. - http://public.activestate.com/pub/apc/ - ftp://public.activestate.com/pub/apc/ +How to clone and use the git perl repository is described in L<perlrepository>. -If you're looking for a particular change, or a change that affected -a particular set of files, you may find the B<Perl Repository Browser> -useful: +You can also choose to use rsync to get a copy of the current source tree +for the bleadperl branch and all maintenance branches : - http://public.activestate.com/cgi-bin/perlbrowse + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-current . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.10.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.8.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.6.x . + $ rsync -avz rsync://perl5.git.perl.org/APC/perl-5.005xx . + +(Add the C<--delete> option to remove leftover files) You may also want to subscribe to the perl5-changes mailing list to receive a copy of each patch that gets submitted to the maintenance @@ -240,334 +239,6 @@ Needless to say, the source code in perl-current is usually in a perpetual state of evolution. You should expect it to be very buggy. Do B<not> use it for any purpose other than testing and development. -Keeping in sync with the most recent branch can be done in several ways, -but the most convenient and reliable way is using B<rsync>, available at -ftp://rsync.samba.org/pub/rsync/ . (You can also get the most recent -branch by FTP.) - -If you choose to keep in sync using rsync, there are two approaches -to doing so: - -=over 4 - -=item rsync'ing the source tree - -Presuming you are in the directory where your perl source resides -and you have rsync installed and available, you can "upgrade" to -the bleadperl using: - - # rsync -avz rsync://public.activestate.com/perl-current/ . - -This takes care of updating every single item in the source tree to -the latest applied patch level, creating files that are new (to your -distribution) and setting date/time stamps of existing files to -reflect the bleadperl status. - -Note that this will not delete any files that were in '.' before -the rsync. Once you are sure that the rsync is running correctly, -run it with the --delete and the --dry-run options like this: - - # rsync -avz --delete --dry-run rsync://public.activestate.com/perl-current/ . - -This will I<simulate> an rsync run that also deletes files not -present in the bleadperl master copy. Observe the results from -this run closely. If you are sure that the actual run would delete -no files precious to you, you could remove the '--dry-run' option. - -You can than check what patch was the latest that was applied by -looking in the file B<.patch>, which will show the number of the -latest patch. - -If you have more than one machine to keep in sync, and not all of -them have access to the WAN (so you are not able to rsync all the -source trees to the real source), there are some ways to get around -this problem. - -=over 4 - -=item Using rsync over the LAN - -Set up a local rsync server which makes the rsynced source tree -available to the LAN and sync the other machines against this -directory. - -From http://rsync.samba.org/README.html : - - "Rsync uses rsh or ssh for communication. It does not need to be - setuid and requires no special privileges for installation. It - does not require an inetd entry or a daemon. You must, however, - have a working rsh or ssh system. Using ssh is recommended for - its security features." - -=item Using pushing over the NFS - -Having the other systems mounted over the NFS, you can take an -active pushing approach by checking the just updated tree against -the other not-yet synced trees. An example would be - - #!/usr/bin/perl -w - - use strict; - use File::Copy; - - my %MF = map { - m/(\S+)/; - $1 => [ (stat $1)[2, 7, 9] ]; # mode, size, mtime - } `cat MANIFEST`; - - my %remote = map { $_ => "/$_/pro/3gl/CPAN/perl-5.7.1" } qw(host1 host2); - - foreach my $host (keys %remote) { - unless (-d $remote{$host}) { - print STDERR "Cannot Xsync for host $host\n"; - next; - } - foreach my $file (keys %MF) { - my $rfile = "$remote{$host}/$file"; - my ($mode, $size, $mtime) = (stat $rfile)[2, 7, 9]; - defined $size or ($mode, $size, $mtime) = (0, 0, 0); - $size == $MF{$file}[1] && $mtime == $MF{$file}[2] and next; - printf "%4s %-34s %8d %9d %8d %9d\n", - $host, $file, $MF{$file}[1], $MF{$file}[2], $size, $mtime; - unlink $rfile; - copy ($file, $rfile); - utime time, $MF{$file}[2], $rfile; - chmod $MF{$file}[0], $rfile; - } - } - -though this is not perfect. It could be improved with checking -file checksums before updating. Not all NFS systems support -reliable utime support (when used over the NFS). - -=back - -=item rsync'ing the patches - -The source tree is maintained by the pumpking who applies patches to -the files in the tree. These patches are either created by the -pumpking himself using C<diff -c> after updating the file manually or -by applying patches sent in by posters on the perl5-porters list. -These patches are also saved and rsync'able, so you can apply them -yourself to the source files. - -Presuming you are in a directory where your patches reside, you can -get them in sync with - - # rsync -avz rsync://public.activestate.com/perl-current-diffs/ . - -This makes sure the latest available patch is downloaded to your -patch directory. - -It's then up to you to apply these patches, using something like - - # last="`cat ../perl-current/.patch`.gz" - # rsync -avz rsync://public.activestate.com/perl-current-diffs/ . - # find . -name '*.gz' -newer $last -exec gzcat {} \; >blead.patch - # cd ../perl-current - # patch -p1 -N <../perl-current-diffs/blead.patch - -or, since this is only a hint towards how it works, use CPAN-patchaperl -from Andreas König to have better control over the patching process. - -=back - -=head2 Why rsync the source tree - -=over 4 - -=item It's easier to rsync the source tree - -Since you don't have to apply the patches yourself, you are sure all -files in the source tree are in the right state. - -=item It's more reliable - -While both the rsync-able source and patch areas are automatically -updated every few minutes, keep in mind that applying patches may -sometimes mean careful hand-holding, especially if your version of -the C<patch> program does not understand how to deal with new files, -files with 8-bit characters, or files without trailing newlines. - -=back - -=head2 Why rsync the patches - -=over 4 - -=item It's easier to rsync the patches - -If you have more than one machine that you want to keep in track with -bleadperl, it's easier to rsync the patches only once and then apply -them to all the source trees on the different machines. - -In case you try to keep in pace on 5 different machines, for which -only one of them has access to the WAN, rsync'ing all the source -trees should than be done 5 times over the NFS. Having -rsync'ed the patches only once, I can apply them to all the source -trees automatically. Need you say more ;-) - -=item It's a good reference - -If you do not only like to have the most recent development branch, -but also like to B<fix> bugs, or extend features, you want to dive -into the sources. If you are a seasoned perl core diver, you don't -need no manuals, tips, roadmaps, perlguts.pod or other aids to find -your way around. But if you are a starter, the patches may help you -in finding where you should start and how to change the bits that -bug you. - -The file B<Changes> is updated on occasions the pumpking sees as his -own little sync points. On those occasions, he releases a tar-ball of -the current source tree (i.e. perl@7582.tar.gz), which will be an -excellent point to start with when choosing to use the 'rsync the -patches' scheme. Starting with perl@7582, which means a set of source -files on which the latest applied patch is number 7582, you apply all -succeeding patches available from then on (7583, 7584, ...). - -You can use the patches later as a kind of search archive. - -=over 4 - -=item Finding a start point - -If you want to fix/change the behaviour of function/feature Foo, just -scan the patches for patches that mention Foo either in the subject, -the comments, or the body of the fix. A good chance the patch shows -you the files that are affected by that patch which are very likely -to be the starting point of your journey into the guts of perl. - -=item Finding how to fix a bug - -If you've found I<where> the function/feature Foo misbehaves, but you -don't know how to fix it (but you do know the change you want to -make), you can, again, peruse the patches for similar changes and -look how others apply the fix. - -=item Finding the source of misbehaviour - -When you keep in sync with bleadperl, the pumpking would love to -I<see> that the community efforts really work. So after each of his -sync points, you are to 'make test' to check if everything is still -in working order. If it is, you do 'make ok', which will send an OK -report to I<perlbug@perl.org>. (If you do not have access to a mailer -from the system you just finished successfully 'make test', you can -do 'make okfile', which creates the file C<perl.ok>, which you can -than take to your favourite mailer and mail yourself). - -But of course, as always, things will not always lead to a success -path, and one or more test do not pass the 'make test'. Before -sending in a bug report (using 'make nok' or 'make nokfile'), check -the mailing list if someone else has reported the bug already and if -so, confirm it by replying to that message. If not, you might want to -trace the source of that misbehaviour B<before> sending in the bug, -which will help all the other porters in finding the solution. - -Here the saved patches come in very handy. You can check the list of -patches to see which patch changed what file and what change caused -the misbehaviour. If you note that in the bug report, it saves the -one trying to solve it, looking for that point. - -=back - -If searching the patches is too bothersome, you might consider using -perl's bugtron to find more information about discussions and -ramblings on posted bugs. - -If you want to get the best of both worlds, rsync both the source -tree for convenience, reliability and ease and rsync the patches -for reference. - -=back - -=head2 Working with the source - -Because you cannot use the Perforce client, you cannot easily generate -diffs against the repository, nor will merges occur when you update -via rsync. If you edit a file locally and then rsync against the -latest source, changes made in the remote copy will I<overwrite> your -local versions! - -The best way to deal with this is to maintain a tree of symlinks to -the rsync'd source. Then, when you want to edit a file, you remove -the symlink, copy the real file into the other tree, and edit it. You -can then diff your edited file against the original to generate a -patch, and you can safely update the original tree. - -Perl's F<Configure> script can generate this tree of symlinks for you. -The following example assumes that you have used rsync to pull a copy -of the Perl source into the F<perl-rsync> directory. In the directory -above that one, you can execute the following commands: - - mkdir perl-dev - cd perl-dev - ../perl-rsync/Configure -Dmksymlinks -Dusedevel -D"optimize=-g" - -This will start the Perl configuration process. After a few prompts, -you should see something like this: - - Symbolic links are supported. - - Checking how to test for symbolic links... - Your builtin 'test -h' may be broken. - Trying external '/usr/bin/test -h'. - You can test for symbolic links with '/usr/bin/test -h'. - - Creating the symbolic links... - (First creating the subdirectories...) - (Then creating the symlinks...) - -The specifics may vary based on your operating system, of course. -After you see this, you can abort the F<Configure> script, and you -will see that the directory you are in has a tree of symlinks to the -F<perl-rsync> directories and files. - -If you plan to do a lot of work with the Perl source, here are some -Bourne shell script functions that can make your life easier: - - function edit { - if [ -L $1 ]; then - mv $1 $1.orig - cp $1.orig $1 - vi $1 - else - vi $1 - fi - } - - function unedit { - if [ -L $1.orig ]; then - rm $1 - mv $1.orig $1 - fi - } - -Replace "vi" with your favorite flavor of editor. - -Here is another function which will quickly generate a patch for the -files which have been edited in your symlink tree: - - mkpatchorig() { - local diffopts - for f in `find . -name '*.orig' | sed s,^\./,,` - do - case `echo $f | sed 's,.orig$,,;s,.*\.,,'` in - c) diffopts=-p ;; - pod) diffopts='-F^=' ;; - *) diffopts= ;; - esac - diff -du $diffopts $f `echo $f | sed 's,.orig$,,'` - done - } - -This function produces patches which include enough context to make -your changes obvious. This makes it easier for the Perl pumpking(s) -to review them when you send them to the perl5-porters list, and that -means they're more likely to get applied. - -This function assumed a GNU diff, and may require some tweaking for -other diff variants. - =head2 Perlbug administration There is a single remote administrative interface for modifying bug status, @@ -587,20 +258,14 @@ Always submit patches to I<perl5-porters@perl.org>. If you're patching a core module and there's an author listed, send the author a copy (see L<Patching a core module>). This lets other porters review your patch, which catches a surprising number of errors in patches. -Either use the diff program (available in source code form from -ftp://ftp.gnu.org/pub/gnu/ , or use Johan Vromans' I<makepatch> -(available from I<CPAN/authors/id/JV/>). Unified diffs are preferred, -but context diffs are accepted. Do not send RCS-style diffs or diffs -without context lines. More information is given in the -I<Porting/patching.pod> file in the Perl source distribution. Please -patch against the latest B<development> version. (e.g., even if you're -fixing a bug in the 5.8 track, patch against the latest B<development> -version rsynced from rsync://public.activestate.com/perl-current/ ) +Please patch against the latest B<development> version. (e.g., even if +you're fixing a bug in the 5.8 track, patch against the C<blead> branch in +the git repository.) If changes are accepted, they are applied to the development branch. Then -the 5.8 pumpking decides which of those patches is to be backported to the -maint branch. Only patches that survive the heat of the development -branch get applied to maintenance versions. +the maintenance pumpking decides which of those patches is to be +backported to the maint branch. Only patches that survive the heat of the +development branch get applied to maintenance versions. Your patch should update the documentation and test suite. See L<Writing a test>. If you have added or removed files in the distribution, @@ -2646,6 +2311,62 @@ sizeof() of the field =item * +Assuming the character set is ASCIIish + +Perl can compile and run under EBCDIC platforms. See L<perlebcdic>. +This is transparent for the most part, but because the character sets +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.) + +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 'z'. +But '0' - '9' is an unbroken range in both systems. Don't assume anything +about other ranges. + +Many of the comments in the existing code ignore the possibility of EBCDIC, +and may be wrong therefore, even if the code works. +This is actually a tribute to the successful transparent insertion of being +able to handle EBCDIC without having to change pre-existing code. + +UTF-8 and UTF-EBCDIC are two different encodings used to represent Unicode +code points as sequences of bytes. Macros +with the same names (but different definitions) +in C<utf8.h> and C<utfebcdic.h> +are used to allow the calling code to think that there is only one such +encoding. +This is almost always referred to as C<utf8>, but it means the EBCDIC version +as well. Again, comments in the code may well be wrong even if the code itself +is right. +For example, the concept of C<invariant characters> differs between ASCII and +EBCDIC. +On ASCII platforms, only characters that do not have the high-order +bit set (i.e. whose ordinals are strict ASCII, 0 - 127) +are invariant, and the documentation and comments in the code +may assume that, +often referring to something like, say, C<hibit>. +The situation differs and is not so simple on EBCDIC machines, but as long as +the code itself uses the C<NATIVE_IS_INVARIANT()> macro appropriately, it +works, even if the comments are wrong. + +=item * + +Assuming the character set is just ASCII + +ASCII is a 7 bit encoding, but bytes have 8 bits in them. The 128 extra +characters have different meanings depending on the locale. Absent a locale, +currently these extra characters are generally considered to be unassigned, +and this has presented some problems. +This is scheduled to be changed in 5.12 so that these characters will +be considered to be Latin-1 (ISO-8859-1). + +=item * + Mixing #define and #ifdef #define BURGLE(x) ... \ @@ -2660,7 +2381,7 @@ you need two separate BURGLE() #defines, one for each #ifdef branch. =item * -Adding stuff after #endif or #else +Adding non-comment stuff after #endif or #else #ifdef SNOSH ... @@ -2836,7 +2557,7 @@ admittedly use them if available to gain some extra speed =item * -Binding together several statements +Binding together several statements in a macro Use the macros STMT_START and STMT_END. @@ -3196,6 +2917,27 @@ memory usage, so it shouldn't be used in production environments. It also converts C<new_SV()> from a macro into a real function, so you can use your favourite debugger to discover where those pesky SVs were allocated. +If you see that you're leaking memory at runtime, but neither valgrind +nor C<-DDEBUG_LEAKING_SCALARS> will find anything, you're probably +leaking SVs that are still reachable and will be properly cleaned up +during destruction of the interpreter. In such cases, using the C<-Dm> +switch can point you to the source of the leak. If the executable was +built with C<-DDEBUG_LEAKING_SCALARS>, C<-Dm> will output SV allocations +in addition to memory allocations. Each SV allocation has a distinct +serial number that will be written on creation and destruction of the SV. +So if you're executing the leaking code in a loop, you need to look for +SVs that are created, but never destroyed between each cycle. If such an +SV is found, set a conditional breakpoint within C<new_SV()> and make it +break only when C<PL_sv_serial> is equal to the serial number of the +leaking SV. Then you will catch the interpreter in exactly the state +where the leaking SV is allocated, which is sufficient in many cases to +find the source of the leak. + +As C<-Dm> is using the PerlIO layer for output, it will by itself +allocate quite a bunch of SVs, which are hidden to avoid recursion. +You can bypass the PerlIO layer if you use the SV logging provided +by C<-DPERL_MEM_LOG> instead. + =head2 PERL_MEM_LOG If compiled with C<-DPERL_MEM_LOG>, all Newx() and Renew() allocations @@ -3209,6 +2951,17 @@ This logging is somewhat similar to C<-Dm> but independent of C<-DDEBUGGING>, and at a higher level (the C<-Dm> is directly at the point of C<malloc()>, while the C<PERL_MEM_LOG> is at the level of C<New()>). +In addition to memory allocations, SV allocations will be logged, just as +with C<-Dm>. However, since the logging doesn't use PerlIO, all SV allocations +are logged and no extra SV allocations are introduced by enabling the logging. +If compiled with C<-DDEBUG_LEAKING_SCALARS>, the serial number for each SV +allocation is also logged. + +You can control the logging from your environment if you compile with +C<-DPERL_MEM_LOG_ENV>. Then you need to explicitly set C<PERL_MEM_LOG> and/or +C<PERL_SV_LOG> to a non-zero value to enable logging of memory and/or SV +allocations. + =head2 Profiling Depending on your platform there are various of profiling Perl. @@ -3552,7 +3305,66 @@ activity as well, and probably sooner than you'd think. If you can do these things, you've started on the long road to Perl porting. Thanks for wanting to help make Perl better - and happy hacking! +=head2 Metaphoric Quotations + +If you recognized the quote about the Road above, you're in luck. + +Most software projects begin each file with a literal description of each +file's purpose. Perl instead begins each with a literary allusion 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. + +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 +page numbers are given using the following editions: + +=over 4 + +=item * + +I<The Hobbit>, by J.R.R. Tolkien. The hardcover, 70th-anniversary +edition of 2007 was used, published in the UK by Harper Collins Publishers +and in the US by the Houghton Mifflin Company. + +=item * + +I<The Lord of the Rings>, by J.R.R. Tolkien. The hardcover, +50th-anniversary edition of 2004 was used, published in the UK by Harper +Collins Publishers and in the US by the Houghton Mifflin Company. + +=item * + +I<The Lays of Beleriand>, by J.R.R. Tolkien and published posthumously by his +son and literary executor, C.J.R. Tolkien, being the 3rd of the 12 volumes +in Christopher's mammoth I<History of Middle Earth>. Page numbers derive +from the hardcover edition, first published in 1983 by George Allen & +Unwin; no page numbers changed for the special 3-volume omnibus edition of +2002 or the various trade-paper editions, all again now by Harper Collins +or Houghton Mifflin. + +=back + +Other JRRT books fair game for quotes would thus include I<The Adventures of +Tom Bombadil>, I<The Silmarillion>, I<Unfinished Tales>, and I<The Tale of +the Children of Hurin>, all but the first posthumously assembled by CJRT. +But I<The Lord of the Rings> itself is perfectly fine and probably best to +quote from, provided you can find a suitable quote there. + +So if you were to supply a new, complete, top-level source file to add to +Perl, you should conform to this peculiar practice by yourself selecting an +appropriate quotation from Tolkien, retaining the original spelling and +punctuation and using the same format the rest of the quotes are in. +Indirect and oblique is just fine; remember, it's a metaphor, so being meta +is, after all, what it's for. + =head1 AUTHOR This document was written by Nathan Torkington, and is maintained by the perl5-porters mailing list. + +=head1 SEE ALSO + +L<perlrepository> diff --git a/pod/perlhist.pod b/pod/perlhist.pod index 0f89157be3..a69fa266cc 100644 --- a/pod/perlhist.pod +++ b/pod/perlhist.pod @@ -386,6 +386,9 @@ the strings?). 5.8.7 2005-May-30 5.8.8-RC1 2006-Jan-20 5.8.8 2006-Jan-31 + 5.8.9-RC1 2008-Nov-10 + 5.8.9-RC2 2008-Dec-06 + 5.8.9 2008-Dec-14 Hugo 5.9.0 2003-Oct-27 Rafael 5.9.1 2004-Mar-16 diff --git a/pod/perlintern.pod b/pod/perlintern.pod index daa62a9ceb..4107d5e63f 100644 --- a/pod/perlintern.pod +++ b/pod/perlintern.pod @@ -334,8 +334,8 @@ Found in file pad.h =over 8 -=item is_gv_magical -X<is_gv_magical> +=item is_gv_magical_sv +X<is_gv_magical_sv> Returns C<TRUE> if given the name of a magical GV. @@ -349,17 +349,7 @@ 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) + bool is_gv_magical_sv(SV *const name_sv, U32 flags) =for hackers Found in file gv.c @@ -460,11 +450,15 @@ 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). +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) +If setmagic is false then no set magic will be called on the new (empty) SV. +This typically means that assignment will soon follow (e.g. 'local $x = $y'), +and that will handle the magic. + + void mg_localize(SV* sv, SV* nsv, bool setmagic) =for hackers Found in file mg.c @@ -476,25 +470,6 @@ Found in file mg.c =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> @@ -509,7 +484,7 @@ 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) + AV* mro_get_linear_isa_dfs(HV* stash, U32 level) =for hackers Found in file mro.c @@ -950,12 +925,12 @@ The GV which was last used for a filehandle input operation. (C<< <FH> >>) =for hackers Found in file intrpvar.h -=item PL_ofs_sv -X<PL_ofs_sv> +=item PL_ofsgv +X<PL_ofsgv> -The output field separator - C<$,> in Perl space. +The glob containing the output field separator - C<*,> in Perl space. - SV* PL_ofs_sv + GV* PL_ofsgv =for hackers Found in file intrpvar.h @@ -1092,7 +1067,7 @@ 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) + SV* find_uninit_var(const OP *const obase, const SV *const uninit_sv, bool top) =for hackers Found in file sv.c @@ -1102,7 +1077,7 @@ X<report_uninit> Print appropriate "Use of uninitialized variable" warning - void report_uninit(SV* uninit_sv) + void report_uninit(const SV *uninit_sv) =for hackers Found in file sv.c diff --git a/pod/perliol.pod b/pod/perliol.pod index 136faa6b6e..a560d970cb 100644 --- a/pod/perliol.pod +++ b/pod/perliol.pod @@ -145,7 +145,7 @@ same as the public C<PerlIO_xxxxx> functions: IV (*Pushed)(pTHX_ PerlIO *f,const char *mode,SV *arg, PerlIO_funcs *tab); IV (*Popped)(pTHX_ PerlIO *f); PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, - AV *layers, IV n, + PerlIO_list_t *layers, IV n, const char *mode, int fd, int imode, int perm, PerlIO *old, @@ -486,7 +486,7 @@ C<PerlIO_fdopen> and C<PerlIO_reopen>. The full prototype is as follows: PerlIO * (*Open)(pTHX_ PerlIO_funcs *tab, - AV *layers, IV n, + PerlIO_list_t *layers, IV n, const char *mode, int fd, int imode, int perm, PerlIO *old, @@ -494,7 +494,7 @@ follows: Open should (perhaps indirectly) call C<PerlIO_allocate()> to allocate a slot in the table and associate it with the layers information for -the opened file, by calling C<PerlIO_push>. The I<layers> AV is an +the opened file, by calling C<PerlIO_push>. The I<layers> is an array of all the layers destined for the C<PerlIO *>, and any arguments passed to them, I<n> is the index into that array of the layer being called. The macro C<PerlIOArg> will return a (possibly diff --git a/pod/perlipc.pod b/pod/perlipc.pod index 3e916a07af..de6ba581e6 100644 --- a/pod/perlipc.pod +++ b/pod/perlipc.pod @@ -536,7 +536,7 @@ output doesn't wind up on the user's terminal). or die "Can't write to /dev/null: $!"; defined(my $pid = fork) or die "Can't fork: $!"; exit if $pid; - setsid or die "Can't start a new session: $!"; + die "Can't start a new session: $!" if setsid == -1; open STDERR, '>&STDOUT' or die "Can't dup stdout: $!"; } diff --git a/pod/perlmodlib.pod b/pod/perlmodlib.pod index c0a447ee77..291361655c 100644 --- a/pod/perlmodlib.pod +++ b/pod/perlmodlib.pod @@ -55,6 +55,10 @@ Get/set subroutine or variable attributes Set/get attributes of a subroutine (deprecated) +=item autodie + +Replace functions with ones that succeed or die with lexical scope + =item autouse Postpone load of modules until a function is used diff --git a/pod/perlobj.pod b/pod/perlobj.pod index b0592ffc6d..5b6adbabd4 100644 --- a/pod/perlobj.pod +++ b/pod/perlobj.pod @@ -313,6 +313,19 @@ 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. +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. + +For example, the following calls to $display are equivalent: + + my $display = sub { my $self = shift; ... }; + $fred->$display("Height", "Weight"); + $display->($fred, "Height", "Weight"); + =head2 Indirect Object Syntax X<indirect object syntax> X<invocation, indirect> X<indirect> diff --git a/pod/perlop.pod b/pod/perlop.pod index 7b0b0d2294..f52f79f5be 100644 --- a/pod/perlop.pod +++ b/pod/perlop.pod @@ -2246,6 +2246,18 @@ internally--<> is just a synonym for <ARGV>, which is magical. (The pseudo code above doesn't work because it treats <ARGV> as non-magical.) +Since the null filehandle uses the two argument form of L<perlfunc/open> +it interprets special characters, so if you have a script like this: + + while (<>) { + print; + } + +and call it with C<perl dangerous.pl 'rm -rfv *|'>, it actually opens a +pipe, executes the C<rm> command and reads C<rm>'s output from that pipe. +If you want all items in C<@ARGV> to be interpreted as file names, you +can use the module C<ARGV::readonly> from CPAN. + You can modify @ARGV before the first <> as long as the array ends up containing the list of filenames you really want. Line numbers (C<$.>) continue as though the input were one big happy file. See the example diff --git a/pod/perlopentut.pod b/pod/perlopentut.pod index 566ba0f721..b9033786b6 100644 --- a/pod/perlopentut.pod +++ b/pod/perlopentut.pod @@ -165,6 +165,33 @@ If you would like to open a bidirectional pipe, the IPC::Open2 library will handle this for you. Check out L<perlipc/"Bidirectional Communication with Another Process"> +perl-5.6.x introduced a version of piped open that executes a process +based on its command line arguments without relying on the shell. (Similar +to the C<system(@LIST)> notation.) This is safer and faster than executing +a single argument pipe-command, but does not allow special shell +constructs. (It is also not supported on Microsoft Windows, Mac OS Classic +or RISC OS.) + +Here's an example of C<open '-|'>, which prints a random Unix +fortune cookie as uppercase: + + my $collection = shift(@ARGV); + open my $fortune, '-|', 'fortune', $collection + or die "Could not find fortune - $!"; + while (<$fortune>) + { + print uc($_); + } + close($fortune); + +And this C<open '|-'> pipes into lpr: + + open my $printer, '|-', 'lpr', '-Plp1' + or die "can't run lpr: $!"; + print {$printer} "stuff\n"; + close($printer) + or die "can't close lpr: $!"; + =head2 The Minus File Again following the lead of the standard shell utilities, Perl's diff --git a/pod/perlperf.pod b/pod/perlperf.pod new file mode 100644 index 0000000000..3faf36485c --- /dev/null +++ b/pod/perlperf.pod @@ -0,0 +1,1183 @@ +=head1 NAME + +perlperf - Perl Performance and Optimization Techniques + +=head1 DESCRIPTION + +This is an introduction to the use of performance and optimization techniques +which can be used with particular reference to perl progams. While many perl +developers have come from other languages, and can use their prior knowledge +where appropriate, there are many other people who might benefit from a few +perl specific pointers. If you want the condensed version, perhaps the best +advice comes from the renowned Japanese Samurai, Miyamoto Musashi, who said: + + "Do Not Engage in Useless Activity" + +in 1645. + +=head1 OVERVIEW + +Perhaps the most common mistake programmers make is to attempt to optimize +their code before a program actually does anything useful - this is a bad idea. +There's no point in having an extremely fast program that doesn't work. The +first job is to get a program to I<correctly> do something B<useful>, (not to +mention ensuring the test suite is fully functional), and only then to consider +optimizing it. Having decided to optimize existing working code, there are +several simple but essential steps to consider which are intrinsic to any +optimization process. + +=head2 ONE STEP SIDEWAYS + +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, +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. + +=head2 ONE STEP FORWARD + +Next, having examined the program for I<hot spots>, (places where the code +seems to run slowly), change the code with the intention of making it run +faster. Using version control software, like C<subversion>, will ensure no +changes are irreversible. It's too easy to fiddle here and fiddle there - +don't change too much at any one time or you might not discover which piece of +code B<really> was the slow bit. + +=head2 ANOTHER STEP SIDEWAYS + +It's not enough to say: "that will make it run faster", you have to check it. +Rerun the code under control of the benchmarking or profiling modules, from the +first step above, and check that the new code executed the B<same task> in +I<less time>. Save your work and repeat... + +=head1 GENERAL GUIDELINES + +The critical thing when considering performance is to remember there is no such +thing as a C<Golden Bullet>, which is why there are no rules, only guidelines. + +It is clear that inline code is going to be faster than subroutine or method +calls, because there is less overhead, but this approach has the disadvantage +of being less maintainable and comes at the cost of greater memory usage - +there is no such thing as a free lunch. If you are searching for an element in +a list, it can be more efficient to store the data in a hash structure, and +then simply look to see whether the key is defined, rather than to loop through +the entire array using grep() for instance. substr() may be (a lot) faster +than grep() but not as flexible, so you have another trade-off to access. Your +code may contain a line which takes 0.01 of a second to execute which if you +call it 1,000 times, quite likely in a program parsing even medium sized files +for instance, you already have a 10 second delay, in just one single code +location, and if you call that line 100,000 times, your entire program will +slow down to an unbearable crawl. + +Using a subroutine as part of your sort is a powerful way to get exactly what +you want, but will usually be slower than the built-in I<alphabetic> C<cmp> and +I<numeric> C<E<lt>=E<gt>> sort operators. It is possible to make multiple +passes over your data, building indices to make the upcoming sort more +efficient, and to use what is known as the C<OM> (Orcish Maneuver) to cache the +sort keys in advance. The cache lookup, while a good idea, can itself be a +source of slowdown by enforcing a double pass over the data - once to setup the +cache, and once to sort the data. Using C<pack()> to extract the required sort +key into a consistent string can be an efficient way to build a single string +to compare, instead of using multiple sort keys, which makes it possible to use +the standard, written in C<c> and fast, perl C<sort()> function on the output, +and is the basis of the C<GRT> (Guttman Rossler Transform). Some string +combinations can slow the C<GRT> down, by just being too plain complex for it's +own good. + +For applications using database backends, the standard C<DBIx> namespace has +tries to help with keeping things nippy, not least because it tries to I<not> +query the database until the latest possible moment, but always read the docs +which come with your choice of libraries. Among the many issues facing +developers dealing with databases should remain aware of is to always use +C<SQL> placeholders and to consider pre-fetching data sets when this might +prove advantageous. Splitting up a large file by assigning multiple processes +to parsing a single file, using say C<POE>, C<threads> or C<fork> can also be a +useful way of optimizing your usage of the available C<CPU> resources, though +this technique is fraught with concurrency issues and demands high attention to +detail. + +Every case has a specific application and one or more exceptions, and there is +no replacement for running a few tests and finding out which method works best +for your particular environment, this is why writing optimal code is not an +exact science, and why we love using Perl so much - TMTOWTDI. + +=head1 BENCHMARKS + +Here are a few examples to demonstrate usage of Perl's benchmarking tools. + +=head2 Assigning and Dereferencing Variables. + +I'm sure most of us have seen code which looks like, (or worse than), this: + + if ( $obj->{_ref}->{_myscore} >= $obj->{_ref}->{_yourscore} ) { + ... + +This sort of code can be a real eyesore to read, as well as being very +sensitive to typos, and it's much clearer to dereference the variable +explicitly. We're side-stepping the issue of working with object-oriented +programming techniques to encapsulate variable access via methods, only +accessible through an object. Here we're just discussing the technical +implementation of choice, and whether this has an effect on performance. We +can see whether this dereferencing operation, has any overhead by putting +comparative code in a file and running a C<Benchmark> test. + +# dereference + + #!/usr/bin/perl + + use strict; + use warnings; + + use Benchmark; + + my $ref = { + 'ref' => { + _myscore => '100 + 1', + _yourscore => '102 - 1', + }, + }; + + timethese(1000000, { + 'direct' => sub { + my $x = $ref->{ref}->{_myscore} . $ref->{ref}->{_yourscore} ; + }, + 'dereference' => sub { + my $ref = $ref->{ref}; + my $myscore = $ref->{_myscore}; + my $yourscore = $ref->{_yourscore}; + my $x = $myscore . $yourscore; + }, + }); + +It's essential to run any timing measurements a sufficient number of times so +the numbers settle on a numerical average, otherwise each run will naturally +fluctuate due to variations in the environment, to reduce the effect of +contention for C<CPU> resources and network bandwidth for instance. Running +the above code for one million iterations, we can take a look at the report +output by the C<Benchmark> module, to see which approach is the most effective. + + $> perl dereference + + Benchmark: timing 1000000 iterations of dereference, direct... + dereference: 2 wallclock secs ( 1.59 usr + 0.00 sys = 1.59 CPU) @ 628930.82/s (n=1000000) + direct: 1 wallclock secs ( 1.20 usr + 0.00 sys = 1.20 CPU) @ 833333.33/s (n=1000000) + +The difference is clear to see and the dereferencing approach is slower. While +it managed to execute an average of 628,930 times a second during our test, the +direct approach managed to run an additional 204,403 times, unfortunately. +Unfortunately, because there are many examples of code written using the +multiple layer direct variable access, and it's usually horrible. It is, +however, miniscully faster. The question remains whether the minute gain is +actually worth the eyestrain, or the loss of maintainability. + +=head2 Search and replace or tr + +If we have a string which needs to be modified, while a regex will almost +always be much more flexible, C<tr>, an oft underused tool, can still be a +useful. One scenario might be replace all vowels with another character. The +regex solution might look like this: + + $str =~ s/[aeiou]/x/g + +The C<tr> alternative might look like this: + + $str =~ tr/aeiou/xxxxx/ + +We can put that into a test file which we can run to check which approach is +the fastest, using a global C<$STR> variable to assign to the C<my $str> +variable so as to avoid perl trying to optimize any of the work away by +noticing it's assigned only the once. + +# regex-transliterate + + #!/usr/bin/perl + + use strict; + use warnings; + + use Benchmark; + + my $STR = "$$-this and that"; + + timethese( 1000000, { + 'sr' => sub { my $str = $STR; $str =~ s/[aeiou]/x/g; return $str; }, + 'tr' => sub { my $str = $STR; $str =~ tr/aeiou/xxxxx/; return $str; }, + }); + +Running the code gives us our results: + + $> perl regex-transliterate + + Benchmark: timing 1000000 iterations of sr, tr... + sr: 2 wallclock secs ( 1.19 usr + 0.00 sys = 1.19 CPU) @ 840336.13/s (n=1000000) + tr: 0 wallclock secs ( 0.49 usr + 0.00 sys = 0.49 CPU) @ 2040816.33/s (n=1000000) + +The C<tr> version is a clear winner. One solution is flexible, the other is +fast - and it's appropriately the programmers choice which to use in the +circumstances. + +Check the C<Benchmark> docs for further useful techniques. + +=head1 PROFILING TOOLS + +A slightly larger piece of code will provide something on which a profiler can +produce more extensive reporting statistics. This example uses the simplistic +C<wordmatch> program which parses a given input file and spews out a short +report on the contents. + +# wordmatch + + #!/usr/bin/perl + + use strict; + use warnings; + + =head1 NAME + + filewords - word analysis of input file + + =head1 SYNOPSIS + + filewords -f inputfilename [-d] + + =head1 DESCRIPTION + + This program parses the given filename, specified with C<-f>, and displays a + simple analysis of the words found therein. Use the C<-d> switch to enable + debugging messages. + + =cut + + use FileHandle; + use Getopt::Long; + + my $debug = 0; + my $file = ''; + + my $result = GetOptions ( + 'debug' => \$debug, + 'file=s' => \$file, + ); + die("invalid args") unless $result; + + unless ( -f $file ) { + die("Usage: $0 -f filename [-d]"); + } + my $FH = FileHandle->new("< $file") or die("unable to open file($file): $!"); + + my $i_LINES = 0; + my $i_WORDS = 0; + my %count = (); + + my @lines = <$FH>; + foreach my $line ( @lines ) { + $i_LINES++; + $line =~ s/\n//; + my @words = split(/ +/, $line); + my $i_words = scalar(@words); + $i_WORDS = $i_WORDS + $i_words; + debug("line: $i_LINES supplying $i_words words: @words"); + my $i_word = 0; + foreach my $word ( @words ) { + $i_word++; + $count{$i_LINES}{spec} += matches($i_word, $word, '[^a-zA-Z0-9]'); + $count{$i_LINES}{only} += matches($i_word, $word, '^[^a-zA-Z0-9]+$'); + $count{$i_LINES}{cons} += matches($i_word, $word, '^[(?i:bcdfghjklmnpqrstvwxyz)]+$'); + $count{$i_LINES}{vows} += matches($i_word, $word, '^[(?i:aeiou)]+$'); + $count{$i_LINES}{caps} += matches($i_word, $word, '^[(A-Z)]+$'); + } + } + + print report( %count ); + + sub matches { + my $i_wd = shift; + my $word = shift; + my $regex = shift; + my $has = 0; + + if ( $word =~ /($regex)/ ) { + $has++ if $1; + } + + debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/"); + + return $has; + } + + sub report { + my %report = @_; + my %rep; + + foreach my $line ( keys %report ) { + foreach my $key ( keys %{ $report{$line} } ) { + $rep{$key} += $report{$line}{$key}; + } + } + + my $report = qq| + $0 report for $file: + lines in file: $i_LINES + words in file: $i_WORDS + words with special (non-word) characters: $i_spec + words with only special (non-word) characters: $i_only + words with only consonants: $i_cons + words with only capital letters: $i_caps + words with only vowels: $i_vows + |; + + return $report; + } + + sub debug { + my $message = shift; + + if ( $debug ) { + print STDERR "DBG: $message\n"; + } + } + + exit 0; + +=head2 Devel::DProf + +This venerable module has been the de-facto standard for Perl code profiling +for more than a decade, but has been replaced by a number of other modules +which have brought us back to the 21st century. Although you're recommended to +evaluate your tool from the several mentioned here and from the CPAN list at +the base of this document, (and currently L<Devel::NYTProf> seems to be the +weapon of choice - see below), we'll take a quick look at the output from +L<Devel::DProf> first, to set a baseline for Perl profiling tools. Run the +above program under the control of C<Devel::DProf> by using the C<-d> switch on +the command-line. + + $> perl -d:DProf wordmatch -f perl5db.pl + + <...multiple lines snipped...> + + wordmatch report for perl5db.pl: + lines in file: 9428 + words in file: 50243 + words with special (non-word) characters: 20480 + words with only special (non-word) characters: 7790 + words with only consonants: 4801 + words with only capital letters: 1316 + words with only vowels: 1701 + +C<Devel::DProf> produces a special file, called F<tmon.out> by default, and +this file is read by the C<dprofpp> program, which is already installed as part +of the C<Devel::DProf> distribution. If you call C<dprofpp> with no options, +it will read the F<tmon.out> file in the current directory and produce a human +readable statistics report of the run of your program. Note that this may take +a little time. + + $> dprofpp + + Total Elapsed Time = 2.951677 Seconds + User+System Time = 2.871677 Seconds + Exclusive Times + %Time ExclSec CumulS #Calls sec/call Csec/c Name + 102. 2.945 3.003 251215 0.0000 0.0000 main::matches + 2.40 0.069 0.069 260643 0.0000 0.0000 main::debug + 1.74 0.050 0.050 1 0.0500 0.0500 main::report + 1.04 0.030 0.049 4 0.0075 0.0123 main::BEGIN + 0.35 0.010 0.010 3 0.0033 0.0033 Exporter::as_heavy + 0.35 0.010 0.010 7 0.0014 0.0014 IO::File::BEGIN + 0.00 - -0.000 1 - - Getopt::Long::FindOption + 0.00 - -0.000 1 - - Symbol::BEGIN + 0.00 - -0.000 1 - - Fcntl::BEGIN + 0.00 - -0.000 1 - - Fcntl::bootstrap + 0.00 - -0.000 1 - - warnings::BEGIN + 0.00 - -0.000 1 - - IO::bootstrap + 0.00 - -0.000 1 - - Getopt::Long::ConfigDefaults + 0.00 - -0.000 1 - - Getopt::Long::Configure + 0.00 - -0.000 1 - - Symbol::gensym + +C<dprofpp> will produce some quite detailed reporting on the activity of the +C<wordmatch> program. The wallclock, user and system, times are at the top of +the analysis, and after this are the main columns defining which define the +report. Check the C<dprofpp> docs for details of the many options it supports. + +See also C<Apache::DProf> which hooks C<Devel::DProf> into C<mod_perl>. + +=head2 Devel::Profiler + +Let's take a look at the same program using a different profiler: +C<Devel::Profiler>, a drop-in Perl-only replacement for C<Devel::DProf>. The +usage is very slightly different in that instead of using the special C<-d:> +flag, you pull C<Devel::Profiler> in directly as a module using C<-M>. + + $> perl -MDevel::Profiler wordmatch -f perl5db.pl + + <...multiple lines snipped...> + + wordmatch report for perl5db.pl: + lines in file: 9428 + words in file: 50243 + words with special (non-word) characters: 20480 + words with only special (non-word) characters: 7790 + words with only consonants: 4801 + words with only capital letters: 1316 + words with only vowels: 1701 + + +C<Devel::Profiler> generates a tmon.out file which is compatible with the +C<dprofpp> program, thus saving the construction of a dedicated statistics +reader program. C<dprofpp> usage is therefore identical to the above example. + + $> dprofpp + + Total Elapsed Time = 20.984 Seconds + User+System Time = 19.981 Seconds + Exclusive Times + %Time ExclSec CumulS #Calls sec/call Csec/c Name + 49.0 9.792 14.509 251215 0.0000 0.0001 main::matches + 24.4 4.887 4.887 260643 0.0000 0.0000 main::debug + 0.25 0.049 0.049 1 0.0490 0.0490 main::report + 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::GetOptions + 0.00 0.000 0.000 2 0.0000 0.0000 Getopt::Long::ParseOptionSpec + 0.00 0.000 0.000 1 0.0000 0.0000 Getopt::Long::FindOption + 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::new + 0.00 0.000 0.000 1 0.0000 0.0000 IO::Handle::new + 0.00 0.000 0.000 1 0.0000 0.0000 Symbol::gensym + 0.00 0.000 0.000 1 0.0000 0.0000 IO::File::open + +Interestingly we get slightly different results, which is mostly because the +algorithm which generates the report is different, even though the output file +format was allegedly identical. The elapsed, user and system times are clearly +showing the time it took for C<Devel::Profiler> to execute it's own run, but +the column listings feel more accurate somehow than the ones we had earlier +from C<Devel::DProf>. The 102% figure has disappeared, for example. This is +where we have to use the tools at our disposal, and recognise their pros and +cons, before using them. Interestingly, the numbers of calls for each +subroutine are identical in the two reports, it's the percentages which differ. +As the author of C<Devel::Proviler> writes: + + ...running HTML::Template's test suite under Devel::DProf shows output() + taking NO time but Devel::Profiler shows around 10% of the time is in output(). + I don't know which to trust but my gut tells me something is wrong with + Devel::DProf. HTML::Template::output() is a big routine that's called for + every test. Either way, something needs fixing. + +YMMV. + +See also C<Devel::Apache::Profiler> which hooks C<Devel::Profiler> into C<mod_perl>. + +=head2 Devel::SmallProf + +The C<Devel::SmallProf> profiler examines the runtime of your Perl program and +produces a line-by-line listing to show how many times each line was called, +and how long each line took to execute. It is called by supplying the familiar +C<-d> flag to Perl at runtime. + + $> perl -d:SmallProf wordmatch -f perl5db.pl + + <...multiple lines snipped...> + + wordmatch report for perl5db.pl: + lines in file: 9428 + words in file: 50243 + words with special (non-word) characters: 20480 + words with only special (non-word) characters: 7790 + words with only consonants: 4801 + words with only capital letters: 1316 + words with only vowels: 1701 + +C<Devel::SmallProf> writes it's output into a file called F<smallprof.out>, by +default. The format of the file looks like this: + + <num> <time> <ctime> <line>:<text> + +When the program has terminated, the output may be examined and sorted using +any standard text filtering utilities. Something like the following may be +sufficient: + + $> cat smallprof.out | grep \d*: | sort -k3 | tac | head -n20 + + 251215 1.65674 7.68000 75: if ( $word =~ /($regex)/ ) { + 251215 0.03264 4.40000 79: debug("word: $i_wd ".($has ? 'matches' : + 251215 0.02693 4.10000 81: return $has; + 260643 0.02841 4.07000 128: if ( $debug ) { + 260643 0.02601 4.04000 126: my $message = shift; + 251215 0.02641 3.91000 73: my $has = 0; + 251215 0.03311 3.71000 70: my $i_wd = shift; + 251215 0.02699 3.69000 72: my $regex = shift; + 251215 0.02766 3.68000 71: my $word = shift; + 50243 0.59726 1.00000 59: $count{$i_LINES}{cons} = + 50243 0.48175 0.92000 61: $count{$i_LINES}{spec} = + 50243 0.00644 0.89000 56: my $i_cons = matches($i_word, $word, + 50243 0.48837 0.88000 63: $count{$i_LINES}{caps} = + 50243 0.00516 0.88000 58: my $i_caps = matches($i_word, $word, '^[(A- + 50243 0.00631 0.81000 54: my $i_spec = matches($i_word, $word, '[^a- + 50243 0.00496 0.80000 57: my $i_vows = matches($i_word, $word, + 50243 0.00688 0.80000 53: $i_word++; + 50243 0.48469 0.79000 62: $count{$i_LINES}{only} = + 50243 0.48928 0.77000 60: $count{$i_LINES}{vows} = + 50243 0.00683 0.75000 55: my $i_only = matches($i_word, $word, '^[^a- + +You can immediately see a slightly different focus to the subroutine profiling +modules, and we start to see exactly which line of code is taking the most +time. That regex line is looking a bit suspicious, for example. Remember that +these tools are supposed to be used together, there is no single best way to +profile your code, you need to use the best tools for the job. + +See also C<Apache::SmallProf> which hooks C<Devel::SmallProf> into C<mod_perl>. + +=head2 Devel::FastProf + +C<Devel::FastProf> is another Perl line profiler. This was written with a view +to getting a faster line profiler, than is possible with for example +C<Devel::SmallProf>, because it's written in C<C>. To use C<Devel::FastProf>, +supply the C<-d> argument to Perl: + + $> perl -d:FastProf wordmatch -f perl5db.pl + + <...multiple lines snipped...> + + wordmatch report for perl5db.pl: + lines in file: 9428 + words in file: 50243 + words with special (non-word) characters: 20480 + words with only special (non-word) characters: 7790 + words with only consonants: 4801 + words with only capital letters: 1316 + words with only vowels: 1701 + +C<Devel::FastProf> writes statistics to the file F<fastprof.out> in the current +directory. The output file, which can be specified, can be interpreted by using +the C<fprofpp> command-line program. + + $> fprofpp | head -n20 + + # fprofpp output format is: + # filename:line time count: source + wordmatch:75 3.93338 251215: if ( $word =~ /($regex)/ ) { + wordmatch:79 1.77774 251215: debug("word: $i_wd ".($has ? 'matches' : 'does not match')." chars: /$regex/"); + wordmatch:81 1.47604 251215: return $has; + wordmatch:126 1.43441 260643: my $message = shift; + wordmatch:128 1.42156 260643: if ( $debug ) { + wordmatch:70 1.36824 251215: my $i_wd = shift; + wordmatch:71 1.36739 251215: my $word = shift; + wordmatch:72 1.35939 251215: my $regex = shift; + +Straightaway we can see that the number of times each line has been called is +identical to the C<Devel::SmallProf> output, and the sequence is only very +slightly different based on the ordering of the amount of time each line took +to execute, C<if ( $debug ) { > and C<my $message = shift;>, for example. The +differences in the actual times recorded might be in the algorithm used +internally, or it could be due to system resource limitations or contention. + +See also the L<DBIx::Profiler> which will profile database queries running +under the C<DBIx::*> namespace. + +=head2 Devel::NYTProf + +C<Devel::NYTProf> is the B<next generation> of Perl code profiler, fixing many +shortcomings in other tools and implementing many cool features. First of all it +can be used as either a I<line> profiler, a I<block> or a I<subroutine> +profiler, all at once. It can also use sub-microsecond (100ns) resolution on +systems which provide C<clock_gettime()>. It can be started and stopped even +by the program being profiled. It's a one-line entry to profile C<mod_perl> +applications. It's written in C<c> and is probably the fastest profiler +available for Perl. The list of coolness just goes on. Enough of that, let's +see how to it works - just use the familiar C<-d> switch to plug it in and run +the code. + + $> perl -d:NYTProf wordmatch -f perl5db.pl + + wordmatch report for perl5db.pl: + lines in file: 9427 + words in file: 50243 + words with special (non-word) characters: 20480 + words with only special (non-word) characters: 7790 + words with only consonants: 4801 + words with only capital letters: 1316 + words with only vowels: 1701 + +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 +F<nytprof/index.html> file for convenience here. + + $> html2text nytprof/index.html + + Performance Profile Index + For wordmatch + Run on Fri Sep 26 13:46:39 2008 + Reported on Fri Sep 26 13:47:23 2008 + + Top 15 Subroutines -- ordered by exclusive time + |Calls |P |F |Inclusive|Exclusive|Subroutine | + | | | |Time |Time | | + |251215|5 |1 |13.09263 |10.47692 |main:: |matches | + |260642|2 |1 |2.71199 |2.71199 |main:: |debug | + |1 |1 |1 |0.21404 |0.21404 |main:: |report | + |2 |2 |2 |0.00511 |0.00511 |XSLoader:: |load (xsub) | + |14 |14|7 |0.00304 |0.00298 |Exporter:: |import | + |3 |1 |1 |0.00265 |0.00254 |Exporter:: |as_heavy | + |10 |10|4 |0.00140 |0.00140 |vars:: |import | + |13 |13|1 |0.00129 |0.00109 |constant:: |import | + |1 |1 |1 |0.00360 |0.00096 |FileHandle:: |import | + |3 |3 |3 |0.00086 |0.00074 |warnings::register::|import | + |9 |3 |1 |0.00036 |0.00036 |strict:: |bits | + |13 |13|13|0.00032 |0.00029 |strict:: |import | + |2 |2 |2 |0.00020 |0.00020 |warnings:: |import | + |2 |1 |1 |0.00020 |0.00020 |Getopt::Long:: |ParseOptionSpec| + |7 |7 |6 |0.00043 |0.00020 |strict:: |unimport | + + For more information see the full list of 189 subroutines. + +The first part of the report already shows the critical information regarding +which subroutines are using the most time. The next gives some statistics +about the source files profiled. + + Source Code Files -- ordered by exclusive time then name + |Stmts |Exclusive|Avg. |Reports |Source File | + | |Time | | | | + |2699761|15.66654 |6e-06 |line . block . sub|wordmatch | + |35 |0.02187 |0.00062|line . block . sub|IO/Handle.pm | + |274 |0.01525 |0.00006|line . block . sub|Getopt/Long.pm | + |20 |0.00585 |0.00029|line . block . sub|Fcntl.pm | + |128 |0.00340 |0.00003|line . block . sub|Exporter/Heavy.pm | + |42 |0.00332 |0.00008|line . block . sub|IO/File.pm | + |261 |0.00308 |0.00001|line . block . sub|Exporter.pm | + |323 |0.00248 |8e-06 |line . block . sub|constant.pm | + |12 |0.00246 |0.00021|line . block . sub|File/Spec/Unix.pm | + |191 |0.00240 |0.00001|line . block . sub|vars.pm | + |77 |0.00201 |0.00003|line . block . sub|FileHandle.pm | + |12 |0.00198 |0.00016|line . block . sub|Carp.pm | + |14 |0.00175 |0.00013|line . block . sub|Symbol.pm | + |15 |0.00130 |0.00009|line . block . sub|IO.pm | + |22 |0.00120 |0.00005|line . block . sub|IO/Seekable.pm | + |198 |0.00085 |4e-06 |line . block . sub|warnings/register.pm| + |114 |0.00080 |7e-06 |line . block . sub|strict.pm | + |47 |0.00068 |0.00001|line . block . sub|warnings.pm | + |27 |0.00054 |0.00002|line . block . sub|overload.pm | + |9 |0.00047 |0.00005|line . block . sub|SelectSaver.pm | + |13 |0.00045 |0.00003|line . block . sub|File/Spec.pm | + |2701595|15.73869 | |Total | + |128647 |0.74946 | |Average | + | |0.00201 |0.00003|Median | + | |0.00121 |0.00003|Deviation | + + Report produced by the NYTProf 2.03 Perl profiler, developed by Tim Bunce and + Adam Kaplan. + +At this point, if you're using the I<html> report, you can click through the +various links to bore down into each subroutine and each line of code. Because +we're using the text reporting here, and there's a whole directory full of +reports built for each source file, we'll just display a part of the +corresponding F<wordmatch-line.html> file, sufficient to give an idea of the +sort of output you can expect from this cool tool. + + $> html2text nytprof/wordmatch-line.html + + Performance Profile -- -block view-.-line view-.-sub view- + For wordmatch + Run on Fri Sep 26 13:46:39 2008 + Reported on Fri Sep 26 13:47:22 2008 + + File wordmatch + + Subroutines -- ordered by exclusive time + |Calls |P|F|Inclusive|Exclusive|Subroutine | + | | | |Time |Time | | + |251215|5|1|13.09263 |10.47692 |main::|matches| + |260642|2|1|2.71199 |2.71199 |main::|debug | + |1 |1|1|0.21404 |0.21404 |main::|report | + |0 |0|0|0 |0 |main::|BEGIN | + + + |Line|Stmts.|Exclusive|Avg. |Code | + | | |Time | | | + |1 | | | |#!/usr/bin/perl | + |2 | | | | | + | | | | |use strict; | + |3 |3 |0.00086 |0.00029|# spent 0.00003s making 1 calls to strict:: | + | | | | |import | + | | | | |use warnings; | + |4 |3 |0.01563 |0.00521|# spent 0.00012s making 1 calls to warnings:: | + | | | | |import | + |5 | | | | | + |6 | | | |=head1 NAME | + |7 | | | | | + |8 | | | |filewords - word analysis of input file | + <...snip...> + |62 |1 |0.00445 |0.00445|print report( %count ); | + | | | | |# spent 0.21404s making 1 calls to main::report| + |63 | | | | | + | | | | |# spent 23.56955s (10.47692+2.61571) within | + | | | | |main::matches which was called 251215 times, | + | | | | |avg 0.00005s/call: # 50243 times | + | | | | |(2.12134+0.51939s) at line 57 of wordmatch, avg| + | | | | |0.00005s/call # 50243 times (2.17735+0.54550s) | + |64 | | | |at line 56 of wordmatch, avg 0.00005s/call # | + | | | | |50243 times (2.10992+0.51797s) at line 58 of | + | | | | |wordmatch, avg 0.00005s/call # 50243 times | + | | | | |(2.12696+0.51598s) at line 55 of wordmatch, avg| + | | | | |0.00005s/call # 50243 times (1.94134+0.51687s) | + | | | | |at line 54 of wordmatch, avg 0.00005s/call | + | | | | |sub matches { | + <...snip...> + |102 | | | | | + | | | | |# spent 2.71199s within main::debug which was | + | | | | |called 260642 times, avg 0.00001s/call: # | + | | | | |251215 times (2.61571+0s) by main::matches at | + |103 | | | |line 74 of wordmatch, avg 0.00001s/call # 9427 | + | | | | |times (0.09628+0s) at line 50 of wordmatch, avg| + | | | | |0.00001s/call | + | | | | |sub debug { | + |104 |260642|0.58496 |2e-06 |my $message = shift; | + |105 | | | | | + |106 |260642|1.09917 |4e-06 |if ( $debug ) { | + |107 | | | |print STDERR "DBG: $message\n"; | + |108 | | | |} | + |109 | | | |} | + |110 | | | | | + |111 |1 |0.01501 |0.01501|exit 0; | + |112 | | | | | + +Oodles of very useful information in there - this seems to be the way forward. + +See also C<Devel::NYTProf::Apache> which hooks C<Devel::NYTProf> into C<mod_perl>. + +=head1 SORTING + +Perl modules are not the only tools a performance analyst has at their +disposal, system tools like C<time> should not be overlooked as the next +example shows, where we take a quick look at sorting. Many books, theses and +articles, have been written about efficient sorting algorithms, and this is not +the place to repeat such work, there's several good sorting modules which +deserve taking a look at too: C<Sort::Maker>, C<Sort::Key> spring to mind. +However, it's still possible to make some observations on certain Perl specific +interpretations on issues relating to sorting data sets and give an example or +two with regard to how sorting large data volumes can effect performance. +Firstly, an often overlooked point when sorting large amounts of data, one can +attempt to reduce the data set to be dealt with and in many cases C<grep()> can +be quite useful as a simple filter: + + @data = sort grep { /$filter/ } @incoming + +A command such as this can vastly reduce the volume of material to actually +sort through in the first place, and should not be too lightly disregarded +purely on the basis of it's simplicity. The C<KISS> principle is too often +overlooked - the next example uses the simple system C<time> utility to +demonstrate. Let's take a look at an actual example of sorting the contents of +a large file, an apache logfile would do. This one has over a quarter of a +million lines, is 50M in size, and a snippet of it looks like this: + +# logfile + + 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + 188.209-65-87.adsl-dyn.isp.belgacom.be - - [08/Feb/2007:12:57:16 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + 151.56.71.198 - - [08/Feb/2007:12:57:41 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1" + 151.56.71.198 - - [08/Feb/2007:12:57:42 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1" + 151.56.71.198 - - [08/Feb/2007:12:57:43 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.2; en-US; rv:1.8.1.1) Gecko/20061204 Firefox/2.0.0.1" + 217.113.68.60 - - [08/Feb/2007:13:02:15 +0000] "GET / HTTP/1.1" 304 - "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + 217.113.68.60 - - [08/Feb/2007:13:02:16 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)" + debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)" + debora.to.isac.cnr.it - - [08/Feb/2007:13:03:58 +0000] "GET /favicon.ico HTTP/1.1" 404 209 "-" "Mozilla/5.0 (compatible; Konqueror/3.4; Linux) KHTML/3.4.0 (like Gecko)" + 195.24.196.99 - - [08/Feb/2007:13:26:48 +0000] "GET / HTTP/1.0" 200 3309 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9" + 195.24.196.99 - - [08/Feb/2007:13:26:58 +0000] "GET /data/css HTTP/1.0" 404 206 "http://www.rfi.net/" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9" + 195.24.196.99 - - [08/Feb/2007:13:26:59 +0000] "GET /favicon.ico HTTP/1.0" 404 209 "-" "Mozilla/5.0 (Windows; U; Windows NT 5.1; fr; rv:1.8.0.9) Gecko/20061206 Firefox/1.5.0.9" + crawl1.cosmixcorp.com - - [08/Feb/2007:13:27:57 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "voyager/1.0" + crawl1.cosmixcorp.com - - [08/Feb/2007:13:28:25 +0000] "GET /links.html HTTP/1.0" 200 3413 "-" "voyager/1.0" + fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:32 +0000] "GET /suse-on-vaio.html HTTP/1.1" 200 2858 "http://www.linux-on-laptops.com/sony.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + fhm226.internetdsl.tpnet.pl - - [08/Feb/2007:13:37:34 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net/suse-on-vaio.html" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; SV1)" + 80.247.140.134 - - [08/Feb/2007:13:57:35 +0000] "GET / HTTP/1.1" 200 3309 "-" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)" + 80.247.140.134 - - [08/Feb/2007:13:57:37 +0000] "GET /data/css HTTP/1.1" 404 206 "http://www.rfi.net" "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 5.1; .NET CLR 1.1.4322)" + pop.compuscan.co.za - - [08/Feb/2007:14:10:43 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net" + livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /robots.txt HTTP/1.0" 200 179 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)" + livebot-207-46-98-57.search.live.com - - [08/Feb/2007:14:12:04 +0000] "GET /html/oracle.html HTTP/1.0" 404 214 "-" "msnbot/1.0 (+http://search.msn.com/msnbot.htm)" + dslb-088-064-005-154.pools.arcor-ip.net - - [08/Feb/2007:14:12:15 +0000] "GET / HTTP/1.1" 200 3309 "-" "www.clamav.net" + 196.201.92.41 - - [08/Feb/2007:14:15:01 +0000] "GET / HTTP/1.1" 200 3309 "-" "MOT-L7/08.B7.DCR MIB/2.2.1 Profile/MIDP-2.0 Configuration/CLDC-1.1" + +The specific task here is to sort the 286,525 lines of this file by Response +Code, Query, Browser, Referring Url, and lastly Date. One solution might be to +use the following code, which iterates over the files given on the +command-line. + +# sort-apache-log + + #!/usr/bin/perl -n + + use strict; + use warnings; + + my @data; + + LINE: + while ( <> ) { + my $line = $_; + if ( + $line =~ m/^( + ([\w\.\-]+) # client + \s*-\s*-\s*\[ + ([^]]+) # date + \]\s*"\w+\s* + (\S+) # query + [^"]+"\s* + (\d+) # status + \s+\S+\s+"[^"]*"\s+" + ([^"]*) # browser + " + .* + )$/x + ) { + my @chunks = split(/ +/, $line); + my $ip = $1; + my $date = $2; + my $query = $3; + my $status = $4; + my $browser = $5; + + push(@data, [$ip, $date, $query, $status, $browser, $line]); + } + } + + my @sorted = sort { + $a->[3] cmp $b->[3] + || + $a->[2] cmp $b->[2] + || + $a->[0] cmp $b->[0] + || + $a->[1] cmp $b->[1] + || + $a->[4] cmp $b->[4] + } @data; + + foreach my $data ( @sorted ) { + print $data->[5]; + } + + exit 0; + +When running this program, redirect C<STDOUT> so it is possible to check the +output is correct from following test runs and use the system C<time> utility +to check the overall runtime. + + $> time ./sort-apache-log logfile > out-sort + + real 0m17.371s + user 0m15.757s + sys 0m0.592s + +The program took just over 17 wallclock seconds to run. Note the different +values C<time> outputs, it's important to always use the same one, and to not +confuse what each one means. + +=over 4 + +=item Elapsed Real Time + +The overall, or wallclock, time between when C<time> was called, and when it +terminates. The elapsed time includes both user and system times, and time +spent waiting for other users and processes on the system. Inevitably, this is +the most approximate of the measurements given. + +=item User CPU Time + +The user time is the amount of time the entire process spent on behalf of the +user on this system executing this program. + +=item System CPU Time + +The system time is the amount of time the kernel itself spent executing +routines, or system calls, on behalf of this process user. + +=back + +Running this same process as a C<Schwarzian Transform> it is possible to +eliminate the input and output arrays for storing all the data, and work on the +input directly as it arrives too. Otherwise, the code looks fairly similar: + +# sort-apache-log-schwarzian + + #!/usr/bin/perl -n + + use strict; + use warnings; + + print + + map $_->[0] => + + sort { + $a->[4] cmp $b->[4] + || + $a->[3] cmp $b->[3] + || + $a->[1] cmp $b->[1] + || + $a->[2] cmp $b->[2] + || + $a->[5] cmp $b->[5] + } + map [ $_, m/^( + ([\w\.\-]+) # client + \s*-\s*-\s*\[ + ([^]]+) # date + \]\s*"\w+\s* + (\S+) # query + [^"]+"\s* + (\d+) # status + \s+\S+\s+"[^"]*"\s+" + ([^"]*) # browser + " + .* + )$/xo ] + + => <>; + + exit 0; + +Run the new code against the same logfile, as above, to check the new time. + + $> time ./sort-apache-log-schwarzian logfile > out-schwarz + + real 0m9.664s + user 0m8.873s + sys 0m0.704s + +The time has been cut in half, which is a respectable speed improvement by any +standard. Naturally, it is important to check the output is consistent with +the first program run, this is where the unix system C<cksum> utility comes in. + + $> cksum out-sort out-schwarz + 3044173777 52029194 out-sort + 3044173777 52029194 out-schwarz + +BTW. Beware too of pressure from managers who see you speed a program up by 50% +of the runtime once, only to get a request one month later to do the same again +(true story) - you'll just have to point out your only human, even if you are a +Perl programmer, and you'll see what you can do... + +=head1 LOGGING + +An essential part of any good development process is appropriate error handling +with appropriately informative messages, however there exists a school of +thought which suggests that log files should be I<chatty>, as if the chain of +unbroken output somehow ensures the survival of the program. If speed is in +any way an issue, this approach is wrong. + +A common sight is code which looks something like this: + + logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) ) + +The problem is that this code will always be parsed and executed, even when the +debug level set in the logging configuration file is zero. Once the debug() +subroutine has been entered, and the internal C<$debug> variable confirmed to +be zero, for example, the message which has been sent in will be discarded and +the program will continue. In the example given though, the \%INC hash will +already have been dumped, and the message string constructed, all of which work +could be bypassed by a debug variable at the statement level, like this: + + logger->debug( "A logging message via process-id: $$ INC: " . Dumper(\%INC) ) if $DEBUG; + +This effect can be demonstrated by setting up a test script with both forms, +including a C<debug()> subroutine to emulate typical C<logger()> functionality. + +# ifdebug + + #!/usr/bin/perl + + use strict; + use warnings; + + use Benchmark; + use Data::Dumper; + my $DEBUG = 0; + + sub debug { + my $msg = shift; + + if ( $DEBUG ) { + print "DEBUG: $msg\n"; + } + }; + + timethese(100000, { + 'debug' => sub { + debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) + }, + 'ifdebug' => sub { + debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if $DEBUG + }, + }); + +Let's see what C<Benchmark> makes of this: + + $> perl ifdebug + Benchmark: timing 100000 iterations of constant, sub... + ifdebug: 0 wallclock secs ( 0.01 usr + 0.00 sys = 0.01 CPU) @ 10000000.00/s (n=100000) + (warning: too few iterations for a reliable count) + debug: 14 wallclock secs (13.18 usr + 0.04 sys = 13.22 CPU) @ 7564.30/s (n=100000) + +In the one case the code, which does exactly the same thing as far as +outputting any debugging information is concerned, in other words nothing, +takes 14 seconds, and in the other case the code takes one hundredth of a +second. Looks fairly definitive. Use a C<$DEBUG> variable BEFORE you call the +subroutine, rather than relying on the smart functionality inside it. + +=head2 Logging if DEBUG (constant) + +It's possible to take the previous idea a little further, by using a compile +time C<DEBUG> constant. + +# ifdebug-constant + + #!/usr/bin/perl + + use strict; + use warnings; + + use Benchmark; + use Data::Dumper; + use constant + DEBUG => 0 + ; + + sub debug { + if ( DEBUG ) { + my $msg = shift; + print "DEBUG: $msg\n"; + } + }; + + timethese(100000, { + 'debug' => sub { + debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) + }, + 'constant' => sub { + debug( "A $0 logging message via process-id: $$" . Dumper(\%INC) ) if DEBUG + }, + }); + +Running this program produces the following output: + + $> perl ifdebug-constant + Benchmark: timing 100000 iterations of constant, sub... + constant: 0 wallclock secs (-0.00 usr + 0.00 sys = -0.00 CPU) @ -7205759403792793600000.00/s (n=100000) + (warning: too few iterations for a reliable count) + sub: 14 wallclock secs (13.09 usr + 0.00 sys = 13.09 CPU) @ 7639.42/s (n=100000) + +The C<DEBUG> constant wipes the floor with even the C<$debug> variable, +clocking in at minus zero seconds, and generates a "warning: too few iterations +for a reliable count" message into the bargain. To see what is really going +on, and why we had too few iterations when we thought we asked for 100000, we +can use the very useful C<B::Deparse> to inspect the new code: + + $> perl -MO=Deparse ifdebug-constant + + use Benchmark; + use Data::Dumper; + use constant ('DEBUG', 0); + sub debug { + use warnings; + use strict 'refs'; + 0; + } + use warnings; + use strict 'refs'; + timethese(100000, {'sub', sub { + debug "A $0 logging message via process-id: $$" . Dumper(\%INC); + } + , 'constant', sub { + 0; + } + }); + ifdebug-constant syntax OK + +The output shows the constant() subroutine we're testing being replaced with +the value of the C<DEBUG> constant: zero. The line to be tested has been +completely optimized away, and you can't get much more efficient than that. + +=head1 POSTSCRIPT + +This document has provided several way to go about identifying hot-spots, and +checking whether any modifications have improved the runtime of the code. + +As a final thought, remember that it's not (at the time of writing) possible to +produce a useful program which will run in zero or negative time and this basic +principle can be written as: I<useful programs are slow> by their very +definition. It is of course possible to write a nearly instantaneous program, +but it's not going to do very much, here's a very efficient one: + + $> perl -e 0 + +Optimizing that any further is a job for C<p5p>. + +=head1 SEE ALSO + +Further reading can be found using the modules and links below. + +=head2 PERLDOCS + +For example: perldoc -f sort + + L<perlfaq4> + L<perlfork> + L<perlfunc> + L<perlretut> + L<perlthrtut> + L<threads> + +=head2 MAN PAGES + + L<time> + +=head2 MODULES + +It's not possible to individually showcase all the performance related code for +Perl here, naturally, but here's a short list of modules from the CPAN which +deserve further attention. + + L<Apache::DProf> + L<Apache::SmallProf> + L<Benchmark> + L<DBIx::Profiler> + L<Devel::AutoProfiler> + L<Devel::DProf> + L<Devel::DProfLB> + L<Devel::FastProf> + L<Devel::GraphVizProf> + L<Devel::NYTProf> + L<Devel::NYTProf::Apache> + L<Devel::Profiler> + L<Devel::Profile> + L<Devel::Profit> + L<Devel::SmallProf> + L<Devel::WxProf> + L<POE::Devel::Profiler> + L<Sort::Key> + L<Sort::Maker> + +=head2 URLS + +Very useful online reference material: + + http://www.ccl4.org/~nick/P/Fast_Enough/ + + http://www-128.ibm.com/developerworks/library/l-optperl.html + + http://perlbuzz.com/2007/11/bind-output-variables-in-dbi-for-speed-and-safety.html + + http://en.wikipedia.org/wiki/Performance_analysis + + http://apache.perl.org/docs/1.0/guide/performance.html + + http://perlgolf.sourceforge.net/ + + http://www.sysarch.com/Perl/sort_paper.html + + http://www.unix.org.ua/orelly/perl/prog/ch08_03.htm + +=head1 AUTHOR + +Richard Foley <richard.foley@rfi.net> Copyright (c) 2008 + +=cut diff --git a/pod/perlport.pod b/pod/perlport.pod index ff1ba39675..39a7441956 100644 --- a/pod/perlport.pod +++ b/pod/perlport.pod @@ -812,6 +812,7 @@ are a few of the more popular Unix flavors: dgux dgux AViiON-dgux DYNIX/ptx dynixptx i386-dynixptx FreeBSD freebsd freebsd-i386 + Haiku haiku BePC-haiku Linux linux arm-linux Linux linux i386-linux Linux linux i586-linux diff --git a/pod/perlrepository.pod b/pod/perlrepository.pod new file mode 100644 index 0000000000..5b9069c62c --- /dev/null +++ b/pod/perlrepository.pod @@ -0,0 +1,474 @@ +=head1 NAME + +perlrepository - Using the Perl source repository + +=head1 SYNOPSIS + +All of Perl's source code is kept centrally in a Git repository. 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 master 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 this over the web. This allows you to browse the tree, +see recent commits, search for particular commits and more. You may +access it at: + + http://perl5.git.perl.org/perl.git + +=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 'perl-ssh' +directory. + +If you clone using git, 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 actually +optional. + +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@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 user@camel:/gitroot/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>. + +=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 + +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@nmrc.ucc.ie> + Laszlo Molnar <laszlo.molnar@eth.ericsson.se> + Leif Huhn <leif@hale.dkstat.com> + Len Johnson <lenjay@ibm.net> + -Leon Brocard <acme@astray.com> + +Orange Brocard <acme@astray.com> + Les Peters <lpeters@aol.net> + Lesley Binks <lesley.binks@gmail.com> + Lincoln D. Stein <lstein@cshl.org> + +Now commit your change locally: + + % git add AUTHORS + % git commit -m 'Rename Leon Brocard to Orange Brocard' + Created commit 6196c1d: Rename Leon Brocard to Orange Brocard + 1 files changed, 1 insertions(+), 1 deletions(-) + +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@perl.org with a +description of your changes, and attach 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. + +=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 -am "Some fixing" --author="That Guy <that.guy@internets.com>" + +Now we can inspect the change: + + % git log + commit b1b3dab48344cff6de4087efca3dbd63548ab5e2 + Author: Leon Brocard <acme@astray.com> + Date: Fri Dec 19 17:02:59 2008 +0000 + + Rename Leon Brocard to Orange Brocard + ... + + % git diff blead + diff --git a/AUTHORS b/AUTHORS + index 293dd70..722c93e 100644 + --- a/AUTHORS + +++ b/AUTHORS + @@ -541,7 +541,7 @@ Lars Hecking <lhecking@nmrc.ucc.ie> + Laszlo Molnar <laszlo.molnar@eth.ericsson.se> + Leif Huhn <leif@hale.dkstat.com> + Len Johnson <lenjay@ibm.net> + -Leon Brocard <acme@astray.com> + +Orange Brocard <acme@astray.com> + Les Peters <lpeters@aol.net> + Lesley Binks <lesley.binks@gmail.com> + Lincoln D. Stein <lstein@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 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. + +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" || exit 125 + make || exit 125 + ./perl -Ilib ~/testcase.pl + +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@fdisolutions.com> + Date: Sat Feb 9 14:56:23 2008 +0000 + + [perl #49472] Attributes + Unkown 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 COMITTING TO MAINTENANCE VERSIONS + +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>. diff --git a/pod/perlrun.pod b/pod/perlrun.pod index 2a53ec72d4..d8e718ef1b 100644 --- a/pod/perlrun.pod +++ b/pod/perlrun.pod @@ -77,9 +77,10 @@ Parsing of the #! switches starts wherever "perl" is mentioned in the line. The sequences "-*" and "- " are specifically ignored so that you could, if you were so inclined, say - #!/bin/sh -- # -*- perl -*- -p - eval 'exec perl -wS $0 ${1+"$@"}' - if $running_under_some_shell; + #!/bin/sh + #! -*-perl-*- + eval 'exec perl -x -wS $0 ${1+"$@"}' + if 0; to let Perl see the B<-p> switch. @@ -341,6 +342,11 @@ that enabled the use of Unicode-aware "wide system call" Win32 APIs. This feature was practically unused, however, and the command line switch was therefore "recycled".) +B<Note:> Since perl 5.10.0, the -C option can no longer be used +on the #! line. It wasn't working there anyway, since the standard streams +are already set up at this point in the execution of the perl interpreter. +You can use binmode() instead to get the desired behaviour. + =item B<-c> X<-c> @@ -395,7 +401,7 @@ B<-D14> is equivalent to B<-Dtls>): 16 o Method and overloading resolution 32 c String/numeric conversions 64 P Print profiling info, source file input state - 128 m Memory allocation + 128 m Memory and SV allocation 256 f Format processing 512 r Regular expression parsing and execution 1024 x Syntax tree dump @@ -655,6 +661,10 @@ Note that the lines are not printed by default. See B<-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. +Also note that C<< <> >> passes command line arguments to +L<perlfunc/open>, which doesn't necessarily interpret them as file names. +See L<perlop> for possible security implications. + Here is an efficient way to delete all files that haven't been modified for at least a week: diff --git a/pod/perltie.pod b/pod/perltie.pod index 162272bd74..9f26473879 100644 --- a/pod/perltie.pod +++ b/pod/perltie.pod @@ -952,6 +952,19 @@ This method will be called when the C<getc> function is called. sub GETC { print "Don't GETC, Get Perl"; return "a"; } +=item EOF this +X<EOF> + +This method will be called when the C<eof> function is called. + +Starting with Perl 5.12, an additional integer parameter will be passed. It +will be zero if C<eof> is called without parameter; C<1> if C<eof> is given +a filehandle as a parameter, e.g. C<eof(FH)>; and C<2> in the very special +case that the tied filehandle is C<ARGV> and C<eof> is called with an empty +parameter list, e.g. C<eof()>. + + sub EOF { not length $stringbuf } + =item CLOSE this X<CLOSE> diff --git a/pod/perltoc.pod b/pod/perltoc.pod index 1836d4ac6a..1d57ee1149 100644 --- a/pod/perltoc.pod +++ b/pod/perltoc.pod @@ -653,6 +653,84 @@ X<record> X<structure> X<struct> =back +=head2 perlperf - Perl Performance and Optimization Techniques + +=over 4 + +=item DESCRIPTION + +=item OVERVIEW + +=over 4 + +=item ONE STEP SIDEWAYS + +=item ONE STEP FORWARD + +=item ANOTHER STEP SIDEWAYS + +=back + +=item GENERAL GUIDELINES + +=item BENCHMARKS + +=over 4 + +=item Assigning and Dereferencing Variables. + +=item Search and replace or tr + +=back + +=item PROFILING TOOLS + +=over 4 + +=item Devel::DProf + +=item Devel::Profiler + +=item Devel::SmallProf + +=item Devel::FastProf + +=item Devel::NYTProf + +=back + +=item SORTING + +Elapsed Real Time, User CPU Time, System CPU Time + +=item LOGGING + +=over 4 + +=item Logging if DEBUG (constant) + +=back + +=item POSTSCRIPT + +=item SEE ALSO + +=over 4 + +=item PERLDOCS + +=item MAN PAGES + +=item MODULES + +=item URLS + +=back + +=item AUTHOR + +=back + =head2 perlstyle - Perl style guide =over 4 @@ -1312,6 +1390,10 @@ array of hashes or arrays? =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 change, delete, or insert a line in a file, or append to the +beginning of a file? +X<file, editing> + =item How do I count the number of lines in a file? X<file, counting lines> X<lines> X<line> @@ -1343,6 +1425,9 @@ 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 output my numbers with commas added? +X<number, commify> + =item How can I translate tildes (~) in a filename? X<tilde> X<tilde expansion> @@ -1866,7 +1951,7 @@ X<block> =item Switch statements X<switch> X<case> X<given> X<when> X<default> -o, o, o, o, o, o, o +o, o =item Goto X<goto> @@ -1997,6 +2082,10 @@ X<%=> X<^=> X<x=> =item Comma Operator X<comma> X<operator, comma> X<,> +=item Yada Yada Operators +X<...> X<... operator> X<!!!> X<!!! operator> X<???> X<??? operator> +X<yada yada operator> + =item List Operators (Rightward) X<operator, list, rightward> X<list operator> @@ -2028,9 +2117,10 @@ 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> +/PATTERN/msixpogc, The empty pattern //, Matching in list context, \G +assertion, ?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> @@ -2196,81 +2286,82 @@ 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 +X<core> X<undump>, dump, each HASH X<each> X<hash, iterator>, each ARRAY +X<array, 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>, keys ARRAY, 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/, qx/STRING/, qw/STRING/, +qr/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 @@ -2311,10 +2402,11 @@ 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/// +Module, use VERSION, utime LIST X<utime>, values HASH X<values>, values +ARRAY, 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 @@ -2607,10 +2699,9 @@ 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> +X<-n>, 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 @@ -2880,8 +2971,9 @@ 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> +[1], [2], [3], [1], [2], [3], C<$>, C<+> C<< < >> C<=> C<< > >> C<|> C<~>, +C<^> C<`>, cntrl X<cntrl>, graph X<graph>, print X<print>, punct X<punct>, +xdigit X<xdigit> =item Extended Patterns @@ -3173,7 +3265,8 @@ 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> +isa(CLASS) X<isa>, DOES(ROLE), can(METHOD) X<can>, VERSION( [NEED] ) +X<VERSION> =item Destructors X<destructor> X<DESTROY> @@ -3231,8 +3324,8 @@ 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> +READLINE this X<READLINE>, GETC this X<GETC>, EOF this X<EOF>, CLOSE this +X<CLOSE>, UNTIE this X<UNTIE>, DESTROY this X<DESTROY> =item UNTIE this X<UNTIE> @@ -3970,6 +4063,9 @@ classes, Use of "Is" Prefix, Blocks =item Interaction with Locales +=item Problems with characters whose ordinal numbers are in the range 128 - +255 with no Locale specified + =item Interaction with Extensions =item Speed @@ -4153,7 +4249,7 @@ chr(), ord(), pack(), print(), printf(), sort(), sprintf(), unpack() =item Convert, sort data, then re convert. -=item Perform sorting on one type of machine only. +=item Perform sorting on one type of platform only. =back @@ -4281,43 +4377,44 @@ X<CLONE> X<CLONE_SKIP> X<thread> X<threads> X<ithread> =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 +attributes, attrs, autodie, 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, parent, 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, +AnyDBM_File, App::Prove, App::Prove::State, Archive::Extract, Archive::Tar, +Archive::Tar::File, Attribute::Handlers, AutoLoader, AutoSplit, B, +B::Concise, B::Debug, B::Deparse, B::Lint, B::Lint::Debug, 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_Darwin, 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, @@ -4338,18 +4435,19 @@ 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, +IPC::Msg, IPC::Open2, IPC::Open3, IPC::Semaphore, IPC::SharedMem, +IPC::SysV, 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, @@ -4382,18 +4480,28 @@ 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, +Sys::Syslog::win32::Win32, TAP::Base, TAP::Formatter::Color, +TAP::Formatter::Console, TAP::Formatter::Console::ParallelSession, +TAP::Formatter::Console::Session, TAP::Harness, TAP::Parser, +TAP::Parser::Aggregator, TAP::Parser::Grammar, TAP::Parser::Iterator, +TAP::Parser::Iterator::Array, TAP::Parser::Iterator::Process, +TAP::Parser::Iterator::Stream, TAP::Parser::Multiplexer, +TAP::Parser::Result, TAP::Parser::Result::Bailout, +TAP::Parser::Result::Comment, TAP::Parser::Result::Plan, +TAP::Parser::Result::Pragma, TAP::Parser::Result::Test, +TAP::Parser::Result::Unknown, TAP::Parser::Result::Version, +TAP::Parser::Result::YAML, TAP::Parser::Source, TAP::Parser::Source::Perl, +TAP::Parser::Utils, TAP::Parser::YAMLish::Reader, +TAP::Parser::YAMLish::Writer, 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, +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 @@ -4666,9 +4774,9 @@ 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> +L<perlbug|perlbug>, L<perlthanks|perlthanks>, 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 @@ -5761,6 +5869,10 @@ find_runcv X<find_runcv> packlist X<packlist>, unpackstring X<unpackstring> +=item Functions in file pp_sys.c + +setdefout X<setdefout> + =item GV Functions GvSV X<GvSV>, gv_const_sv X<gv_const_sv>, gv_fetchmeth X<gv_fetchmeth>, @@ -5777,8 +5889,8 @@ Nullsv X<Nullsv> 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>, +X<HeSVKEY_force>, HeSVKEY_set X<HeSVKEY_set>, HeUTF8 X<HeUTF8>, 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>, @@ -5862,21 +5974,21 @@ 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> +X<MARK>, mPUSHi X<mPUSHi>, mPUSHn X<mPUSHn>, mPUSHp X<mPUSHp>, mPUSHs +X<mPUSHs>, mPUSHu X<mPUSHu>, mXPUSHi X<mXPUSHi>, mXPUSHn X<mXPUSHn>, +mXPUSHp X<mXPUSHp>, mXPUSHs X<mXPUSHs>, 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 @@ -5886,10 +5998,11 @@ 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 +croak_xs_usage X<croak_xs_usage>, get_sv X<get_sv>, newRV_inc X<newRV_inc>, +newSVpvn_utf8 X<newSVpvn_utf8>, 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 @@ -5897,15 +6010,15 @@ 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<SvNV_set>, SvOK X<SvOK>, SvOOK X<SvOOK>, SvOOK_offset X<SvOOK_offset>, +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 @@ -5923,14 +6036,15 @@ 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> +X<sv_setsv_nomg>, sv_utf8_upgrade_nomg X<sv_utf8_upgrade_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 +newSVpvn_flags X<newSVpvn_flags>, newSVpvn_share X<newSVpvn_share>, +newSVpvs X<newSVpvs>, newSVpvs_flags X<newSVpvs_flags>, 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 @@ -5945,31 +6059,31 @@ 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> +sv_insert_flags X<sv_insert_flags>, 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 @@ -6033,7 +6147,7 @@ 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> +is_gv_magical_sv X<is_gv_magical_sv> =item Hash Manipulation Functions @@ -6046,7 +6160,8 @@ start_glob X<start_glob> =item Magical Functions -magic_sethint X<magic_sethint>, mg_localize X<mg_localize> +magic_clearhint X<magic_clearhint>, magic_sethint X<magic_sethint>, +mg_localize X<mg_localize> =item MRO Functions @@ -6068,8 +6183,8 @@ 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> +PL_dowarn X<PL_dowarn>, PL_last_in_gv X<PL_last_in_gv>, PL_ofsgv +X<PL_ofsgv>, PL_rs X<PL_rs> =item Stack Manipulation Macros @@ -6364,10 +6479,48 @@ DEFINES, USE_MULTI = define, #PERL_MALLOC = define, CFG = Debug I<The Road goes ever on and on, down from the door where it began.> +=over 4 + +=item Metaphoric Quotations + +=back + =item AUTHOR =back +=head2 perlrepository - Using the Perl source repository + +=over 4 + +=item SYNOPSIS + +=item GETTING ACCESS TO THE REPOSITORY + +=over 4 + +=item READ ACCESS VIA THE WEB + +=item READ ACCESS VIA GIT + +=item WRITE ACCESS TO THE REPOSITORY + +=back + +=item OVERVIEW OF THE REPOSITORY + +=over 4 + +=item FINDING OUT YOUR STATUS + +=back + +=item SUBMITTING A PATCH + +=item ACCEPTING A PATCH + +=back + =head2 perlbook - Perl book information =over 4 @@ -6420,18 +6573,14 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =over 4 -=item Remove duplication of test setup. - -=item merge common code in installperl and installman +=item Smartmatch design issues -=item common test code for timed bail out +=item Remove duplication of test setup. =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 @@ -6440,15 +6589,13 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =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 Bundle dual life modules in ext/ =item POSIX memory footprint @@ -6456,6 +6603,8 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =item use strict; and AutoLoad +=item profile installman + =back =item Tasks that need a little sysadmin-type knowledge @@ -6476,13 +6625,17 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =item roffitall +=item Split "linker" from "compiler" + +C<cc> (in F<cc.U>), C<ld> (in F<dlsrc.U>) + =back =item Tasks that need a little C knowledge =over 4 -=item Exterminate PL_na! +=item Weed out needless PERL_UNUSED_ARG =item Modernize the order of directories in @INC @@ -6498,16 +6651,24 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =item Use secure CRT functions when building with VC8 on Win32 +=item Fix POSIX::access() and chdir() on Win32 + =item strcat(), strcpy(), strncat(), strncpy(), sprintf(), vsprintf() =item -D_FORTIFY_SOURCE=2, -fstack-protector +=item Arenas for GPs? For MAGIC? + +=item Shared arenas + =back =item Tasks that need a knowledge of XS =over 4 +=item safely supporting POSIX SA_SIGINFO + =item autovivification =item Unicode in Filenames @@ -6532,11 +6693,6 @@ L<http://perl.com/>, L<http://use.perl.org/>, L<http://www.perlmonks.org/> =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 @@ -6545,6 +6701,10 @@ Perl_gv_fetchmethod_autoload() =over 4 +=item error reporting of [$a ; $b] + +=item lexicals used only once + =item UTF-8 revamp =item Properly Unicode safe tokeniser and pads. @@ -6563,8 +6723,6 @@ Perl_gv_fetchmethod_autoload() =item LVALUE functions for lists -=item LVALUE functions in the debugger - =item regexp optimiser optional =item delete &function @@ -6583,12 +6741,18 @@ Perl_gv_fetchmethod_autoload() =item Optimize away @_ -=item The yada yada yada operators - =item Virtualize operating system access =item Investigate PADTMP hash pessimisation +=item Store the current pad in the OP slab allocator + +=item repack the optree + +=item eliminate incorrect line numbers in warnings + +=item optimize tail-calls + =back =item Big projects @@ -6619,8 +6783,8 @@ Perl_gv_fetchmethod_autoload() =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> +B<-h>, B<-D>, B<-t>, B<-u>, B<-m> I<module>, B<-l>, B<-F>, B<-f> +I<perlfunc>, B<-q> I<perlfaq-search-regexp>, B<-v> I<perlvar>, 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>, @@ -6630,6 +6794,8 @@ B<-V> =item ENVIRONMENT +=item CHANGES + =item AUTHOR =back @@ -6664,272 +6830,40 @@ B<-V> =back -=head2 perldelta, perl5100delta - what is new for perl 5.10.0 +=head2 perldelta - what is new for perl v5.11.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 Core Enhancements =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 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 =over 4 -=item UTF-8 problems +=item Platform Specific Problems =back -=item Platform Specific Problems - =item Reporting Bugs =item SEE ALSO @@ -10315,6 +10249,44 @@ a), b), c), d), a), b), c), d) =item Compiling Perl 5 on AIX +=item Supported Compilers + +=item Perl 5.8.9 was successfully compiled and tested on: + + AIX Level | Compiler Level | w th | w/o th + --------------------------+-------------------------+------+------- + 5.1 TL9 32 bit | XL C/C++ V7 | OK | OK + 5.1 TL9 32 bit | gcc 3.2.2 | OK | OK + 5.1 TL9 64 bit | XL C/C++ V7 | OK | OK + 5.2 TL10 32 bit | XL C/C++ V8 | OK | OK + 5.2 TL10 64 bit | XL C/C++ V8 | OK | OK + 5.3 TL7 32 bit | XL C/C++ V9 + IZ35785 | OK | OK + 5.3 TL7 32 bit | gcc 4.2.4 | OK | OK + 5.3 TL7 64 bit | XL C/C++ V9 + IZ35785 | OK | OK + 6.1 TL1 32 bit | XL C/C++ V10 | OK | OK + 6.1 TL1 64 bit + IZ39077 | XL C/C++ V10 | OK | OK + + w th = with thread + w/o th = without thread + +=item Building Dynamic Extensions on AIX + +=item Using Large Files with Perl + +=item Threaded Perl + +=item 64-bit Perl + +=item Recommended Options AIX 5.1/5.2/5.3 and 6.1 (threaded/32-bit) + +=item Recommended Options AIX 5.1/5.2/5.3 and 6.1 (32-bit) + +=item Recommended Options AIX 5.1/5.2/5.3 and 6.1 (threaded/64-bit) + +=item Recommended Options AIX 5.1/5.2/5.3 and 6.1(64-bit) + +=item Compiling Perl 5 on older AIX versions up to 4.3.3 + =item OS level =item Building Dynamic Extensions on AIX @@ -10323,7 +10295,7 @@ a), b), c), d), a), b), c), d) =item The usenm option -=item Using GNU's gcc for building perl +=item Using GNU's gcc for building Perl =item Using Large Files with Perl @@ -10335,7 +10307,7 @@ a), b), c), d), a), b), c), d) =back -=item AUTHOR +=item AUTHORS =item DATE @@ -10757,6 +10729,20 @@ DJGPP, Pthreads =back +=head2 perlhaiku, README.haiku - Perl version 5.10+ on Haiku + +=over 4 + +=item DESCRIPTION + +=item BUILD AND INSTALL + +=item KNOWN PROBLEMS + +=item CONTACT + +=back + =head2 perlhpux, README.hpux - Perl version 5 on Hewlett-Packard Unix (HP-UX) systems @@ -10786,6 +10772,8 @@ DJGPP, Pthreads =item Itanium, Itanium 2 & Madison 6 +=item HP-UX versions + =item Building Dynamic Extensions on HP-UX =item The HP ANSI C Compiler @@ -10804,8 +10792,6 @@ DJGPP, Pthreads =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 @@ -11822,7 +11808,7 @@ utime LIST, waitpid PID,FLAGS =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, +C++ 2008 Express Edition, 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 @@ -11924,10 +11910,10 @@ data structures between threads =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 +share VARIABLE, shared_clone REF, 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 @@ -11939,6 +11925,8 @@ cond_broadcast VARIABLE =item AUTHOR +=item LICENSE + =back =head2 threads - Perl interpreter-based threads @@ -12015,8 +12003,8 @@ 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> +Returning objects from threads, END blocks in threads, Perl Bugs and the +CPAN Version of L<threads> =item REQUIREMENTS @@ -12024,6 +12012,8 @@ L<threads> =item AUTHOR +=item LICENSE + =item ACKNOWLEDGEMENTS =back @@ -12038,6 +12028,8 @@ L<threads> =over 4 +=item What C<import> does + =item Built-in Attributes locked, method, lvalue @@ -12068,8 +12060,117 @@ FETCH_I<type>_ATTRIBUTES, MODIFY_I<type>_ATTRIBUTES =item EXAMPLES +=item MORE EXAMPLES + +=item SEE ALSO + +=back + +=head2 autodie - Replace functions with ones that succeed or die with +lexical scope + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item EXCEPTIONS + +=item CATEGORIES + +=item FUNCTION SPECIFIC NOTES + +=over 4 + +=item flock + +=item system/exec + +=back + +=item GOTCHAS + +=item DIAGNOSTICS + +:void cannot be used with lexical scope + +=item BUGS + +=over 4 + +=item REPORTING BUGS + +=back + +=item FEEDBACK + +=item AUTHOR + +=item LICENSE + +=item SEE ALSO + +=item ACKNOWLEDGEMENTS + +=back + +=head2 autodiexception, autodie::exception - Exceptions from autodying +functions. + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Common Methods + +=back + +=back + +=over 4 + +=item Advanced methods + +=back + +=over 4 + =item SEE ALSO +=item LICENSE + +=item AUTHOR + +=back + +=head2 autodiexception::system, autodie::exception::system - Exceptions +from autodying system(). + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=over 4 + +=item stringify + +=back + +=over 4 + +=item LICENSE + +=item AUTHOR + =back =head2 autouse - postpone load of modules until a function is used @@ -12341,11 +12442,13 @@ escapes =item CAVEATS +=item SEE ALSO + =item BUGS =item AUTHORS -=item COPYRIGHT +=item COPYRIGHT & LICENSE =back @@ -12393,10 +12496,6 @@ escapes =item Side effects -=item Side effects - -=item Side effects - =back =item FEATURES THAT REQUIRE 5.8.1 @@ -12625,6 +12724,8 @@ This probably does nothing, This works only on 5.10+ =item AUTHOR +=item COPYRIGHT AND LICENSE + =back =head2 locale - Perl pragma to use and avoid POSIX locales for built-in @@ -12853,6 +12954,33 @@ type, `%s' is not a code reference =back +=head2 parent - Establish an ISA relationship with base classes at compile +time + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item DIAGNOSTICS + +Class 'Foo' tried to inherit from itself + +=item HISTORY + +=item CAVEATS + +=item SEE ALSO + +=item AUTHORS AND CONTRIBUTORS + +=item MAINTAINER + +=item LICENSE + +=back + =head2 sigtrap - Perl pragma to enable simple signal handling =over 4 @@ -12934,10 +13062,10 @@ structures between threads =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 +share VARIABLE, shared_clone REF, 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 @@ -12949,6 +13077,8 @@ cond_broadcast VARIABLE =item AUTHOR +=item LICENSE + =back =head2 utf8 - Perl pragma to enable/disable UTF-8 (or UTF-EBCDIC) in source @@ -13101,6 +13231,183 @@ warnings::warnif($object, $message) =back +=head2 App::Prove - Implements the C<prove> command. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Attributes + +C<archive>, C<argv>, C<backwards>, C<blib>, C<color>, C<directives>, +C<dry>, C<exec>, C<extension>, C<failures>, C<fork>, C<formatter>, +C<harness>, C<ignore_exit>, C<includes>, C<jobs>, C<lib>, C<merge>, +C<modules>, C<parse>, C<plugins>, C<quiet>, C<really_quiet>, C<recurse>, +C<rules>, C<show_count>, C<show_help>, C<show_man>, C<show_version>, +C<shuffle>, C<state>, C<taint_fail>, C<taint_warn>, C<test_args>, C<timer>, +C<verbose>, C<warnings_fail>, C<warnings_warn> + +=back + +=head2 App::Prove::State - State storage for the C<prove> command. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item C<result_class> + +=back + +=over 4 + +=item C<extension> + +=back + +=over 4 + +=item C<results> + +=back + +=over 4 + +=item C<commit> + +=back + +=over 4 + +=item Instance Methods + +C<last>, C<failed>, C<passed>, C<all>, C<hot>, C<todo>, C<slow>, C<fast>, +C<new>, C<old>, C<save> + +=back + +=head2 App::Prove::State::Result - Individual test suite results. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item C<state_version> + +=back + +=over 4 + +=item C<test_class> + +=back + +=head2 App::Prove::State::Result::Test - Individual test results. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + =head2 Archive::Extract - A generic archive extracting mechanism =over 4 @@ -13120,7 +13427,7 @@ warnings::warnif($object, $message) =item $ae = Archive::Extract->new(archive => '/path/to/archive',[type => TYPE]) -tar, tgz, gz, Z, zip, bz2, tbz +tar, tgz, gz, Z, zip, bz2, tbz, lzma =back @@ -13168,6 +13475,8 @@ $ae->extract_path, $ae->files =item $ae->is_zip +=item $ae->is_lzma + =back =over 4 @@ -13178,6 +13487,14 @@ $ae->extract_path, $ae->files =item $ae->bin_unzip +=item $ae->bin_unlzma + +=back + +=over 4 + +=item $bool = $ae->have_old_bunzip2 + =back =over 4 @@ -13240,9 +13557,9 @@ Mime magic support =over 4 -=item $tar->read ( $filename|$handle, $compressed, {opt => 'val'} ) +=item $tar->read ( $filename|$handle, [$compressed, {opt => 'val'}] ) -limit, extract +limit, filter, extract =back @@ -13340,37 +13657,55 @@ FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET =over 4 -=item $bool = $tar->has_io_string +=item Class Methods + +=over 4 + +=item Archive::Tar->create_archive($file, $compressed, @filelist) + +=back =back =over 4 -=item $bool = $tar->has_perlio +=item Archive::Tar->iter( $filename, [ $compressed, {opt => $val} ] ) =back =over 4 -=item Class Methods +=item Archive::Tar->list_archive($file, $compressed, [\@properties]) + +=back =over 4 -=item Archive::Tar->create_archive($file, $compression, @filelist) +=item Archive::Tar->extract_archive($file, $compressed) =back +=over 4 + +=item $bool = Archive::Tar->has_io_string + +=back + +=over 4 + +=item $bool = Archive::Tar->has_perlio + =back =over 4 -=item Archive::Tar->list_archive ($file, $compressed, [\@properties]) +=item $bool = Archive::Tar->has_zlib_support =back =over 4 -=item Archive::Tar->extract_archive ($file, $gzip) +=item $bool = Archive::Tar->has_bzip2_support =back @@ -13412,7 +13747,7 @@ FILE, HARDLINK, SYMLINK, CHARDEV, BLOCKDEV, DIR, FIFO, SOCKET 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 +Can 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 @@ -13462,55 +13797,61 @@ uname, gname, devmajor, devminor, prefix, raw =over 4 -=item new( file => $path ) +=item Archive::Tar::File->new( file => $path ) -=item new( data => $path, $data, $opt ) +=item Archive::Tar::File->new( data => $path, $data, $opt ) -=item new( chunk => $chunk ) +=item Archive::Tar::File->new( chunk => $chunk ) + +=back =back +=over 4 + +=item $bool = $file->extract( [ $alternative_name ] ) + =back =over 4 -=item full_path +=item $path = $file->full_path =back =over 4 -=item validate +=item $bool = $file->validate =back =over 4 -=item has_content +=item $bool = $file->has_content =back =over 4 -=item get_content +=item $content = $file->get_content =back =over 4 -=item get_content_by_ref +=item $cref = $file->get_content_by_ref =back =over 4 -=item replace_content( $content ) +=item $bool = $file->replace_content( $content ) =back =over 4 -=item rename( $new_name ) +=item $bool = $file->rename( $new_name ) =back @@ -13518,8 +13859,9 @@ uname, gname, devmajor, devminor, prefix, raw =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 +$file->is_file, $file->is_dir, $file->is_hardlink, $file->is_symlink, +$file->is_chardev, $file->is_blockdev, $file->is_fifo, $file->is_socket, +$file->is_longlink, $file->is_label, $file->is_unknown =back @@ -13563,7 +13905,7 @@ be able to apply END handler> =item BUGS -=item COPYRIGHT +=item COPYRIGHT AND LICENSE =back @@ -13595,6 +13937,10 @@ be able to apply END handler> =item SEE ALSO +=item AUTHOR + +=item COPYRIGHT AND LICENSE + =back =head2 AutoSplit - split a package for autoloading @@ -13615,6 +13961,10 @@ $keep, $check, $modtime =item DIAGNOSTICS +=item AUTHOR + +=item COPYRIGHT AND LICENSE + =back =head2 B - The Perl Compiler @@ -13888,8 +14238,14 @@ a{_POSIX_SAVED_IDS}', perl -MB::Concise -e =item DESCRIPTION +=item OPTIONS + +=item Changes + =item AUTHOR +=item LICENSE + =back =head2 B::Deparse - Perl compiler backend to produce perl code @@ -13959,6 +14315,16 @@ validate against older perls =item AUTHOR +=item ACKNOWLEDGEMENTS + +=back + +=head2 B::Lint::Debug - Adds debugging stringification to B:: + +=over 4 + +=item DESCRIPTION + =back =head2 B::O, O - Generic interface to Perl Compiler backends @@ -14132,8 +14498,8 @@ B<:standard>, B<:all> =item PRAGMAS --any, -compile, -nosticky, -tabindex, -no_undef_params, -no_xhtml, -nph, --newstyle_urls, -oldstyle_urls, -autoload, -no_debug, -debug, +-any, -compile, -nosticky, -tabindex, -no_undef_params, -no_xhtml, -utf8, +-nph, -newstyle_urls, -oldstyle_urls, -autoload, -no_debug, -debug, -private_tempfiles =item SPECIAL FORMS FOR IMPORTING HTML-TAG FUNCTIONS @@ -14591,6 +14957,8 @@ and the C<fforce> pragma, Lockfile, Signals =item Integrating local directories +=item Redirection + =back =item CONFIGURATION @@ -14633,8 +15001,9 @@ cwd, getcwd, fastcwd, backtickcwd =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] +FEATURE ***, disabled [boolean], features [array] *** EXPERIMENTAL FEATURE +***, goto [string], install [hash], make [hash], match [hash], patches +[array], pl [hash], test [hash] =item Processing Instructions @@ -14669,21 +15038,21 @@ CPAN::Distribution::containsmods(), CPAN::Distribution::cvs_import(), CPAN::Distribution::dir(), CPAN::Distribution::force($method,@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,@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::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,@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() @@ -14742,7 +15111,8 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade =item FAQ -1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11), 12), 13), 14), 15), 16) +1), 2), 3), 4), 5), 6), 7), 8), 9), 10), 11), 12), 13), 14), 15), 16), 17), +18) =item COMPATIBILITY @@ -14790,6 +15160,37 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade =back +=head2 CPAN::Distroprefs -- read and match distroprefs + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item INTERFACE + +a CPAN::Distroprefs::Result object, C<undef>, indicating that no prefs +files remain to be found + +=item RESULTS + +=over 4 + +=item Common + +=item Errors + +=item Successes + +=back + +=item PREFS + +=item LICENSE + +=back + =head2 CPAN::FirstTime - Utility for CPAN::Config file Initialization =over 4 @@ -14803,14 +15204,17 @@ http firewall, ftp firewall, One way visibility, SOCKS, IP Masquerade 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 +connect_to_internet_ok, ftp_passive, ftpstats_period, ftpstats_size, +getcwd, halt_on_failure, 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, +perl5lib_verbosity, trust_test_report_history, use_sqlite, yaml_load_code, +yaml_module =over 4 @@ -16968,6 +17372,35 @@ B<-ADLER32>, B<-ConsumeInput> =back +=head2 Compress::Raw::Zlib::pod::FAQ, Compress::Raw::Zlib::FAQ -- +Frequently Asked Questions about Compress::Raw::Zlib + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Compatibility with Unix compress/uncompress. + +=item Accessing .tar.Z files + +=item Accessing Zip Files + +=item Zlib Library Version Support + +=back + +=item SEE ALSO + +=item AUTHOR + +=item MODIFICATION HISTORY + +=item COPYRIGHT AND LICENSE + +=back + =head2 Compress::Zlib - Interface to zlib compression library =over 4 @@ -17018,7 +17451,8 @@ 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<($out, $status) = $d-E<gt>flush()> +=head2 B<($out, $status) = $d-E<gt>flush($flush_type)> =item B<$status = $d-E<gt>deflateParams([OPT])> @@ -17125,7 +17559,8 @@ 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<($out, $status) = $d-E<gt>flush()> +=head2 B<($out, $status) = $d-E<gt>flush($flush_type)> =item B<$status = $d-E<gt>deflateParams([OPT])> @@ -17181,6 +17616,33 @@ B<-WindowBits>, B<-Bufsize>, B<-Dictionary> =back +=head2 Compress::Zlib::pod::FAQ, Compress::Zlib::FAQ -- Frequently Asked +Questions about Compress::Zlib + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Compatibility with Unix compress/uncompress. + +=item Accessing .tar.Z files + +=item Accessing Zip Files + +=back + +=item SEE ALSO + +=item AUTHOR + +=item MODIFICATION HISTORY + +=item COPYRIGHT AND LICENSE + +=back + =head2 Config - access Perl configuration information =over 4 @@ -17197,25 +17659,41 @@ myconfig(), config_sh(), config_re($regex), config_vars(@names) =item GLOSSARY +=back + =over 4 =item _ +=back + C<_a>, C<_exe>, C<_o> +=over 4 + =item a +=back + 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> +=over 4 + =item b +=back + C<baserev>, C<bash>, C<bin>, C<binexp>, C<bison>, C<byacc>, C<byteorder> +=over 4 + =item c +=back + 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>, @@ -17224,61 +17702,68 @@ 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> +=over 4 + =item d +=back + 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_archlib>, C<d_asctime64>, C<d_asctime_r>, C<d_atolf>, C<d_atoll>, +C<d_attribute_deprecated>, 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_ctime64>, C<d_ctime_r>, C<d_cuserid>, C<d_dbl_dig>, C<d_dbminitproto>, +C<d_difftime>, C<d_difftime64>, 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_gdbm_ndbm_h_uses_prototypes>, +C<d_gdbmndbm_h_uses_prototypes>, 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_gmtime64>, 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_libm_lib_version>, C<d_link>, C<d_localtime64>, 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_mkstemps>, C<d_mktime>, C<d_mktime64>, 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_ndbm>, +C<d_ndbm_h_uses_prototypes>, 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>, @@ -17318,7 +17803,7 @@ 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_telldirproto>, C<d_time>, C<d_timegm>, 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>, @@ -17328,23 +17813,35 @@ 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> +C<doublesize>, C<drand01>, C<drand48_r_proto>, C<dtrace>, C<dynamic_ext> + +=over 4 =item e +=back + 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> +C<expr>, C<extensions>, C<extern_C>, C<extras> + +=over 4 =item f +=back + 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> +=over 4 + =item g +=back + 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>, @@ -17356,49 +17853,66 @@ 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> +=over 4 + =item h +=back + C<h_fcntl>, C<h_sysfile>, C<hint>, C<hostcat>, C<html1dir>, C<html1direxp>, C<html3dir>, C<html3direxp> +=over 4 + =item i +=back + 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> +C<i8size>, C<i8type>, C<i_arpainet>, C<i_assert>, 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_gdbm_ndbm>, +C<i_gdbmndbm>, 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_mallocmalloc>, 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_syspoll>, +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> + +=over 4 =item k +=back + C<known_extensions>, C<ksh> +=over 4 + =item l +=back + 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>, @@ -17407,38 +17921,54 @@ C<localtime_r_proto>, C<locincpth>, C<loclibpth>, C<longdblsize>, C<longlongsize>, C<longsize>, C<lp>, C<lpr>, C<ls>, C<lseeksize>, C<lseektype> +=over 4 + =item m +=back + 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<man1direxp>, C<man1ext>, C<man3dir>, C<man3direxp>, C<man3ext>, +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> -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> +=over 4 =item n +=back + 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> +C<nonxs_ext>, C<nroff>, C<nv_overflows_integers_at>, +C<nv_preserves_uv_bits>, C<nveformat>, C<nvEUformat>, C<nvfformat>, +C<nvFUformat>, C<nvgformat>, C<nvGUformat>, C<nvsize>, C<nvtype> + +=over 4 =item o +=back + C<o_nonblock>, C<obj_ext>, C<old_pthread_create_joinable>, C<optimize>, C<orderlib>, C<osname>, C<osvers>, C<otherlibdirs> +=over 4 + =item p +=back + C<package>, C<pager>, C<passcat>, C<patchlevel>, C<path_sep>, C<perl>, C<perl5> +=over 4 + =item P +=back + 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>, @@ -17446,30 +17976,43 @@ 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> +=over 4 + =item q +=back + C<quadkind>, C<quadtype> +=over 4 + =item r +=back + 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> +=over 4 + =item s +=back + 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<setprotoent_r_proto>, C<setpwent_r_proto>, C<setservent_r_proto>, +C<sGMTIME_max>, C<sGMTIME_min>, 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<sLOCALTIME_max>, C<sLOCALTIME_min>, 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>, @@ -17479,27 +18022,40 @@ 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> +=over 4 + =item t +=back + 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> +=over 4 + =item u +=back + 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> +C<use64bitint>, C<usecrosscompile>, C<usedevel>, C<usedl>, C<usedtrace>, +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> + +=over 4 =item v +=back + C<vendorarch>, C<vendorarchexp>, C<vendorbin>, C<vendorbinexp>, C<vendorhtml1dir>, C<vendorhtml1direxp>, C<vendorhtml3dir>, C<vendorhtml3direxp>, C<vendorlib>, C<vendorlib_stem>, C<vendorlibexp>, @@ -17508,19 +18064,31 @@ C<vendorman3direxp>, C<vendorprefix>, C<vendorprefixexp>, C<vendorscript>, C<vendorscriptexp>, C<version>, C<version_patchlevel_string>, C<versiononly>, C<vi>, C<voidflags> +=over 4 + =item x +=back + C<xlibpth> +=over 4 + =item y +=back + C<yacc>, C<yaccflags> +=over 4 + =item z +=back + C<zcat>, C<zip> -=back +=over 4 =item NOTE @@ -17927,32 +18495,6 @@ Dumper =back -=head2 Devel::Arena - Perl extension for inspecting the core's arena -structures - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=over 4 - -=item EXPORT - -sv_stats [DONT_SHARE], shared_string_table, sizes, HEK_size STRING, -shared_string_table_effectiveness, write_stats_at_END - -=back - -=item SEE ALSO - -=item AUTHOR - -=item COPYRIGHT AND LICENSE - -=back - =head2 Devel::DProf - a Perl code profiler =over 4 @@ -18035,10 +18577,10 @@ shared_string_table_effectiveness, write_stats_at_END =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 +perl 5.11.0, perl 5.10.0, 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 @@ -18112,59 +18654,6 @@ perl 5.6.1, perl 5.6.0, perl 5.005_03, perl 5.005, perl 5.004_05, perl =back -=head2 Devel::Size - Perl extension for finding the memory usage of Perl -variables - -=over 4 - -=item SYNOPSIS - -=item DESCRIPTION - -=item FUNCTIONS - -=over 4 - -=item size($ref) - -=item total_size($ref) - -=back - -=item EXPORT - -=item UNDERSTANDING MEMORY ALLOCATION - -=over 4 - -=item The C library - -=item Perl - -=back - -=item DANGERS - -=item Messages: texts originating from this module. - -=over 4 - -=item Errors - -=item warnings - -=back - -=item BUGS - -=item AUTHOR - -=item COPYRIGHT - -=item SEE ALSO - -=back - =head2 Digest - Modules that calculate message digests =over 4 @@ -18267,6 +18756,55 @@ B<hmac_sha384_base64($data, $key)>, B<hmac_sha512_base64($data, $key)> =back +=head2 Digest::SHA::lib::Digest::SHA, 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 @@ -18392,7 +18930,7 @@ C<XSLoader::load('Your::Module', $Your::Module::VERSION)> =item AUTHORS -=item COPYRIGHT +=item COPYRIGHT & LICENSE =back @@ -18444,6 +18982,12 @@ Encode::FB_PERLQQ), HTML charref mode (I<CHECK> = Encode::FB_HTMLCREF), XML charref mode (I<CHECK> = Encode::FB_XMLCREF), The bitmask, Encode::LEAVE_SRC +=over 4 + +=item coderef for CHECK + +=back + =item Defining Encodings =item The UTF8 flag @@ -19176,10 +19720,6 @@ non-ascii or non-utf8 =item Side effects -=item Side effects - -=item Side effects - =back =item FEATURES THAT REQUIRE 5.8.1 @@ -19320,7 +19860,7 @@ arrays =item How to Import -C<use ModuleName;>, C<use ModuleName ();>, C<use ModuleName qw(...);> +C<use YourModule;>, C<use YourModule ();>, C<use YourModule qw(...);> =back @@ -19501,14 +20041,15 @@ IV, UV, NV, PV, PVN, SV, YES, NO, UNDEF constant_types -XS_constant PACKAGE, TYPES, SUBNAME, C_SUBNAME +XS_constant PACKAGE, TYPES, XS_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 +BREAKOUT_AT, NAMES, PROXYSUBS, C_FH, C_FILE, XS_FH, XS_FILE, XS_SUBNAME, +C_SUBNAME =over 4 @@ -19623,6 +20164,10 @@ ccopts(), xsi_header(), xsi_protos(@modules), xsi_body(@modules) =item SYNOPSIS +=back + +=over 4 + =item DESCRIPTION _chmod($$;$), _warnonce(@), _choke(@) @@ -19637,22 +20182,22 @@ _unlink_or_rename( $file, $tryhard, $installing ) =item Functions -B<install> +_get_install_skip =back -_get_install_skip - _have_write_access _can_write_dir(C<$dir>) -_mkpath($dir,$show,$mode,$verbose,$fake) +_mkpath($dir,$show,$mode,$verbose,$dry_run) -_copy($from,$to,$verbose,$fake) +_copy($from,$to,$verbose,$dry_run) _chdir($from) +B<install> + _do_cleanup install_rooted_file( $file ), install_rooted_dir( $dir ) @@ -19665,7 +20210,7 @@ B<install_default> I<DISCOURAGED> B<uninstall> -inc_uninstall($filepath,$libdir,$verbose,$nonono,$ignore) +inc_uninstall($filepath,$libdir,$verbose,$dry_run,$ignore,$results) run_filter($cmd,$src,$dest) @@ -19680,7 +20225,7 @@ _invokant =item ENVIRONMENT B<PERL_INSTALL_ROOT>, B<EU_INSTALL_IGNORE_SKIP>, -B<EU_INSTALL_SITE_SKIPFILE> +B<EU_INSTALL_SITE_SKIPFILE>, B<EU_INSTALL_ALWAYS_COPY> =item AUTHOR @@ -19894,6 +20439,37 @@ B<replace_manpage_separator> =back +=head2 ExtUtils::MM_Darwin - special behaviors for OS X + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item Overriden Methods + +=back + +=back + +=head2 ExtUtils::MM_Haiku - methods to override UN*X behaviour in +ExtUtils::MakeMaker + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +os_flavor + +init_linker + =head2 ExtUtils::MM_MacOS - once produced Makefiles for MacOS Classic =over 4 @@ -20485,14 +21061,15 @@ 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 +MAKEAPERL, MAKEFILE_OLD, MAN1PODS, MAN3PODS, MAP_TARGET, META_ADD, +META_MERGE, MIN_PERL_VERSION, 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 @@ -20662,6 +21239,8 @@ skipcheck maniread +maniskip + manicopy maniadd @@ -20792,18 +21371,30 @@ errors() =back -=head2 Fatal - replace functions with equivalents which succeed or die +=head2 Fatal - Replace functions with equivalents which succeed or die =over 4 =item SYNOPSIS +=item BEST PRACTICE + =item DESCRIPTION +=item DIAGNOSTICS + +Bad subroutine name for Fatal: %s, %s is not a Perl subroutine, %s is +neither a builtin, nor a Perl subroutine, Cannot make the non-overridable +%s fatal, Internal error: %s + =item BUGS =item AUTHOR +=item LICENSE + +=item SEE ALSO + =back =head2 Fcntl - load the C Fcntl.h defines @@ -21089,10 +21680,6 @@ C<GLOB_NOSPACE>, C<GLOB_ABEND> =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 @@ -21139,16 +21726,21 @@ B<~>, B<~user>, B<.>, B<*>, B<?>, B<\>, B<[]>, B<{,}>, B<()> =item DESCRIPTION -=over 4 +make_path( $dir1, $dir2, .... ), make_path( $dir1, $dir2, ...., \%opts ), +mode => $num, verbose => $bool, error => \$err, mkpath( $dir ), mkpath( +$dir, $verbose, $mode ), mkpath( [$dir1, $dir2,...], $verbose, $mode ), +mkpath( $dir1, $dir2,..., \%opt ), remove_tree( $dir1, $dir2, .... ), +remove_tree( $dir1, $dir2, ...., \%opts ), verbose => $bool, safe => $bool, +keep_root => $bool, result => \$res, error => \$err, rmtree( $dir ), +rmtree( $dir, $verbose, $safe ), rmtree( [$dir1, $dir2,...], $verbose, +$safe ), rmtree( $dir1, $dir2,..., \%opt ) -=item FUNCTIONS - -mode, verbose, error, verbose, safe, keep_root, result, error - -=item TRADITIONAL INTERFACE +=over 4 =item ERROR HANDLING +B<NOTE:> + =item NOTES =back @@ -21158,17 +21750,18 @@ mode, verbose, error, verbose, safe, keep_root, result, error 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 +directory [dir] changed before chdir, expected dev=[n] ino=[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] +[dir]: [errmsg], cannot remove [dir] when cwd is [dir], 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] ino=[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 @@ -21510,9 +22103,11 @@ B<new> =back +B<newdir> + B<filename> -B<unlink_on_destroy> +B<dirname>, B<unlink_on_destroy> B<DESTROY> @@ -21594,6 +22189,8 @@ B<$KEEP_ALL>, B<$DEBUG> =item Forking +=item Directory removal + =item BINMODE =back @@ -21693,7 +22290,9 @@ from the other partial filters described in the previous section. =item AUTHOR -=item COPYRIGHT +=item CONTACT + +=item COPYRIGHT AND LICENSE =back @@ -22511,6 +23110,14 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -22614,6 +23221,14 @@ C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1 =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -22713,6 +23328,14 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -22763,12 +23386,13 @@ A filename, A filehandle, A scalar reference 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 >> +$attr >>, C<< exTime => [$atime, $mtime, $ctime] >>, C<< exUnix2 => [$uid, +$gid] >>, 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 @@ -22818,6 +23442,14 @@ Minimal => 1|0 >>, C<< BlockSize100K => number >>, C<< WorkFactor => number =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -23169,6 +23801,12 @@ the sub-field structure as defined in RFC 1952 =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -23404,6 +24042,12 @@ Name, Comment =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -23509,6 +24153,12 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -23614,6 +24264,12 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -23719,6 +24375,14 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=item Walking through a zip file + +=back + =item SEE ALSO =item AUTHOR @@ -23764,7 +24428,7 @@ IO::Zlib::import: 'gzip_read_open' requires an argument, IO::Zlib::import: 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 +IO::Zlib::WRITE: too long LENGTH =item SEE ALSO @@ -24030,10 +24694,6 @@ File Glob to Allow Input and Output Files =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 @@ -24216,6 +24876,40 @@ Base Class for IO::Uncompress modules =back +=head2 IO_Compress_Base::pod::FAQ, IO::Compress::Base::FAQ -- Frequently +Asked Questions about IO::Compress::Base + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Compatibility with Unix compress/uncompress. + +=item Accessing .tar.Z files + +=item Accessing Zip Files + +=item Compressed files and Net::FTP + +=item How do I recompress using a different compression? + +=item Using C<InputLength> to uncompress data embedded in a larger +file/buffer. + +=back + +=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 @@ -24306,6 +25000,14 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24410,6 +25112,14 @@ C<< ExtraField => $data >>, C<< ExtraFlags => $value >>, C<< Strict => 0|1 =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24510,6 +25220,14 @@ Filehandle, C<< Merge => 0|1 >>, -Level, -Strategy, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24561,12 +25279,13 @@ A filename, A filehandle, A scalar reference 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 >> +$attr >>, C<< exTime => [$atime, $mtime, $ctime] >>, C<< exUnix2 => [$uid, +$gid] >>, 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 @@ -24616,6 +25335,14 @@ Minimal => 1|0 >>, C<< BlockSize100K => number >>, C<< WorkFactor => number =item EXAMPLES +=over 4 + +=item Apache::GZip Revisited + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24727,6 +25454,12 @@ the sub-field structure as defined in RFC 1952 =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24838,6 +25571,12 @@ Name, Comment =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -24944,6 +25683,12 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -25050,6 +25795,12 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=back + =item SEE ALSO =item AUTHOR @@ -25156,6 +25907,50 @@ $size >>, C<< Append => 0|1 >>, C<< Strict => 0|1 >> =item EXAMPLES +=over 4 + +=item Working with Net::FTP + +=item Walking through a zip file + +=back + +=item SEE ALSO + +=item AUTHOR + +=item MODIFICATION HISTORY + +=item COPYRIGHT AND LICENSE + +=back + +=head2 IO_Compress_Zlib::pod::FAQ, IO::Compress::Zlib::FAQ -- Frequently +Asked Questions about IO::Compress::Zlib + +=over 4 + +=item DESCRIPTION + +=over 4 + +=item Compatibility with Unix compress/uncompress. + +=item Accessing .tar.Z files + +=item Accessing Zip Files + +=item Compressed files and Net::FTP + +=item How do I recompress using a different compression? + +=item Apache::GZip Revisited + +=item Using C<InputLength> to uncompress data embedded in a larger +file/buffer. + +=back + =item SEE ALSO =item AUTHOR @@ -25182,7 +25977,7 @@ FLAGS ] ), stat =item SEE ALSO -=item AUTHOR +=item AUTHORS =item COPYRIGHT @@ -25236,13 +26031,34 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =item SEE ALSO -=item AUTHOR +=item AUTHORS + +=item COPYRIGHT + +=back + +=head2 IPC::SharedMem - SysV Shared Memory IPC object class + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +new ( KEY , SIZE , FLAGS ), id, read ( POS, SIZE ), write ( STRING, POS, +SIZE ), remove, is_removed, stat, attach ( [FLAG] ), detach, addr + +=item SEE ALSO + +=item AUTHORS =item COPYRIGHT =back -=head2 IPC::SysV - SysV IPC constants +=head2 IPC::SysV - System V IPC constants and system calls =over 4 @@ -25250,7 +26066,8 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =item DESCRIPTION -ftok( PATH, ID ) +ftok( PATH ), ftok( PATH, ID ), shmat( ID, ADDR, FLAG ), shmdt( ADDR ), +memread( ADDR, VAR, POS, SIZE ), memwrite( ADDR, STRING, POS, SIZE ) =item SEE ALSO @@ -25260,7 +26077,7 @@ ftok( PATH, ID ) =back -=head2 IPC::SysV::Msg, IPC::Msg - SysV Msg IPC object class +=head2 IPC::SysV::lib::IPC::Msg, IPC::Msg - SysV Msg IPC object class =over 4 @@ -25276,14 +26093,14 @@ FLAGS ] ), stat =item SEE ALSO -=item AUTHOR +=item AUTHORS =item COPYRIGHT =back -=head2 IPC::SysV::Semaphore, IPC::Semaphore - SysV Semaphore IPC object -class +=head2 IPC::SysV::lib::IPC::Semaphore, IPC::Semaphore - SysV Semaphore IPC +object class =over 4 @@ -25300,7 +26117,49 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =item SEE ALSO -=item AUTHOR +=item AUTHORS + +=item COPYRIGHT + +=back + +=head2 IPC::SysV::lib::IPC::SharedMem, IPC::SharedMem - SysV Shared Memory +IPC object class + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +new ( KEY , SIZE , FLAGS ), id, read ( POS, SIZE ), write ( STRING, POS, +SIZE ), remove, is_removed, stat, attach ( [FLAG] ), detach, addr + +=item SEE ALSO + +=item AUTHORS + +=item COPYRIGHT + +=back + +=head2 IPC::SysV::lib::IPC::SysV, IPC::SysV - System V IPC constants and +system calls + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +ftok( PATH ), ftok( PATH, ID ), shmat( ID, ADDR, FLAG ), shmdt( ADDR ), +memread( ADDR, VAR, POS, SIZE ), memwrite( ADDR, STRING, POS, SIZE ) + +=item SEE ALSO + +=item AUTHORS =item COPYRIGHT @@ -25318,7 +26177,7 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =over 4 -=item $bool = IPC::Cmd->can_use_ipc_run( [VERBOSE] ) +=item $ipc_run_version = IPC::Cmd->can_use_ipc_run( [VERBOSE] ) =back @@ -25326,7 +26185,7 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =over 4 -=item $bool = IPC::Cmd->can_use_ipc_open3( [VERBOSE] ) +=item $ipc_open3_version = IPC::Cmd->can_use_ipc_open3( [VERBOSE] ) =back @@ -25351,10 +26210,17 @@ set ( NAME => VALUE [, NAME => VALUE ...] ), setall ( VALUES ), setval ( N =over 4 =item $ok | ($ok, $err, $full_buf, $stdout_buff, $stderr_buff) = run( -command => COMMAND, [verbose => BOOL, buffer => \$SCALAR] ); +command => COMMAND, [verbose => BOOL, buffer => \$SCALAR, timeout => DIGIT] +); -command, verbose, buffer, success, errorcode, full_buffer, out_buffer, -error_buffer +command, verbose, buffer, timeout, success, error message, full_buffer, +out_buffer, error_buffer + +=back + +=over 4 + +=item $q = QUOTE =back @@ -25378,7 +26244,8 @@ error_buffer =item Caveats -Whitespace, IO Redirect +Whitespace and IPC::Open3 / system(), Whitespace and IPC::Run, IO Redirect, +Interleaving STDOUT/STDERR =item See Also @@ -25454,8 +26321,6 @@ set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF =item COPYRIGHT -=item BLATANT PLUG - =back =head2 Locale::Constants - constants for Locale codes @@ -26535,6 +27400,8 @@ the same terms as Perl itself. =item as_int()/as_number() +=item as_float() + =item as_hex() =item as_bin() @@ -26603,6 +27470,8 @@ the same terms as Perl itself. =item config() +=item objectify() + =back =item BUGS @@ -26642,10 +27511,14 @@ functions =item USAGE +=item CONSTANTS + =over 4 =item PI +=item Inf + =back =item ERRORS DUE TO DIVISION BY ZERO OR LOGARITHM OF ZERO @@ -26654,8 +27527,12 @@ functions =item BUGS +=item SEE ALSO + =item AUTHORS +=item LICENSE + =back =head2 Math::Trig - trigonometric functions @@ -26720,12 +27597,18 @@ cylindrical_to_spherical, spherical_to_cartesian, spherical_to_cylindrical =item CAVEAT FOR GREAT CIRCLE FORMULAS +=item Real-valued asin and acos + +asin_real, acos_real + =back =item BUGS =item AUTHORS +=item LICENSE + =back =head2 Memoize - Make functions faster by trading space for time @@ -26925,13 +27808,14 @@ 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() +recursive_test_files, requires, script_files, sign, test_files, +use_tap_harness, tap_harness_args, 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(), +autosplit_file($from, $to), base_dir(), build_requires(), cbuilder(), 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 => @@ -26939,8 +27823,8 @@ $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), +feature($name), feature($name => $value), fix_shebang_line(@files), +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 => @@ -26963,9 +27847,10 @@ 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() +pod_files(), pollute(), prefix(), prereq_action_types(), program_name(), +quiet(), recommends(), recurse_into(), recursive_test_files(), requires(), +scripts(), sign(), tap_harness_args(), test_file_exts(), use_rcfile(), +use_tap_harness(), verbose(), xs_files() =back @@ -27333,6 +28218,10 @@ _detildefy find_perl_interpreter +localize_file_path + +localize_dir_path + =over 4 =item AUTHOR @@ -27486,7 +28375,7 @@ at runtime =item $href = check_install( module => NAME [, version => VERSION, verbose => BOOL ] ); -module, version, verbose, file, version, uptodate +module, version, verbose, file, dir, version, uptodate =back @@ -27565,6 +28454,8 @@ modules, verbose, nocache =over 4 +=item BUG REPORTS + =item AUTHOR =item COPYRIGHT @@ -27610,6 +28501,8 @@ have plugins =item file_regex +=item include_editor_junk + =back =item METHODs @@ -27641,6 +28534,122 @@ ability to have plugins =item DESCRIPTION +=item OPTIONS + +=item AUTHOR + +=item COPYING + +=item BUGS + +=item SEE ALSO + +=back + +=head2 Module::Pluggable::lib::Devel::InnerPackage, 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 Module::Pluggable::lib::Module::Pluggable, 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 + +=item include_editor_junk + +=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::lib::Module::Pluggable::Object, +Module::Pluggable::Object - automatically give your module the ability to +have plugins + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item OPTIONS + =item AUTHOR =item COPYING @@ -28265,6 +29274,13 @@ C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> =over 4 +=item $bool = $self->mk_aliases( alias => method, [alias2 => method2, ...] +); + +=back + +=over 4 + =item $clone = $self->mk_clone; =back @@ -28307,6 +29323,12 @@ C<O_RDONLY>, C<O_WRONLY>, C<O_RDWR> =over 4 +=item $bool = $self->___alias( ALIAS => METHOD ); + +=back + +=over 4 + =item LVALUE ACCESSORS =over 4 @@ -28341,6 +29363,8 @@ Allow handlers, Callbacks =item CAVEATS +=item BUG REPORTS + =item AUTHOR =item COPYRIGHT @@ -28413,8 +29437,8 @@ a new namespace, an operator mask 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) +(PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING, STRICT), rdo +(FILENAME), root (NAMESPACE), mask (MASK) =item Some Safety Issues @@ -28605,6 +29629,8 @@ WTERMSIG, WIFSTOPPED, WSTOPSIG =over 4 +=item BUG REPORTS + =item AUTHOR =item COPYRIGHT @@ -29336,7 +30362,7 @@ B<_split_delimited> =item DESCRIPTION center, date, fixed, fixedbold, fixeditalic, fixedbolditalic, name, quotes, -release, section +release, section, stderr, utf8 =item DIAGNOSTICS @@ -29716,6 +30742,54 @@ I<code-ref>|I<method-name> =back +=head2 Pod::Perldoc - Look up Perl documentation in Pod format. + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=item COPYRIGHT AND DISCLAIMERS + +=item AUTHOR + +=back + +=head2 Pod::Perldoc::BaseTo - Base for Pod::Perldoc formatters + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=item COPYRIGHT AND DISCLAIMERS + +=item AUTHOR + +=back + +=head2 Pod::Perldoc::GetOptsOO - Customized option parser for Pod::Perldoc + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item SEE ALSO + +=item COPYRIGHT AND DISCLAIMERS + +=item AUTHOR + +=back + =head2 Pod::Perldoc::ToChecker - let Perldoc check Pod for errors =over 4 @@ -30034,6 +31108,8 @@ $parser->source_dead >> =item AUTHOR +Allison Randal C<allison@perl.org>, Hans Dieter Pearcey C<hdp@cpan.org> + =back =head2 Pod::Simple::Checker -- check the Pod syntax of a document @@ -30483,6 +31559,70 @@ I<SOMEVALUE> ) >>, C<< $parser->preserve_whitespace( I<SOMEVALUE> ) >> =back +=head2 Pod::Simple::XHTML -- format Pod as validating XHTML + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item perldoc_url_prefix + +=item perldoc_url_postfix + +=item title_prefix, title_postfix + +=item html_css + +=item html_javascript + +=item html_doctype + +=item html_header_tags + +=item default_title + +=item force_title + +=item html_header, html_footer + +=item index + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=back + +=over 4 + +=item handle_text + +=back + +=over 4 + +=item SEE ALSO + +=item COPYRIGHT + +=item AUTHOR + +=back + =head2 Pod::Simple::XMLOutStream -- turn Pod into XML =over 4 @@ -30532,13 +31672,17 @@ parse tree =item DESCRIPTION -alt, code, indent, loose, margin, quotes, sentence, width +alt, code, indent, loose, margin, quotes, sentence, stderr, utf8, width =item DIAGNOSTICS Bizarre space in item, Item called without tag, Can't open %s for reading: %s, Invalid quote specification "%s" +=item BUGS + +=item CAVEATS + =item NOTES =item SEE ALSO @@ -30567,8 +31711,8 @@ Bizarre space in item, Item called without tag, Can't open %s for reading: =back -=head2 Pod::Text::Overstrike - Convert POD data to formatted overstrike -text +=head2 Pod::Text::Overstrike, =for stopwords +overstrike =over 4 @@ -30677,8 +31821,8 @@ a new namespace, an operator mask 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) +(PACKAGE, ARRAYREF), varglob (VARNAME), reval (STRING, STRICT), rdo +(FILENAME), root (NAMESPACE), mask (MASK) =item Some Safety Issues @@ -30708,8 +31852,6 @@ set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF =item COPYRIGHT -=item BLATANT PLUG - =back =head2 Search::Dict, look - search for key in dictionary file @@ -30758,6 +31900,10 @@ set_prototype CODEREF, PROTOTYPE, tainted EXPR, weaken REF =item Multiple packages and fully qualified subroutine names +=item AUTHOR + +=item COPYRIGHT AND LICENSE + =back B<_make_cmd> @@ -30952,6 +32098,7 @@ 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<setlogsock($sock_type, $stream_location, $sock_timeout)> (added in 0.25), B<Note>, B<closelog()> =item THE RULES OF SYS::SYSLOG @@ -31028,6 +32175,7 @@ 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<setlogsock($sock_type, $stream_location, $sock_timeout)> (added in 0.25), B<Note>, B<closelog()> =item THE RULES OF SYS::SYSLOG @@ -31100,6 +32248,1209 @@ Sys::Syslog =back +=head2 TAP::Base - Base class that provides common functionality to +L<TAP::Parser> and L<TAP::Harness> + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAP::Formatter::Color - Run Perl test scripts with color + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAP::Formatter::Console - Harness output delegate for default +console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<verbosity>, C<verbose>, C<timer>, C<failures>, C<quiet>, C<really_quiet>, +C<silent>, C<errors>, C<directives>, C<stdout>, C<color>, C<jobs>, +C<show_count> + +=back + +=back + +=head2 TAP::Formatter::Console::ParallelSession - Harness output delegate +for parallel console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAP::Formatter::Console::Session - Harness output delegate for +default console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<formatter>, C<parser>, C<name>, C<show_count> + +=back + +=back + +=head2 TAP::Harness - Run test scripts with statistics + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<verbosity>, C<timer>, C<failures>, C<show_count>, C<lib>, C<switches>, +C<test_args>, C<color>, C<exec>, C<merge>, C<aggregator_class>, +C<formatter_class>, C<multiplexer_class>, C<parser_class>, +C<scheduler_class>, C<formatter>, C<errors>, C<directives>, C<ignore_exit>, +C<jobs>, C<fork>, C<rules>, C<stdout> + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +the file name of a test script to run, a reference to a [ file name, +display name ] array + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Methods + +C<start>, C<tests> + +=back + +=back + +=over 4 + +=item REPLACING + +=item SEE ALSO + +=back + +=head2 TAP::Object - Base class that provides common functionality to all +C<TAP::*> modules + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser, TAP::Parser - Parse L<TAP|Test::Harness::TAP> output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +C<source>, C<tap>, C<exec>, C<callback>, C<switches>, C<test_args>, +C<spool>, C<merge>, C<source_class>, C<perl_source_class>, +C<grammar_class>, C<iterator_factory_class>, C<result_factory_class> + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item INDIVIDUAL RESULTS + +=over 4 + +=item Result types + +Version, Plan, Pragma, Test, Comment, Bailout, Unknown + +=item Common type methods + +=item C<plan> methods + +=item C<pragma> methods + +=item C<bailout> methods + +=item C<unknown> methods + +=item C<test> methods + +=back + +=item TOTAL RESULTS + +=over 4 + +=item Individual Results + +=back + +=back + +=over 4 + +=item Pragmas + +=back + +=over 4 + +=item Summary Results + +=back + +=over 4 + +=item C<ignore_exit> + +=back + +Misplaced plan, No plan, More than one plan, Test numbers out of sequence + +=over 4 + +=item CALLBACKS + +C<test>, C<version>, C<plan>, C<comment>, C<bailout>, C<yaml>, C<unknown>, +C<ELSE>, C<ALL>, C<EOF> + +=item TAP GRAMMAR + +=item BACKWARDS COMPATABILITY + +=over 4 + +=item Differences + +TODO plans, 'Missing' tests + +=back + +=item SUBCLASSING + +=over 4 + +=item Parser Components + +option 1, option 2 + +=back + +=item ACKNOWLEDGEMENTS + +Michael Schwern, Andy Lester, chromatic, GEOFFR, Shlomi Fish, Torsten +Schoenfeld, Jerry Gay, Aristotle, Adam Kennedy, Yves Orton, Adrian Howard, +Sean & Lil, Andreas J. Koenig, Florian Ragwitz, Corion, Mark Stosberg, Matt +Kraai, David Wheeler, Alex Vandiver + +=item AUTHORS + +=item BUGS + +=item COPYRIGHT & LICENSE + +=back + +=head2 TAParser::Aggregator, TAP::Parser::Aggregator - Aggregate +TAP::Parser results + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item Summary methods + +failed, parse_errors, passed, skipped, todo, todo_passed, wait, exit + +=back + +Failed tests, Parse erros, Bad exit or wait status + +=over 4 + +=item See Also + +=back + +=head2 TAParser::Grammar, TAP::Parser::Grammar - A grammar for the Test +Anything Protocol. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item TAP GRAMMAR + +=item SUBCLASSING + +=item SEE ALSO + +=back + +=head2 TAParser::Iterator, TAP::Parser::Iterator - Internal base class for +TAP::Parser Iterators + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 TAParser::Iterator::Array, TAP::Parser::Iterator::Array - Internal +TAP::Parser array Iterator + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO + +=back + +=head2 TAParser::Iterator::Process, TAP::Parser::Iterator::Process - +Internal TAP::Parser Iterator + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO + +=back + +=head2 TAParser::Iterator::Stream, TAP::Parser::Iterator::Stream - Internal +TAP::Parser Iterator + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO + +=back + +=head2 TAParser::IteratorFactory, TAP::Parser::IteratorFactory - Internal +TAP::Parser Iterator + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item ATTRIBUTION + +=item SEE ALSO + +=back + +=head2 TAParser::Multiplexer, TAP::Parser::Multiplexer - Multiplex multiple +TAP::Parsers + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item See Also + +=back + +=head2 TAParser::Result, TAP::Parser::Result - Base class for TAP::Parser +output objects + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=over 4 + +=item DESCRIPTION + +=item METHODS + +=back + +=back + +=over 4 + +=item Boolean methods + +C<is_plan>, C<is_pragma>, C<is_test>, C<is_comment>, C<is_bailout>, +C<is_version>, C<is_unknown>, C<is_yaml> + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 TAParser::Result::Bailout, TAP::Parser::Result::Bailout - Bailout +result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::Result::Comment, TAP::Parser::Result::Comment - Comment +result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::Result::Plan, TAP::Parser::Result::Plan - Plan result +token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::Result::Pragma, TAP::Parser::Result::Pragma - TAP pragma +token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::Result::Test, TAP::Parser::Result::Test - Test result +token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +=over 4 + +=item Instance Methods + +=back + +=back + +=head2 TAParser::Result::Unknown, TAP::Parser::Result::Unknown - Unknown +result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=head2 TAParser::Result::Version, TAP::Parser::Result::Version - TAP syntax +version token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::Result::YAML, TAP::Parser::Result::YAML - YAML result +token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 TAParser::ResultFactory, TAP::Parser::ResultFactory - Factory for +creating TAP::Parser output objects + +=over 4 + +=item SYNOPSIS + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item METHODS + +=item Class Methods + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 TAParser::Scheduler, TAP::Parser::Scheduler - Schedule tests during +parallel testing + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAParser::Scheduler::Job, TAP::Parser::Scheduler::Job - A single +testing job. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAParser::Scheduler::Spinner, TAP::Parser::Scheduler::Spinner - A +no-op job. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 TAParser::Source, TAP::Parser::Source - Stream output from some +source + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 TAParser::Source::Perl, TAP::Parser::Source::Perl - Stream Perl +output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 TAParser::Utils, TAP::Parser::Utils - Internal TAP::Parser utilities + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item INTERFACE + +=back + +=back + +=head2 TAParser::YAMLish::Reader, TAP::Parser::YAMLish::Reader - Read +YAMLish data from iterator + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=item AUTHOR + +=item SEE ALSO + +=item COPYRIGHT + +=back + +=head2 TAParser::YAMLish::Writer, TAP::Parser::YAMLish::Writer - Write +YAMLish data + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +a reference to a scalar to append YAML to, the handle of an open file, a +reference to an array into which YAML will be pushed, a code reference + +=back + +=item AUTHOR + +=item SEE ALSO + +=item COPYRIGHT + +=back + =head2 Term::ANSIColor - Color screen output using ANSI escape sequences =over 4 @@ -31402,12 +33753,10 @@ B<reset> =item Setting up tests -B<exported_to> +B<plan> =back -B<plan> - B<expected_tests> B<no_plan> @@ -31416,6 +33765,8 @@ B<has_plan> B<skip_all> +B<exported_to> + =over 4 =item Running tests @@ -31478,12 +33829,16 @@ B<diag> =back -B<_print> +B<note> -B<_print_diag> +B<explain> + +B<_print> B<output>, B<failure_output>, B<todo_output> +reset_outputs + carp, croak =over 4 @@ -31500,6 +33855,14 @@ B<details> B<todo> +B<find_TODO> + +B<in_todo> + +B<todo_start> + +C<todo_end> + B<caller> B<_sanity_check> @@ -31622,81 +33985,611 @@ Test::Builder::Tester =item DESCRIPTION +=item FUNCTIONS + =over 4 -=item Taint mode +=item runtests( @test_files ) -=item Configuration variables. +=back -C<$Test::Harness::Verbose>, C<$Test::Harness::switches>, -C<$Test::Harness::Timer> +=back -=item Failure +=over 4 -B<Failed Test>, B<Stat>, B<Wstat>, B<Total>, B<Fail>, B<List of Failed> +=item execute_tests( tests => \@test_files, out => \*FH ) =back -=item FUNCTIONS +=over 4 + +=item EXPORT + +=item ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS + +C<HARNESS_ACTIVE>, C<HARNESS_VERSION> + +=item ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS + +C<HARNESS_TIMER>, C<HARNESS_VERBOSE>, C<HARNESS_OPTIONS>, C<< j<n> >>, C<< +f >> + +=item Taint Mode + +=item SEE ALSO + +=item BUGS + +=item AUTHORS + +=item LICENCE AND COPYRIGHT + +=back + +=head2 Test::Harness::lib::App::Prove, App::Prove - Implements the C<prove> +command. =over 4 -=item runtests( @test_files ) +=item VERSION =back +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + =back =over 4 -=item execute_tests( tests => \@test_files, out => \*FH ) +=item METHODS + +=over 4 + +=item Class Methods + +=back =back =over 4 -=item EXPORT +=item Attributes -=item DIAGNOSTICS +C<archive>, C<argv>, C<backwards>, C<blib>, C<color>, C<directives>, +C<dry>, C<exec>, C<extension>, C<failures>, C<fork>, C<formatter>, +C<harness>, C<ignore_exit>, C<includes>, C<jobs>, C<lib>, C<merge>, +C<modules>, C<parse>, C<plugins>, C<quiet>, C<really_quiet>, C<recurse>, +C<rules>, C<show_count>, C<show_help>, C<show_man>, C<show_version>, +C<shuffle>, C<state>, C<taint_fail>, C<taint_warn>, C<test_args>, C<timer>, +C<verbose>, C<warnings_fail>, C<warnings_warn> -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> +=back -=item ENVIRONMENT VARIABLES THAT TEST::HARNESS SETS +=head2 Test::Harness::lib::App::Prove::State, App::Prove::State - State +storage for the C<prove> command. -C<HARNESS_ACTIVE>, C<HARNESS_VERSION> +=over 4 -=item ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS +=item VERSION -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> +=back -=item EXAMPLE +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item C<result_class> + +=back + +=over 4 + +=item C<extension> + +=back + +=over 4 + +=item C<results> + +=back + +=over 4 + +=item C<commit> + +=back + +=over 4 + +=item Instance Methods + +C<last>, C<failed>, C<passed>, C<all>, C<hot>, C<todo>, C<slow>, C<fast>, +C<new>, C<old>, C<save> + +=back + +=head2 Test::Harness::lib::App::Prove::State::Result, +App::Prove::State::Result - Individual test suite results. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item C<state_version> + +=back + +=over 4 + +=item C<test_class> + +=back + +=head2 Test::Harness::lib::App::Prove::State::Result::Test, +App::Prove::State::Result::Test - Individual test results. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAP::Base, TAP::Base - Base class that provides +common functionality to L<TAP::Parser> and L<TAP::Harness> + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 Test::Harness::lib::TAP::Formatter::Color, TAP::Formatter::Color - +Run Perl test scripts with color + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 Test::Harness::lib::TAP::Formatter::Console, TAP::Formatter::Console +- Harness output delegate for default console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<verbosity>, C<verbose>, C<timer>, C<failures>, C<quiet>, C<really_quiet>, +C<silent>, C<errors>, C<directives>, C<stdout>, C<color>, C<jobs>, +C<show_count> + +=back + +=back + +=head2 Test::Harness::lib::TAP::Formatter::Console::ParallelSession, +TAP::Formatter::Console::ParallelSession - Harness output delegate for +parallel console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=head2 Test::Harness::lib::TAP::Formatter::Console::Session, +TAP::Formatter::Console::Session - Harness output delegate for default +console output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<formatter>, C<parser>, C<name>, C<show_count> + +=back + +=back + +=head2 Test::Harness::lib::TAP::Harness, TAP::Harness - Run test scripts +with statistics + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item SYNOPSIS + +=back + +=over 4 + +=item METHODS + +=over 4 + +=item Class Methods + +C<verbosity>, C<timer>, C<failures>, C<show_count>, C<lib>, C<switches>, +C<test_args>, C<color>, C<exec>, C<merge>, C<aggregator_class>, +C<formatter_class>, C<multiplexer_class>, C<parser_class>, +C<scheduler_class>, C<formatter>, C<errors>, C<directives>, C<ignore_exit>, +C<jobs>, C<fork>, C<rules>, C<stdout> + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +the file name of a test script to run, a reference to a [ file name, +display name ] array + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Methods + +C<start>, C<tests> + +=back + +=back + +=over 4 + +=item REPLACING =item SEE ALSO -=item TODO +=back -=item BUGS +=head2 Test::Harness::lib::TAP::Object, TAP::Object - Base class that +provides common functionality to all C<TAP::*> modules -=item SUPPORT +=over 4 -AnnoCPAN: Annotated CPAN documentation, CPAN Ratings, RT: CPAN's request -tracker, Search CPAN +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser, TAP::Parser - Parse +L<TAP|Test::Harness::TAP> output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +C<source>, C<tap>, C<exec>, C<callback>, C<switches>, C<test_args>, +C<spool>, C<merge>, C<source_class>, C<perl_source_class>, +C<grammar_class>, C<iterator_factory_class>, C<result_factory_class> + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item INDIVIDUAL RESULTS + +=over 4 + +=item Result types + +Version, Plan, Pragma, Test, Comment, Bailout, Unknown + +=item Common type methods + +=item C<plan> methods + +=item C<pragma> methods + +=item C<bailout> methods + +=item C<unknown> methods + +=item C<test> methods -=item SOURCE CODE +=back + +=item TOTAL RESULTS + +=over 4 + +=item Individual Results + +=back + +=back + +=over 4 + +=item Pragmas + +=back + +=over 4 + +=item Summary Results + +=back + +=over 4 + +=item C<ignore_exit> + +=back + +Misplaced plan, No plan, More than one plan, Test numbers out of sequence + +=over 4 + +=item CALLBACKS + +C<test>, C<version>, C<plan>, C<comment>, C<bailout>, C<yaml>, C<unknown>, +C<ELSE>, C<ALL>, C<EOF> + +=item TAP GRAMMAR + +=item BACKWARDS COMPATABILITY + +=over 4 + +=item Differences + +TODO plans, 'Missing' tests + +=back + +=item SUBCLASSING + +=over 4 + +=item Parser Components + +option 1, option 2 + +=back + +=item ACKNOWLEDGEMENTS + +Michael Schwern, Andy Lester, chromatic, GEOFFR, Shlomi Fish, Torsten +Schoenfeld, Jerry Gay, Aristotle, Adam Kennedy, Yves Orton, Adrian Howard, +Sean & Lil, Andreas J. Koenig, Florian Ragwitz, Corion, Mark Stosberg, Matt +Kraai, David Wheeler, Alex Vandiver =item AUTHORS -=item COPYRIGHT +=item BUGS + +=item COPYRIGHT & LICENSE =back -=head2 Test::Harness::Assert - simple assert +=head2 Test::Harness::lib::TAParser::Aggregator, TAP::Parser::Aggregator - +Aggregate TAP::Parser results + +=over 4 + +=item VERSION + +=back =over 4 @@ -31704,11 +34597,11 @@ tracker, Search CPAN =item DESCRIPTION -=item FUNCTIONS +=item METHODS =over 4 -=item C<assert()> +=item Class Methods =back @@ -31716,13 +34609,75 @@ tracker, Search CPAN =over 4 -=item AUTHOR +=item Instance Methods + +=back + +=over 4 + +=item Summary methods + +failed, parse_errors, passed, skipped, todo, todo_passed, wait, exit + +=back + +Failed tests, Parse erros, Bad exit or wait status + +=over 4 + +=item See Also + +=back + +=head2 Test::Harness::lib::TAParser::Grammar, TAP::Parser::Grammar - A +grammar for the Test Anything Protocol. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=back + +=back + +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item TAP GRAMMAR + +=item SUBCLASSING =item SEE ALSO =back -=head2 Test::Harness::Iterator - Internal Test::Harness Iterator +=head2 Test::Harness::lib::TAParser::Iterator, TAP::Parser::Iterator - +Internal base class for TAP::Parser Iterators + +=over 4 + +=item VERSION + +=back =over 4 @@ -31730,58 +34685,122 @@ tracker, Search CPAN =item DESCRIPTION +=item METHODS + =over 4 -=item new() +=item Class Methods -=item next() +=item Instance Methods =back =back -=head2 Test::Harness::Point - object for tracking a single test point +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 Test::Harness::lib::TAParser::Iterator::Array, +TAP::Parser::Iterator::Array - Internal TAP::Parser array Iterator + +=over 4 + +=item VERSION + +=back =over 4 =item SYNOPSIS -=item CONSTRUCTION +=item DESCRIPTION + +=item METHODS =over 4 -=item new() +=item Class Methods + +=item Instance Methods + +=back =back +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO + =back +=head2 Test::Harness::lib::TAParser::Iterator::Process, +TAP::Parser::Iterator::Process - Internal TAP::Parser Iterator + =over 4 -=item from_test_line( $line ) +=item VERSION =back =over 4 -=item ACCESSORS +=item SYNOPSIS + +=item DESCRIPTION -ok, number +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO =back -=head2 Test::Harness::Results - object for tracking results from a single -test file +=head2 Test::Harness::lib::TAParser::Iterator::Stream, +TAP::Parser::Iterator::Stream - Internal TAP::Parser Iterator + +=over 4 + +=item VERSION + +=back =over 4 =item SYNOPSIS -=item CONSTRUCTION +=item DESCRIPTION + +=item METHODS =over 4 -=item new() +=item Class Methods =back @@ -31789,13 +34808,26 @@ test file =over 4 -=item ACCESSORS +=item Instance Methods -wait, exit +=back + +=over 4 + +=item ATTRIBUTION + +=item SEE ALSO =back -=head2 Test::Harness::Straps - detailed analysis of test results +=head2 Test::Harness::lib::TAParser::IteratorFactory, +TAP::Parser::IteratorFactory - Internal TAP::Parser Iterator + +=over 4 + +=item VERSION + +=back =over 4 @@ -31803,23 +34835,52 @@ wait, exit =item DESCRIPTION -=item CONSTRUCTION +=item METHODS =over 4 -=item new() +=item Class Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example =back +=item ATTRIBUTION + +=item SEE ALSO + =back +=head2 Test::Harness::lib::TAParser::Multiplexer, TAP::Parser::Multiplexer +- Multiplex multiple TAP::Parsers + =over 4 -=item ANALYSIS +=item VERSION + +=back =over 4 -=item $strap->analyze( $name, \@output_lines ) +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods =back @@ -31827,134 +34888,555 @@ wait, exit =over 4 -=item $strap->analyze_file( $test_file ) +=item Instance Methods =back =over 4 -=item Parsing +=item See Also =back +=head2 Test::Harness::lib::TAParser::Result, TAP::Parser::Result - Base +class for TAP::Parser output objects + =over 4 -=item EXAMPLES +=item VERSION -=item AUTHOR +=back + +=over 4 + +=item SYNOPSIS + +=over 4 + +=item DESCRIPTION + +=item METHODS + +=back + +=back + +=over 4 + +=item Boolean methods + +C<is_plan>, C<is_pragma>, C<is_test>, C<is_comment>, C<is_bailout>, +C<is_version>, C<is_unknown>, C<is_yaml> + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back =item SEE ALSO =back -=head2 Test::Harness::TAP - Documentation for the TAP format +=head2 Test::Harness::lib::TAParser::Result::Bailout, +TAP::Parser::Result::Bailout - Bailout result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::Result::Comment, +TAP::Parser::Result::Comment - Comment result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::Result::Plan, +TAP::Parser::Result::Plan - Plan result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::Result::Pragma, +TAP::Parser::Result::Pragma - TAP pragma token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::Result::Test, +TAP::Parser::Result::Test - Test result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +=over 4 + +=item Instance Methods + +=back + +=back + +=head2 Test::Harness::lib::TAParser::Result::Unknown, +TAP::Parser::Result::Unknown - Unknown result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=head2 Test::Harness::lib::TAParser::Result::Version, +TAP::Parser::Result::Version - TAP syntax version token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::Result::YAML, +TAP::Parser::Result::YAML - YAML result token. + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item DESCRIPTION + +=item OVERRIDDEN METHODS + +C<as_string>, C<raw> + +=back + +=over 4 + +=item Instance Methods + +=back + +=head2 Test::Harness::lib::TAParser::ResultFactory, +TAP::Parser::ResultFactory - Factory for creating TAP::Parser output +objects =over 4 =item SYNOPSIS -=item TODO +=item VERSION -=item THE TAP FORMAT +=back -=item HARNESS BEHAVIOR +=over 4 -=item TESTS LINES AND THE PLAN +=item DESCRIPTION + +=item METHODS + +=item Class Methods + +=back =over 4 -=item The plan +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 Test::Harness::lib::TAParser::Scheduler, TAP::Parser::Scheduler - +Schedule tests during parallel testing -=item The test line +=over 4 -C<ok> or C<not ok>, Test number, Description, Directive, ok/not ok -(required), Test number (recommended), Description (recommended), Directive -(only when necessary) +=item VERSION =back -=item DIRECTIVES +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS =over 4 -=item TODO tests +=item Class Methods -=item Skipping tests +=back =back -=item OTHER LINES +=head2 Test::Harness::lib::TAParser::Scheduler::Job, +TAP::Parser::Scheduler::Job - A single testing job. =over 4 -=item Bail out! +=item VERSION -=item Diagnostics +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 -=item Anything else +=item Class Methods =back -=item EXAMPLES +=back + +=head2 Test::Harness::lib::TAParser::Scheduler::Spinner, +TAP::Parser::Scheduler::Spinner - A no-op job. =over 4 -=item Common with explanation +=item VERSION -=item Unknown amount and failures +=back -=item Giving up +=over 4 -=item Skipping a few +=item SYNOPSIS + +=item DESCRIPTION -=item Skipping everything +=item METHODS -=item Got spare tuits? +=over 4 + +=item Class Methods -=item Creative liberties +=back =back -=item Non-Perl TAP +=head2 Test::Harness::lib::TAParser::Source, TAP::Parser::Source - Stream +output from some source =over 4 -=item C/C++ +=item VERSION -Specify a test plan, Run tests, Skip tests in certain situations, Have TODO -tests, Produce TAP compatible diagnostics +=back -=item Python +=over 4 -=item JavaScript +=item SYNOPSIS -=item PHP +=item DESCRIPTION -phpt, PHPUnit, SimpleTest, Apache-Test +=item METHODS + +=over 4 + +=item Class Methods =back -=item AUTHORS +=back -=item ACKNOWLEDGEMENTS +=over 4 + +=item Instance Methods + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 Test::Harness::lib::TAParser::Source::Perl, +TAP::Parser::Source::Perl - Stream Perl output + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=back + +=over 4 + +=item SUBCLASSING + +=over 4 + +=item Example + +=back + +=item SEE ALSO + +=back + +=head2 Test::Harness::lib::TAParser::Utils, TAP::Parser::Utils - Internal +TAP::Parser utilities + +=over 4 + +=item VERSION + +=back + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=over 4 + +=item INTERFACE + +=back + +=back + +=head2 Test::Harness::lib::TAParser::YAMLish::Reader, +TAP::Parser::YAMLish::Reader - Read YAMLish data from iterator + +=over 4 + +=item VERSION + +=item SYNOPSIS + +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +=back + +=item AUTHOR + +=item SEE ALSO =item COPYRIGHT =back -=head2 Test::Harness::Util - Utility functions for Test::Harness::* +=head2 Test::Harness::lib::TAParser::YAMLish::Writer, +TAP::Parser::YAMLish::Writer - Write YAMLish data =over 4 +=item VERSION + =item SYNOPSIS -=item PUBLIC FUNCTIONS +=item DESCRIPTION + +=item METHODS + +=over 4 + +=item Class Methods + +=item Instance Methods + +a reference to a scalar to append YAML to, the handle of an open file, a +reference to an array into which YAML will be pushed, a code reference + +=back + +=item AUTHOR + +=item SEE ALSO + +=item COPYRIGHT + +=back + +=head2 Test::Harness::lib::Test::Harness, Test::Harness - Run Perl standard +test scripts with statistics =over 4 -=item all_in( {parm => value, parm => value} ) +=item VERSION + +=back -start, recurse +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=item FUNCTIONS + +=over 4 + +=item runtests( @test_files ) =back @@ -31962,13 +35444,32 @@ start, recurse =over 4 -=item shuffle( @list ) +=item execute_tests( tests => \@test_files, out => \*FH ) =back =over 4 -=item blibdir() +=item EXPORT + +=item ENVIRONMENT VARIABLES THAT TAP::HARNESS::COMPATIBLE SETS + +C<HARNESS_ACTIVE>, C<HARNESS_VERSION> + +=item ENVIRONMENT VARIABLES THAT AFFECT TEST::HARNESS + +C<HARNESS_TIMER>, C<HARNESS_VERBOSE>, C<HARNESS_OPTIONS>, C<< j<n> >>, C<< +f >> + +=item Taint Mode + +=item SEE ALSO + +=item BUGS + +=item AUTHORS + +=item LICENCE AND COPYRIGHT =back @@ -32010,6 +35511,8 @@ B<can_ok> B<isa_ok> +B<new_ok> + B<pass>, B<fail> =over 4 @@ -32034,10 +35537,12 @@ B<is_deeply> =item Diagnostics -B<diag> +B<diag>, B<note> =back +B<explain> + =over 4 =item Conditional tests @@ -32122,8 +35627,7 @@ B<ok> =item SEE ALSO -L<Test::More>, L<Test>, L<Test::Unit>, L<Test::Inline>, L<SelfTest>, -L<Test::Harness> +L<Test::More> =item AUTHORS @@ -32131,8 +35635,6 @@ L<Test::Harness> =back -=head2 Test::Tutorial - A tutorial about writing really basic tests - =over 4 =item DESCRIPTION @@ -32350,33 +35852,66 @@ lock(\&sub), eval, flags =back -=head2 Thread::Queue - thread-safe queues +=head2 Thread::Queue - Thread-safe queues =over 4 +=item VERSION + =item SYNOPSIS =item DESCRIPTION -=item FUNCTIONS AND METHODS +Ordinary scalars, Array refs, Hash refs, Scalar refs, Objects based on the +above + +=item QUEUE CREATION + +->new(), ->new(LIST) + +=item BASIC METHODS + +->enqueue(LIST), ->dequeue(), ->dequeue(COUNT), ->dequeue_nb(), +->dequeue_nb(COUNT), ->pending() -new, enqueue LIST, dequeue, dequeue_nb, pending +=item ADVANCED METHODS + +->peek(), ->peek(INDEX), ->insert(INDEX, LIST), ->extract(), +->extract(INDEX), ->extract(INDEX, COUNT) + +=item NOTES + +=item LIMITATIONS =item SEE ALSO +=item MAINTAINER + +=item LICENSE + =back -=head2 Thread::Semaphore - thread-safe semaphores +=head2 Thread::Semaphore - Thread-safe semaphores =over 4 +=item VERSION + =item SYNOPSIS =item DESCRIPTION -=item FUNCTIONS AND METHODS +=item METHODS + +->new(), ->new(NUMBER), ->down(), ->down(NUMBER), ->up(), ->up(NUMBER) + +=item NOTES + +=item SEE ALSO + +=item MAINTAINER -new, new NUMBER, down, down NUMBER, up, up NUMBER +=item LICENSE =back @@ -32578,6 +36113,16 @@ TIESCALAR classname, LIST, FETCH this, STORE this, value, DESTROY this =back +=head2 Tie::StdHandle - base class definitions for tied handles + +=over 4 + +=item SYNOPSIS + +=item DESCRIPTION + +=back + =head2 Tie::SubstrHash - Fixed-table-size, fixed-key-length hashing =over 4 @@ -32621,6 +36166,10 @@ $flags = 0), clock(), stat, stat FH, stat EXPR =item internal error: useconds < 0 (unsigned ... signed ...) +=item useconds or uinterval equal to or more than 1000000 + +=item unimplemented in this platform + =back =item CAVEATS @@ -32944,83 +36493,87 @@ http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/ =item DESCRIPTION -=back - =over 4 -=item charinfo +=item code point argument -=back +=item B<charinfo()> -=over 4 +B<code>, B<name>, B<category>, B<combining>, B<bidi>, B<decomposition>, +B<decimal>, B<digit>, B<numeric>, B<mirrored>, B<unicode10>, B<comment>, +B<upper>, B<lower>, B<title>, B<block>, B<script> -=item charblock +=back =back =over 4 -=item charscript +=item B<charblock()> =back =over 4 -=item charblocks +=item B<charscript()> =back =over 4 -=item charscripts +=item B<charblocks()> =back =over 4 -=item Blocks versus Scripts +=item B<charscripts()> -=item Matching Scripts and Blocks +=back -=item Code Point Arguments +=over 4 -=item charinrange +=item B<charinrange()> =back =over 4 -=item general_categories +=item B<general_categories()> =back =over 4 -=item bidi_types +=item B<bidi_types()> =back =over 4 -=item compexcl +=item B<compexcl()> =back =over 4 -=item casefold +=item B<casefold()> + +B<code>, B<full>, B<simple>, B<mapping>, B<status>, B<*>, B<*>, B<turkic> =back =over 4 -=item casespec +=item B<casespec()> + +B<code>, B<lower>, B<title>, B<lower>, B<condition> =back =over 4 -=item namedseq() +=item B<namedseq()> =back @@ -33032,6 +36585,10 @@ http://www.unicode.org/review/pr-29.html, http://www.unicode.org/notes/tn5/ =over 4 +=item B<Blocks versus Scripts> + +=item B<Matching Scripts and Blocks> + =item Implementation Note =back @@ -33100,11 +36657,11 @@ 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::GetChipName(), Win32::GetCwd(), Win32::GetCurrentProcessId(), +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), @@ -33306,7 +36863,7 @@ C<XSLoader::load('Your::Module', $Your::Module::VERSION)> =item AUTHORS -=item COPYRIGHT +=item COPYRIGHT & LICENSE =back diff --git a/pod/perltodo.pod b/pod/perltodo.pod index 30f17b04cb..00effc392f 100644 --- a/pod/perltodo.pod +++ b/pod/perltodo.pod @@ -91,13 +91,6 @@ 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 merge checkpods and podchecker - -F<pod/checkpods.PL> (and C<make check> in the F<pod/> subdirectory) -implements a very basic check for pod files, but the errors it discovers -aren't found by podchecker. Add this check to podchecker, get rid of -checkpods and have C<make check> use podchecker. - =head2 Parallel testing (This probably impacts much more than the core: also the Test::Harness @@ -126,28 +119,6 @@ tests that are currently missing. A full test suite for the B module would be nice. -=head2 Deparse inlined constants - -Code such as this - - use constant PI => 4; - warn PI - -will currently deparse as - - use constant ('PI', 4); - warn 4; - -because the tokenizer inlines the value of the constant subroutine C<PI>. -This allows various compile time optimisations, such as constant folding -and dead code elimination. Where these haven't happened (such as the example -above) it ought be possible to make B::Deparse work out the name of the -original constant, because just enough information survives in the symbol -table to do this. Specifically, the same scalar is used for the constant in -the optree as is used for the constant subroutine, so by iterating over all -symbol tables and generating a mapping of SV address to constant name, it -would be possible to provide B::Deparse with this functionality. - =head2 A decent benchmark C<perlbench> seems impervious to any recent changes made to the perl core. It @@ -384,14 +355,14 @@ Right now, Configure probes for two commands, and sets two variables: =over 4 -=item * C<cc (cc.U)> +=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 * ld (dlsrc.U) +=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>. @@ -845,6 +816,23 @@ also the warning messages (see L<perllexwarn>, C<warnings.pl>). These tasks would need C knowledge, and knowledge of how the interpreter works, or a willingness to learn. +=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 +http://www.xray.mpe.mpg.de/mailing-lists/perl5-porters/2008-09/msg00573.html + =head2 lexicals used only once This warns: @@ -924,11 +912,6 @@ could probably be optimized. The old perltodo notes that lvalue functions don't work for list or hash slices. This would be good to fix. -=head2 LVALUE functions in the debugger - -The old perltodo notes that lvalue functions don't work in the debugger. This -would be good to fix. - =head2 regexp optimiser optional The regexp optimiser is not optional. It should configurable to be, to allow diff --git a/pod/perlunicode.pod b/pod/perlunicode.pod index 4e62fed0b5..3a52933854 100644 --- a/pod/perlunicode.pod +++ b/pod/perlunicode.pod @@ -79,6 +79,16 @@ character semantics. For operations where this determination cannot be made without additional information from the user, Perl decides in favor of compatibility and chooses to use byte semantics. +Under byte semantics, when C<use locale> is in effect, Perl uses the +semantics associated with the current locale. Absent a C<use locale>, Perl +currently 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 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:]>.) + This behavior preserves compatibility with earlier versions of Perl, which allowed byte semantics in Perl operations only if none of the program's inputs were marked as being as source of Unicode @@ -105,10 +115,8 @@ Otherwise, byte semantics are in effect. The C<bytes> pragma should be used to force byte semantics on Unicode data. If strings operating under byte semantics and strings with Unicode -character data are concatenated, the new string will be created by -decoding the byte strings as I<ISO 8859-1 (Latin-1)>, even if the -old Unicode string used EBCDIC. This translation is done without -regard to the system's native 8-bit encoding. +character data are concatenated, the new string will have +character semantics. This can cause surprises: See L</BUGS>, below Under character semantics, many operations that formerly operated on bytes now operate on characters. A character in Perl is @@ -135,7 +143,7 @@ occur directly within the literal strings in UTF-8 encoding, or UTF-16. Unicode characters can also be added to a string by using the C<\x{...}> notation. The Unicode code for the desired character, in hexadecimal, should be placed in the braces. For instance, a smiley face is -C<\x{263A}>. This encoding scheme only works for all characters, but +C<\x{263A}>. This encoding scheme works for all characters, but for characters under 0x100, note that Perl may use an 8 bit encoding internally, for optimization and/or backward compatibility. @@ -939,8 +947,8 @@ Level 1 - Basic Unicode Support user-defined character properties [b] to emulate set operations [6] \b \B [7] note that Perl does Full case-folding in matching, not Simple: - for example U+1F88 is equivalent with U+1F00 U+03B9, - not with 1F80. This difference matters for certain Greek + 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. @@ -1299,15 +1307,13 @@ readdir, readlink =head2 Forcing Unicode in Perl (Or Unforcing Unicode in Perl) Sometimes (see L</"When Unicode Does Not Happen">) there are -situations where you simply need to force Perl to believe that a byte -string is UTF-8, or vice versa. The low-level calls -utf8::upgrade($bytestring) and utf8::downgrade($utf8string) are +situations where you simply need to force a byte +string into UTF-8, or vice versa. The low-level calls +utf8::upgrade($bytestring) and utf8::downgrade($utf8string[, FAIL_OK]) are the answers. -Do not use them without careful thought, though: Perl may easily get -very confused, angry, or even crash, if you suddenly change the 'nature' -of scalar like that. Especially careful you have to be if you use the -utf8::upgrade(): any random byte string is not valid UTF-8. +Note that utf8::downgrade() can fail if the string contains characters +that don't fit into a byte. =head2 Using Unicode in XS @@ -1321,7 +1327,7 @@ details. =item * C<DO_UTF8(sv)> returns true if the C<UTF8> flag is on and the bytes -pragma is not in effect. C<SvUTF8(sv)> returns true is the C<UTF8> +pragma is not in effect. C<SvUTF8(sv)> returns true if the C<UTF8> flag is on; the bytes pragma is ignored. The C<UTF8> flag being on does B<not> mean that there are any characters of code points greater than 255 (or 127) in the scalar or that there are even any characters @@ -1334,15 +1340,15 @@ Unicode model is not to use UTF-8 until it is absolutely necessary. =item * -C<uvuni_to_utf8(buf, chr)> writes a Unicode character code point into +C<uvchr_to_utf8(buf, chr)> writes a Unicode character code point into a buffer encoding the code point as UTF-8, and returns a pointer -pointing after the UTF-8 bytes. +pointing after the UTF-8 bytes. It works appropriately on EBCDIC machines. =item * -C<utf8_to_uvuni(buf, lenp)> reads UTF-8 encoded bytes from a buffer and +C<utf8_to_uvchr(buf, 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. +the UTF-8 byte sequence. It works appropriately on EBCDIC machines. =item * @@ -1388,7 +1394,7 @@ two pointers pointing to the same UTF-8 encoded buffer. =item * -C<utf8_hop(s, off)> will return a pointer to an UTF-8 encoded buffer +C<utf8_hop(s, off)> will return a pointer to a UTF-8 encoded buffer that is C<off> (positive or negative) Unicode characters displaced from the UTF-8 buffer C<s>. Be careful not to overstep the buffer: C<utf8_hop()> will merrily run off the end or the beginning of the @@ -1406,7 +1412,7 @@ output more readable. =item * -C<ibcmp_utf8(s1, pe1, u1, l1, u1, s2, pe2, l2, u2)> can be used to +C<ibcmp_utf8(s1, pe1, l1, u1, s2, pe2, l2, u2)> can be used to compare two strings case-insensitively in Unicode. For case-sensitive comparisons you can just use C<memEQ()> and C<memNE()> as usual. @@ -1426,6 +1432,28 @@ use characters above that range when mapped into Unicode. Perl's Unicode support will also tend to run slower. Use of locales with Unicode is discouraged. +=head2 Problems with characters whose ordinal numbers are in the range 128 - 255 with no Locale specified + +Without a locale specified, unlike all other characters or code points, +these characters have very different semantics in byte semantics versus +character semantics. +In character semantics they are interpreted as Unicode code points, which means +they are viewed 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 not members of various character classes. +None are considered to match C<\w> for example, but all match C<\W>. +Besides these class matches, +the known operations that this affects are those that change the case, +regular expression matching while ignoring case, +and B<quotemeta()>. +This can lead to unexpected results in which a string's semantics suddenly +change if a code point above 255 is appended to or removed from it, +which changes the string's semantics from byte to character or vice versa. +This behavior is scheduled to change in version 5.12, but in the meantime, +a workaround is to always call utf8::upgrade($string), or to use the +standard modules L<Encode> or L<charnames>. + =head2 Interaction with Extensions When Perl exchanges data with an extension, the extension should be @@ -1506,6 +1534,15 @@ be quite a bit slower (5-20 times) than their simpler counterparts like C<\d> (then again, there 268 Unicode characters matching C<Nd> compared with the 10 ASCII characters matching C<d>). +=head2 Possible problems on EBCDIC platforms + +In earlier versions, when byte and character data were concatenated, +the new string was sometimes created by +decoding the byte strings as I<ISO 8859-1 (Latin-1)>, even if the +old Unicode string used EBCDIC. + +If you find any of these, please report them as bugs. + =head2 Porting code from perl-5.6.X Perl 5.8 has a different Unicode model from 5.6. In 5.6 the programmer diff --git a/pod/perlunifaq.pod b/pod/perlunifaq.pod index b2913349cc..83edc7d488 100644 --- a/pod/perlunifaq.pod +++ b/pod/perlunifaq.pod @@ -145,11 +145,13 @@ strings differently, depending on the internal state. Affected are C<uc>, C<lc>, C<ucfirst>, C<lcfirst>, C<\U>, C<\L>, C<\u>, C<\l>, C<\d>, C<\s>, C<\w>, C<\D>, C<\S>, C<\W>, C</.../i>, C<(?i:...)>, -C</[[:posix:]]/>. +C</[[:posix:]]/>, and C<quotemeta> (though this last should not cause any real +problems). To force Unicode semantics, you can upgrade the internal representation to -by doing C<utf8::upgrade($string)>. This does not change strings that were -already upgraded. +by doing C<utf8::upgrade($string)>. This can be used +safely on any string, as it checks and does not change strings that have +already been upgraded. For a more detailed discussion, see L<Unicode::Semantics> on CPAN. diff --git a/pod/perluniintro.pod b/pod/perluniintro.pod index 86360d4a72..36f729c67b 100644 --- a/pod/perluniintro.pod +++ b/pod/perluniintro.pod @@ -24,7 +24,7 @@ Unicode 1.0 was released in October 1991, and 4.0 in April 2003. A Unicode I<character> is an abstract entity. It is not bound to any particular integer width, especially not to the C language C<char>. Unicode is language-neutral and display-neutral: it does not encode the -language of the text and it does not define fonts or other graphical +language of the text and it does not generally define fonts or other graphical layout details. Unicode operates on characters and on text built from those characters. @@ -125,8 +125,7 @@ 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. -B<Starting from Perl 5.8.0, the use of C<use utf8> is no longer -necessary.> In earlier releases the C<utf8> pragma was used to declare +B<Starting from Perl 5.8.0, the use of C<use utf8> is needed only in much more restricted circumstances.> In earlier releases the C<utf8> pragma 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 @@ -514,8 +513,8 @@ CAPITAL LETTER As should be considered equal, or even As of any case. The long answer is that you need to consider character normalization and casing issues: see L<Unicode::Normalize>, Unicode Technical Reports #15 and #21, I<Unicode Normalization Forms> and I<Case -Mappings>, http://www.unicode.org/unicode/reports/tr15/ and -http://www.unicode.org/unicode/reports/tr21/ +Mappings>, L<http://www.unicode.org/unicode/reports/tr15/> and +L<http://www.unicode.org/unicode/reports/tr21/> As of Perl 5.8.0, the "Full" case-folding of I<Case Mappings/SpecialCasing> is implemented. @@ -538,7 +537,7 @@ C<0x00C1> > C<0x00C0>. The long answer is that "it depends", and a good answer cannot be given without knowing (at the very least) the language context. See L<Unicode::Collate>, and I<Unicode Collation Algorithm> -http://www.unicode.org/unicode/reports/tr10/ +L<http://www.unicode.org/unicode/reports/tr10/> =back @@ -552,7 +551,7 @@ Character Ranges and Classes Character ranges in regular expression character classes (C</[a-z]/>) and in the C<tr///> (also known as C<y///>) operator are not magically -Unicode-aware. What this means that C<[A-Za-z]> will not magically start +Unicode-aware. What this means is that C<[A-Za-z]> will not magically start to mean "all alphabetic letters"; not that it does mean that even for 8-bit characters, you should be using C</[[:alpha:]]/> in that case. @@ -603,11 +602,12 @@ Unicode; for that, see the earlier I/O discussion. How Do I Know Whether My String Is In Unicode? -You shouldn't care. No, you really shouldn't. No, really. If you -have to care--beyond the cases described above--it means that we -didn't get the transparency of Unicode quite right. +You shouldn't have to care. But you may, because currently the semantics of the +characters whose ordinals are in the range 128 to 255 is different depending on +whether the string they are contained within is in Unicode or not. +(See L<perlunicode>.) -Okay, if you insist: +To determine if a string is in Unicode, use: print utf8::is_utf8($string) ? 1 : 0, "\n"; @@ -634,8 +634,8 @@ C<$a> will stay byte-encoded. Sometimes you might really need to know the byte length of a string instead of the character length. For that use either the -C<Encode::encode_utf8()> function or the C<bytes> pragma and its only -defined function C<length()>: +C<Encode::encode_utf8()> function or the C<bytes> pragma and +the C<length()> function: my $unicode = chr(0x100); print length($unicode), "\n"; # will print 1 @@ -653,7 +653,7 @@ Use the C<Encode> package to try converting it. For example, use Encode 'decode_utf8'; - + if (eval { decode_utf8($string, Encode::FB_CROAK); 1 }) { # $string is valid utf8 } else { @@ -724,18 +724,20 @@ or: $Unicode = pack("U0a*", $bytes); -You can convert well-formed UTF-8 to a sequence of bytes, but if -you just want to convert random binary data into UTF-8, you can't. -B<Any random collection of bytes isn't well-formed UTF-8>. You can -use C<unpack("C*", $string)> for the former, and you can create -well-formed Unicode data by C<pack("U*", 0xff, ...)>. +You can find the bytes that make up a UTF-8 sequence with + + @bytes = unpack("C*", $Unicode_string) + +and you can create well-formed Unicode with + + $Unicode_string = pack("U*", 0xff, ...) =item * How Do I Display Unicode? How Do I Input Unicode? -See http://www.alanwood.net/unicode/ and -http://www.cl.cam.ac.uk/~mgk25/unicode.html +See L<http://www.alanwood.net/unicode/> and +L<http://www.cl.cam.ac.uk/~mgk25/unicode.html> =item * @@ -787,44 +789,44 @@ show a decimal number in hexadecimal. If you have just the Unicode Consortium -http://www.unicode.org/ +L<http://www.unicode.org/> =item * Unicode FAQ -http://www.unicode.org/unicode/faq/ +L<http://www.unicode.org/unicode/faq/> =item * Unicode Glossary -http://www.unicode.org/glossary/ +L<http://www.unicode.org/glossary/> =item * Unicode Useful Resources -http://www.unicode.org/unicode/onlinedat/resources.html +L<http://www.unicode.org/unicode/onlinedat/resources.html> =item * Unicode and Multilingual Support in HTML, Fonts, Web Browsers and Other Applications -http://www.alanwood.net/unicode/ +L<http://www.alanwood.net/unicode/> =item * UTF-8 and Unicode FAQ for Unix/Linux -http://www.cl.cam.ac.uk/~mgk25/unicode.html +L<http://www.cl.cam.ac.uk/~mgk25/unicode.html> =item * Legacy Character Sets -http://www.czyborra.com/ -http://www.eki.ee/letter/ +L<http://www.czyborra.com/> +L<http://www.eki.ee/letter/> =item * diff --git a/pod/perlvar.pod b/pod/perlvar.pod index 6e62a10689..68573e3d49 100644 --- a/pod/perlvar.pod +++ b/pod/perlvar.pod @@ -1217,7 +1217,8 @@ Debug subroutine enter/exit. =item 0x02 -Line-by-line debugging. +Line-by-line debugging. Causes DB::DB() subroutine to be called for each +statement executed. Also causes saving source code lines (like 0x400). =item 0x04 @@ -1254,12 +1255,13 @@ were compiled. =item 0x400 -Debug assertion subroutines enter/exit. +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 $LAST_REGEXP_CODE_RESULT diff --git a/pod/perlxs.pod b/pod/perlxs.pod index c2cae2269a..c367f4c1ca 100644 --- a/pod/perlxs.pod +++ b/pod/perlxs.pod @@ -293,7 +293,7 @@ or less equivalent: ST(0) = newSVpv("Hello World",0); sv_2mortal(ST(0)); XSRETURN(1); - + SV * beta() CODE: diff --git a/pod/pod2man.PL b/pod/pod2man.PL index c98f8de989..25df0df0b4 100644 --- a/pod/pod2man.PL +++ b/pod/pod2man.PL @@ -58,14 +58,15 @@ use vars qw($running_under_some_shell); my $stdin; @ARGV = map { $_ eq '-' && !$stdin++ ? ('--', $_) : $_ } @ARGV; -# Parse our options, trying to retain backwards compatibility with pod2man but +# 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, 'section|s=s', 'release|r:s', 'center|c=s', - 'date|d=s', 'fixed=s', 'fixedbold=s', 'fixeditalic=s', - 'fixedbolditalic=s', 'name|n=s', 'official|o', 'quotes|q=s', - 'lax|l', 'help|h', 'verbose|v', 'utf8|u') or exit 1; +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. @@ -77,7 +78,7 @@ if ($options{official} && !defined $options{center}) { my $verbose = $options{verbose}; delete $options{verbose}; -# This isn't a valid Pod::Man option and is only accepted for backwards +# This isn't a valid Pod::Man option and is only accepted for backward # compatibility. delete $options{lax}; @@ -98,15 +99,16 @@ __END__ pod2man - Convert POD data to formatted *roff input =for stopwords -en em --utf8 UTF-8 overdo markup MT-LEVEL Allbery +en em --stderr stderr --utf8 UTF-8 overdo markup MT-LEVEL Allbery Solaris +URL troff troff-specific formatters uppercased Christiansen =head1 SYNOPSIS -pod2man [B<--section>=I<manext>] [B<--release>[=I<version>]] - [B<--center>=I<string>] [B<--date>=I<string>] [B<--fixed>=I<font>] - [B<--fixedbold>=I<font>] [B<--fixeditalic>=I<font>] +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<--lax>] [B<--quotes>=I<quotes>] [B<--verbose>] + [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> @@ -125,8 +127,8 @@ 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 +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 @@ -189,9 +191,9 @@ 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 -backwards compatibility; this option no longer does anything. +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> @@ -246,6 +248,13 @@ 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 @@ -262,6 +271,12 @@ 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. @@ -538,8 +553,8 @@ section numbering conventions. =head1 SEE ALSO -L<Pod::Man>, L<Pod::Simple>, L<man(1)>, L<nroff(1)>, L<podchecker(1)>, -L<troff(1)>, L<man(7)> +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. diff --git a/pod/pod2text.PL b/pod/pod2text.PL index 81d29a6d69..ede0fe76b0 100644 --- a/pod/pod2text.PL +++ b/pod/pod2text.PL @@ -79,7 +79,9 @@ $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', 'termcap|t', 'width|w=i') or exit 1; + '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. @@ -112,12 +114,13 @@ __END__ pod2text - Convert POD data to formatted ASCII text =for stopwords --aclost --alt Allbery +-aclostu --alt --stderr Allbery --overstrike overstrike --termcap --utf8 +UTF-8 =head1 SYNOPSIS -pod2text [B<-aclost>] [B<--code>] [B<-i> I<indent>] S<[B<-q> I<quotes>]> - S<[B<-w> I<width>]> [I<input> [I<output> ...]] +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> @@ -202,6 +205,13 @@ 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 @@ -212,6 +222,18 @@ 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, @@ -263,7 +285,7 @@ current terminal device. =head1 SEE ALSO L<Pod::Text>, L<Pod::Text::Color>, L<Pod::Text::Overstrike>, -L<Pod::Text::Termcap>, L<Pod::Simple> +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 |